plan

---
name: plan
description: Decompose goals into issue plans.
practices:
- adr
- agile-manifesto
- pragmatic-programmer
hexagonal_role: domain
consumes:
- standards
produces:
- .agents/plans/*.md
- execution-packet.json
context_rel:
- kind: shared-kernel
  with: standards
skill_api_version: 1
metadata:
  tier: execution
  dependencies:
  - research
  - beads
  - pre-mortem
  - crank
  - implement
context:
  window: fork
  intent:
    mode: task
  intel_scope: topic
output_contract: .agents/plans/YYYY-MM-DD-*.md, beads (via bd create)
---
# 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)

```bash
# 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
```bash
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 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](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`. Opt-out: `--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)
- **Scenarios**: A Gherkin `## Scenarios` block (Given/When/Then) — **mandatory by default** for every bead (see Scenarios contract below)
- **Acceptance criteria**: How to verify it's done — emitted as a fenced YAML `acceptance_criteria` block (see contract below)
- **Test levels**: Which pyramid levels (L0–L3) this issue's tests cover

#### Gherkin Scenarios Contract (mandatory, default)

**Every bead this skill creates MUST carry an embedded `## Scenarios` block in Gherkin (Given/When/Then) — by default, without being asked.** Free-text-only acceptance is invalid (AGENTS.md: "Free-text acceptance is invalid — promote it to scenarios before work begins"). The operator never hand-specifies BDD: planning emits behavior-based acceptance as scenarios automatically.

Each bead body (and the parent epic body) carries a `## Scenarios` block of one or more scenarios:

```markdown
## Scenarios
Scenario: <behavior named as an observable outcome>
  Given <precondition / starting state>
  When <action / event>
  Then <expected observable result>
  And <additional assertion>   # optional
```

Rules:
- One scenario per distinct Given/When/Then behavior; a bead with N behaviors carries N scenarios.
- Scenarios describe **observable behavior**, not implementation steps.
- The `## Scenarios` block sits in the bead description ABOVE the `acceptance_criteria` YAML; the YAML is the machine-checkable layer, Gherkin is the behavior layer (they are complementary, not substitutes).
- A bead emitted without a `## Scenarios` block is a contract violation — promote any free-text acceptance to scenarios before creating the bead.

This is the same `## Scenarios` block the bead-embedded acceptance model expects (`scenario-hash-stability` CI gate) and that `/discovery` lifts into the execution packet.

#### Acceptance Criteria Contract (mandatory)

Every issue body MUST contain an `acceptance_criteria` fenced YAML block. The block lives BELOW the issue's `## Scenarios` block and ABOVE any "Reference" or "Notes" trailer. The parent epic body carries its own `acceptance_criteria` block (epic-level criteria); each child bead carries its own. `/discovery` STEP 6 lifts both into the execution packet under `epic_criteria` and `bead_criteria`. Canonical shape: [`schemas/execution-packet.schema.json`](../../schemas/execution-packet.schema.json) (`#/$defs/Criterion`).

The `## Scenarios` Gherkin block above is the behavior layer and is mandatory by
default for every bead; the `acceptance_criteria` YAML is the machine-checkable
layer. They are complementary, never substitutes. Every non-trivial plan and
bead body SHOULD also include the `hexagon:`
boundary block from `docs/architecture/intent-to-loop-hexagon.md` so the next
agent knows the inbound port, bounded context, adapters, context packet, and
done state.

```yaml
acceptance_criteria:
  - id: ac-<scope>.<n>
    description: "<one-line measurable statement>"
    check_type: test_pass | command_exit_zero | file_exists | grep_match | manual | council_judge | custom_rubric
    check_command: "<shell command or script path>"
    evidence_path: "<glob>"
    evidence_required: true | false
    weight: 0.0–1.0
    optional: true | false
    agent_judge: "<council:name>"  # REQUIRED only when check_type == custom_rubric
```

`agent_judge` is REQUIRED when `check_type == "custom_rubric"` — `custom_rubric` accepts free-text `check_command`, so the judge field names the council/judge that owns the verdict. The schema enforces this with an `if/then` clause; an issue body that omits it for a `custom_rubric` criterion is a contract violation, not a soft warning.

Read [references/decomposition.md](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](references/plan-document-template.md). Read [references/planning-rules.md](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` is blocked. Every `write` is an ownership claim: two same-wave tasks claiming `write` on the same file MUST be serialized (`blockedBy`) or merged. `read` conflicts with concurrent `write` but not with other reads. Include tests, docs, schemas, fixtures, generated artifacts, and Codex companion files — not just primary sources. The swarm skill's local-mode Pre-Spawn Conflict Check consumes this matrix.

Read [references/wave-matrices.md](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](references/plan-document-template.md) for the full canonical template (Context, Intent Issue, Files to Modify, Boundaries, Baseline Audit, Implementation, Tests, Slice Validation Plan, 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` to opt out). The **Intent Issue** section links the upstream [BDD intent issue](../../docs/templates/intent-issue.md) and carries its acceptance examples; the **Slice Validation Plan** section embeds the [slice-validation surface](../../docs/templates/slice-validation.md) (one slice per Given/When/Then with a first failing test, write scope, bounded context, owner), the wave-validity gate, and a roll-up acceptance table. Conformance Checks remains the machine-checkable layer — Gherkin is the behavior layer, not a replacement.

### Step 7: Create Tasks for In-Session Tracking

Read [references/task-creation.md](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 in issue bodies, cross-cutting constraint injection on the epic, wave formation via `blocks` dependencies, and the **Step 7b post-creation validation-block verification** gate.

### Step 8: Request Human Approval (Gate 2)

**Skip this step if `--auto` flag is set.** In auto mode, proceed directly to Step 9.

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

```bash
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"`** — Reads research, decomposes into 5 issues (middleware, session store, token validation, tests, docs), creates epic with 2 waves, writes plan to `.agents/plans/`.

**`/plan --auto "refactor payment module"`** — Skips approval gates, creates 3-wave/8-issue epic autonomously, ready for `/crank`.

**`/plan "remove dead code"`** — Runs quantitative audit (3,003 LOC), creates issues with exact file/LOC targets, includes deletion verification checks.

**`/plan "add stale run detection to RPI status"`** — Symbol-level detail: names exact functions, struct fields, JSON tags, test names. Implementer executes in a single pass.

See [references/examples.md](references/examples.md) for full walkthroughs.

## Troubleshooting

| Problem | Solution |
|---------|----------|
| bd create fails | Run `bd init --prefix <prefix>` first |
| Plan too large (>20 issues) | Narrow goal or split into multiple epics |
| Wave structure incorrect | Review dependencies: does blocked issue modify blocker's files? |
| Conformance checks missing | Add `files_exist`, `content_check`, `tests`, or `command` checks |

See [references/examples.md](references/examples.md) for more troubleshooting scenarios.

## Reference Documents

- [references/planning-rules.md](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](references/implementation-detail.md) — symbol-level implementation specs, test pyramid classification, verification procedures, data transformation tables, symbol verification.
- [references/decomposition.md](references/decomposition.md) — anti-pattern pre-flight, design briefs, issue granularity, conformance checks, schema strictness.
- [references/wave-matrices.md](references/wave-matrices.md) — file-conflict matrix, cross-wave shared file registry, dependency-necessity validation.
- [references/plan-document-template.md](references/plan-document-template.md) — canonical `.agents/plans/*.md` document template with baseline audit gate.
- [references/task-creation.md](references/task-creation.md) — TaskCreate/beads creation, validation-block embedding, post-creation verification.
- [references/plan-mutations.md](references/plan-mutations.md)
- [references/complexity-estimation.md](references/complexity-estimation.md)
- [references/detail-templates.md](references/detail-templates.md)
- [references/examples.md](references/examples.md)
- [references/plan-to-beads-workflow.md](references/plan-to-beads-workflow.md)
- [references/sdd-patterns.md](references/sdd-patterns.md)
- [references/templates.md](references/templates.md)