/plan

name: completely:plan
description: Plan a phase or feature DIRECTLY into Beads — no PLAN.md, no markdown bridge. Runs GSD-style socratic discovery + decomposition + a goal-backward self-check, then emits a structured plan that `cmpl plan-apply` materializes as a Beads epic + worker-contract tasks + dependency waves + human checkpoints. One source of truth from the first planning act. Use to turn an idea or phase into ready Beads work.
version: 0.4.0
user-invocable: true
argument-hint: "[phase or feature]"

Plan **into Beads directly**. Do NOT write a `PLAN.md` / `STATE.md` — the plan lives in Beads.

Method (GSD methodology, Beads-first)

1. **Discover (socratic).** Ask clarifying questions ONE at a time until the goal is unambiguous; offer 2–3 approaches with trade-offs; confirm scope. If a spec is already frozen, read it instead. 2. **Decompose** into atomic tasks (2–5 min each). Each task MUST carry the worker-contract: `title` (imperative), `acceptance` (observable/testable), `design` (approach/why), `write_zone` (exact files/globs), `verify` (the proof command), `deps` (other task keys). ~2–3 tasks per unit; split if a unit exceeds ~5 tasks or ~10 files (context budget). **Also fill the context fields — the engine consumes them directly:**

• `read_context` — the exact files/interfaces the worker must READ first but won't edit

(contracts, schemas, neighbouring patterns). Injected verbatim into the worker's dispatch header, so a fresh context reads exactly this instead of guessing or scanning the tree.

• `must_haves` — the goal-backward checklist `{truths, artifacts, key_links}` the default-FAIL

evaluator grades against at VERIFY. No must_haves ⇒ the evaluator has only the acceptance line.

• `requirements` — requirement IDs this task covers (traceability), when the phase has them.

3. **Checkpoints.** Where a human must verify/decide, add `{key,title,after,how}`; make downstream tasks depend on `cp:<key>` so the wave blocks until the human closes it. 4. **Self-check (goal-backward, GSD plan-checker's 7 dimensions).** Before applying, verify: requirement coverage · task completeness (acceptance+verify present) · dependencies acyclic · artifacts wired together (not isolated) · scope within context budget · acceptance is user-observable · honors the user's frozen decisions. Fix gaps — don't apply a plan that won't reach the goal. 5. **Apply.** Emit the plan as JSON and pipe it to the materializer: `cat <<'PLAN' | cmpl plan-apply` … `PLAN`. It creates the epic + tasks + deps + checkpoints + a `bd swarm` (native waves). Then show `bd ready` and `bd swarm status`.

Plan JSON schema

`{ "epic": "...", "tasks": [ {"key","title","acceptance","design","write_zone":[...],"verify","deps":[...],"labels":[...],"read_context":[...],"must_haves":{"truths":[...],"artifacts":[...],"key_links":[...]},"requirements":[...]} ], "checkpoints": [ {"key","title","after","how"} ] }`

Rules

• Beads is the only artifact. Never persist a markdown plan.
• Every task lint-clean (acceptance + design + write_zone) — `plan-apply` + `cmpl lint` enforce it.
• One question at a time; respect a frozen spec; don't over-interrogate.