Plan

---
name: plan
description: 'Use when implementation work should become a written `.context/` plan before coding starts — either multi-phase work (a feature build, a migration, a refactor spanning backend/frontend/infra) or a single scoped change where only the file list and acceptance criteria need pinning down; a triage step picks which. Fires on "create a plan for X", "let''s plan X", "I want to plan X", "we need to plan X", "plan the migration of X", "let''s build a multi-phase plan", "implement X minimally", "a small scoped change to X", "just the minimum to ship X". Not for: fixing a bug or regression, which needs a failing test (/aidex:bugfix); deferring or parking an idea for later (/aidex:backlog); ADRs (/aidex:decision), requests (/aidex:request), research (/aidex:research), or references (/aidex:reference); ecosystem audits (/aidex:aidex); project-state audits (/aidex:audit); coding without a plan doc.'
disable-model-invocation: false
allowed-tools: Bash Read Write Agent
model-policy: inherit-session
---

# Plan

Create a structured multi-step implementation plan in `.context/plans/` before
coding starts. This skill is the single-purpose entry point for **planning**;
the formatting canon lives in the shared `conventions` reference package
(not forked here).

## Triage — pick the mode before anything else

Runs on **every** invocation, before Step 0. Skip it in one line only when the user names
the mode outright ("plan this as scoped", "/aidex:plan full"). Canon:
`plan-conventions.md` §Plan mode.

The discriminator is **not size** — it is whether more than one viable design exists and
whether choosing wrong is expensive. Delegate the investigation to a **subagent**
(a read-only lookup agent: your roster's own lookup agent when one is registered, otherwise
`Explore`; never an unrestricted `general-purpose`, which carries the full tool schema for
a read; `model-policy: inherit-session` — a repo read at the session's own depth,
deliberately not pinned): it may read as much of the repo as it
needs, but its output contract is fixed — the five signals with their evidence, plus one recommended
outcome. No design sketches, no architectural alternatives. If it cannot decide from what
it read, the outcome is already `research`.

| Observable | If yes |
|---|---|
| An existing repo pattern this change repeats | scoped |
| Touches a shared contract, or an API another module consumes | full |
| Requires a migration or schema change | full |
| Reverts with a single `git revert` | scoped |
| Two or more viable designs where choosing wrong costs a rewrite | full |

Present the **evidence per signal**, then the recommendation — a bare verdict invites a
rubber stamp, which is the failure this replaces. The user ratifies or corrects in one
round. Four outcomes:

- **direct** — one file, trivial. Say so and do the work; no plan doc.
- **scoped** — go to Step 0 (scoped), below.
- **full** — go to Step 0 (full), below.
- **research** — the *how* is unknown. Hand off to `research`; planning now is invention.

**Screen gate.** When the request adds or changes a screen (anything a user sees), the
plan names `/aidex:ui-contract` as **step 0**, before any phase is written, in the scoped
and the full outcome alike, unless the request names an already-decided `ui-contract.md`
(Step 0 full, item 3: carry it over). A request that touches no screen is unaffected.

**A screen plan names the project's components, not the UI kit's** (BL-702: a plan that
said "shadcn dialog and sheet primitives" got a raw Sheet built where the project mandates
its own FormSheet):

1. The components reused / new list names, per surface (list, form, dialog, side panel,
   detail), the project's wrapper component found by reading its shared components
   directory — never only the UI-kit primitive.
2. Every impl brief for a screen lists the project's component reference and frontend
   skill under "Files to read first".
3. The brief says: a shared component missing a state (a FormFooter with no saving state)
   is reported as a finding, never worked around inside the consumer.

## Step 0 (scoped) — one confirmation round

For `mode: scoped` only. The scope **is** the file list plus the acceptance criteria, so
Step 0 collapses to a single confirm-or-correct round on exactly those two — no
four-question interrogation, and **no adversarial design pass**: that already ran, once,
at triage. If the request waives questions ("no me preguntes", "ya está todo definido",
"don't ask, just write it") there is no round at all: take the recommended answers as
confirmed, record them in the plan's Context, and write the plan in this same turn.

