| 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)
- 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.
- 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.
- 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.
- 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.
- 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.
