architecture/skills/spawn-issues/SKILL.md

---
name: spawn-issues
description: Orchestrate parallel issue implementation with review cycles
model: haiku
argument-hint: <issue-number> [<issue-number>...]
allowed-tools: Bash, Task, Read, TaskOutput
user-invocable: true
---

# 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 and Setup Worktrees

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

# Create parent worktrees directory
mkdir -p "${REPO_PATH}/../worktrees"
WORKTREES_DIR="${REPO_PATH}/../worktrees"
```

For each issue, create the worktree upfront:
```bash
# Fetch latest from origin
cd "${REPO_PATH}"
git fetch origin

# Get issue details for branch naming
ISSUE_TITLE=$(tea issues <ISSUE_NUMBER> | grep "TITLE" | head -1)
BRANCH_NAME="issue-<ISSUE_NUMBER>-<kebab-title>"

# Create worktree for this issue
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-issue-<ISSUE_NUMBER>" \
  -b "${BRANCH_NAME}" origin/main
```

Track the worktree path for each issue.

### 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>
- Worktree path: <WORKTREE_PATH>

Process:
1. Setup worktree:
   cd <WORKTREE_PATH>

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: No cleanup needed - orchestrator handles worktree removal

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/fixers, create worktrees for them and pass the path.

For review, create a review worktree from the PR branch:
```bash
cd "${REPO_PATH}"
git fetch origin
git worktree add "${WORKTREES_DIR}/${REPO_NAME}-review-<PR_NUMBER>" \
  origin/<BRANCH_NAME>
```

Pass this worktree path to the reviewer/fixer agents.

**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>
- PR number: <PR_NUMBER>
- Worktree path: <WORKTREE_PATH>

Process:
1. Move to worktree:
   cd <WORKTREE_PATH>

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: No cleanup needed - orchestrator handles worktree removal

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>
- PR number: <NUMBER>
- Worktree path: <WORKTREE_PATH>

Process:
1. Move to worktree:
   cd <WORKTREE_PATH>

2. Get feedback: tea pulls <NUMBER> --comments

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: No cleanup needed - orchestrator handles worktree removal

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

## Worktree Cleanup

After all issues reach terminal state, clean up all worktrees:

```bash
# Remove all worktrees created for this run
for worktree in "${WORKTREES_DIR}"/*; do
  if [ -d "$worktree" ]; then
    cd "${REPO_PATH}"
    git worktree remove "$worktree" --force
  fi
done

# Remove worktrees directory if empty
rmdir "${WORKTREES_DIR}" 2>/dev/null || true
```

**Important:** Always clean up worktrees, even if the orchestration failed partway through.

## 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
- Always clean up all worktrees before exiting