feat: add cc-taskrunner plugin — autonomous task queue

plugins/README.md

@@ -13,6 +13,7 @@ Learn more in the [official plugins documentation](https://docs.claude.com/en/do
 | Name | Description | Contents |
 |------|-------------|----------|
 | [agent-sdk-dev](./agent-sdk-dev/) | Development kit for working with the Claude Agent SDK | **Command:** `/new-sdk-app` - Interactive setup for new Agent SDK projects<br>**Agents:** `agent-sdk-verifier-py`, `agent-sdk-verifier-ts` - Validate SDK applications against best practices |
+| [cc-taskrunner](./cc-taskrunner/) | Autonomous task queue with safety hooks, branch isolation, and automatic PR creation | **Commands:** `/taskrunner`, `/taskrunner-add`, `/taskrunner-list` - Queue and execute tasks in headless Claude Code sessions<br>**Agent:** `task-executor` - Debug and monitor autonomous task execution |
 | [claude-opus-4-5-migration](./claude-opus-4-5-migration/) | Migrate code and prompts from Sonnet 4.x and Opus 4.1 to Opus 4.5 | **Skill:** `claude-opus-4-5-migration` - Automated migration of model strings, beta headers, and prompt adjustments |
 | [code-review](./code-review/) | Automated PR code review using multiple specialized agents with confidence-based scoring to filter false positives | **Command:** `/code-review` - Automated PR review workflow<br>**Agents:** 5 parallel Sonnet agents for CLAUDE.md compliance, bug detection, historical context, PR history, and code comments |
 | [commit-commands](./commit-commands/) | Git workflow automation for committing, pushing, and creating pull requests | **Commands:** `/commit`, `/commit-push-pr`, `/clean_gone` - Streamlined git operations |

plugins/cc-taskrunner/.claude-plugin/plugin.json

@@ -0,0 +1,9 @@
+{
+  "name": "cc-taskrunner",
+  "version": "1.0.0",
+  "description": "Autonomous task queue for Claude Code with safety hooks, branch isolation, and automatic PR creation",
+  "author": {
+    "name": "Kurt Overmier",
+    "email": "admin@stackbilt.dev"
+  }
+}

plugins/cc-taskrunner/README.md

@@ -0,0 +1,78 @@
+# cc-taskrunner
+
+Autonomous task queue for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) with safety hooks, branch isolation, and automatic PR creation.
+
+Queue tasks. Go to sleep. Wake up to PRs.
+
+## Installation
+
+```bash
+claude plugin:add /path/to/cc-taskrunner
+```
+
+Or clone from the [cc-taskrunner repository](https://github.com/Stackbilt-dev/cc-taskrunner) and add the `plugin/` directory.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/taskrunner` | Run pending tasks from the queue |
+| `/taskrunner-add` | Add a task to the queue |
+| `/taskrunner-list` | Show all tasks and their status |
+
+### Quick Start
+
+```
+> /taskrunner-add Write unit tests for the auth middleware in src/middleware.ts
+
+Added task a1b2c3d4: Write unit tests for the auth middleware
+
+> /taskrunner --max 1
+```
+
+## Safety Architecture
+
+Three layers of protection prevent autonomous sessions from causing damage:
+
+1. **Safety hooks** — Block `AskUserQuestion`, destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`), production deploys, and secret access
+2. **CLI constraints** — `--max-turns` caps agentic loops, `--output-format json` enables structured parsing
+3. **Mission brief** — Every task gets explicit constraints: no questions, no deploys, no destructive ops, commit work, output completion signal
+
+Safety hooks are **only active during task execution**, not during interactive Claude Code sessions.
+
+## Branch Isolation
+
+Each task runs on its own branch (`auto/{task-id}`). Main is never directly modified.
+
+- Uncommitted work is stashed before task execution and restored after
+- Tasks that produce commits get automatic PRs via `gh` CLI
+- Empty branches (no commits) are cleaned up automatically
+
+## Agents
+
+The `task-executor` agent helps monitor and debug task execution:
+
+```
+> "Why did my last task fail?"
+```
+
+It checks queue status, exit codes, Claude Code process state, and provides debugging guidance.
+
+## Requirements
+
+- bash 4+, python3, jq
+- [Claude Code CLI](https://docs.anthropic.com/en/docs/claude-code) (`claude` on PATH)
+- Optional: `gh` CLI for automatic PR creation
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_QUEUE_FILE` | `./queue.json` | Path to the task queue |
+| `CC_POLL_INTERVAL` | `60` | Seconds between polls in loop mode |
+| `CC_MAX_TASKS` | `0` | Max tasks per run (0 = unlimited) |
+| `CC_MAX_TURNS` | `25` | Default Claude Code turns per task |
+
+## License
+
+Apache License 2.0 — Copyright 2026 Stackbilt LLC

plugins/cc-taskrunner/agents/task-executor.md

@@ -0,0 +1,62 @@
+---
+name: task-executor
+description: Use this agent to monitor or debug autonomous task execution. Examples - "Why did my task fail?", "Show me the output from the last task run", "Check if the taskrunner is still running"
+model: inherit
+color: cyan
+tools: ["Bash", "Read", "Grep", "Glob"]
+---
+
+You are a task execution specialist that helps users monitor, debug, and understand cc-taskrunner execution.
+
+## Capabilities
+
+1. **Check running tasks**: Look for active Claude Code processes
+2. **Read task output**: Parse JSON output files from completed tasks
+3. **Debug failures**: Analyze why tasks failed or got blocked
+4. **Queue analysis**: Identify duplicate tasks, conflicting file targets, or sizing issues
+
+## Debugging a Failed Task
+
+When a task fails, check these in order:
+
+1. **Queue status** — Read the queue file to find the failed task and its `result` field:
+   ```bash
+   cat ${CC_QUEUE_FILE:-queue.json} | python3 -c "import json,sys; [print(json.dumps(t, indent=2)) for t in json.load(sys.stdin) if t.get('status')=='failed']"
+   ```
+
+2. **Exit code meaning**:
+   - `0` = success with TASK_COMPLETE signal
+   - `1` = Claude Code error or crash
+   - `2` = TASK_BLOCKED reported
+   - `3` = no completion signal (task may have run out of turns)
+
+3. **Common failure patterns**:
+   - **Out of turns**: Task needed more than `max_turns`. Suggest increasing or splitting the task.
+   - **Blocked by safety hook**: Check if the task tried a destructive operation. Look for "BLOCKED:" in output.
+   - **TASK_BLOCKED**: Task hit an obstacle it couldn't resolve. Read the reason.
+   - **Branch conflict**: Task branch already exists with divergent history. Check `git branch -a`.
+
+4. **PR status** — If a task completed but PR creation failed:
+   ```bash
+   gh pr list --head "auto/<task-id-prefix>" --state all
+   ```
+
+## Queue Health Check
+
+Analyze the queue for issues:
+- Tasks targeting the same files (merge conflict risk)
+- Tasks with overly broad prompts (scope creep risk)
+- Tasks with `max_turns` > 25 (should be split)
+- Stale `running` tasks (process may have crashed)
+
+## Process Check
+
+Look for running taskrunner processes:
+```bash
+ps aux | grep taskrunner.sh | grep -v grep
+```
+
+Look for active Claude Code sessions:
+```bash
+ps aux | grep "claude -p" | grep -v grep
+```

plugins/cc-taskrunner/commands/taskrunner-add.md

@@ -0,0 +1,75 @@
+---
+description: Add a task to the autonomous queue
+argument-hint: "<task description>"
+allowed-tools: ["Bash", "Read", "Write", "AskUserQuestion"]
+---
+
+# cc-taskrunner — Add Task
+
+Add a task to the cc-taskrunner queue for autonomous execution.
+
+## Behavior
+
+**If $ARGUMENTS is provided:**
+Use it as the task title and prompt.
+
+**If $ARGUMENTS is empty:**
+Ask the user what task to add using AskUserQuestion with these fields:
+- Title: short description of the task
+- Prompt: detailed instructions (file paths, constraints, completion criteria)
+- Authority: `auto_safe` (branch + PR) or `operator` (run on current branch)
+- Max turns: 5-25 (default 25)
+
+## Steps
+
+1. Parse or gather task details.
+
+2. Add the task:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/taskrunner.sh add "$TASK_TITLE"
+   ```
+
+   For more control (custom repo, prompt, authority, turns), write directly to the queue file:
+   ```bash
+   python3 -c "
+   import json, uuid, datetime
+   task = {
+       'id': str(uuid.uuid4()),
+       'title': '''$TITLE''',
+       'repo': '$REPO',
+       'prompt': '''$PROMPT''',
+       'authority': '$AUTHORITY',
+       'max_turns': $MAX_TURNS,
+       'status': 'pending',
+       'created_at': datetime.datetime.utcnow().strftime('%Y-%m-%dT%H:%M:%SZ')
+   }
+   queue_file = '${CC_QUEUE_FILE:-queue.json}'
+   try:
+       with open(queue_file) as f:
+           queue = json.load(f)
+   except (FileNotFoundError, json.JSONDecodeError):
+       queue = []
+   queue.append(task)
+   with open(queue_file, 'w') as f:
+       json.dump(queue, f, indent=2)
+   print(f'Added task {task[\"id\"][:8]}: {task[\"title\"]}')
+   "
+   ```
+
+3. Show confirmation with task ID and suggest running `/taskrunner` to execute.
+
+## Prompt Writing Tips
+
+Good prompts are specific:
+- Name file paths explicitly: "Read `src/services/quota.ts`"
+- State completion criteria: "Tests should pass"
+- Include context: each task is a fresh session
+- Say what NOT to do: "Do NOT modify the database schema"
+- End with: "Commit your work with a descriptive message"
+
+## Authority Levels
+
+| Authority | Branch? | PR? | Use for |
+|-----------|---------|-----|---------|
+| `operator` | No | No | Tasks that run on your current branch |
+| `auto_safe` | Yes | Yes | Tests, docs, research, refactors |

plugins/cc-taskrunner/commands/taskrunner-list.md

@@ -0,0 +1,26 @@
+---
+description: Show the current task queue
+argument-hint: ""
+allowed-tools: ["Bash", "Read"]
+---
+
+# cc-taskrunner — List Queue
+
+Show all tasks in the queue with their status.
+
+## Steps
+
+1. Run the list command:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/taskrunner.sh list
+   ```
+
+2. If the queue file doesn't exist or is empty, tell the user and suggest `/taskrunner-add`.
+
+3. Present the results. Status symbols:
+   - `○` pending — waiting to run
+   - `▶` running — currently executing
+   - `✓` completed — finished successfully
+   - `✗` failed — task errored or was blocked
+
+4. If there are pending tasks, suggest `/taskrunner` to execute them.

plugins/cc-taskrunner/commands/taskrunner.md

@@ -0,0 +1,70 @@
+---
+description: Run pending tasks from the queue, show status, or execute a specific number of tasks
+argument-hint: "[--max N] [--dry-run] [--loop]"
+allowed-tools: ["Bash", "Read", "Glob", "Grep", "Agent"]
+---
+
+# cc-taskrunner — Run Task Queue
+
+Execute pending tasks from the queue using headless Claude Code sessions with safety hooks, branch isolation, and automatic PR creation.
+
+## Behavior
+
+**If $ARGUMENTS is empty or contains only flags:**
+Run the taskrunner with the provided flags (or defaults).
+
+**If $ARGUMENTS contains "--dry-run":**
+Preview what would run without executing.
+
+**If $ARGUMENTS contains "--max N":**
+Run at most N tasks.
+
+**If $ARGUMENTS contains "--loop":**
+Run in polling mode (check queue every 60s).
+
+## Steps
+
+1. Verify prerequisites exist:
+   ```bash
+   command -v claude && command -v jq && command -v python3
+   ```
+   If any are missing, tell the user what to install.
+
+2. Check that the taskrunner script exists:
+   ```bash
+   ls ${CLAUDE_PLUGIN_ROOT}/taskrunner.sh
+   ```
+
+3. Check current queue status first:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/taskrunner.sh list
+   ```
+
+4. If queue is empty and no `--loop` flag, inform user and suggest `/taskrunner-add` to queue tasks.
+
+5. If queue has pending tasks, execute:
+   ```bash
+   bash ${CLAUDE_PLUGIN_ROOT}/taskrunner.sh $ARGUMENTS
+   ```
+
+6. After execution completes, show a summary:
+   - Number of tasks completed vs failed
+   - Links to any PRs created
+   - Any tasks that reported TASK_BLOCKED
+
+## Important Notes
+
+- Tasks run in headless Claude Code sessions — safety hooks block interactive questions, destructive operations, and production deploys
+- Each task gets its own git branch (`auto/{task-id}`) unless it has `operator` authority
+- Uncommitted work in the repo is automatically stashed and restored
+- Tasks that produce commits get automatic PRs via `gh` CLI
+- The `--dry-run` flag previews tasks without executing them
+
+## Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `CC_QUEUE_FILE` | `./queue.json` | Path to the task queue |
+| `CC_POLL_INTERVAL` | `60` | Seconds between polls in loop mode |
+| `CC_MAX_TASKS` | `0` | Max tasks per run (0 = unlimited) |
+| `CC_MAX_TURNS` | `25` | Default Claude Code turns per task |

plugins/cc-taskrunner/safety/block-interactive.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# block-interactive.sh — Blocks AskUserQuestion in unattended sessions
+#
+# PreToolUse hook: exits 2 to block, 0 to allow.
+# When Claude tries to ask a question, this forces it to decide instead.
+#
+# Copyright 2026 Stackbilt LLC — Apache 2.0
+
+INPUT=$(cat)
+TOOL=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+if [[ "$TOOL" == "AskUserQuestion" ]]; then
+  echo "BLOCKED: Autonomous mode — do not ask questions. Make a reasonable decision and document your reasoning." >&2
+  exit 2
+fi
+
+exit 0