architecture/commands/spawn-issues.md

---
allowed-tools: Bash, Task, Read, TaskOutput
description: Orchestrate parallel issue implementation with review cycles
argument-hint: <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

```bash
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: "general-purpose"
  - 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 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 Prompt

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

```
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