Then, **before saving**, run the necessity recheck in both directions — file→criterion
and criterion→file (`plan-conventions.md` §The necessity recheck). "Is this necessary?"
asked of yourself always returns yes; the paired form is falsifiable.

Write the plan with `mode: scoped` in the front-matter, exactly one phase, `**Files:**`
enumerated, `**Out of scope:**` non-empty (one line), and ≥1 machine-checkable acceptance
criterion. `validate.py` enforces all four as violations — skip Step 3's decomposition
rules below, and go straight to the Self-check.

## Step 0 (full) — Align before planning (human-in-the-loop)

Before writing any phases, establish a **shared design concept** with the user. This is the one
step that must stay human-in-the-loop: defining scope and success criteria is the judgment an
agent grading its own clarifying questions gets wrong, and it is exactly what the `plan-exec`
promotion threshold excludes from batch execution (a `hitl-align` phase, see below).

1. Ask **at most four** clarifying questions, covering:
   - **Scope** — what is in, and the boundary of this work.
   - **Success criteria** — how we'll know each phase is done (prefer machine-checkable gates).
   - **Explicit non-goals** — what this plan will deliberately *not* do.
   - **Constraints** — stack, deadlines, compatibility, anything that can't change.
   Give each question a **recommended answer** to confirm or correct, so a well-scoped request
   resolves in one or two confirmations rather than an interrogation.
   Ask questions whose answers do not depend on each other **in one round**; serialize only
   when a later question's wording depends on an earlier answer (Pocock `grilling`).
   **Spend the four on leverage, not on coverage.** The four bullets are slots the plan
   must fill, not a questionnaire to walk: ask about whatever is genuinely ambiguous,
   prioritizing the answers that would change the design, and fill the settled slots
   yourself with a recommended answer the user only has to correct. A round that asks a
   constraints question whose answer is already in the repo, and misses the one ambiguity
   that forks the architecture, has spent its budget on coverage.
2. Synthesize the answers into a **one-paragraph shared design concept** and have the user
   **ratify it** before you write phases. If the request is already unambiguous and the
   recommended answers all stand, a single "confirm this concept?" round is enough.
   Closing the round is synthesis of what was already said: reflect it back, do not open a
   new interview (Pocock `to-spec`). A resolved answer gets its own decision or reference
   artifact only if it passes the three gates in `artifact/references/02-local-first-artifacts.md`
   § 8.4; otherwise it stays in this paragraph.
3. **A decided `ui-contract.md` is ratification.** When the request names a
   `ui-contract.md` (or the consultation that wrote one, `/ui-contract` Step 0), read it
   first: its level, reference screen, components, state matrix and variants are already
   ratified, so ask only what is still open, and carry the file into the plan's
   `## UI contract` section rather than re-asking it.
4. Skip Step 0 only for a trivial, already-fully-specified plan — and say you're skipping it, and why.

## Workflow

1. Read the plan conventions canon:
   `${CLAUDE_PLUGIN_ROOT}/skills/conventions/references/plan-conventions.md`
   (or `.claude/skills/conventions/references/plan-conventions.md` if a
   project-level copy exists).
2. Decide the structure per that canon:
   - **Scoped** (`mode: scoped`): always single-file, exactly one phase. The rest of
     this step does not apply.
   - **Single-file** (`.context/plans/YYYY-MM-DD-<feature>.md`): ≤ 4 phases,
     < 20 tasks, small-medium scope.
   - **Multi-file** (`.context/plans/YYYY-MM-DD-<feature>/` with `00-index.md`):
     5+ phases, 20+ tasks, multi-layer (backend + frontend + infra), or phases
     executed by different sessions/teammates.
