name: plan description: 'Decompose goals into issue plans.'

$plan - Issue-Ready Decomposition

Quick ref: turn a goal or research artifact into .agents/plans/*.md, optional bd issues, dependency waves, file ownership, and validation checks.

Execute this workflow. Do not only describe it. Keep planning separate from implementation. A finished plan should let $crank, $implement, or a future Codex session execute without chat-only context.

Inputs And Flags

Given $plan <goal> [--auto]:

If bd is unavailable, still write the markdown plan in .agents/plans/.

Workflow

1. Pre-flight stale bead scope. If the input is a bead ID and the work is full-complexity, older than 7 days, or inherited from another session, run ao beads verify <bead-id> before decomposition. Do not plan against stale citations without revalidation.
2. Set up artifacts. Create .agents/plans/ and locate prior research, handoffs, findings, planning rules, and relevant .agents/ history.
3. Load prevention context. Prefer .agents/planning-rules/*.md; fall back to .agents/findings/registry.jsonl. Treat active findings as hard planning context. Record applied finding IDs in the plan with an Applied findings: line, even when the value is none.
4. Explore only as needed. If prior research does not provide enough file and symbol detail, inspect the codebase or dispatch a bounded explorer. Demand file inventory, symbol names, reuse points with file:line, test locations, and package/import relationships.
5. Baseline audit. Mechanically count the current state before making quantitative claims: files, sections, LOC, tests, fixtures, schemas, and any SKILL.md files near size limits. Record commands and results.
6. Choose detail level. Minimal for 1-2 simple issues, Standard for 3-6 issues, Deep for 7+ issues, broad refactors, or --deep.
7. Decompose into issues. Each issue needs title, file ownership, dependencies, acceptance criteria, test levels, and at least one mechanical conformance check (files_exist, content_check, command, tests, or lint).
8. Compute waves. Group independent issues by dependency. Serialize or merge same-file writes. Include generated artifacts, docs, schemas, fixtures, Codex companions, manifests, and hash markers in ownership. Generated Artifact Companion Scope is mandatory: list every touched file, including tests, docs, schemas, fixtures, runtime copies, parity manifests, hash markers, and generated Codex artifacts. If skill behavior or runtime UX changes, include bash scripts/refresh-codex-artifacts.sh --scope worktree in verification.
9. Write the plan. Use .agents/plans/YYYY-MM-DD-<goal-slug>.md and the template in references/plan-document-template.md.
10. Create tracking tasks. Prefer bd issues with validation blocks and dependency edges. If bd is missing, leave the markdown plan as the durable handoff.
11. Approval gate. Skip only with --auto; otherwise ask whether to proceed, revise, or return to research.

Required Plan Sections

Every non-trivial plan must include:

• context and applied findings
• files to modify
• boundaries and non-goals
• baseline audit evidence
• issue list with acceptance criteria and validation
• execution order/waves
• file dependency matrix
• file-conflict matrix
• cross-wave shared file registry when applicable
• planning rules compliance
• verification commands
• next steps

Read references/plan-document-template.md for the canonical shape.

Codex Guardrails

• Keep WHAT and HOW distinct; do not implement while planning.
• Prefer concrete file paths, symbol names, and validation commands over long narrative.
• Treat Codex companion files as part of the same issue when skill behavior or runtime UX changes.
• If a plan changes a schema with additionalProperties: false, put schema work before consumers in an earlier wave.
• If an acceptance criterion cannot be checked mechanically, mark it underspecified before handing it to execution.

Examples

User says: $plan "add rate limiting" Produce a plan with file inventory, issues, validation, and wave order.

User says: $plan --auto ".agents/research/auth.md" Use the research as input, write the plan, create tracking tasks when possible, and skip the approval gate.

Read references/examples.md for full examples.

Troubleshooting

Reference Documents

• references/complexity-estimation.md
• references/decomposition.md
• references/detail-templates.md
• references/examples.md
• references/implementation-detail.md
• references/plan-document-template.md
• references/plan-mutations.md
• references/planning-rules.md
• references/pre-decomposition.md
• references/sdd-patterns.md
• references/task-creation.md
• references/templates.md
• references/wave-matrices.md