architecture/commands/spawn-issues.md

allowed-tools, description, argument-hint

allowed-tools	description	argument-hint
Bash, Task, Read, TaskOutput	Orchestrate parallel issue implementation with review cycles	<issue-number> [<issue-number>...]

Spawn Issues (Orchestrator)

Orchestrate parallel issue implementation: spawn workers, review PRs, fix feedback, until all approved.

Arguments

One or more issue numbers separated by spaces: $ARGUMENTS

Example: /spawn-issues 42 43 44

Orchestration Flow

Concurrent Pipeline - each issue flows independently:

  Issue #42 ──► worker ──► PR #55 ──► review ──► fix? ──► ✓
  Issue #43 ──► worker ──► PR #56 ──► review ──► ✓
  Issue #44 ──► worker ──► PR #57 ──► review ──► fix ──► ✓

As each step completes, immediately:
1. Print a status update
2. Start the next step for that issue

Don't wait for all workers before reviewing - pipeline each issue.

Status Updates

Print a brief status update whenever any step completes:

[#42] Worker completed → PR #55 created
[#43] Worker completed → PR #56 created
[#42] Review: needs work → spawning fixer
[#43] Review: approved ✓
[#42] Fix completed → re-reviewing
[#44] Worker completed → PR #57 created
[#42] Review: approved ✓
[#44] Review: approved ✓

All done! Final summary:
| Issue | PR  | Status   |
|-------|-----|----------|
| #42   | #55 | approved |
| #43   | #56 | approved |
| #44   | #57 | approved |

Implementation

Step 1: Parse and Validate

Parse $ARGUMENTS into a list of issue numbers. If empty, inform the user:

Usage: /spawn-issues <issue-number> [<issue-number>...]
Example: /spawn-issues 42 43 44

Step 2: Get Repository Info

REPO_PATH=$(pwd)
REPO_NAME=$(basename $REPO_PATH)

Step 3: Spawn All Issue Workers

For each issue number, spawn a background issue-worker agent and track its task_id:

Task tool with:
  - subagent_type: "issue-worker"
  - run_in_background: true
  - prompt: <issue-worker prompt below>

Track state for each issue:

issues = {
  42: { task_id: "xxx", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
  43: { task_id: "yyy", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
  44: { task_id: "zzz", stage: "implementing", pr: null, branch: null, review_iterations: 0 },
}

Print initial status:

Spawned 3 issue workers:
  [#42] implementing...
  [#43] implementing...
  [#44] implementing...

Issue Worker Prompt:

You are an issue-worker agent. Implement issue #<NUMBER> autonomously.

Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- Issue number: <NUMBER>

Process:
1. Setup worktree:
   cd <REPO_PATH> && git fetch origin
   git worktree add ../<REPO_NAME>-issue-<NUMBER> -b issue-<NUMBER>-<short-title> origin/main
   cd ../<REPO_NAME>-issue-<NUMBER>

2. Get issue: tea issues <NUMBER> --comments

3. Plan with TodoWrite, implement the changes

4. Commit: git add -A && git commit -m "...\n\nCloses #<NUMBER>\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"

5. Push: git push -u origin <branch-name>

6. Create PR: tea pulls create --title "[Issue #<NUMBER>] <title>" --description "Closes #<NUMBER>\n\n..."
   Capture the PR number.

7. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-issue-<NUMBER> --force

8. Output EXACTLY this format (orchestrator parses it):
   ISSUE_WORKER_RESULT
   issue: <NUMBER>
   pr: <PR_NUMBER>
   branch: <branch-name>
   status: <success|partial|failed>
   title: <issue title>
   summary: <1-2 sentence description>

Work autonomously. If blocked, note it in PR description and report status as partial/failed.

Step 4: Event-Driven Pipeline

Do NOT poll. Wait for <task-notification> messages that arrive automatically when background tasks complete.

When a notification arrives:

1. Read the output file to get the result
2. Parse the result and print status update
3. Spawn the next stage (reviewer/fixer) in background
4. Continue waiting for more notifications

On <task-notification> for task_id X:
  - Find which issue this task belongs to
  - Read output file, parse result
  - Print status update
  - If not terminal state, spawn next agent in background
  - Update issue state
  - If all issues terminal, print final summary

State transitions:

implementing → (worker done) → reviewing → (approved) → DONE
                             → (needs-work) → fixing → reviewing...
                             → (3 iterations) → needs-manual-review
           → (worker failed) → FAILED

On each notification, print status:

[#42] Worker completed → PR #55 created, starting review
[#43] Worker completed → PR #56 created, starting review
[#42] Review: needs work → spawning fixer
[#43] Review: approved ✓
[#42] Fix completed → re-reviewing
[#44] Worker completed → PR #57 created, starting review
[#42] Review: approved ✓
[#44] Review: approved ✓

Step 5: Spawn Reviewers and Fixers

When spawning reviewers, pass the PR number AND branch name from the issue worker result. Each reviewer/fixer uses its own worktree for isolation - this prevents parallel agents from interfering with each other.

Code Reviewer:

Task tool with:
  - subagent_type: "code-reviewer"
  - run_in_background: true
  - prompt: <code-reviewer prompt below>

Code Reviewer Prompt:

You are a code-reviewer agent. Review PR #<PR_NUMBER> autonomously.

Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- PR number: <PR_NUMBER>
- PR branch: <BRANCH_NAME>

Process:
1. Setup worktree for isolated review:
   cd <REPO_PATH> && git fetch origin
   git worktree add ../<REPO_NAME>-review-<PR_NUMBER> origin/<BRANCH_NAME>
   cd ../<REPO_NAME>-review-<PR_NUMBER>

2. Get PR details: tea pulls <PR_NUMBER> --comments

3. Review the diff: git diff origin/main...HEAD

4. Analyze changes for:
   - Code quality and style
   - Potential bugs or logic errors
   - Test coverage
   - Documentation

5. Post review comment: tea comment <PR_NUMBER> "<review summary>"

6. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-review-<PR_NUMBER> --force

7. Output EXACTLY this format:
   REVIEW_RESULT
   pr: <PR_NUMBER>
   verdict: <approved|needs-work>
   summary: <1-2 sentences>

Work autonomously. Be constructive but thorough.

PR Fixer Prompt: (see below)

Step 6: Final Report

When all issues reach terminal state, display summary:

All done!

| Issue | PR  | Status              |
|-------|-----|---------------------|
| #42   | #55 | approved            |
| #43   | #56 | approved            |
| #44   | #57 | approved            |

3 PRs created and approved

PR Fixer

When spawning pr-fixer for a PR that needs work:

Task tool with:
  - subagent_type: "pr-fixer"
  - run_in_background: true
  - prompt: <pr-fixer prompt below>

PR Fixer Prompt:

You are a pr-fixer agent. Address review feedback on PR #<NUMBER>.

Context:
- Repository path: <REPO_PATH>
- Repository name: <REPO_NAME>
- PR number: <NUMBER>

Process:
1. Get feedback: tea pulls <NUMBER> --comments

2. Setup worktree from PR branch:
   cd <REPO_PATH> && git fetch origin
   git worktree add ../<REPO_NAME>-pr-<NUMBER> origin/<branch-name>
   cd ../<REPO_NAME>-pr-<NUMBER>
   git checkout <branch-name>

3. Address each piece of feedback

4. Commit and push:
   git add -A && git commit -m "Address review feedback\n\nCo-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
   git push

5. Cleanup: cd <REPO_PATH> && git worktree remove ../<REPO_NAME>-pr-<NUMBER> --force

6. Output EXACTLY:
   PR_FIXER_RESULT
   pr: <NUMBER>
   status: <fixed|partial|failed>
   changes: <summary of fixes>

Work autonomously. If feedback is unclear, make reasonable judgment calls.

Error Handling

• If an issue-worker fails, continue with others
• If a review fails, mark as "review-failed" and continue
• If pr-fixer fails after 3 iterations, mark as "needs-manual-review"
• Always report final status even if some items failed