Plan

$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/.

Discovery Boundary

Use the Skill Ports and Adapters vocabulary for the boundary from Discovery into Plan:

Feature: Plan converts dense intent into executable slices
  Scenario: Plan consumes Discovery output
    Given Discovery provides density fields and artifact links
    When Plan receives the `plan_slices` port request
    Then each slice has acceptance criteria, write scope, test levels, and ownership
    And no slice depends on raw Discovery chat context

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. Recommend a strategic duel when warranted. If the plan spans more than one execution session and has at least one contested operator-default decision, recommend the dueling-idea-wizards route ($council --mode=debate --focus=ideas) before decomposition. Keep it advisory, not mandatory. Skip it for single-session or non-contested plans. Evidence from the 2026-05-17 Mt Olympus run: roughly 22 min wall-clock, 3/5 operator defaults flipped, and one already-shipped adapter bug surfaced.
5. 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.
6. 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.
7. Choose detail level. Minimal for 1-2 simple issues, Standard for 3-6 issues, Deep for 7+ issues, broad refactors, or --deep.
8. 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). Feature, bug, and product-facing behavior issues also need a fenced gherkin block or a link to the upstream intent issue scenario. Non-trivial plans and bead bodies should include the hexagon: boundary block: inbound port, bounded context, adapters, context packet, and done state.
9. 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.
10. Write the plan. Use .agents/plans/YYYY-MM-DD-<goal-slug>.md and the template in references/plan-document-template.md.
11. Create tracking tasks. Prefer bd issues with validation blocks and dependency edges. If bd is missing, leave the markdown plan as the durable handoff.
12. 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/plan-to-beads-workflow.md
• references/planning-rules.md
• references/pre-decomposition.md
• references/sdd-patterns.md
• references/task-creation.md
• references/templates.md
• references/wave-matrices.md