Parallel Dev

# /parallel-dev

Orchestrate parallel autonomous dev sessions — dispatch multiple agents into isolated worktrees to implement GitHub issues with TDD simultaneously, then run sequential reviews. Each agent works independently in its own worktree, eliminating branch conflicts.

## Arguments

- `$ARGUMENTS` - Issue source and options. Examples:
  - `label:ready-to-build` (all open issues with this label)
  - `milestone:"v1.2"` (all open issues in milestone)
  - `#12 #15 #18` or `12 15 18` (specific issues by number)
  - `label:ready-to-build parallel:4` (with concurrency override)
  - If empty, auto-detect: scan open issues sorted by complexity (low first, then medium, skip high)
  - Options: `max:N` (default 8, hard cap 10), `parallel:N` (default 3, max 5), `sort:created-asc` (default) or `sort:created-desc`

## Instructions

### Phase 0: Queue Setup

```bash
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)

# Branch prefix for autonomous session branches
BRANCH_PREFIX="auto/"

# Default concurrency — 3 balances throughput against TypeScript build/test load
PARALLEL=3

Parse $ARGUMENTS to determine the issue source:

• Explicit list: Strip # prefixes, run gh issue view ${NUM} --json number,title,state,labels,body,assignees for each
• Label: gh issue list --label "${LABEL}" --state open --json number,title,labels,assignees --limit ${MAX}
• Milestone: gh issue list --milestone "${MILESTONE}" --state open --json number,title,labels,assignees --limit ${MAX}
• Auto-detect (empty args): gh issue list --state open --json number,title,labels,assignees --limit 20 then sort by complexity label (low first, then medium, skip high)

Extract parallel:N from arguments if present, override default. Cap at 5.

Apply sort order and cap to max (hard cap 10 — parallel sessions should be focused and well-scoped). Recommended: 3-5 issues for first use.

Filter out assigned issues — exclude issues with assignees from the working queue. Show in queue table as informational.

Check for existing branches/PRs for each issue — skip any that already have open PRs or merged branches (same resume logic as autonomous-dev-flow).

Validate the queue before starting:

• At least 1 issue must be open, unassigned, and without an existing PR
• If all matching issues are assigned, report "All N matching issues are assigned — nothing to process" and stop
• If 0 issues match, report and stop — don't start an empty session
• Show the user the queue and get confirmation

## Parallel Work Queue ({N} issues, {P} concurrent agents)

| # | Issue | Labels | Action |
|---|-------|--------|--------|
| 1 | #12 — Add retry logic to API client | enhancement | Implement (batch 1) |
| 2 | #15 — Fix login timeout | bug | Implement (batch 1) |
| 3 | #18 — Add integration tests | testing | Implement (batch 1) |
| 4 | #20 — Update error messages | enhancement | Implement (batch 2) |
| — | #16 — Refactor auth module | enhancement | Assigned to @user (skipped) |

Mode: **Parallel** ({P} agents per batch, {B} batches)
Start parallel dev session?

Wait for user confirmation. This is the ONLY confirmation point — everything after runs autonomously.

After confirmation, create task list tracking:

For each issue in work queue:
  TaskCreate: "Issue #N — <title>" with status pending

Phase 0.5: Auto-Decompose High-Complexity Issues

Before dispatching parallel agents, decompose issues that are too large.

When the queue contains issues labeled complexity:high or equivalent:

For each high-complexity issue:

0. Check for prior decomposition — scan comments for existing "Decomposed into #A, #B, #C"
1. Read the full issue body: gh issue view ${ISSUE_NUM} --json body,comments -q .
2. Break into 2-5 sub-issues, each independently implementable
3. Create sub-issues via gh issue create (same format as autonomous-dev-flow)
4. Insert sub-issues at FRONT of queue (context is fresh from reading the parent)
5. Comment on parent: "Decomposed into #A, #B, #C — each independently implementable with TDD."
6. Parent stays open until all sub-issues merge — do NOT close it

After decomposition, if total queue exceeds 10, truncate to 10.

Skip criteria — auto-skip these issues (comment on each with reason):

• Empty issue body or no identifiable acceptance criteria
• No code path (manual testing, design docs, decisions needed)
• Requires user input not present in the description
• Deployment/release tasks
• Issues labeled blocked or wontfix
• Issues requiring design decisions with multiple valid approaches not specified

Phase 1: Build Agent Prompts

Before dispatching agents, prepare everything they need.

1. Read CLAUDE.md once — store the content to embed in every agent prompt
2. Sync to latest main:

git checkout main
git pull origin main

3. Fetch each issue's full details — for each issue in the queue:

gh issue view ${ISSUE_NUM} --json title,body,labels,comments

4. Build a self-contained prompt for each agent using the Agent Prompt Template below. Each prompt must include everything the agent needs — it cannot access the coordinator's memory or other agents' state.

Phase 2: Parallel Implementation (Fan-Out)

Launch implementation agents using the Agent tool with isolation: "worktree". Each agent gets its own isolated copy of the repository — the platform handles worktree creation, branch management, and cleanup. Worktrees live under .claude/worktrees/.

Batching: If the queue has more issues than PARALLEL, process in batches:

• Batch 1: first PARALLEL agents in parallel
• Wait for all to complete
• Batch 2: next PARALLEL agents in parallel
• Continue until queue is exhausted

For each agent, launch with the Agent tool:

• Set isolation: "worktree" to give the agent its own worktree
• Pass the self-contained prompt from Phase 1
• Run as foreground calls (NOT background) so output returns directly

**I ```