swarm-plan

swarm-plan — Phase 5.5: decompose for parallel execution

Invoked after /approve-direction and before /tdd on any spec that has ≥ project.json → swarm.min_tasks_worth_swarming independent components worth parallelizing (default 1, so swarm is the default code-generation route). A spec whose dependency graph exposes no independent component falls through to /tdd solo.

Post-§18 amendment. Beyond the canonical .claude/state/swarm/<slug>.json plan, swarm-plan ALSO emits a runtime sub-track overlay at .claude/state/swarm/<slug>.jsonl (JSONL) when the chosen workflow track contains a selector node whose swarm-implementation alternate is chosen. The overlay's single line is a transient Track record with selectable: false, track_id: "swarm-runtime-<slug>", and nodes[] enumerating the swarm-worker dispatches as can_parallel: true peers. The harness reloads runtime overlays from .claude/state/swarm/*.jsonl at the same time it reads .claude/workflows.jsonl, so the runtime Track set is the union. The overlay is deleted by /archive along with the rest of the workflow's swarm state.

Prereqs

1. .claude/state/spec_approvals/<slug>.approval exists (spec is human-approved).
2. docs/specs/<slug>.md exists and passes /spec-lint.
3. docs/scout/<slug>.md exists (component → file mapping is its job).

If any prereq is missing, stop and surface what's needed.

Output contract

.claude/state/swarm/<slug>.json:

{
  "slug": "<slug>",
  "spec": "docs/specs/<slug>.md",
  "created_at": <epoch>,
  "status": "planned",
  "tasks": [
    {
      "id": "T-001",
      "title": "<what the task does — one line>",
      "component": "<component id from C4 Component diagram>",
      "acs": ["AC-001", "AC-002"],
      "write_set": ["src/foo/bar.py", "tests/foo/test_bar.py"],
      "read_set": ["src/common/http.py"],
      "depends_on": [],
      "execution": "worker-safe"
    }
  ],
  "waves": null
}

You produce tasks[]. The validator (validate.mjs) computes waves[] deterministically via Kahn-with-disjointness.