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. Consumes the BDD intent issue; produces a slice validation plan — 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 vocabulary and the Intent-to-Loop Hexagon for the boundary from Discovery into Plan:

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

Flags

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

Read 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 for the full