plan

Plan Skill

Quick Ref: Decompose goal into trackable issues with waves. Output: .agents/plans/*.md + bd issues.

YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.

Loop position

Moves 3 (vertical slice decomposition) and 5 (wave validity check) of the [operating loop](../../docs/architecture/operating-loop.md). Consumes the [BDD intent issue](../../docs/templates/intent-issue.md); produces a [slice validation plan](../../docs/templates/slice-validation.md) — one slice per Given/When/Then row with a first-failing-test target, write-scope, bounded context, and ownership. Slices group into a wave only when every row of the wave-validity check passes (distinct write scopes, no shared migration/contract/CLI surface, declared integration order, owner per slice, discard path per slice). Default to sequential when in doubt — parallel waves are an optimization, not a default.

CLI dependencies: bd (issue creation). If bd is unavailable, write the plan to .agents/plans/ as markdown with issue descriptions, and use TaskList for tracking instead. The plan document is always created regardless of bd availability.

Discovery Boundary

Use the [Skill Ports and Adapters](../../docs/contracts/skill-ports-and-adapters.md) vocabulary and the [Intent-to-Loop Hexagon](../../docs/architecture/intent-to-loop-hexagon.md) for the boundary from Discovery into Plan:

| Boundary piece | Plan contract | |---|---| | Inbound port | plan_slices from BDD intent, bead, research artifact, or execution packet | | Outbound ports | persist_issue, verify_symbols, retrieve_context, seed_execution_packet | | Driving adapter | /plan skill invocation | | Driven adapters | bd, rg, .agents/findings, .agents/plans, execution-packet writer | | Context packet | slice plan, file dependency matrix, acceptance criteria, test levels | | Guard adapter | stale-scope verification, symbol verification, wave-validity check |

Executable acceptance: [references/plan.feature](references/plan.feature) — consumes Discovery output, one slice per Given/When/Then row, wave-validity gate, durable slice-validation artifact.

Flags

| Flag | Default | Description | |------|---------|-------------| | --auto | off | Skip human approval gate. Used by /rpi --auto for fully autonomous lifecycle. | | --fast-path | off | Force Minimal detail template (see Step 3.2) | | --skip-symbol-check | off | Skip symbol verification in Step 3.6 (for greenfield plans) | | --skip-audit-gate | off | Skip baseline audit gate in Step 6 (for documentation-only plans) |

Execution Steps

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

Step 0: Bead-Input Pre-Flight (Stale-Scope Gate)

When the input to /plan is a bead ID (matches pattern [a-z]{2,6}-[0-9a-z.]+) AND any of the following conditions hold, automatically run ao beads verify <bead-id> as the very first action before any other planning step:

• complexity is "full"
• the bead is older than 7 days
• the bead description was filed by a prior session (e.g., handoff-sourced, deferred, or reopened)

# Example guard — run before Step 1
if [[ "$INPUT" =~ ^[a-z]{2,6}-[0-9a-z.]+$ ]]; then
    ao beads verify "$INPUT" || true
fi

If ao beads verify reports any STALE citations, present them to the user (or log them to the execution packet in --auto mode) and ask for scope re-validation before proceeding to Step 1. Do not decompose against stale evidence.

This implements the shared stale-scope validation rule — re-validate inherited scope estimates against HEAD before acting on deferred beads, handoff docs, or prior-session plans.

Step 1: Setup

mkdir -p .agents/plans

Step 2: Check for Prior Research + Knowledge Flywheel

ls -la .agents/research/ and use Grep to find prior research. If found, read it before planning.

Then run ao search / ao lookup for prior planning patterns and apply (not just retrieve) any relevant learnings as planning constraints. Record citations with ao metrics cite --type applied|retrieved.

Read [references/pre-decomposition.md](references/pre-decomposition.md) for full flywheel-search commands, the apply-retrieved-knowledge contract, and section-evidence handling.

Step 2.1: Load Compiled Prevention First (Mandatory)

Load compiled planning rules from .agents/planning-rules/*.md (primary) and fall back to .agents/findings/registry.jsonl. Match by finding ID, applicable_when, language, literal goal-text overlap, and changed-file overlap. Cap at top 5.

Record applied finding IDs and how they changed the plan. Fail open on missing/malformed files. Read [references/pre-decomposition.md](references/pre-decomposition.md) for the full ranked-packet contract.

Active findings from .agents/findings/registry.jsonl are a fallback planning input. Every written plan must include an Applied findings: line, even when the value is none.

Step 2.2: Read and Validate Research Content

If research files exist, read the most recent one and verify it contains substantive sections (Summary, Findings, Architecture, Executive Summary, Recommendations) before proceeding. See [references/pre-decomposition.md](references/pre-decomposition.md) for the validation grep and warning behavior.

Step 2.3: Optional Strategic Duel Gate

When the plan is likely to span more than one execution session AND it contains at least one contested operator-default decision, recommend the dueling-idea-wizards route (/council --mode=debate --focus=ideas) on the strategic question before decomposition. Treat it as advisory, not a hard prerequisite: skip it for single-session plans or plans with no meaningful contested default. Evidence from the 2026-05-17 Mt Olympus run: a roughly 22 minute duel flipped 3/5 operator defaults and surfaced one already-shipped adapter bug that ordinary review and passing tests had missed.

Step 3: Explore the Codebase (if needed)

Dispatch an Explore sub-agent (Task tool) with a prompt that demands symbol-level detail: file inventory, function/method signatures, struct/type definitions, reuse points with file:line, test file locations and naming conventions, import paths. Read [references/pre-decomposition.md](references/pre-decomposition.md) for the canonical explore prompt.

Pre-Planning Baseline Audit (Mandatory)

Before decomposing, run grep/wc/ls commands to quantify files to change, sections to add/remove, LOC to modify, coverage gaps. Record commands alongside results. File size limits (800-line SKILL.md lint limit) and test fixture counts are mandatory checks. Ground truth with numbers prevents scope creep.

Read [references/pre-decomposition.md](references/pre-decomposition.md) for the bad/good examples table and the full audit recipe.

Step 3.2: Scale Detail by Complexity

Auto-select plan detail level based on issue count and goal complexity:

| Level | Criteria | Template | Description | |-------|----------|----------|-------------| | Minimal | 1-2 issues, fast complexity | Bullet points per issue | Title, 2-line description, acceptance criteria, files list | | Standard | 3-6 issues, standard complexity | Current plan format | Full implementation specs, tests, verification | | Deep | 7+ issues, full complexity, or --deep | Extended format | Symbol-level specs, data transformation tables, design briefs, cross-wave registry |

Read [references/detail-templates.md](references/detail-templates.md) for the template definitions.

Override: --deep forces Deep regardless of issue count. --fast-path forces Minimal.

Step 3.5: Generate Implementation Detail (Mandatory)

After exploring the codebase, generate symbol-level implementation detail for EVERY file in the plan. A worker reading the plan should know exactly what to write without rediscovering function names, parameters, or code locations.

Read [references/implementation-detail.md](references/implementation-detail.md) for the full