---
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]`:

| Flag | Purpose |
|------|---------|
| `--auto` | Skip the human approval gate for `$rpi` and other autonomous chains |
| `--fast-path` | Force the minimal 1-2 issue plan shape |
| `--deep` | Force symbol-level/deep plan detail |
| `--skip-symbol-check` | Skip symbol verification for greenfield plans |
| `--skip-audit-gate` | Skip baseline audit gate for docs-only plans |

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](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](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](references/examples.md) for full examples.

## Troubleshooting

| Problem | Response |
|---------|----------|
| bd is missing | Write the markdown plan and note that issue creation was skipped |
| Prior research is thin | Explore enough to produce file and symbol evidence |
| Same file appears in parallel issues | Serialize or merge those issues before handoff |
| Baseline audit is missing | Mark the plan incomplete unless `--skip-audit-gate` is justified |

## Reference Documents

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