create-plan

Reading workflow files (TOC protocol)

When you Read any file under .claude/workflow/ or .claude/skills/, follow the protocol in conventions.md §1.8:

1. Read the TOC region: from <!--Document index start--> to <!--Document index end--> (read to the closing delimiter, not a fixed line count). If the file has no TOC region (a file whose only ## heading is this bootstrap block carries none, per §1.8(d)), read the file in full.
2. Match TOC rows where Roles contains any of your roles (or your role is any, or the row's Roles is any) AND Phases contains any of your phases (or your phase is any, or the row's Phases is any).
3. Use Read(offset, limit) to read only matched sections; if no row matches your role/phase, the file holds nothing for you — do not read further.

Your role: planner. Your phase: determined by the auto-resume State in workflow.md § Startup Protocol.

Inline refs you find inside workflow files carry the same name:roles:phases suffix; apply file-level filtering before opening: a ref matches when any of your roles is in its roles and any of your phases is in its phases, your own any on either axis matches every ref on that axis, and a ref whose own roles or phases is any matches you. Backtick-wrapped refs carry no suffix; open or skip them at your discretion.

Read and follow the workflow for Phase 0 (Research) and Phase 1 (Planning).

House style for chat-scale prose. User-facing prose produced from this file (status updates, escalation prompts, replanning summaries, review-mode loop turns, handoff notes, whichever apply) follows the AI-tell subset of house-style.md: ## Banned sentence patterns, ## Banned analysis patterns, ## Orientation, and ## Plain language. Structural rules (§ BLUF lead, § Structural rules for the ≤200-word section cap, § Document-shape rules (design / ADR-specific)) do not apply to chat-scale prose. See conventions.md:planner:0,1 §1.5 for the workflow-level anchor and tier mapping.

Stamp discipline. Every _workflow/** artifact this SKILL creates carries a line-1 <!-- workflow-sha: <40-char SHA> --> stamp written at creation. Direct-mutation kinds applied later by edit-design (content-edit, section-add, section-remove, section-rename, section-move, structural-rewrite, mechanics-edit, design-sync) leave the stamp untouched and preserve its line-1 position; only artifact creation, migration replay, and no-drift normalization write the stamp. The format definition, parser idioms, and the paired SHA-computation idiom this SKILL copies into its planning-transition step are anchored in conventions.md:planner:1 §1.6. Read that section for the single source of truth.

Step 1 — Read workflow documents.

Read these in order before doing anything else (do NOT ask the user anything yet):

1. .claude/workflow/conventions.md — shared formats, glossary (including the complexity axes and design gate terms), plan file structure, the §1.2 Per-axis artifact set, scope indicators, review iteration protocol
2. .claude/workflow/research.md — Phase 0 instructions: interactive research, code exploration, internet research, the research log (the durable Phase-0/1 decision ledger Phase 0 writes), transition rules

Do NOT read .claude/workflow/planning.md or .claude/workflow/design-document-rules.md yet — they are only needed when the user asks to create the plan (Step 4). Load them on demand at that point.

Resolve <dir-name>. All subsequent steps reference docs/adr/<dir-name>/_workflow/; resolve the placeholder once before running any command that uses it. If "$ARGUMENTS" is non-empty, use it. Otherwise, default to $(git branch --show-current).

Step 1.5 — Workflow drift check (mandatory, before any other on-disk work).

Ordering: this step depends on the <dir-name> resolver above being complete and Step 1b's mkdir not yet having run — see the trailing paragraph below for the gate's Skip-#1 rationale.

Invoke the drift gate defined in workflow-drift-check.md:planner:1. The gate is shared with /execute-tracks; its intro names both callers and its body is caller-symmetric, so this step is a thin orchestration handoff that defers to the gate rather than restating its detection. Run the gate's § Detection against the resolved <dir-name> from the previous block. Detection now runs the two-phase drift walk inside .claude/scripts/workflow-startup-precheck.sh under --mode full and reads the resulting drift JSON object; the script resolves the plan dir from the active branch, so no inline PLAN_DIR= bash line runs here. Follow its § Skip conditions, § No-drift normalization, and § Resolutions flow verbatim.

The three-resolution prompt fires only when drift surfaces and no skip condition matched. The user picks one:

• Migrate now — print Run /migrate-workflow from this worktree, then re-invoke /create-plan afterward. (the single instruction line per workflow-drift-check.md § Migrate now, with the /create-plan re-invocation hint appended), then end the session. Exit immediately; no on-disk work has run yet (Step 1b's mkdir, Step 2's aim prompt, and Step 5's commit and push are all downstream of Step 1.5).
• Defer — continue this session. Record the deferred-drift count via the TaskCreate todo described in workflow-drift-check.md § Defer; Step 5's deferred-drift recital reads that todo and prints the same line shape workflow.md § What to do before ending a session uses for /execute-tracks. If TaskCreate is unavailable in this session, hold the <count> and <short-stamp-base-SHA> (or the unstamped variant flag) in in-context memory instead, matching the gate file's § Defer paragraph.
• Suppress — continue this session with no recital at session end.

No-drift (with or without the gate's normalization commit), Defer, and Suppress all proceed to Step 1a without further user prompt. Ordering: Step 1.5 runs after the <dir-name> resolver (so the resolved name is available when the script's --mode full walk resolves the plan dir from the active branch) and before Step 1b's mkdir (so the script's internal Skip-#1 directory check reads the pre-creation _workflow/ state on fresh /create-plan invocations). The skip check is now internal to the script, not an inline gate-bash [ -d … ].

Interaction with Step 1a's handoff scan. Step 1.5 fires before Step 1a. On a /create-plan resume where handoff-*.md exists in docs/adr/<dir-name>/_workflow/, the drift gate fires before the handoff loader notices. No failure mode loses the handoff: on Migrate now the handoff file persists on disk (it is already committed) and the next /create-plan invocation's Step 1a picks it up after the drift gate clears; on Defer or Suppress, Step 1a's handoff resume runs after Step 1.5 in the same session. Per-session TaskCreate todos do not survive /clear, so a paused Session A's Defer state is not carried into Session B — Session B's Step 1.5 re-evaluates drift independently.

Step 1a — Handoff check (mandatory, before any other on-disk work). Run:

ls -t docs/adr/<dir-name>/_workflow/handoff-*.md 2>/dev/null

If any files exist, load mid-phase-handoff.md:planner:1 and follow its §Resume protocol BEFORE Step 1b. A previous /create-plan session paused mid-research or mid-planning and left a handoff to be re-presented. Do NOT ask for the aim, start fresh research, or write plan files until the handoff is resolved.

Step 1b — Create the workflow directory.

As the first durable action of /create-plan, ensure the workflow directory exists so research handoff files have a home if context fills up before Step 4:

mkdir -p docs/adr/<dir-name>/_workflow/plan

This is idempotent — safe to re-run on resume. The directory carries the research log, plan, design, track files, review files, and handoff files; the Phase 4 cleanup commit removes it before merge (see .claude/workflow/conventions.md §1.2).

Step 1c — Resume check (before the aim prompt).

After Step 1.5 (drift) and Step 1a (handoff) have cleared, check the design-first artifacts plus the phase ledger and the single-track glob on disk:

ls docs/adr/<dir-name>/_workflow/design.md \
   docs/adr/<dir-name>/_workflow/implementation-plan.md \
   docs/adr/<dir-name>/_workflow/phase-ledger.md \
   docs/adr/<dir-name>/_workflow/plan/track-1.md 2>/dev/null

The routing signal is the three complexity axes the ledger now carries (D10): the design gate (does a design.md exist), the plan-presence / track-count signal (how many track files the planner authored — more than one means an implementation-plan.md exists), and the Phase-1-complete marker (did Phase 1 finish cleanly). A plan-less change has no plan (D2), so implementation-plan.md presence cannot disambiguate it; the phase ledger is the signal — when the ledger records design_gate=no and the plan-presence signal is single (tracks=1), an interrupted plan-less session resumes off the ledger, with the plan/track-1.md glob as the secondary signal that the one track file was written. When the plan is present (tracks > 1), implementation-plan.md presence stays the routing signal, and the design gate is read from the ledger design_gate field, never from a plan line (the plan no longer carries a tier line; the classification moved to the ledger per D4) and never from a fresh read of the research log, which would be a third decision-content read site and break S2.

The new shape the three axes make expressible is a design with one track and no plan (design_gate=yes, tracks=1): on disk it is a design.md, no plan, and one track file — a file set identical to a mid-authoring crash that wrote design.md before deriving any plan. File presence alone cannot tell the two apart, so the Phase-1-complete marker is the disambiguator: set (phase1_complete=yes) means the design+single-track steady state (do not re-author); unset means a mid-authoring crash (re-enter Step 4a). The marker check runs first to separate "Phase 1 is done" from "Phase 1 is not done"; the existing committed-and-clean design.md check still applies within the crash arm to tell a frozen design apart from an unfrozen one.

Read the three fields from the ledger once before routing — the same last-value-wins fields the script's --append-ledger seeds at Phase 1 (conventions.md §1.1 Phase ledger):

LEDGER="docs/adr/<dir-name>/_workflow/phase-ledger.md"
# design gate (yes/no), track count (integer), and the Phase-1-complete
# marker (yes); each last-value-wins, empty if no ledger or no such line.
LEDGER_DESIGN_GATE="$(sed -n 's/.* design_gate=\([a-z]*\).*/\1/p' "$LEDGER" 2>/dev/null | tail -n 1)"
LEDGER_TRACKS="$(sed -n 's/.* tracks=\([0-9]*\).*/\1/p' "$LEDGER" 2>/dev/null | tail -n 1)"
LEDGER_PHASE1_COMPLETE="$(sed -n 's/.* phase1_complete=\([a-z]*\).*/\1/p' "$LEDGER" 2>/dev/null | tail -n 1)"

Route on what exists. Evaluate the branches in order; the first whose condition holds wins. The design.md-present branch fans out on the Phase-1-complete marker (steady state vs mid-authoring crash); the no-design branches differ from it by design.md absence. The plan-less resume branch and the fresh-start branch both describe the no-plan/no-design state, so the order matters: the more-specific plan-less resume is reached first and the fresh-start branch is the catch-all that fires only when no earlier branch matched.

• design.md exists, implementation-plan.md does not — a design.md is written (design_gate=yes) and no plan exists. Two on-disk-identical states share this signature — the design+single-track steady state and a mid-authoring crash — so check the Phase-1-complete marker first:

  • Marker set (LEDGER_PHASE1_COMPLETE = yes) — Phase 1 finished cleanly. This is the design+single-track steady state (design_gate=yes, tracks=1): the design and its one track file are the durable Phase-1 artifacts and there is no plan by derivation (a cross-track summary is vacuous for one track). This is a normal resume, not a Step-4 entry: the drift / handoff / state routing above already handled it; do not re-author the design or re-derive a plan. Proceed to Step 2 only if the user explicitly asks to start a new aim against the same dir (rare). The marker alone is sufficient by construction here: a clean Phase-1 seed co-writes phase1_complete=yes and design_gate=yes on the same line, so a set marker implies the gate and no cross-check of LEDGER_DESIGN_GATE is needed on this arm. The LEDGER_DESIGN_GATE / LEDGER_TRACKS locals parsed at the top of the step are read only by the lower no-design branches — they are intentionally unused here, not a missing check.

  • Marker unset (LEDGER_PHASE1_COMPLETE blank) — Phase 1 did not finish: the prior /create-plan invocation authored (and possibly committed) design.md but ended — crash, context-full /clear, or the user stopping the session — before the plan derivation completed and the marker was seeded. This is the crash-recovery arm. File presence alone is not proof the design is frozen: edit-design writes design.md to disk in its apply step, before the cold-read review runs and before the design commit lands. A session interrupted after the write but before the review passed leaves an unreviewed, uncommitted design.md on disk. So confirm the design is committed and clean — the on-disk proxy for "frozen and reviewed", since the Add initial design commit lands only after its review passes:

    # committed: at least one commit touches design.md
    git log -1 --format=%h -- docs/adr/<dir-name>/_workflow/design.md
    # clean: no uncommitted changes to design.md (empty output = clean)
    git status --porcelain docs/adr/<dir-name>/_workflow/design.md
    

    • Committed (non-empty git log) AND clean (empty git status) — the design is frozen and reviewed, and the prior invocation crashed between the design commit and the plan derivation. Auto-resume into Step 4b (plan derivation): skip Step 2's aim prompt and Step 3's Phase 0 research loop entirely — the aim and research are already captured in the frozen design.md and the conversation that produced it. Read planning.md (deferred from Step 1) and derive the plan from the frozen design. This crash-recovery resume reaches the same Step 4b the collapsed happy path flows into directly, so the plan derives identically whether or not the prior session was interrupted.
    • Uncommitted (empty git log) OR dirty (non-empty git status) — a session was interrupted mid-design-authoring (before the Add initial design freeze-and-commit). Resume Step 4a, not Step 4b: re-enter the edit-design review loop so the adversarial gate and cold-read pass run and the design is committed before any plan derives from it. This arm is retained by the collapse: even though the happy path no longer crosses a session boundary, a crash mid-authoring still leaves an unfrozen design.md, and re-entering Step 4a is how that state recovers. Re-entering the loop on an already-good design is idempotent and harmless, so this branch is safe even on a false alarm (e.g., a stray editor write left the file dirty).
• implementation-plan.md exists, design.md does not — a no-design multi-track change whose plan is already derived (design_gate=no, tracks > 1; a one-track change has no plan, so it never reaches this branch). The missing design.md is by derivation (design_gate=no), not a sign of an interrupted Step 4a. This is a normal resume, not a Step-4 entry: the drift / handoff / state routing above already handled it; do not re-run Step 4 and do not route to design authoring. If the ledger instead records design_gate=yes (or is absent / unreadable), a multi-track plan with no design.md is malformed (the design should have been authored and committed first) or the branch predates the ledger scheme; treat it as the Both files exist normal resume below and surface the inconsistency to the user rather than silently re-deriving. Proceed to Step 2 only if the user explicitly asks to start a new aim against the same dir (rare).
• Plan-less resume — ledger records design_gate=no and tracks=1, plan/track-1.md present, no implementation-plan.md, no design.md — a no-design single-track session whose one track file is already written (D10). The ledger, not a plan, is the resume signal here; the plan/track-1.md glob is the secondary signal that the track file landed. This is a normal resume, not a Step-4 entry: the drift / handoff / state routing above already handled it; do not re-run Step 4 and do not author a plan (a one-track change has none). Proceed to Step 2 only if the user explicitly asks to start a new aim against the same dir (rare).
• Ledger absent, plan/track-1.md present, no implementation-plan.md, no design.md — a no-design single-track Phase-1 session interrupted between the track-file write and the ledger seed (the seed runs after the track file is written; Step "Seed the phase ledger"). The durable Phase-1 artifact for a one-track no-design change is the track file, and it landed, so this is not a fresh start: re-authoring plan/track-1.md would clobber work already on disk. Resume by seeding the ledger (--design-gate no --tracks 1, plus the matched categories and any §1.7 staging mode) and continuing from the recorded state, not by re-running research, classification, or the Step-4b track-file Write. (A multi-track change cannot reach this branch: its durable Phase-1 artifact is implementation-plan.md, whose presence is matched by an earlier branch above.)
• Neither implementation-plan.md nor design.md exists, and no plan-less resume signal is present — fresh start. The "no plan-less resume signal" condition is the OR of three testable arms, evaluated against the LEDGER_DESIGN_GATE / LEDGER_TRACKS values parsed at the top of this step: the ledger is absent; OR the ledger is present but its design_gate field is empty or unreadable (LEDGER_DESIGN_GATE blank); OR the ledger records design_gate=no and tracks=1 but plan/track-1.md has not been written yet (the branch immediately above already claimed the case where the track file exists). Proceed to Step 2 (aim), then Step 3 (research), then Step 4 (the design-gate classifier + adversarial gate, then Step 4a/4b). This also covers the narrow /clear window where Step 4's gate cleared but no artifact was written yet: with no plan, no design.md, no seeded ledger fields, and no track file on disk there is no resume signal, so the resume correctly reads as a fresh start and Step 4's classifier re-runs, re-deriving the classification from the now-populated log through its existing sanctioned authoring read — no extra read site, S2 intact.
• Both files exist — the plan is already derived (a design-and-plan change with both committed); this is a normal resume, not a Step-4 entry. The drift / handoff / state routing above already handled it; do not re-run Step 4. Proceed to Step 2 only if the user explicitly asks to start a new aim against the same dir (rare); the common case is the session has nothing new to plan.

This check has a defined resume path for every artifact combination, so the "never a dead end" invariant holds for every arm. A design.md with no plan is never a dead end — with the marker set it is the design+single-track steady state (do not re-author); with the marker unset it is a crash, and the committed-and-clean check then routes a frozen design to Step 4b and an unfrozen one back to Step 4a. A derived plan resumes normally without re-entering design authoring, and a plan-less single-track session resumes off the ledger and its single track file (or, when the seed had not yet run, by seeding the ledger and continuing) rather than reading as a fresh start. The check runs after the drift and handoff gates so a pending migration or handoff resolves first (those can change what is on disk), and before the aim prompt so a Step-4b crash-recovery resume does not re-ask for an aim already captured in the design or the research log.

Step 2 — Ask the user for the aim, then seed the research log.

Skip this step when Step 1c auto-resumed into Step 4b (the aim is already captured in the frozen design.md and the research log). Otherwise, after you have finished reading the workflow documents, ask the user to describe the aim and goal for this session. Do NOT proceed until the user provides the aim. Wait for the user's response before starting any research or planning work.

Once the user provides the aim, write the research log's ## Initial request (the verbatim aim) as the first durable Phase-0 action. The _workflow/plan/ directory already exists from Step 1b (mkdir -p .../plan), so write the log directly: create docs/adr/<dir-name>/_workflow/research-log.md (a Write, not a shell command) with the six sections research.md §The research log defines: ## Initial request (the verbatim aim, written once); the empty ## Decision Log, ## Surprises & Discoveries, ## Open Questions continuous logs; ## Baseline and re-validation filled only on a workflow-modifying branch; and the empty ## Adversarial gate record the Step 4 gate appends its verdict headings to. The log is created unstamped: it is on the §1.6(f) never-stamped list (D19), so no line-1 workflow-sha comment is written and the §1.6(b) paired-idiom does not run for it. Idempotent on resume: if the log already exists (a prior Phase-0 session created it), leave its ## Initial request intact and append to the continuous logs only. The log is the agent's internal memory: seed it without narrating the seeding to the user (research.md §Rules, the Keep the research log agent-internal rule).

The plan will be saved to: docs/adr/<dir-name>/_workflow/implementation-plan.md (the _workflow/ subdir holds every ephemeral working file — research log, plan, design, track files, reviews — and is removed in the Phase 4 cleanup commit before merge; see conventions.md §1.2 and workflow.md § Final Artifacts). The codebase is at the current working directory.

Step 3 — Research phase (Phase 0).

Once the user provides the aim, enter research mode. In this mode:

• Answer user questions about the codebase, architecture, and design
• Explore code (read files, search for patterns, trace call chains)
• Perform internet research when asked (web search, fetch documentation)
• Present findings and intermediate conclusions
• Help the user evaluate trade-offs and alternatives
• Append decisions, surprises, and open questions to the research log as they settle — each entry an ISO timestamp and a [ctx=<level>] tag, each ## Decision Log entry carrying the **Why:** and **Alternatives rejected:** fields the Step-4 adversarial gate challenges (research.md §The research log for the append cadence). Do this silently: the log is agent-internal, so surface its content to the user as plain conversational prose, never as log quotes, section names, or D-numbers (research.md §Rules, the Keep the research log agent-internal rule)
• Do NOT produce plan files, design documents, or track decompositions