--- description: "Parallel batch coordinator for independent work units" argument-hint: "" --- # /feature-coordinate "" Parallel batch coordinator. Launches independent work units as parallel subagents, waits for completion, then launches the next batch. Only used when `execution_strategy` is `balanced` or `speed`. --- ## Step 0 โ€” Pre-flight Read `.feature//status.md`. - Verify `execution_strategy` is `balanced` or `speed`. If it is `cost` or `not-set`: ``` ๐Ÿ”€ COORDINATOR ยท โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Execution strategy is '' โ€” parallel coordination not applicable. Use /feature-test "" to start sequential execution. ``` Stop. - Read `automation_mode` from status.md. Display opening header: ``` โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ๐Ÿ”€ COORDINATOR ยท โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ ``` --- ## Step 0a โ€” Progress tracking Use TodoWrite to show progress in the Claude Code UI (visible via Ctrl+T). Each TodoWrite call replaces the full list โ€” always include all items. **The coordinator owns TodoWrite in parallel mode.** Subagents launched by the coordinator MUST NOT call TodoWrite โ€” their writes would overwrite the coordinator's checklist since only one list exists at a time. Build the checklist dynamically from the Work Units table. Include pipeline context and one item per work unit. Use `activeForm` to show which stage each active unit is in. Example for 3 units mid-batch: ```json [ {"id": "pipeline-scoping", "content": "Scoping", "status": "completed", "priority": "medium"}, {"id": "pipeline-domains", "content": "Domain analysis", "status": "completed", "priority": "medium"}, {"id": "pipeline-planning", "content": "Work planning", "status": "completed", "priority": "medium"}, {"id": "pipeline-parallel", "content": "Parallel execution", "status": "in_progress", "priority": "high", "activeForm": "Batch 1 โ€” 2 units running"}, {"id": "pipeline-pr", "content": "PR draft", "status": "pending", "priority": "medium"}, {"id": "wu-1", "content": "WU-1: Auth types", "status": "in_progress", "priority": "high", "activeForm": "implementing โ€” 4/6 tests passing"}, {"id": "wu-2", "content": "WU-2: Token store", "status": "in_progress", "priority": "high", "activeForm": "writing tests"}, {"id": "wu-3", "content": "WU-3: Middleware", "status": "pending", "priority": "high"}, {"id": "merge", "content": "Merge logs and integration tests", "status": "pending", "priority": "medium"} ] ``` Update unit items to `completed` as each subagent returns. The coordinator can update `activeForm` on in-progress units based on their per-unit status.md between batches. --- ## Step 1 โ€” Build dependency graph and display execution plan Read the Work Units table from status.md. Build the full dependency graph. **If all units are `complete`:** skip to Step 4 (merge + finalize). Compute the **critical path** โ€” the longest chain of dependent units. This determines the minimum wall-clock time regardless of parallelism. Display the execution plan: ``` โ”€โ”€ Execution plan โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ Dependency graph: WU-1 โ”€โ”€โ” โ”œโ”€โ”€ WU-3 โ”€โ”€ WU-5 WU-2 โ”€โ”€โ”˜ WU-4 (independent) Critical path: WU-1 โ†’ WU-3 โ†’ WU-5 (3 sequential stages) Max parallelism: 3 units (WU-1 + WU-2 + WU-4) Ready now: โ†’ WU-1: โ†’ WU-2: โ†’ WU-4: Waiting: โ—‹ WU-3: (needs WU-1, WU-2) โ—‹ WU-5: (needs WU-3) Previously completed: โœ“ ``` **In `speed` mode:** launch all ready units immediately โ€” no batch grouping. As each unit completes, check if new units are unblocked and launch them in the same cycle. Units start as soon as their dependencies resolve, not when an entire batch finishes. **In `balanced` mode:** group ready units into batches as before, wait for the full batch, then launch the next. This is simpler and uses fewer parallel sub-agents. --- ## Step 1a โ€” Subagent dispatch contract Every Agent call the coordinator issues to run a work unit MUST include the following termination contract in the prompt. The pipeline skills (`/feature-test`, `/feature-implement`, `/feature-refactor`) already mode-gate their AskUserQuestion sites against `execution_strategy: balanced | speed`, so subagents will chain autonomously between stages. The contract below closes the remaining hang vector: subagents that finish their work but keep taking actions instead of returning. Hang root-cause (2026-04-23): WU-3 wrote status.md = COMPLETE and all tests green, then the subagent continued running ~2 min with no further meaningful work before the user had to Ctrl+C to unblock the coordinator. The Agent tool blocks the parent until the child emits its final assistant message; there is no timeout, no polling, no "you're clearly done" signal. ### Required prompt fragments Include these verbatim (or paraphrased keeping the semantics) in every subagent prompt: ``` ## Termination contract (MANDATORY) The Agent tool call that launched you returns to the coordinator only when you emit your final assistant message. The coordinator has no timeout and cannot poll you. You MUST return to the coordinator IMMEDIATELY after: - writing units/WU-/status.md with Substage = `complete`, OR - writing an escalation entry to cycle-log.md and setting substage to `escalated-`. Your final message MUST be the single-line summary below โ€” nothing else. Do NOT run any more tools, re-verify, re-read cycle-log.md, or polish. If you catch yourself about to call another tool after marking complete, STOP and emit the summary instead. ## Return format (exactly one line) WU-: | ERROR> โ€” , , ``` ### Automation mode Every dispatched subagent prompt must explicitly set the expectation: ``` Treat automation_mode as autonomous. Do NOT pause between pipeline stages. All AskUserQuestion sites in /feature-test, /feature-implement, /feature-refactor are mode-gated against execution_strategy = balanced/speed โ€” you will not encounter an interactive prompt. If a pipeline skill would still try to open AskUserQuestion (new site added without gating), treat that as a bug: record it to cycle-log.md and return ESCALATED. ``` ### KB tendency-scan contract (MANDATORY) Rich per-unit dispatch prompts describe the work concretely (spec requirements, construct contracts, test expectations). A side-effect is that cross-cutting pipeline steps buried inside `/feature-implement` and `/feature-test` never surface into the subagent's attention โ€” the subagent runs the dispatch prompt faithfully and skips the skill's numbered steps it was nominally told to invoke. Empirical gap (2026-04-24): across a 4-WU parallel run, 0 of 4 subagents consulted `.kb/` during implementation. The Step 8 tendency scan in `/feature-implement` and the Lens B scan in `/feature-test` did not fire on any unit. Audit subsequently produced findings for patterns already in `.kb/` as adversarial-finding entries. Include the following verbatim (or paraphrased keeping the semantics) in every subagent prompt that invokes `/feature-implement` or `/feature-test`: ``` ## KB tendency-scan contract (MANDATORY) After each construct's tests pass in `/feature-implement` Step 8 โ€” and for each new test class in `/feature-test` Lens B โ€” you MUST run: bash .claude/scripts/kb-search.sh " " --kb-root .kb --top 5 For each result with `type: adversarial-finding`: - Read the entry's `applies_to` patterns and `## Test guidance` - Check your just-implemented code (or tests) against the pattern - If matched: fix proactively and re-run tests (implementation), or add a targeted test method (tests) - If not applicable: record why in a one-line note After each scan, write the substage checkpoint to units/WU-/status.md: Substage: tendency-scan-complete: patterns checked, applied Append one line to units/WU-/cycle-log.md: tendency-scan (): results / applied / skipped Budget: <30 seconds per construct, โ‰ค5 KB entries deep-read. The scan prevents re-introducing patterns already known to `.kb/`. Skipping it is a silent correctness loss, not a performance win โ€” audit will rediscover the same patterns at higher cost. ``` ### Coordinator-side verification After each subagent returns, in addition to checking status.md for `complete` vs escalation substage, the coordinator should sanity-check: - Status.md Stage/Substage matches the summary line verb (COMPLETE โ†’ `complete`; ESCALATED โ†’ `escalated-`). - If they disagree, trust status.md โ€” the canonical state is on disk. - Grep `units/WU-/cycle-log.md` for `tendency-scan (` entries. A COMPLETE unit with zero `tendency-scan` entries AND a non-empty `.kb/` is a contract violation โ€” the KB scan contract was dispatched but the subagent skipped it. Record this to the feature-level `cycle-log.md`: `tendency-scan-missing: WU- โ€” , KB present`. Do not escalate; surface this in the Step 4e token summary so the user knows KB leverage was lost for that unit. --- ## Step 2 โ€” Launch and monitor (speed mode) The coordinator runs a **completion-driven loop** instead of batch-wait: 1. **Launch** all currently ready units as parallel sub-agents (invoke `/feature-test "" --unit WU-` for each). All invocations in a single response โ€” Claude Code runs them in parallel. 2. **Monitor** โ€” as each sub-agent returns: a. **Verify working directory** โ€” run `pwd` and confirm it is the project root (not a `.claude/worktrees/` path). If in a worktree path, `cd` back to the project root before any file operations. This prevents phantom "file not found" errors after subagent completion. b. Read its `units/WU-N/status.md` to check the result. c. If refactor complete โ†’ mark `complete` in the feature-level Work Units table. d. If escalation โ†’ handle immediately (see escalation handling below). e. **Check for newly unblocked units** โ€” scan the Work Units table for any unit whose dependencies are now all `complete` and status is `not-started`. f. If new units are ready โ†’ launch them immediately as sub-agents. Display: ` โ†’ WU-: (unblocked by WU-)` 3. **Repeat** until all units are complete or blocked by escalations. This means a unit deep in the dependency chain starts as soon as its last dependency finishes โ€” it doesn't wait for unrelated units in an earlier "batch" to complete. For a graph like: ``` WU-1 (fast, 2 constructs) โ”€โ”€โ†’ WU-3 โ”€โ”€โ†’ WU-5 WU-2 (slow, 6 constructs) โ”€โ”€โ†— WU-4 (independent) ``` Batch mode would run: {WU-1, WU-2, WU-4} โ†’ wait for all โ†’ {WU-3} โ†’ {WU-5}. Speed mode runs: {WU-1, WU-2, WU-4} โ†’ WU-1 finishes โ†’ can't start WU-3 yet (needs WU-2) โ†’ WU-4 finishes โ†’ WU-2 finishes โ†’ immediately start WU-3 โ†’ WU-3 finishes โ†’ immediately start WU-5. If WU-3 only depended on WU-1, it would start as soon as WU-1 finishes without waiting for WU-2. **While sub-agents are running:** update the TodoWrite checklist with each unit's latest state by reading per-unit `status.md`: ``` "activeForm": " โ€” " ``` Examples: - `"testing โ€” writing tests (3 of 5)"` - `"implementing โ€” 4/6 tests passing"` - `"refactor โ€” 2c security"` --- ## Step 2b โ€” Launch and monitor (balanced mode) Balanced mode uses the simpler batch approach: 1. **Compute batch** โ€” find all units where status is `not-started` AND all dependencies are `complete`. Group as the current batch. 2. **Launch** all batch units as parallel sub-agents. 3. **Wait** for all sub-agents in the batch to return. 4. **Verify working directory** โ€” same as speed mode Step 2.2a. Always confirm `pwd` is the project root after subagents complete. 5. **Check results** โ€” mark completed units, handle escalations. 6. **Loop** โ€” go back to step 1 for the next batch. This is the same behaviour as before โ€” predictable batch boundaries with clear checkpoints between batches. --- ## Step 2c โ€” Stall detection Subagents can hang silently with no output or progress. The coordinator cannot set hard timeouts (Claude Code does not expose this), but it should surface staleness to the user. **Between sub-agent checks:** if a sub-agent has been running with no status.md update for an extended period, note this in the TodoWrite checklist: ``` "activeForm": "running โ€” no status update in >10m โš ๏ธ" ``` **If the user reports a stall or asks about progress:** check the unit's `status.md` for the last substage update. If the substage has not changed, advise the user: ``` โ”€โ”€ Possible stall โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€ WU-: last status update was at