plan-with-docs

Plan With Docs

Use this after grilling has resolved enough uncertainty to create an implementation plan. The output is a durable feature or concept doc that the agent can resume from later.

Boundary With Grill With Docs

plan-with-docs is for writing the agreed plan, not for discovering the work's boundaries. Use it only when the important decisions are already settled enough to define scope, non-goals, acceptance criteria, verification, and implementation steps.

Do not use plan-with-docs yet if any meaningful decision is still open:

• product behavior, user workflow, or success criteria
• architecture, migration, compatibility, or data-shape tradeoffs
• scope, non-goals, rollout, or reversibility
• affected callers, docs, tests, or dependent features
• verification strategy or acceptance criteria
• the right durable doc home for the decision

When those questions remain, switch to grill-with-docs first. Ask one sharp decision question with a recommended answer, wait for the user to settle it, then return to planning.

Workflow

1. Read docs/.registry.json, docs/overview.md, relevant feature/concept docs, and relevant ADRs. For a feature or file you already know is in scope, codument context --feature <slug> / --file <path> projects the grounded slice in one deterministic read — the owning doc's orientation, its invariants with their test pointers, the primary sources, and one-hop dependencies — instead of hand-assembling those registry lookups; add --budget <tokens> to cap it (it trims tail-first and says what it dropped). Fall back to reading the registry and docs directly if the CLI is unavailable.
2. Choose the narrowest doc home:
   • Feature behavior: docs/features/{feature}.md
   • Cross-cutting model or pattern: docs/concepts/{concept}.md
   • Hard-to-reverse architecture decision: docs/architecture/decisions/{NNN}-{title}.md
3. Write or update the durable doc in the documentation standard's layers (the doc-audience-layers concept): ## In plain terms, ## Design approach, ## Invariants & boundaries, ## Decisions, ## Key files. Fill these at plan time — they are the knowledge that outlives the work, written at intent altitude (no identifiers, counts, or call order; that is mechanism and lives in code).
4. Append a transient ## Delivery Plan block — the working artifact, not durable doc content. It carries the step checklist, the Feature Map (when the plan introduces source files — see below), the Outcome, acceptance criteria, verification strategy, and open questions. It compacts out when the work ships (see Compaction on ship).
5. Mark the Delivery Plan as awaiting approval.
6. Show the delivery-plan checklist, the outcome, and the open questions inline (see Approval Summary), run the adversarial plan pass and fold its objections in, then stop and ask the user to approve or change the plan before implementation. Never make the user open the doc to see what they are approving.