architecture/skills/spawn-issues/SKILL.md

name, description, model, argument-hint, allowed-tools, user-invocable

name	description	model	argument-hint	allowed-tools	user-invocable
spawn-issues	Orchestrate parallel issue implementation with automated review cycles. Use when implementing multiple issues concurrently, or when user says /spawn-issues.	claude-haiku-4-5	<issue-number> [<issue-number>...]	Bash, Task, Read, TaskOutput	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

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

Verify in git repository:

git rev-parse --git-dir >/dev/null 2>&1 || exit 1

3. Create All Worktrees Upfront

For each issue, create worktree using script:

cd "$REPO_PATH"
worktree_path=$(~/.claude/skills/worktrees/scripts/create-worktree.sh issue <ISSUE_NUMBER>)

Track worktree paths:

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:

branch_name = worker_result.branch

Create review worktree:

cd "$REPO_PATH"
review_worktree=$(~/.claude/skills/worktrees/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):

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:

cd "$REPO_PATH"
~/.claude/skills/worktrees/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