Spawn Bead Workers

# Bead Worker Orchestration

Spawn parallel subagents for dependency-ready beads with full enriched context.

## Critical Rules

- **Maximum 3 parallel implementers** — HARD LIMIT. Never spawn a 4th implementer while three are still in flight. If more than 3 beads are ready, queue the extras and spawn them as slots free up. Auditors/verifiers are read-only and do NOT count against this cap.
- **Only spawn implementers for enriched beads** — every bead must have an `Implementation Context` block in its notes before dispatch.
- **Never more than one build-guardian at a time** — one per wave, sequential, after all beads and per-bead auditors resolve.

## Skill dependencies (source of truth — do NOT re-inline)

This command orchestrates around three skills that hold the authoritative prose. Reference them; never duplicate their content here.

- [`bead-wave-orchestration`](../skills/bead-wave-orchestration/SKILL.md) — wave lifecycle: the 3-implementer cap, per-bead auditor cascade, wave-end verification chain (cross-bead-integration-verifier → architecture-auditor → build-guardian), failure handling, retry rules, epic completion sweep.
- [`implementer-prompt-template`](../skills/implementer-prompt-template/SKILL.md) — canonical implementer subagent prompt: bead-first read, refusal protocol for unenriched beads, TDD, pre-close checklist (kill vitest, lint, targeted tests, `bd close`).
- [`agent-discovery`](../skills/agent-discovery/SKILL.md) — dynamic discovery and matching of auditor/verifier agents. Primary entry points used here: `match-agents.sh auditor` (per-bead) and `discover-agents.sh {auditor,verifier}` (epic-completion sweep).

## Overview

1. Read the epic structure and implementation context from bead notes (populated by `/analyze-bead`).
2. Confirm ready beads are enriched; enrich any that aren't before spawning implementers.
3. Spawn implementers (max 3 parallel) per `implementer-prompt-template`; cascade per-bead auditors via `agent-discovery` as each closes.
4. Run the sequential wave-end chain; run ONE build-guardian per wave.
5. Cascade to the next wave; repeat until no ready beads remain; run the epic-completion sweep.

## Prerequisites

- Epic has been analyzed: epic notes contain structure overview and leaf beads contain implementation context.
- OR: Run `/analyze-bead <epic-id>` first to populate bead notes.
- Load the `epic-bead-workflow` skill.

## Process

### PHASE 1: Load Epic Analysis

IF an epic ID is provided:
1. Load the epic: `bd show <epic-id>`.
2. Check that notes contain an "Epic Analysis" section.
3. If missing, offer to run `/analyze-bead` first.

IF no epic ID provided:
1. List open epics: `bd list --status=open --type=epic`.
2. Ask which epic to orchestrate.

### PHASE 2: Confirm Ready Beads (Initial Enrichment Gate)

```bash
bd show <epic-id>   # hierarchy
bd ready            # unblocked beads

For each ready leaf bead, run bd show <bead-id> and sort into enriched (notes contain Implementation Context) vs. unenriched (missing). The deterministic check is bash .claude/skills/bead-state-assessment/bd-enrichment-check.sh <bead-id> — exit 0 means enriched, exit 1 means not.

Enrichment gate (REFUSE to start if any targeted bead lacks Implementation Context). If any ready or user-selected bead is unenriched:

1. Report the list of unenriched beads to the user.
2. Spawn a general-purpose enrichment subagent that populates notes following /analyze-bead Phase 4. Enrichment does NOT count against the 3-implementer cap and does NOT count as a retry (see bead-wave-orchestration).
3. Wait for enrichment to complete. Re-run the enrichment check. Do NOT spawn implementers until every targeted bead is enriched.

Display the enriched, ready beads and let the user proceed, select a subset, or adjust.

PHASE 3: Spawn Implementers

Reference: bead-wave-orchestration "Wave lifecycle → 2. Spawn implementers" for the full cap/queue semantics; implementer-prompt-template for the canonical prompt the Task tool must render (verbatim — do not paraphrase) when dispatching each implementer.

Spawning rules (invariants):

• If ≤ 3 enriched beads remain: spawn all in one parallel Task batch.
• If > 3: spawn the first 3, queue the remainder; pop into slots as earlier implementers close. HARD LIMIT: 3 parallel implementers.
• Never spawn an implementer for an unenriched bead (the refusal protocol in the template is a belt-and-braces backstop; the Phase 2 gate is the primary enforcement).

PHASE 4: Monitor & Per-Bead Audits

Reference: bead-wave-orchestration "Wave lifecycle → 3. Per-bead auditor cascade".

As each implementer closes (via bd close):

1. Collect the bead's changed file list (typically git diff --name-only over the implementer's commit, falling back to the bead's Files to Modify).
2. Pipe the list into bash .claude/skills/agent-discovery/match-agents.sh auditor. This is the ONLY source for auditor selection — do not maintain a hardcoded list.
3. Spawn every matched auditor in a single parallel Task batch. If an auditor's description accepts a spec path, pass Spec: {spec_path}.
4. Auditors are read-only and run concurrently with other implementers and each other; they do NOT count against the 3-slot implementer budget.
5. Apply auditor verdicts per review-mode-auditor: PASS proceeds; PASS WITH WARNINGS is recorded in the wave summary; FAIL returns findings to the implementer for a single retry round.

PHASE 5: Handle Failures

Reference: bead-wave-orchestration "Failure handling" for the full recovery protocols. Invariants this command preserves:

• Unenriched-bead refusal from implementer — spawn a general-purpose enrichment subagent scoped to just that bead, then r