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.

CLI dependencies: bd (issue creation). If bd is unavailable, write the plan to

.agents/plans/

Flags

--auto

/rpi --auto

--fast-path

--skip-symbol-check

--skip-audit-gate

Execution Steps

Given

/plan <goal> [--auto]

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

When the input to

/plan

[a-z]{2,6}-[0-9a-z.]+

ao beads verify <bead-id>

• 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

--auto

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/

Then run

ao search

ao lookup

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

.agents/findings/registry.jsonl

applicable_when

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

Applied findings:

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

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:

--deep

Read references/detail-templates.md for the template definitions.

Override:

--deep

--fast-path

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 contract: file inventory table, per-section implementation specs (function signatures, reuse points, inline code blocks, struct fields, CLI flag definitions), named test functions with pyramid levels, verification procedures, data transformation mapping tables, and symbol verification.

Step 3.6: Symbol Verification (Mandatory)

See the Symbol Verification section in references/implementation-detail.md. For each symbol cited in the plan, grep the codebase to verify it exists. If >20% of cited symbols are stale, WARN (do not block) and log them under

## Stale Symbol Warnings

--skip-symbol-check

Step 4: Decompose into Issues

Analyze the goal and break it into discrete, implementable issues. For each issue define:

• Title: Clear action verb (e.g., "Add authentication middleware")
• Description: What needs to be done
• Dependencies: Which issues must complete first (if any)
• Acceptance criteria: How to verify it's done
• Test levels: Which pyramid levels (L0–L3) this issue's tests cover

Read references/decomposition.md for: anti-pattern pre-flight, design briefs for rewrites, issue granularity rules, operationalization heuristics, conformance checks, and schema strictness pre-flight.

Step 5: Compute Waves

Group issues by dependencies for parallel execution:

• Wave 1: Issues with no dependencies (can run in parallel)
• Wave 2: Issues depending only on Wave 1
• Wave 3: Issues depending on Wave 2
• Continue until all issues assigned

Planning Rules Compliance (Mandatory Gate): After computing waves, fill in the Planning Rules Compliance checklist (PR-001 through PR-007) in the plan document — see the table in references/plan-document-template.md. Read references/planning-rules.md for detection questions and evidence. Every rule MUST have an explicit justification or N/A rationale. If any row has an empty Justification column, mark the plan output as INCOMPLETE and do not proceed to Step 5.5.

Step 5.5: File Dependency Matrix (MANDATORY)

Before writing the plan document, produce an explicit file-level dependency matrix mapping each task to every file it reads or writes (columns: Task, File, Access=read/write, Notes). This matrix is the input to the swarm pre-spawn conflict check — without it, handoff to

/swarm

write

write

blockedBy

read

write

Read references/wave-matrices.md for the full file-conflict matrix format, an example table, cross-wave shared file registry, generated-artifact companion scope, and dependency-necessity validation rules.

Step 6: Write Plan Document

Write to:

.agents/plans/YYYY-MM-DD-<goal-slug>.md

Read references/plan-document-template.md for the full canonical template (Context, Files to Modify, Boundaries, Baseline Audit, Implementation, Tests, Conformance Checks, Verification, Issues, Execution Order, Planning Rules Compliance, Post-Merge Cleanup, Next Steps) and the Baseline Audit Gate (BLOCK if missing, WARN if incomplete,

--skip-audit-gate

Step 7: Create Tasks for In-Session Tracking

Read references/task-creation.md for the full TaskCreate + beads creation workflow, including: persistent beads issues for ratchet tracking, embedding conformance checks as fenced

validation

blocks

Step 8: Request Human Approval (Gate 2)

Skip this step if

--auto

USE AskUserQuestion tool:

Tool: AskUserQuestion
Parameters:
  questions:
    - question: "Plan complete with N tasks in M waves. Approve to proceed?"
      header: "Gate 2"
      options:
        - label: "Approve"
          description: "Proceed to /pre-mortem or /crank"
        - label: "Revise"
          description: "Modify the plan before proceeding"
        - label: "Back to Research"
          description: "Need more research before planning"
      multiSelect: false

Wait for approval before reporting completion.

Step 9: Record Ratchet Progress

ao ratchet record plan 2>/dev/null || true

Step 10: Report to User

Tell the user:

1. Plan document location
2. Number of issues identified
3. Wave structure for parallel execution
4. Tasks created (beads issue IDs or file-backed task refs)
5. Next step:

   /pre-mortem

   for failure simulation, then

   /crank

   for execution

Key Rules

• Read research first if it exists
• Explore codebase to understand current state
• Identify dependencies between issues
• Compute waves for parallel execution
• Always write the plan to

  .agents/plans/

Examples

/plan "add user authentication"

.agents/plans/

/plan --auto "refactor payment module"

/crank

/plan "remove dead code"

/plan "add stale run detection to RPI status"

See references/examples.md for full walkthroughs.

Troubleshooting

bd init --prefix <prefix>

files_exist

content_check

tests

command

See references/examples.md for more troubleshooting scenarios.

Reference Documents

• references/planning-rules.md — seven compiled planning rules (mechanical enforcement, external validation, feedback loops, separation, process gates, cross-layer consistency, phased rollout).
• Shared stale-scope validation rule — re-validate inherited scope estimates against HEAD before acting on deferred beads, handoff docs, or prior-session plans. Invoked by Step 0 via

  ao beads verify

  .
• references/implementation-detail.md — symbol-level implementation specs, test pyramid classification, verification procedures, data transformation tables, symbol verification.
• references/decomposition.md — anti-pattern pre-flight, design briefs, issue granularity, conformance checks, schema strictness.
• references/wave-matrices.md — file-conflict matrix, cross-wave shared file registry, dependency-necessity validation.
• references/plan-document-template.md — canonical

  .agents/plans/*.md

  document template with baseline audit gate.
• references/task-creation.md — TaskCreate/beads creation, validation-block embedding, post-creation verification.
• references/plan-mutations.md
• references/complexity-estimation.md
• references/detail-templates.md
• references/examples.md
• references/sdd-patterns.md
• references/templates.md