architecture/skills/spawn-issues/SKILL.md

---
name: spawn-issues
description: >
  Orchestrate parallel issue implementation with automated review cycles. Use when
  implementing multiple issues concurrently, or when user says /spawn-issues.
model: haiku
argument-hint: <issue-number> [<issue-number>...]
user-invocable: true
---

# Spawn Issues

@~/.claude/skills/worktrees/SKILL.md
@~/.claude/skills/gitea/SKILL.md

Orchestrate parallel implementation of multiple issues with automated PR review and fixes.

## Arguments

One or more issue numbers: `$ARGUMENTS`

Example: `/spawn-issues 42 43 44`

## Workflow

```
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 ──► ✓

Event-driven: As each task completes, immediately start next step.
```

## Process

### 1. Parse and Validate

Parse `$ARGUMENTS` into issue numbers. If empty:
```
Usage: /spawn-issues <issue-number> [<issue-number>...]
Example: /spawn-issues 42 43 44
```

### 2. Setup Repository Context

```bash
REPO_PATH=$(pwd)
REPO_NAME=$(basename "$REPO_PATH")
WORKTREES_DIR="${REPO_PATH}/../worktrees"
```

Verify in git repository:
```bash
git rev-parse --git-dir >/dev/null 2>&1 || exit 1
```

### 3. Create All Worktrees Upfront

For each issue, create worktree using script:
```bash
cd "$REPO_PATH"
worktree_path=$(./scripts/create-worktree.sh issue <ISSUE_NUMBER>)
```

Track worktree paths:
```javascript
issues = {
  42: {
    worktree: "/path/to/worktrees/repo-issue-42",
    stage: "ready",
    task_id: null,
    pr: null,
    branch: null,
    review_iterations: 0
  },
  ...
}
```

Print initial status:
```
Created worktrees for 3 issues:
  [#42] ready
  [#43] ready
  [#44] ready
```

### 4. Spawn All Issue Workers

For each issue, spawn issue-worker agent in background:

```
Task tool with:
  - subagent_type: "issue-worker"
  - run_in_background: true
  - prompt: "Implement issue #<NUMBER>

Repository: <REPO_PATH>
Repository name: <REPO_NAME>
Issue number: <NUMBER>
Worktree: <WORKTREE_PATH>

Follow the issue-worker agent instructions to implement, commit, push, and create PR.
Output the result in ISSUE_WORKER_RESULT format."
```

Track task_id for each issue and update stage to "implementing".

Print status:
```
[#42] implementing...
[#43] implementing...
[#44] implementing...
```

### 5. Event-Driven Pipeline

**Wait for `<task-notification>` messages** that arrive automatically when background tasks complete.

When notification arrives:

1. **Identify which issue/task completed:**
   - Extract task_id from notification
   - Look up which issue this belongs to

2. **Read task output:**
   ```
   TaskOutput tool with task_id
   ```

3. **Parse result and update state:**
   - If issue-worker: extract PR number, branch, status
   - If code-reviewer: extract verdict (approved/needs-work)
   - If pr-fixer: extract status

4. **Print status update:**
   ```
   [#42] Worker completed → PR #55 created, starting review
   [#43] Review: approved ✓
   [#42] Review: needs work → spawning fixer
   ```

5. **Spawn next agent if needed:**
   - Worker done → spawn code-reviewer
   - Reviewer says "needs-work" → spawn pr-fixer
   - Fixer done → spawn code-reviewer again
   - Reviewer says "approved" → mark complete

6. **Check if all done:**
   - If all issues in terminal state → proceed to cleanup

### 6. State Transitions

```
ready → implementing → reviewing → done
                     → needs-work → fixing → reviewing...
                     → (3 iterations) → needs-manual-review
      → failed → done
```

**Terminal states:** done, failed, needs-manual-review

### 7. Spawning Code Reviewer

When worker completes successfully:

**Get PR branch name from worker result:**
```javascript
branch_name = worker_result.branch
```

**Create review worktree:**
```bash
cd "$REPO_PATH"
review_worktree=$(./scripts/create-worktree.sh review <PR_NUMBER> <BRANCH_NAME>)
```

**Spawn code-reviewer agent:**
```
Task tool with:
  - subagent_type: "code-reviewer"
  - run_in_background: true
  - prompt: "Review PR #<PR_NUMBER>

Repository: <REPO_PATH>
PR number: <PR_NUMBER>
Worktree: <REVIEW_WORKTREE>

Follow the code-reviewer agent instructions to review the PR.
Output the result in REVIEW_RESULT format."
```

Update state: stage = "reviewing"

### 8. Spawning PR Fixer

When reviewer says "needs-work":

**Check iteration count:**
- If review_iterations >= 3: mark as "needs-manual-review", skip fixer
- Otherwise: increment review_iterations and spawn fixer

**Use existing issue worktree** (don't create new one):
```javascript
worktree_path = issues[issue_number].worktree
```

**Spawn pr-fixer agent:**
```
Task tool with:
  - subagent_type: "pr-fixer"
  - run_in_background: true
  - prompt: "Fix review feedback for PR #<PR_NUMBER>

Repository: <REPO_PATH>
PR number: <PR_NUMBER>
Worktree: <WORKTREE_PATH>

Follow the pr-fixer agent instructions to address feedback.
Output the result in PR_FIXER_RESULT format."
```

Update state: stage = "fixing"

### 9. Cleanup Worktrees

After all issues reach terminal state:

```bash
cd "$REPO_PATH"
./scripts/cleanup-worktrees.sh "$WORKTREES_DIR"
```

This removes all issue and review worktrees created during this run.

### 10. Final Report

Print summary table:

```
All done!

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

2 approved, 1 needs manual review
```

## Guidelines

**Event-driven execution:**
- Wait for task-notification messages
- Don't poll or check task status manually
- Process notifications as they arrive
- Pipeline each issue independently

**Worktree management:**
- Create all issue worktrees at start
- Create review worktrees on demand
- Reuse issue worktrees for pr-fixer
- Clean up all worktrees at end

**State tracking:**
- Track stage, task_id, PR, branch for each issue
- Update state when notifications arrive
- Print status after each transition

**Error handling:**
- If worker fails: mark as "failed", continue with others
- If reviewer fails: mark as "review-failed", continue
- If 3 review iterations: mark as "needs-manual-review"
- Always cleanup worktrees, even on error

**Review iteration limit:**
- Maximum 3 review/fix cycles per issue
- After 3 iterations: requires manual intervention
- Prevents infinite review loops

## Tips

- Use `cd "$REPO_PATH"` before git/worktree operations
- Scripts are in `~/.claude/skills/worktrees/scripts/`
- Agents output structured results for parsing
- Event notifications include task_id
- Print status frequently to show progress