3. Follow the template in the canon — **plans are specs, not scripts** (canon
   §Philosophy). Write the artifact in English (canon §Language). The authoring
   rules that matter:
   - **Carry the Step-0 ratified paragraph verbatim** into the plan's **Design
     concept** slot, plus **Non-goals** — that layer is the plan's durable core.
   - **Optional `## Open decisions`** (canon §Open decisions): one line per still-open
     decision, each naming its unblocker as `research`, `prototype` or
     `owner conversation`. Omit it when the design is settled; never for a scoped plan.
   - **Per phase: Goal + Acceptance** (2–4 observable behaviors, ≥1
     machine-checkable) **+ a machine gate**. Per task: Files + Spec (intent,
     pattern anchor, discovered constraints). **Do not pre-write implementation
     code** — literal code only in a **Contract** block where the exact text IS
     the spec (signatures, schemas, DDL, invariants). Anchor with symbol names,
     never bare line numbers.
   - **`afk-impl` phases declare `tests: unit | api | component | e2e | none`**
     (`none` needs a written reason) and name the single acceptance test that
     closes the phase, at that layer — write it **before** the implementation
     so it starts red; unit tests continue alongside it. `plan-exec`
     keeps that acceptance test red until the phase's gate passes.
   - **Investigate while planning and record the evidence**: the constraints and
     landmines you discover (existing patterns to mirror, cache/hash seams,
     dead code paths) go in each task's Spec — that investigation, not code, is
     what detailed planning is for.
   - **Proportionality**: every line must pass the removal test ("would the
     executor get this wrong without it?"). Small plans collapse to Goal +
     acceptance + phase list + gates. Soft budgets: single-file ≤ 8 KB, phase
     file ≤ 6 KB (Execution log excluded).
   - **A plan that touches a screen** carries a `## UI contract` section from
     `/ui-contract` (in `00-index.md` when multi-file) — that heading is what makes
     `plan-exec` hold its phases to the UI evidence gate. A heading or a bold lead-in
     that NAMES the section ("UI contract" in a title's first words) marks the plan UI;
     a mention in prose does not. The rule lives in the check script's header.
     **A UI plan orders skeleton, review, then primitives**: the skeleton of the real page
     and the owner's review of it come before any shared primitive is built, then the
     gallery and gate, then the wiring (`/ui-contract` Step 3b owns the shape).
   **Decompose by vertical slices first** (each phase a thin end-to-end piece of
   behavior across layers), not by layer — slices are independently testable and let
   the executor parallelize. Reserve layer-ordering for genuine ordering constraints,
   and push back on a layer-only first phase (see canon §Phase organization). Mark each
   phase's real prerequisites with `depends_on: [...]` (omit/`[]` = independently
   grabbable) so `plan-exec` can choose parallel vs sequential execution, and
   give any depended-on phase a **Contract** block dependents can rely on.
4. **Front-load the autonomy surface** so execution needs no questions (see
   [autonomy-conventions.md](../conventions/references/autonomy-conventions.md)).
   This is the place to resolve every gate up front: which planned **migrations /
   dependency changes** exec may run autonomously (additive ones are autonomous by
   default — flag any destructive migration, which stays gated), any **deploy /
   publish / release** the user pre-authorizes for the run, and anything to keep in
   `deny`. Record it as a short **Autonomy** note in the plan so `plan-exec`
   runs start-to-finish without interrupting.
5. **Capture the isolation surface** if the plan could run parallel to other work.
   Check whether `.context/worktrees/00-index.md` exists in the target project: if it
   does not, invoke `worktree bootstrap` once, up front, as part of this same
   planning session (the initial-phase front-loading moment); if it exists, run
   `check-overview.sh` on it and repair stale script paths (e.g. the retired
   `aidex-worktree` skill path) first, then record
   the worktree command (`worktree.sh new <slug> --branch <branch>`, `--no-infra` only
   when the plan runs no services and touches no DB) as the plan's **Isolation** note. It is a recommendation the **user / project CLAUDE.md
   authorizes** (native worktree entry is opt-in). If the plan is not parallel to
   anything, omit this — just a branch.
6. Save under `.context/plans/` with the dated naming the canon specifies.
7. **Register it in the plans index.** Run the reindexer so the new plan shows up
   in the roll-up state of all plans (`.context/plans/00-index.md`):

   ```bash
   bash "${CLAUDE_SKILL_DIR}/scripts/reindex-plans.sh"
   ```

   `00-index.md` is **auto-generated** from each plan's front-matter (do not
   hand-edit). It mirrors the backlog `00-index.md` pattern: active plans grouped by
   `## Doing` / `## Open`, closed plans rolled up from `_archive/`. `close-plan.sh`
   regenerates it automatically on close; this create-time call keeps it fresh on
   creation. Re-run it any time with `reindex-plans.sh`; `reindex-plans.sh --check`
   reports drift read-only (no write) and is what the shared `backlog/scripts/reconcile.sh` calls.

