codument: Skill for Claude Code

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.

Before lifecycle commands, run the session compatibility check from work-step: the actual codument --help must list work and verify. Repair a mismatch before recording approval; do not substitute older commands or manual checkpoints. Reuse a completed session check.

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 or dependencies whose treatment requires an unapproved behavior or architecture choice
• 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/overview.md and the relevant docs and ADRs. Ground known paths together with one codument context --paths <paths...> query; use --feature <slug> when the feature is known instead. Reuse this planning context during implementation and refresh the affected working set when discoveries or routing changes make it stale. Single-file queries remain useful for ad-hoc ownership questions. Read docs/.registry.json when editing or assessing the whole map, or when the CLI is unavailable. --budget <tokens> is a soft target: optional context can be trimmed, but selected contracts may exceed it and must not be silently discarded.
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. New plans default to Approval-Model: outcome-v1 in its header, alongside Status: awaiting approval and an optional Plan-ID. Include nonempty direct-child ### Outcome, ### Constraints & non-goals, ### Acceptance evidence, and ### Verification sections. Keep the milestone checklist in this selected block; Scope, Feature Map and implementation notes guide routing and cannot hide executable milestones. Sibling or historical plans cannot supply the contract. It compacts out when the work ships.
5. Show the delivery-plan checklist and approval contract 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. Compact verified cleanup uses its approval exception below.
6. After explicit human approval, change only that plan to exact Status: approved, run codument work approve --plan <path> (with --plan-id for an identified section), and stage the plan with docs/.approvals.json. Outcome approval binds promised milestones, outcome, constraints, acceptance evidence and verification; routing updates do not renew it. Existing approvals remain legacy and file-bound unless the human explicitly renews approval to adopt outcome-v1. Never silently add the model to an approved legacy plan. Checkbox and Resume checkpoint updates do not renew approval; frontmatter and another plan's approval authorize nothing.