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.

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/consultation.md § 8.4 (the block shape); 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). 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 "${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:

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 "${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

Related

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