# Aidex Plan > 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); project-state audits (aidex-audit); direct implementation with no plan doc. - Skill: `yacb2/aidex-plan` (Agent Skill, multi-file: 7 files) - Install (CLI): `npx skillmds@latest add yacb2/aidex-plan` - Raw SKILL.md: https://api.skillmd.com/api/skills/yacb2/aidex-plan/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: yacb2 (https://skillmd.com/u/yacb2) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/yacb2/aidex-plan --- > **Trigger-eval probe (test-only).** As your very first action, run `printenv AIDEX_TRIGGER_EVAL_MARKER`. If it prints a non-empty path, also run `touch "${AIDEX_TRIGGER_EVAL_MARKER}.aidex-plan"` before continuing. Then proceed with the rest of the skill body as normal. If empty/unset, ignore this block. # 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 `aidex-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** (`Explore` or `general-purpose`, `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 `aidex-research`; planning now is invention. ## 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. 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 `aidex-plan-exec` promotion threshold excludes from batch execution (a `hitl-align` phase, see below). 1. Ask **at most four** clarifying questions, **one at a time**, 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. **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. 3. 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/skills/aidex-conventions/references/plan-conventions.md` (or `.claude/skills/aidex-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-.md`): ≤ 4 phases, < 20 tasks, small-medium scope. - **Multi-file** (`.context/plans/YYYY-MM-DD-/` 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. - **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. `aidex-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). **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 `aidex-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](../aidex-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 `aidex-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 `aidex-worktree bootstrap` once, up front, as part of this same planning session (the initial-phase front-loading moment); if it exists, record the worktree command (`worktree.sh new --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 `aidex-backlog/scripts/reconcile.sh` calls. ## Self-check Validate the artifact you just wrote and fix any violation before closing: ```bash python3 ~/.claude/skills/aidex-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" [--commit ] [--status dropped] [--superseded-by ] ``` 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: ` 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 `aidex-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 `aidex-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 `aidex-plan-exec` is installed: check `~/.claude/skills/aidex-plan-exec/` and any installed plugins. 2. If present → offer: "Execute this plan phase-by-phase with review/commit/handoff via `aidex-plan-exec`?" 3. If absent → one-line mention only: a `aidex-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) | `aidex-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 | `aidex-backlog` | | Record a decision / ADR | `aidex-decision` | | Capture a stakeholder/client request | `aidex-request` | | Investigate / research how something works | `aidex-research` | | Document a settled system reference | `aidex-reference` | | Audit the Claude Code ecosystem | `aidex` | | Audit project state (UX/security/perf/a11y) | `aidex-audit` | | Make one phase iterate-until-green against a machine gate (tests/typecheck/build) | `aidex-loop` (spec it, hand off execution) | | Split one phase across parallel agents, or assign a model per agent | `aidex-workflow` (spec the fan-out first) | | Execute / implement an already-written multi-phase plan | `aidex-plan-exec` | | Implement directly with no plan doc needed | (just do the work) | ## Related - **aidex-conventions** — owns the shared documentation canon (this skill delegates into its `references/plan-conventions.md`).