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

```
┌─────────────────────────────────────────────────────────────┐
│                     spawn-issues                             │
│                    (orchestrator)                            │
├─────────────────────────────────────────────────────────────┤
│  Phase 1: Implementation                                     │
│  ├── Spawn issue-worker agents (background, parallel)        │
│  ├── Wait for all workers to complete                        │
│  └── Collect PR numbers from results                         │
├─────────────────────────────────────────────────────────────┤
│  Phase 2: Review Loop (for each PR)                          │
│  ├── Spawn code-reviewer (background)                        │
│  ├── Wait for review                                         │
│  ├── If needs work → spawn pr-fixer (background)             │
│  ├── Wait for fix                                            │
│  └── Repeat until approved (max 3 iterations per PR)         │
├─────────────────────────────────────────────────────────────┤
│  Phase 3: Report                                             │
│  └── Display final status table                              │
└─────────────────────────────────────────────────────────────┘
```

## 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: Phase 1 - Spawn Issue Workers

For each issue number, spawn a background issue-worker agent:

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

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

Display progress:
```
Phase 1: Implementation
Spawning issue-worker agents...
  - Issue #42: spawned (task_id: xxx)
  - Issue #43: spawned (task_id: xxx)
  - Issue #44: spawned (task_id: xxx)
```

### Step 4: Wait for Workers

Use TaskOutput to wait for each worker to complete. Parse the ISSUE_WORKER_RESULT from each output to extract:
- issue number
- pr number
- status

Build a tracking table:
```
| Issue | PR  | Status  |
|-------|-----|---------|
| #42   | #55 | success |
| #43   | #56 | success |
| #44   | -   | failed  |
```

### Step 5: Phase 2 - Review Loop

For each PR that was created successfully, run a review loop (max 3 iterations):

```
for each PR:
  iteration = 0
  while iteration < 3:
    # Spawn code-reviewer in background
    Task tool with:
      - subagent_type: "code-reviewer"
      - run_in_background: true
      - prompt: "Review PR #<PR_NUMBER> in <REPO_PATH>. Output EXACTLY:
                 REVIEW_RESULT
                 pr: <PR_NUMBER>
                 verdict: <approved|needs-work>
                 summary: <1-2 sentences>"

    # Wait for review
    Use TaskOutput to get result, parse verdict

    if verdict == "approved":
      mark PR as approved, break

    if verdict == "needs-work":
      # Spawn pr-fixer in background
      Task tool with:
        - subagent_type: "general-purpose"
        - run_in_background: true
        - prompt: <pr-fixer prompt - address feedback, commit, push>

      # Wait for fix
      Use TaskOutput to get result

    iteration++
```

Display progress:
```
Phase 2: Review
  PR #55: reviewing...
  PR #55: needs work → fixing...
  PR #55: re-reviewing...
  PR #55: approved ✓
  PR #56: reviewing...
  PR #56: approved ✓
```

### Step 6: Phase 3 - Final Report

Display final status:

```
Completed: 3 issues processed

| Issue | PR  | Implementation | Review   |
|-------|-----|----------------|----------|
| #42   | #55 | success        | approved |
| #43   | #56 | success        | approved |
| #44   | -   | failed         | -        |

Summary:
- 2 PRs created and approved
- 1 issue failed (see PR description for details)
```

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