Parallel Phases

Parallel Phases

What It Does

Composite skill that executes a multi-phase plan with ≥3 total tasks or ≥2 per-phase tasks by dispatching one agent per task per wave, reconciling outcomes after each wave, enforcing phase gates (type-check, test, build), and emitting a final phase × task × result report.

Replaces: sequential walk-throughs of markdown plans, manual parallel-investigate + write loops, hand-rolled reconciliation tables.

When to Use

• Plans with ≥3 independent tasks total OR ≥2 tasks in a single phase
• Tasks involve write-work (code edits, issue closure, releases, PR merges) — not read-only investigation
• You want to avoid sequential execution bottleneck + manual outcome tracking
• Source: .claude/plans/*.md (markdown with phases + tasks), GitHub issues (via --from-issues "<query>"), or inline prompt with structured tasks

When NOT to Use

• Pure read-only investigation → use parallel-investigate
• Single task per phase → use sequential workflow or loop
• Task dependencies are complex, tightly coupled, or unknown → use orchestrate for routing

Core Patterns

Wave-based fan-out & reconciliation:

1. Phase 0 — RAG pre-flight: query knowledge graph for cached similar runs (skip if fresh run confirmed)
2. Phase 1 — Ingest: parse plan source into structured phases[] with task metadata (id, scope, dependencies, specialist, model tier)
3. Phase 2 — DAG analysis: assign tasks to waves using Kahn's algorithm; conflict-guard demotes tasks overlapping file scope to later waves
4. Phase 2.5 — Critic gate: adversarial read-only review of wave assignments for deadlocks, missed file overlaps, underestimated scope
5. Phase 3 — Pre-snapshot: capture repo state baseline (SHA, branch, issue/PR counts, release tags)
6. Phase 4 — Per-phase execution: for each wave, dispatch ALL agents concurrently, reconcile per-wave (status map), run phase gate (typecheck/test/build), advance or stop
7. Phase 5 — Post-snapshot: capture end state, compute deltas
8. Phase 6 — Reconciliation: emit phase × task × result table, state changes, deferred/blocked tasks, gate pass rate, handoff

Per-wave reconciliation status:

• DONE → advance
• DONE_WITH_CONCERNS → advance unless correctness concerns
• NEEDS_CONTEXT → re-dispatch ONCE with context; if repeats, mark BLOCKED
• BLOCKED → stop phase, write handoff

Conflict resolution: If two agents in same wave touch same file, keep smaller-task-id change; demote other to fix-wave at phase end.

Rules

1. Do NOT fan out write-agents over the same file/branch in one wave without --worktrees (use conflict-guard + worktrees to isolate)
2. Do NOT skip per-wave reconciliation — all agents must return before next wave dispatches
3. Do NOT advance past a failed phase gate (red typecheck/test/build halts the phase)
4. Do NOT inherit parent chat history into sub-agent prompts (context isolation enforced)
5. Phase gates auto-detect: package.json → npm run typecheck && npm test; Cargo.toml → cargo check && cargo test; pyproject.toml + pytest → pytest -q

Related Skills

• parallel-investigate — read-only fan-out (use when no writes)
• orchestrate — meta-router; chains to this skill when ≥3 independent tasks
• loop — sequential when tasks share state
• three-man-team — single feature (architect/builder/reviewer)
• subagent-driven-development — sequential same-session execution
• repo-state-snapshot — integrated into phases 3 & 5
• verify-before-done — optional stricter post-phase gate