## Self-check

Validate the artifact you just wrote and fix any violation before closing:

```bash
python3 ${CLAUDE_PLUGIN_ROOT}/skills/conventions/scripts/validate.py --type plans
```

If the project carries a ratchet baseline (`.context/.validate-baseline.json`),
a non-zero exit means you introduced a NEW violation — fix it before closing.

## Closing a plan

When a plan completes (or is superseded/dropped), close it atomically rather than
hand-editing `status` — this stamps `updated`, records resolving commits where the
work happened (D-09), and archives the plan to `plans/_archive/` (D-10):

```bash
bash "${CLAUDE_SKILL_DIR}/scripts/close-plan.sh" <slug> [--commit <sha>] [--status dropped] [--superseded-by <type/ref>]
```

It refuses to archive a plan that still carries an **unreconciled in-text deferral** —
a line reading "carry this to Phase 7", "follow-up", "should note" with no `BL-NNN` and
no explicit `CLOSE: <reason>` on it. Prose is not a mechanism: a deferral written that
way would vanish with the plan when it archives. Register what is outstanding
(`register-item.sh --origin plan`) or write the `CLOSE` line; `--force` is for a line
that is prose *about* deferring.

After closing, run the shared `backlog/scripts/reconcile.sh` to surface upstream backlog items /
audit findings this plan resolved that may now be closeable (closure propagation).

## Offer to execute (multi-phase plans only)

After writing a plan with **≥ 2 phases**, offer phase-by-phase execution via
`plan-exec` (review → commit → handoff between phases). Single-phase or
trivial plans skip this — do not add noise. A `mode: scoped` plan is one phase by
construction, so it never reaches this step.

1. Detect whether `plan-exec` is installed: check `${CLAUDE_PLUGIN_ROOT}/skills/plan-exec/`
   and any installed plugins.
2. If present → offer: "Execute this plan phase-by-phase with review/commit/handoff
   via `plan-exec`?"
3. If absent → one-line mention only: a `plan-exec` skill exists for running
   multi-phase plans, if they want to install it.

## Boundaries

| The user wants to… | Route to |
|---|---|
| Fix existing behavior that is wrong (a bug, a regression) | `bugfix` — it owns RED-first + regression test. A scoped plan is *new* behavior, minimally delivered; if there is something to reproduce, it is a bugfix, not a scoped plan |
| Defer / park / shelve an idea for later | `backlog` |
| Record a decision / ADR | `decision` |
| Capture a stakeholder/client request | `request` |
| Investigate / research how something works | `research` |
| Document a settled system reference | `reference` |
| Audit the Claude Code ecosystem | `aidex` |
| Audit project state (UX/security/perf/a11y) | `audit` |
| Make one phase iterate-until-green against a machine gate (tests/typecheck/build) | `loop` (spec it, hand off execution) |
| Split one phase across parallel agents, or assign a model per agent | `workflow` (spec the fan-out first) |
| Execute / implement an already-written multi-phase plan | `plan-exec` |
| Implement directly with no plan doc needed | (just do the work) |

## Related

- **conventions** — owns the shared documentation canon (this skill
  delegates into its `references/plan-conventions.md`).