Agent Skills: Dev Workflow

Dev Workflow

Usage

/dev-workflow --init                                     # Project setup (detect check/test commands)
/dev-workflow [--fast|--deep] [--executor <value>] <task>                # Execute workflow (default)
/dev-workflow --resume <state-file> [--fast|--deep] [--executor <value>] # Resume next subtask from a decomposition state file

Prerequisites

Per-skill detail is in references/prerequisites.md; the bold-label one-line summaries below are the index. Source of truth: references/prerequisites.md; keep the two in sync.

• Reviewer skill (reviewer setting, default: ask-peer): Required for plan/code review (Step 3 / Step 8); one of ask-peer / ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy. On a Skill() failure, retry once, then present the three-option fallback prompt (switch reviewer / self-review / pause at the gate) — the one Prerequisites skill whose fallback is a user gate.
• rules-review skill: Required for Step 7.5. On failure (after one retry) skip Step 7.5 naming the Step 8 reviewer as a lightweight backup, and append rules-review unavailable (rules compliance review) to bundle_skills_unavailable.
• extract-rules skill: Required for the Step 11 rule update. On failure (after one retry) Step 11 skips its extraction work and proceeds without it; the fallback + ledger append are defined at Step 11 sub-step 3's extract-rules-unavailable fallback.
• Cleanup skill (Step 6 Tidy): Built-in simplify preferred, bundled Skill(tidy) fallback (and a both-unavailable skip that appends tidy unavailable (cleanup fallback) to bundle_skills_unavailable). No user gate; "available" = the observable call outcome.
• prose-polish skill (Step 4 plan-body polish + Step 6.5 Polish Prose): Refines resolved-language prose; both call sites gated by polish_prose (default true). On failure (after one retry) skip-and-continue without a user gate.

Configuration

Settings files (YAML frontmatter only, merged across layers):

1. ~/.claude/dev-workflow.local.md — User global defaults (lowest priority)
2. .claude/dev-workflow.md — Project shared settings (git tracked, team-shared)
3. .claude/dev-workflow.local.md — Personal overrides (gitignored, highest priority)

Merge strategy per key type (summary — the canonical operational definition, including the null/empty-clears and absent-inherits rules, is the Step 1: Load Settings sub-step 1 Overlay procedure, in references/step1-load-settings.md § Sub-step 1 — Overlay / merge procedure; keep the two in sync):

• Scalar (reviewer, code_review, subagent_model, implementation_executor, interactive_commits, commit_review_gate, polish_prose, custom_instructions, language): higher layer wins (replaces) when the key is present; an absent key inherits from lower layers. The map-valued scalar subagent_model ({<tier>: <model>}) is the same class — a higher layer's map replaces the lower layer's wholesale (no per-key cross-layer merge), and an absent map key falls to its default at resolution time (sonnet for trivial / simple, inherit for moderate / complex)
• List (check_commands, boundary_check_commands): append — lower-layer items first, then higher-layer items, duplicates removed (keep first occurrence)
• List-replace (test_commands): higher layer's list replaces lower layer's list as a whole (no item-level merge or dedup). Defaults to ["Skill(run-tests)"] when unset
• hooks: deep-merge at the hooks level — each sub-key (on_complete) is merged as a list (append, deduplicated)

Keys absent from a higher layer inherit from lower layers. Only specify keys you want to override or extend.

---
reviewer: "ask-peer"
code_review: true
subagent_model:
  trivial: sonnet
  simple: sonnet
implementation_executor: "main"   # main | subagent | ask-claude | ask-codex | ask-gemini | ask-copilot | ask-agy
interactive_commits: true
commit_review_gate: "diff"   # diff | crit
polish_prose: true
custom_instructions: "Always use TDD. Write tests before implementation."
language: "ja"
check_commands:
  - "pnpm run lint:fix"
  - "pnpm run format"
  - "pnpm run typecheck"
boundary_check_commands:          # default none; run as each Build order step's boundary is recorded
  - "lefthook run pre-commit"
test_commands:
  - "Skill(run-tests)"
hooks:
  on_complete:
    - "Skill(work-complete)"
self_retrospective:
  feedback: "owner/repo"        # or "/abs/path", "~/rel", "./rel"
workability_retrospective:
  enabled: false                # opt-in (experimental); Step 11.6 project-tooling retrospective
  backlog_dir: ".claude/improvements"
---

Per-key detail is in references/configuration.md; the bold-label one-line summaries below are the index. Source of truth: references/configuration.md; keep the two in sync.

• reviewer: Reviewer skill name (default ask-peer; one of ask-peer / ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy — unsupported values fall back to ask-peer).
• Run mode: not a config key — the plan-review phase is chosen per invocation from the run mode (§ Mode Detection), together with the assessed tier. There is no plan_review key.
• code_review: Whether Step 8 (Code Review) runs at all — a single pass plus one Critical-triggered escalation pass when it does (default true; a non-boolean warns and falls back to true).
• subagent_model: {tier: model} map governing the model of the workflow's Agent dispatches + propagated Model: args; built-in default {trivial: sonnet, simple: sonnet} (moderate / complex inherit); resolved once at Step 1.5's tier resolution, and re-resolved only when a tier escalation changes the tier.
• implementation_executor: Who executes Step 5 work units — main (default) / subagent / ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy; --executor overrides. Experimental.
• interactive_commits: Whether Step 10 Interactive Commits and the Step 11 rule-update commit gate run (default true). Also gates Step 5's Build-order boundary chain (sub-step 2.5), whose recorded objects only Step 10 consumes.
• commit_review_gate: Code-diff review surface — diff (default) / crit; Step 10's per-commit gate is one consumer.
• polish_prose: Whether the two prose-polish passes (Step 4 plan-body + Step 6.5) run (default true).
• custom_instructions: Free-form development instructions applied across planning / implementation / review / tidy (.claude/rules/ and explicit user requests take precedence). Optional.
• language: Output language for this skill's user-facing prose (resolution: merged config → ~/.claude/settings.json language → default ja). See references/localization.md § Localization granularity. Its Self-application paragraph applies here too; a site with no language note of its own is not exempt.
• check_commands: Static checks (lint / format / typecheck); all run in order during Step 7.
• boundary_check_commands: Shell commands run in order as each Build order step's boundary object is recorded, so what they rewrite lands in that step's own tree (default none — no command runs).
• test_commands: Skill(<name>) entries run sequentially during Step 7 (default ["Skill(run-tests)"]).
• hooks.on_complete: Skills (Skill(<name>)) or shell-command strings run as Step 9 (default none).
• self_retrospective.feedback: Destination (GitHub owner/repo, or a local / / ~/ / ./ / ../ path) for the Step 11.5 bundle-skill improvement signal; unset → Step 11.5 is not registered.
• Agent tool usage: Direct Agent-tool subagent spawns happen at three fixed infrastructure dispatch sites per run — Step 7's two concurrent background launches (initial-pass rules-review + initial-pass code review), and the shared session scan (one dispatch covering the rule-extraction / self-retrospective / workability axes, performed once by whichever of Step 11 / Step 11.5 / Step 11.6 dispatches first — the host step varies across runs but the site count does not; see references/session-scan.md). One further site is per-project rather than per-run: when hooks.on_complete names review-class entries, Step 9 dispatches them concurrently through Agent + run_in_background (references/step9-completion-hooks.md sub-step 1). Beyond these, two conditional delegations may fire: Step 2 MAY delegate read-only codebase research (Step 2 sub-step 3's "Codebase-research delegation"), and Step 5 MAY delegate a settled implementation unit (optional under the default implementation_executor: "main"; the default route per qualifying unit under "subagent"; the external-CLI executor values route the same work through named Skill(ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy) instead, adding no new Agent site — Step 5 sub-step 2). subagent_model propagation: every one of these sites — the three fixed ones and both conditional delegations, the Step 2 research delegation included, but not the Step 9 hook dispatch (excluded) — passes the Step 1.5-resolved subagent_model as the Agent model (omitted when inherit). All other steps delegate to named skills (Skill(ask-peer), Skill(run-tests), Skill(rules-review), Skill(simplify) / Skill(tidy), Skill(prose-polish), etc.) and must not invoke Agent directly (the two delegations and the Step 9 hook dispatch above are the only sanctioned exceptions). Named-skill callees that are not Agent spawns and do not count against the three fixed sites: the Step 3 / Step 8 inline reviewer (subagent_model rides its Skill(<reviewer>) Model: arg), Step 6's tidy fallback (rides Skill(tidy)'s Model:), and Step 6.5's / Step 4's prose-polish file-mode callees (which receive no propagated model). The Step 4 visual plan-review gate and Step 10's commit_review_gate: crit gate each launch their external process via background Bash (run_in_background), not the Agent tool — see references/visual-plan-review.md / crit-commit-review.md — so neither is a subagent dispatch and neither counts against the three fixed sites.
• workability_retrospective: enabled (default false; experimental) gates Step 11.6; backlog_dir (default .claude/improvements) holds the "save to backlog" disposition's candidate files.

Phase naming in user-facing output

Step 1–Step 11.6 and the Step 8-1 / Step 8-2 code-review pass rows are internal identifiers. Never let a bare identifier stand alone in anything the user reads: chat prose, status lines, gate prompts, skip notes, ledger records, the Completion summary, and the task rows themselves. Pair it with what that phase does, or drop the number and name the phase. The test is one question: could the reader recover the meaning from this line alone? Take the name from Step 1 sub-step 7's phase registration list — the single authority — minus any bracketed suffix or parenthesized registration condition that list carries (Step 7: Check / Test [check: … | test: …] yields the name Check / Test; Step 10: Interactive Commits (only if …) yields Interactive Commits), and falling back to the phase's own ### heading for a phase the list omits (Step 1, Step 1.5, Completion). Render Step N (Name) in prose and Step N Name inside a ledger record. A task-row subject instead keeps the registration list's Step N: Name colon form — including Step 7's bracketed command suffix, but not the parenthesized registration condition (Step 9: Completion Hooks / Step 10: Interactive Commits, never … (only if …)) — because every later "mark Step 7.5: Rules Compliance Review completed" / "resolve that Step's task by subject via TaskList" instruction matches on that exact string. Sites that already pair the two (Step 6 Tidy) need no change. Two carve-outs sit outside that authority: inside an existing parenthetical, use the space form (品質ゲート（check_commands / Step 7.5 Rules Compliance Review）); and a drop the number label authored in a reference file that sibling workflows also read (Check / Test:, the rule-update phase) is that file's own wording rather than a name derived from this list. This governs output only — the identifiers this file uses in its own cross-references follow their own number-plus-stable-descriptor rule.

The parenthesized prose form takes the resolved language's own parentheses, and the paired name keeps the registration list's English wording on every language — only the drop the number form names the phase in the resolved language's own words — except a bundle_skills_unavailable record's <context>, which stays English on every language. Paired bilingual sample (runtime rendering demonstration):

• language: ja: Step 7.5（Rules Compliance Review）
• language: en: Step 7.5 (Rules Compliance Review)

Dispatch authorization

This skill's procedure dispatches subagents, so invoking the skill is the request to use that mechanism: an ambient instruction allowing subagent dispatch only when the user asked for it — a permission-shaped restriction — is already satisfied by this invocation. Do not ask the user to re-confirm the dispatch, and do not silently substitute inline execution for a dispatch this procedure specifies. Only two things justify that substitution: technical availability (the dispatch tool is not present and callable on the current tool surface), and an explicit contract term from the caller bounding this skill to its own thread. A permission-shaped restriction is neither.

Mode Detection

• --init → Init Mode
• --resume <state-file> → Execution Mode (Resume sub-mode; see Step 1.5: Task Decomposition)
• Otherwise → Execution Mode (Normal sub-mode)

--fast and --deep are Execution Mode modifiers, not further branches here — each combines with either Normal or Resume sub-mode, and each is ignored under --init. They are the two ends of one run mode axis (fast / normal / deep), resolved into run_mode at Step 1 sub-step 4. Passing both is a fatal error — the two ask for opposite things, so the workflow halts with a diagnostic naming both flags rather than picking one. What each value changes: deep and normal differ in the plan-review phase and in nothing else, while fast turns that phase off and additionally trades the passes named at the read sites references/step1-load-settings.md § Sub-step 4's run_mode row closes its list at.

--executor <value> is also an Execution Mode modifier, not a fourth branch here — it combines with either Normal or Resume sub-mode, is ignored under --init, and overrides the resolved executor for that run per § Configuration's implementation_executor bullet.

Init Mode

Read references/init-mode.md and follow the procedure.

Note: Skills generated by --init (e.g. run-tests) are recognized from the next session onward. Do not run /dev-workflow <task> in the same session as --init.

Execution Mode

No-Stall Principle

Once the workflow has started (after Step 1.5 (Task Decomposition) resolves the effective task), it must run to Completion without pausing, except at the explicit user-gate points enumerated below. Every other step — including every skill invocation, every no-op outcome, every "nothing to report" result — must be judged semantically by the agent and passed through automatically. Do not rely on exact-phrase matching; if the skill result reads as a successful completion (fixes applied, no changes needed, no violations, no new rules, or any equivalent "success / no-op" outcome regardless of wording), treat it as success and proceed to the next step.

Explicit user-gates (the only permissible pause points):

Each bullet names the gate and points to the authoritative definition site. When editing either the enumeration or the definition, update both together — including when the two sit in different files.

• Step 1.5 task-decomposition proposal dialogue — yes / adjust / no confirmation (Normal sub-mode; references/task-decomposition-normal.md § B. Normal sub-mode)
• Step 1.5 leftover-subtask picker dialogue — pick which runnable leftover in_progress subtask to run (Resume sub-mode; references/task-decomposition-resume.md § A. Resume sub-mode)
• Step 4 plan approval (Step 4: Finalize Plan) — a browser-based structured review is the plan-approval surface on every tier but Trivial, where the chat approval is the surface directly; the browser gate returns approve / rewrite-approach / fallback, and its submit is a harness-tracked background boundary (proceed on the process's exit notification, not a "type continue" pause). The browser surface emits no § User-gate summary preamble — the chat approval it degrades to does. Defined in references/visual-plan-review.md (the browser gate) and references/step4-finalize-plan.md's Run the approval gate bullets (the routing, the Trivial-tier route, and the chat approval)
• Step 5 probe → real-implementation user-observation gate — when the Plan stages a probe / intermediate-artifact step before its real-implementation replacement, hold at the boundary until the user signals observation completion; fires conditionally (Step 5's "User-observable artifact protection gate at probe → real-implementation boundary" paragraph, references/step5-implement.md)
• Step 7 pre-execution scope-narrowing stop — a repo-wide auto-fix check_commands entry + unrelated existing changes + narrowing infeasible → stop and ask (run full-width / skip / alternative scoped invocation) (Step 7: Check / Test)
• Step 7 scope-drift stop — check_commands writes non-trivial changes outside the task-scope snapshot → warn and wait (trivial whitespace/comment-only formatting on ≤ 5 lines attributable to the formatter/linter proceeds automatically with a one-line note) (Step 7: Check / Test)
• Step 7 check/test fail-stop — failure after 3 retries: report and stop (an error-stop, not a user-decision pause) (Step 7: Check / Test)
• Step 7.5 persistent-violations decision — rule violations still present after the 2nd rules-review cycle. The gate's body is Step 7.5 (Rules Compliance Review)'s sub-step 3(d) — which is what names it — but the initial Step 7.5 pass never reaches it: it is fired only by the callers that references/step7.5-rules-compliance.md's "Who continues into (b)–(d)" paragraph marks continues
• Step 8 unresolved-findings decision — reviewer-reported actionable findings still unresolved once Step 8's passes have settled (Step 8: Code Review)
• The finish phase's gates — every gate that can fire only after the Step 8.5 → Step 9 boundary, enumerated in references/finish-phase.md § Gates and loaded with that file at that boundary, before any of them can fire. That section is the continuation of this closed list, not an open-ended pointer: no gate exists outside the two halves, and that boundary is what decides which half a gate belongs to — add a new gate here when it can fire before it, there when it cannot.

Fatal errors are out of scope for this principle: configuration-file absence, malformed state file, irrecoverable skill / tool failures, and similar infrastructure-level errors halt the workflow with a diagnostic regardless of whether they appear in the list above.

At any point not listed above — including every sub-skill return, and including collecting the background rules-review result (Step 7.5 sub-step 1) and the background code-review result (Step 8 sub-step 1), both launched in Step 7 — the agent must never wait for the user to say "continue" / "続けて". Semantic judgment of the returned result is sufficient. Likewise, the Step 4 visual gate's wait for the browser submit is a harness-tracked background boundary — proceed on the background serve.mjs process's exit notification without asking the user to "continue".

No standalone waiting turns at async dispatch boundaries. After handing work to a host-tracked background process (a run_in_background Agent dispatch, the Step 4 visual gate's serve.mjs wait, the Step 10 per-commit crit review wait when commit_review_gate: "crit", or any other completion-notified worker), yield immediately and wait for the completion signal — do not emit a content-free "waiting for the background task — I'll continue when it reports back" turn, and do not repeat such a turn while the result is still pending. At most one brief acknowledgement immediately after dispatch is permitted, and only when it carries new information; every turn after that until the completion notification arrives must carry a concrete tool call. When the harness re-invokes the agent before that notification arrives (e.g. a scheduled keep-alive restart) with no new information since the last turn, still issue the required tool call (reissue the same wait/monitor action) but omit any acknowledgment or status prose — a no-new-signal restart is not a decision moment.

No-summary turn at review-return boundaries. When a reviewer or sub-skill returns a result that is semantically "nothing actionable" (no findings, no violations, no changes needed — regardless of the exact wording or the length of the response), the immediately next turn must begin with a tool call (a TaskUpdate to mark the pass as completed, or the next step's invocation), not with a prose summary of the review outcome. Category-by-category verdict lists, conclusion paragraphs, and "shall I proceed?" sentences are the stall pattern — emit them only in the Completion summary (the ### Completion section that runs after the retrospective steps, Step 11.5 / Step 11.6), never at review-return transition boundaries. This applies to every callee that returns a nothing-actionable result: the reviewer skills (Skill(ask-peer) / Skill(ask-claude) / Skill(ask-codex) / Skill(ask-gemini) / Skill(ask-copilot) / Skill(ask-agy)) reporting no actionable findings at Step 3 or Step 8, Skill(simplify) / Skill(tidy) / Skill(prose-polish) reporting no changes, Skill(rules-review) no violations, Skill(extract-rules) no new rules at Step 11, Skill(run-tests), and any other sub-skill whose result is treated as success — whether returned inline or collected from a Step 7 background launch.

Callee verdict transcription is not a turn boundary. When any sub-skill this workflow dispatches returns a fenced JSON verdict, status token, or structured summary, and the orchestrator's response re-transcribes that block (verbatim or paraphrased) in its own output, the transcribed block does not end the orchestrator's turn. The same agent must immediately issue the next tool call in the same turn — the next sub-step's invocation, the next iteration's dispatch, the next phase's transition, the next Step's first tool call. Specifically forbidden: inserting a "shall I proceed?" sentence after the transcribed verdict; emitting "ここまでで一区切り" / "ここまでで完了です" prose summaries between the verdict and the next action; ending the response on the verdict block and waiting for the user to say "continue" / "続けて". Sub-step completion prose ("Step 7.5 (Rules Compliance Review) complete", "(d) verify-diff returned converged") follows the same rule: completion reports in prose are not turn-end signals; the next sub-step's first tool call must follow in the same turn.

Progress Visibility

Before any subagent-backed skill call (Skill(<name>) — run-tests, ask-peer, simplify, tidy, prose-polish, rules-review, extract-rules) or any shell command expected to take ≥ 30 seconds, emit a brief status message naming what is starting (e.g. "Starting test run via run-tests…", "Calling ask-peer for the plan review pass…"), as prose in the same assistant turn that issues the tool call, not a separate preceding turn. After the step returns, proceed immediately to the next step per the No-Stall Principle (no separate acknowledgment turn). Step 7's background rules-review / code-review Agent dispatches each emit their status line here; collecting those results later (Step 7.5 sub-step 1 / Step 8 sub-step 1) is a non-stalling return-boundary — proceed without an acknowledgment turn.

Mid-chain visibility (chained sub-skill calls or extended interpretation between tool calls). When a phase issues sub-skill calls in a chain or spans extended interpretation / preparation across multiple tool calls, also emit a "current-location" line at semantic checkpoints between dispatches — one short sentence naming the current phase and the next action ("Finished verify-diff for Finding 1; next: skill-review polish on the same file"). Three constraints keep it from re-introducing stall: (a) emit it as prose in the same turn as the next tool call, never a standalone turn awaiting input; (b) content is current phase name + next action only — no review-result summaries, decision rationales, or "shall I proceed?" sentences; (c) it does not apply to short same-turn chains completing inside one turn — only to phases where the gap between user-visible signals would otherwise span multiple turns.

Workflow artifacts (cross-step fixed exclusion)

Files this workflow creates and maintains as in-session state — plan documents under .claude/plans/, decomposition state files written by Step 1.5 / Step 10 / Step 11.6, backlog files written by Step 11.6 under workability_retrospective.backlog_dir, the Step 4 visual-gate served / comments / URL / prev / figures files (.claude/plans/<slug>.plan-review.md / .plan-review.comments.json / .plan-review.url / .plan-review.prev.md / .figures.md), the Step 11 rule-extraction candidate file (.claude/plans/<slug>.rule-candidates.md), and other workflow-internal staging artifacts under .claude/ — are cross-step fixed exclusions from any per-step changed-file enumeration (Step 6 Tidy scope, Step 6.5 Polish Prose scope, Step 7.5 rules-review diff input, Step 10 commit grouping, sub-skill dispatch payloads, scope checks). The exclusion is structural — not gated on .gitignore presence, formatter-ignore alignment, or whether the user is touching them this run. Every step that builds a changed-file set, diff-scope set, or commit grouping applies this single shared exclusion. Extend this canonical list when a new in-session-state path appears, rather than threading the exclusion through per-step prose.

Step 1: Load Settings

1. Read settings from up to three layers (~/.claude/dev-workflow.local.md → .claude/dev-workflow.md → .claude/dev-workflow.local.md, lowest → highest priority) and merge type-aware per key (the per-class merge semantics are summarized in § Configuration's "Merge strategy per key type" paragraph). The full overlay / merge procedure is in references/step1-load-settings.md § Sub-step 1 — Overlay / merge procedure.

2. If none of the three files exist, prompt user to run /dev-workflow --init and stop

3. Resolve reviewer from config. If not specified or not in the supported list (ask-peer, ask-claude, ask-codex, ask-gemini, ask-copilot, ask-agy), use ask-peer. Reviewer-family classification: Claude-family = ask-peer / ask-claude — model-controllable (ask-peer via its Model: argument applied to its internal Agent dispatch; ask-claude via the claude -p --model flag); external-CLI = ask-codex / ask-gemini / ask-copilot / ask-agy — not subagent_model-controllable (never receive a propagated model). Initialize the bundle-unavailability ledger here: set bundle_skills_unavailable = []. Records are short human-readable strings, e.g. <skill> unavailable (<context>); § Completion's bundle-skill availability reminder renders the list verbatim. <context> names what the callee was for, never a step number (§ Phase naming in user-facing output's "drop the number" option). Each of the five dev-workflow-bundle sibling skills this workflow depends on (ask-peer, rules-review, extract-rules, tidy, prose-polish) appends at most one record per call site per run, the first time that site's unavailability is declared; prose-polish is the only one with two call sites (Step 4 and Step 6.5) and may append one record for each. Probe the resolved reviewer's availability immediately — the default ask-peer is an independently-installable sibling, not guaranteed present just because dev-workflow is: attempt Skill(<reviewer>) with a one-word probe, retry once on failure; on persistent failure append ask-peer unavailable (reviewer, plan / code review) to bundle_skills_unavailable only when the reviewer is ask-peer, then emit the three-option prompt from § Prerequisites' "Reviewer skill" bullet — do not block the run. Full procedure: references/step1-load-settings.md § Sub-step 3 — reviewer availability probe.

4. Resolve the run mode and the review phases — set run_mode from this invocation's flags (--fast → fast, --deep → deep, neither → normal; both flags: see § Mode Detection), then derive plan_review_enabled and plan_review_scope from it, and code_review_enabled from config code_review. code_review is a boolean defaulting to true; a present non-boolean warns and falls back to true. plan_review_enabled and code_review_enabled are the only control over whether Step 3 (Plan Review) and Step 8 (Code Review) run; plan_review_scope selects the shape of Step 3's single pass (references/step3-plan-review.md sub-step 1's Review scope branch). Each phase, when enabled, is a single pass (Step 8 additionally takes one deterministic escalation pass on Critical findings — see Step 8's escalation-pass paragraph). Step 1.5's tier resolution may lower either to false on the Trivial tier, and both Step 4's rewrite-approach and a tier escalation may re-derive them. Source of truth: references/step1-load-settings.md § Sub-step 4 — review-phase resolution, which holds the run_mode derivation table and the full lifecycle; keep in sync with this summary. A resolved false is a valid outcome, not a validation failure: it routes the phase to the same skip the Trivial tier produces (see Step 3's and Step 8's disabled-phase exception paragraphs).

5. Parse the remaining config keys and emit the Language checkpoint (Output language: <lang>). The full parse detail — hooks / custom_instructions / interactive_commits / commit_review_gate / implementation_executor (+ the --executor override) / polish_prose / subagent_model / language (config → ~/.claude/settings.json → default ja, then the checkpoint note) / self_retrospective.feedback (+ the gh auth status early-warning for owner/repo) / workability_retrospective — is in references/step1-load-settings.md § Sub-step 5 — Parse remaining config keys. Each key's default and invalid-value fallback is canonical in its own § Configuration bullet.

6. Determine execution sub-mode: Resume if --resume <state-file> was provided, otherwise Normal. Step 1.5 branches on this. Every later fast-mode condition reads run_mode == "fast", resolved at sub-step 4. Initialize the cross-step variables in the table below here — for each of them this sub-step is the single init site, and the table is the single source of truth for its lifecycle. (Cross-step state deliberately initialized elsewhere: bundle_skills_unavailable at sub-step 3, run_mode / plan_review_enabled / plan_review_scope / code_review_enabled at sub-step 4, and Step 7's launch / stale flags at every Step 7 entry per its Flag lifecycle contract.)

   | Variable | Init | Lifecycle | |---|---|---| | difficulty_skipped_steps / fast_mode_skipped_steps | [] / [] | Ledgers of rows a tier / fast-mode skip marked completed, written by references/tier-assessment.md § Row marking and rendered by § Completion's difficulty-skip and fast-mode-skip reminders. Each stays [] when nothing is skipped | | subagent_model | inherit | The pre-resolution value; inherit means every downstream Agent dispatch and Model: propagation omits the model. references/tier-assessment.md § Resolution procedure resolves this and both ledgers above | | review_fix_files | [] | The set of repo-relative paths edited by any workflow fix applied from the first review layer's fix sub-step onward (path-independent). Accumulation window opens at Step 7.5 sub-step 3(a) — or, when the difficulty-skip matrix pre-completed Step 7.5 on Simple so it never runs, at Step 8 sub-step 3; fixes before that point are excluded. Append sites (closed list): Step 7.5 sub-step 3(a) (rules-compliance fixes), Step 8 sub-step 3 (code-review fixes), any fix applied while resolving Step 8 sub-step 4's unresolved-findings gate, and both of Step 8.5 (Deferred Verification)'s gates (its check/test gate's test-failure fixes, and its scoped rules-review's sub-step (a)). Read sites (closed list): Step 8.5's two gate conditions plus its gate-2 Files: scoping (references/step8-code-review.md § Deferred verification — gate 2 scoped rules-review detail, which reads the set on both the invocation and the sub-step (c) 2nd-cycle re-run), and references/code-review-payload.md § Sub-step 1 — reviewer report payload's .claude/rules/ safety-net bullet, which weights the reviewer's rules check when the set is non-empty. Stays [] when neither review layer applies a fix | | implementation_boundaries | [] | Ordered list of {heading, object} — one entry per Build order step whose boundary object Step 5 sub-step 2.5 recorded (references/step5-implement.md § Sub-step 2.5 — Build-order boundary chain). Appended there; read by references/interactive-commits.md § Propose commit plan, which takes its chain-absent path when the list is empty. Stays [] when interactive_commits is false (sub-step 2.5 does not run), and is reset to [] if any boundary build fails | | session_scan_dispatched / session_scan_result | false / null | Shared session-scan state (references/session-scan.md § Dispatch-once contract). Set by whichever of Step 11 / Step 11.5 / Step 11.6 performs the scan dispatch; read by the participating step(s) that consume their axis block. Set/read sites confined to Step 11 / Step 11.5 / Step 11.6 |

7. Register all workflow phases with the Task tools — issue one TaskCreate per phase below (each returns an auto-numbered taskId). Do NOT skip any phase:

   • Step 1.5: Task Decomposition (Normal sub-mode only — omit this entry entirely in Resume sub-mode, since the step has nothing to do at registration time there)
   • Step 2: Create Plan
   • Step 3: Plan Review (always registered; registered directly as completed when plan_review_enabled is false — see the disabled-phase clause below)
   • Step 4: Finalize Plan
   • Step 5: Implement
   • Step 6: Tidy
   • Step 6.5: Polish Prose
   • Step 7: Check / Test [check: {check_commands} | test: {test_commands}]
   • Step 7.5: Rules Compliance Review
   • Step 8: Code Review (always registered; registered directly as completed when code_review_enabled is false — see the disabled-phase clause below)
   • Step 8-1: Code Review - review pass (the conditional Step 8-2: Code Review - escalation pass row is registered by Step 8 at the moment it fires, not here)
   • Step 8.5: Deferred Verification (always registered, unconditionally — it is not a review phase, so neither code_review_enabled nor the difficulty-skip matrix touches its row; an empty review_fix_files is what makes it a no-op)
   • Step 9: Completion Hooks (only if hooks.on_complete is configured)
   • Step 10: Interactive Commits (only if interactive_commits is true; single row — per-commit iteration is handled inline within Step 10 because the commit count is not known until the proposal phase)
   • Step 11: Update Rules
   • Step 11.5: Self-Retrospective (only if self_retrospective.feedback is set and parses as a valid destination — see Step 11.5 for detection rules; if unset/invalid, omit this entry)
   • Step 11.6: Workability Retrospective (only if workability_retrospective.enabled is true; if unset/false, omit this entry. Registered regardless of the assessed tier — see Step 11.6) Step 1 registration mechanics: issue every TaskCreate in one upfront burst (before Step 2: Create Plan); conditionally-omitted phases (list items above carrying a condition) are omitted by not issuing their TaskCreate. Disabled-phase clause: when Step 1 sub-step 4's review-phase resolution already produced plan_review_enabled == false (run_mode == "fast") or code_review_enabled == false (a configured code_review: false), that phase's rows — the top-level Step 3: Plan Review / Step 8: Code Review row and, for the code phase, Step 8-1 — are registered directly as completed, settling the skip here rather than at Step 1.5's tier resolution. Where the Task tools (TaskCreate / TaskUpdate / TaskList) are unavailable (VSCode extension, or Claude Code < v2.1.142), use the equivalent TodoWrite operations — identical status values + register-all-upfront semantics; allowed-tools grants both. Full Tool-availability + burst detail: references/step1-load-settings.md § Sub-step 7 — registration mechanics. Task-handle resolution convention: every later "mark Step N as in_progress / completed" instruction is shorthand for resolve that Step's task — by its registration-time captured taskId, or by subject via TaskList — then TaskUpdate {taskId, status}. Phase-boundary self-audit: at every top-level Step transition (not the Step 8 pass sub-rows, governed by the Return-point no-stall reminders below), before the first tool call that advances into a new Step, name the Step you are entering (paired with what it does, per § Phase naming in user-facing output), resolve the prior Step's task by subject via TaskList, and verify it is completed — if it is still pending / in_progress, return to the unfinished Step first. This catches silent phase-skipping that task registration alone cannot prevent. Implementation sub-tasks in Step 5 are additions, not replacements. Note: Step 1.5's tier resolution may lower plan_review_enabled / code_review_enabled to false on the Trivial tier, and marks the express lane's skipped rows completed (references/tier-assessment.md § Row marking). Pre-completed row guard: the shared entry guard for every step that finds its own row already completed on arrival. Four rows can arrive that way — Step 6: Tidy, Step 6.5: Polish Prose, Step 7.5: Rules Compliance Review, and Step 11: Update Rules under the difficulty-skip matrix (the express lane — Trivial or Simple; references/tier-assessment.md § Difficulty-skip matrix) — plus Step 6.5: Polish Prose a second way, under the fast run mode's independent Step 6.5-only skip on a Moderate / Complex tier (that file's § Row marking). On any of them: do not re-mark the row in_progress and do not run its procedure. The Phase-boundary self-audit above treats such a row as the intended skip, not an unrun-step bug. Each of those four sections keeps only what that step must additionally do on its skip path, and that residue decides where control goes next. Three of the four go straight to the following step; Step 11 does not — its own Confirm remaining steps user gate still governs Step 11.5 / Step 11.6, neither of which is ever matrix-skipped.

8. Context-compaction recovery: if the session context was compacted before reaching this step, re-read the configuration files from disk (not the compacted summary) to re-verify each step's skip conditions from the actual merged config. Full detail is in references/step1-load-settings.md § Sub-step 8 — Context-compaction recovery.

9. Interruption re-anchoring: if this invocation is a user-prompted continuation of an interrupted prior session (connection error, browser refresh, etc. — distinct from compaction) and --resume <state-file> was not provided, re-establish position from the in_progress task + re-read config from disk, announce the resumption point, and proceed immediately (do not re-execute completed steps). Full detail in references/step1-load-settings.md § Sub-step 9 — Interruption re-anchoring.

Step 1.5: Task Decomposition

This step decides whether the user's request should be split into multiple smaller subtasks (each delivered as its own PR), or — in Resume sub-mode — picks the next subtask from an existing state file under .claude/plans/dev-workflow.<slug>.md. It also resolves the run's difficulty tier.

Dispatch:

• Resume sub-mode (--resume <state-file> was provided): read references/task-decomposition.md for the shared core (schema, canonical path, progress row), then references/task-decomposition-resume.md and follow section A. Resume sub-mode from top to bottom. Then read references/tier-assessment.md and run its § Resolution procedure against the selected subtask.
• Normal sub-mode: read references/tier-assessment.md first and run its § Resolution procedure against the user's request. When the resolved tier puts the run on the express lane (Trivial or Simple), the request is not decomposed, so mark Step 1.5: Task Decomposition completed, set the "effective task" to the original request, and proceed to Step 2 without reading either references/task-decomposition.md or references/task-decomposition-normal.md. On the full lane, read the former for the shared core and references/task-decomposition-normal.md for section B. Normal sub-mode.

Any decomposition proposal in Step 1.5 is a plain yes/no dialogue, not a plan.

Once the tier is resolved and section A or B has completed, the "effective task" is set for Step 2 onward: the selected subtask when decomposed, otherwise the original request.

Step 2: Create Plan

1. Record the current commit as base-commit (git rev-parse HEAD) for later diff comparison. Every cross-step variable was already initialized at Step 1 sub-step 6's cross-step variable init table.
2. No read-only lock: the sub-step 6 "No code changes in this phase" rule is enforced by agent discipline alone — hold to it through the Step 4 approval gate.

Sub-steps 3–5 are in references/step2-create-plan.md; Read it and apply each in its numbered position. Sub-step 3 holds the state-file framing, TDD-conflict resolution, the Version/identifier string replacement tasks rule, the Task-relevant skill annotation rule, the Codebase-research delegation guidance, and the lane branch that routes express-lane authoring to that file's § Compact plan template; sub-step 4 is the Simplicity self-audit; sub-step 5 the Plan self-check. Sub-steps 1, 2, 6, 7 (Confirm difficulty, one paragraph), and 8 stay inline.

6. No code changes in this phase
7. Confirm difficulty — the tier, and with it every piece of cross-step state the tier governs (plan_review_enabled / code_review_enabled, subagent_model, the difficulty-skip matrix's marked rows, and the difficulty log line), was already resolved at Step 1.5 (Task Decomposition) by references/tier-assessment.md § Resolution procedure. This sub-step is the first of the two escalation checkpoints in references/tier-escalation.md § Tier-change sites (the second is at Step 5 (Implement) completion): re-assess the drafted plan against § Tier criteria and, only when the new assessment is strictly higher than the current tier, read references/tier-escalation.md and follow it. When the assessment is unchanged or lower this sub-step writes nothing; the tier never falls.
8. Do not present the plan to the user or ask for approval/confirmation. The prohibition extends to confirmation-seeking transition sentences such as "if this design looks good, I'll proceed to Step 3 (Plan Review)", "shall I move on to Plan Review?", or any equivalent ask-for-go-ahead phrasing: they read as natural conversation but are the approval gate this sub-step forbids. The moment Step 2 ends, advance directly to Step 3 without emitting any user-facing message about the plan or the transition. The user will see the plan in Step 4 (internally reviewed in Step 3, unless plan_review_enabled is false — see Step 3's Disabled-phase exception — in which case Step 3 is skipped and the plan reaches Step 4 unreviewed).

Step 3: Plan Review

This step is an internal review. Do not present the plan to the user or ask for feedback during this step.

Disabled-phase exception. When plan_review_enabled is false this entire step is skipped. This is the closed list of causes:

• a Trivial task (Trivial disables both review phases, via Step 1.5's tier resolution);
• run_mode == "fast" (the --fast flag), which disables the plan phase on every tier and leaves code_review_enabled alone — resolved at Step 1 sub-step 4, before Step 1.5's tier resolution runs.

Whichever cause applies, the step's row is already completed on entry, so do not re-mark it in_progress. This skip is gated on plan_review_enabled itself, not on the presence of user-provided analysis — the analysis-substitution prohibition below still applies in full whenever the phase is enabled.

Always run (when plan_review_enabled). Step 3 is not skippable on the grounds that the user's task prompt contained design analysis, prior-session handoff material, or review-like commentary: that is upstream planning content the user wrote, not an independent bias-free review pass. Handling rules (closed list):

• (i) The Step 3 reviewer skill is always invoked.
• (ii) User-provided analysis (long task descriptions that themselves argue for the approach, embedded justification in handoff docs, etc.) is fed into the reviewer skill's dispatch payload as additional context so the reviewer can build on it rather than re-derive it.
• (iii) An explicit user override in the task prompt ("you may skip Step 3 for this run", or equivalent) is the only analysis-driven path to skipping (distinct from the disabled-phase exception above). When this fires, record a warning in the Completion summary so the user has a visible signal that the bias-free review pass was bypassed.

A "No actionable findings" outcome is a reviewer-side decision, not a Step-skip, and its semantic-judgment pass-through is unaffected.

If plan_review_enabled is false, skip this step entirely (see the disabled-phase exception above) — its row is already completed, so do not re-mark it in_progress and proceed directly to Step 4. The following in_progress marking and review pass apply only when the phase is enabled.

Mark Step 3: Plan Review as in_progress and run the single review pass.

Read references/step3-plan-review.md and run its procedure — sub-step 1 (call the resolved reviewer with the review payload, whose shape plan_review_scope selects — on full, categories a–d split across three independent groups the reviewer runs in parallel where it can; on rules-only, one unit covering .claude/rules/ compliance alone, with full rubric and per-unit reading lists in the reference — propagating subagent_model to a Claude-family reviewer, and feeding a state file's subtask scope + custom_instructions when set), sub-step 2 (semantic judge → on nothing-actionable, proceed to Step 4), sub-step 3 (apply improvements or reject with reason; the approach-reconsideration self-audit and the prose-integrity self-check live there), and sub-step 4 (carry unresolved points to Step 4). The Return-point no-stall reminder also lives in that reference.

No re-review loop here. Applying findings does not re-dispatch the reviewer. Two paths re-dispatch it — the reference's approach-reconsideration self-audit (at most once per run) and Step 4's rewrite-approach re-open.

Mark Step 3: Plan Review as completed.

Step 4: Finalize Plan (USER APPROVAL GATE)

1. Step 3-completion verification: before presenting, verify via TaskList that Step 3: Plan Review is completed; if it is still pending / in_progress, note that to the user and return to Step 3 before presenting (do not flip the row completed without doing the review). Exception: plan_review_enabled == false (see Step 3's Disabled-phase exception) leaves the row completed — that is the intended skip. Full procedure: references/step4-finalize-plan.md § Sub-step 1 — Step 3-completion verification. 1.5. Prose-language self-audit: before presenting, verify the plan body's explanation prose (Overview / Decisions / Build order / Test plan / Risks-Unknowns narrative) is written in the resolved language, while schema tokens / step labels / enum values / identifiers / quoted code stay verbatim. Audit both wrong-language sentences and over-preserved source-language concept words (per references/localization.md § Localization granularity). This audit re-runs on every entry into Step 4 (initial entry + any re-entry via sub-step 1's return-to-Step-3 or sub-step 3's material-change path). Full procedure: references/step4-finalize-plan.md § Sub-step 1.5 — Prose-language self-audit.

2. Plan presentation. The presentation body — the plan-body prose-polish pass (gated on polish_prose true + run_mode != "fast"; the file-mode dispatch and its unavailability handling are in the reference), then establishing .claude/plans/<slug>.md and running the visual gate → chat-approval fallback chain (the Trivial-tier route straight to chat and the browser-reachability probe both sit in the reference's Run the approval gate bullets; the gate itself returns approve / rewrite-approach / fallback) — is in references/step4-finalize-plan.md; Read it and follow it. On approve proceed to implementation; on rewrite-approach handle per sub-step 3's rewrite-approach bucket.

3. Collaborate with the user to refine the plan as needed (a swap-decisions / rewrite-approach re-presentation re-enters the surface this run reached: the relaunched visual gate, or the chat re-present when the gate fell back). Categorize each user response into one of the four buckets below via semantic judgment (per § No-Stall Principle's "do not rely on exact-phrase matching" rule — example phrasings are illustrative, not literal discriminators):

   • accept: explicit affirmative — "OK" / "approve" / "looks good" / "進めて" / any semantic equivalent. Begin implementation.
   • swap-decisions (Decisions Recommendation/Alternative swap on one or more specific items — "Decision 1 を Alternative に", "swap the recommendation on the language flag", "use the alternative for Decision N", "Decision N と M は Alternative で残りはそのまま"): re-render the plan with the specified Recommendation / Alternative pairs swapped on the named Decisions items, leave other items unchanged, run the read-back sub-step below, then re-present the plan (re-enter the gate). When the user names multiple Decisions in one message, list every affected item on the read-back line.
   • rewrite-approach (Approach / Build order / Scope-level material change — "switch from independent skill to extending sibling mode", "split this into two subtasks", "scope down to only the canonical site", or any change that does not fit a clean Decisions swap): the default path re-opens the Step 3: Plan Review row, runs the read-back sub-step below, returns to Step 3 to re-review the modified plan, then re-enters Step 4 from sub-step 1 — but two exceptions modify this default: the fast run mode's disabled plan phase (the user chose speed for this run, so a material change must not re-enable the phase), and the express-lane re-activation that re-derives the tier, re-marks the Step 3 / Step 8 / Step 6 / Step 6.5 / Step 7.5 / Step 11 rows, and re-populates the difficulty_skipped_steps / fast_mode_skipped_steps ledgers. When run_mode == "fast" or an express-lane tier (Trivial / Simple) is in play, read references/step4-finalize-plan.md § Sub-step 3 — rewrite-approach bucket runtime and follow it before acting (it is the full runtime for this bucket).
   • withdraw: explicit halt — "stop" / "cancel" / "abort" / "やめる" / "取り下げ". Exit the workflow with no further steps; do not proceed to implementation.

   Read-back sub-step (mandatory before applying any swap-decisions / rewrite-approach interpretation): emit a one-line summary of the interpreted change in the resolved language (e.g. Decision 1 を Alternative に切り替え、Decisions 2 と 3 は Recommendation のまま保持します — このまま反映してよろしいですか？) and wait for the user to confirm before re-rendering. The read-back resolves inside the gate that raised it — do not relaunch the gate to run it. If the user's confirmation response itself reads as another swap-decisions / rewrite-approach / withdraw instruction, treat the read-back as un-confirmed and re-classify under the four buckets above.

   NOT approval (interrogative or non-committal — "look good?" / "どう？" / "これでいい？"): treat as ambiguous — ask the user to confirm whether they intended an affirmative or to surface a change request, then re-classify the response under the four buckets above. Do not silently advance.

   After the user accepts (accept bucket), begin implementation.

Step 5: Implement

Step 5's procedure is sub-steps 1–11, with sub-step 2.5 (the Build-order boundary chain) applying between 2 and 3. Sub-steps 1, 2.5, 3–8, 10, and 11 — the plan-entry manual-action check (1), the Build-order boundary chain (2.5), prior-edit respect (3), the implementation self-audits: late-stage scaffolding (4), final-pass literal-value full-repo grep (5), pre-write path scope check (6), the User-observable artifact protection gate at probe → real-implementation boundary (7, a § No-Stall Principle user gate), derived-value claim deferral (8), the side-effecting external-tool launch warning (10), and the tier escalation checkpoint (11, the second of the two checkpoints in references/tier-escalation.md § Tier-change sites) — are in references/step5-implement.md; Read it and apply each sub-step in order (sub-step 2.5 lives in that file's own § Sub-step 2.5 — Build-order boundary chain section). Sub-step 2 keeps its core directive inline below (follow the plan, track progress, optionally register Build order steps as sub-tasks). Three further pieces stay inline: sub-step 2's delegation-route contract (the implementation_executor / subagent_model route that § Configuration's Agent tool usage bullet points to; the full delegation body is in the reference), sub-step 2.5's state-variable contract (implementation_boundaries, read by references/finish-phase.md § Step 10's commit-plan proposal), and sub-step 9 in full (it records implementation_diff_paths, read by references/finish-phase.md § Step 10's Post-hook attribution check).

2. Follow the plan, track progress with the Task tools (TaskUpdate). The Build order is always an ordered, numbered list of implementation steps (per references/plan-authoring.md § Template on the full lane, or references/step2-create-plan.md § Compact plan template on the express lane — do not open the former on a lane that never authored from it), so you MAY register each step as an implementation sub-task and execute them in order, marking each completed as it lands — recommended for long plans, optional for short ones. These rows are additions, not replacements, and leave the Phase-boundary self-audit (which governs only top-level Step transitions) untouched. Apply custom_instructions throughout implementation

   Subagent delegation of a settled work unit (optional, guard-gated). Default under implementation_executor: "main" is main-thread implementation; you MAY delegate a settled work unit (spec fixed; not judgment-heavy / context-dependent / small) to a subagent via the Agent tool. Under implementation_executor: subagent or an external-CLI value this settled-unit path becomes the default route per qualifying unit (unsettled units stay main-thread with a one-line note; hybrid execution is normal). This is one of the sanctioned Agent exceptions in § Configuration's Agent tool usage bullet (the others are the Step 2 research delegation and the Step 9 review-class hook dispatch) and propagates subagent_model (pass model: <subagent_model> when a model id, omit when inherit); external-CLI values route through the matching Skill(ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy) instead (no new Agent site). Executor availability is resolved once per run at the first delegation point (per § Prerequisites), falling back to main with a one-line note. The full delegation procedure — the three guards, payload construction (references/executor-prompt.md), capability-first subagent-type selection, the external-CLI workspace-write dispatch + side-effecting-launch warning, and the post-delegation Step 5 self-audit — is in references/step5-implement.md sub-step 2; Read it and follow it.

   Build-order boundary chain (sub-step 2.5) — state-variable contract. As each Build order step's edits land, record that step's landing point as a dangling commit object and append {heading, object} to implementation_boundaries (initialized [] at Step 1 sub-step 6 — see its cross-step variable init table), so § Step 10 can propose a commit grouping built from the approved Build order instead of grouping the finished working tree from scratch. Runs only when interactive_commits resolves to true, since § Step 10 is the chain's sole consumer. Everything else — the loop's two Step-5-local variables, the failure handling, the exit unstage — is in references/step5-implement.md § Sub-step 2.5 — Build-order boundary chain; Read it and follow it.

3. Implementation diff snapshot: at the conclusion of Step 5 (after all planned edits are applied and the derived-value claim deferral sub-step — sub-step 8, in references/step5-implement.md — completes), run git diff <base-commit> --name-only and store the result as implementation_diff_paths — the set of tracked paths changed by this task's implementation, recorded before any post-implementation review hook or automated fix tool runs. This snapshot is consumed by references/finish-phase.md § Step 10's "Post-hook attribution check" paragraph.

Step 6: Tidy

Difficulty exception. When Step 6: Tidy's row is already completed on entry, apply § Step 1 registration mechanics' Pre-completed row guard and proceed directly to Step 6.5.

The Step 6 cleanup callee is resolved per the Cleanup skill bullet in § Prerequisites: the built-in simplify is the primary callee, the bundled tidy its fallback.

Cross-layer review handoff ledger. Step 6 (cleanup), Step 6.5 (prose-only cleanup), Step 7.5 (rules-review), Step 8 (code review), and any review-class hooks.on_complete entries (an entry is review-class when it is a Skill(<name>) entry whose skill reviews or inspects the change and reports findings — judge semantically from the skill's name and purpose; plain shell-command entries are never review-class and receive no ledger) run sequentially against the same deliverable but share no state by default. From this step onward, keep a lightweight in-memory ledger of each review layer's dispositions: findings deferred (with the reason), findings applied (with the sites covered), and known leftover sites or residual concerns. Include the ledger as a short context item in each subsequent review layer's dispatch payload (the rules-review dispatch, whether Step 7's background launch or its Step 7.5 sequential fallback; the Step 8 review payload, where it complements that payload's same-layer continuation item; and review-class hooks.on_complete callees). When the ledger has no recorded dispositions yet, omit the item from that payload entirely — do not render an empty placeholder. When a later layer re-surfaces a concern the ledger records as deferred or partially applied, resolve it once: sweep all remaining sibling sites in one pass when they are enumerable and within this task's scope; otherwise — sites outside this task's scope, or a sweep too large for this run — record the leftover explicitly in the plan's Risks. Do not let each layer independently re-apply the same structural fix to a different subset of sites.

Step 6's procedure — sub-step 1 (pre-dispatch rename-sweep self-audit), sub-step 2 (dispatch the cleanup skill: Skill(simplify) primary / Skill(tidy) fallback, with the tidy-only Base ref asymmetry and the subagent_model propagation that rides only the tidy path), sub-step 3 (mark Step 6: Tidy completed and proceed to Step 6.5 regardless of outcome), and sub-step 4 (not-observable-result recovery re-exec) — is in references/step6-tidy.md; Read it and follow the procedure from top to bottom.

Step 6.5: Polish Prose

A dedicated pass that refines the resolved-language explanation prose (comments, test / example descriptions, docstrings, user-facing strings) in the changed files into concise, natural native text via Skill(prose-polish) in file mode.

Difficulty exception. When Step 6.5: Polish Prose's row is already completed on entry, apply § Step 1 registration mechanics' Pre-completed row guard and proceed directly to Step 7.

polish_prose gate. When polish_prose is not true (only when explicitly set to false; the default true and a non-boolean fall-back-to-true both run — see § Configuration's polish_prose bullet), Step 6.5 does not run: mark Step 6.5: Polish Prose completed, emit the one-line note below in the resolved language, and proceed to Step 7. This guard is a no-op when the row is already completed — the note fires only when the row is still in_progress when reached. When polish_prose is true, run sub-steps 1–4 below.

• language: ja: Step 6.5（Polish Prose）を skip しました — \polish_prose: false`（opt-out）が設定されています`
• language: en: Step 6.5 (Polish Prose) skipped — \polish_prose: false` (opt-out) is set`

Step 6.5's procedure (run only when the polish_prose gate above passes) — sub-step 1 (collect the changed-file set: tracked + untracked minus § Workflow artifacts, then the scope-awareness filter; empty-set guard skips the dispatch), sub-step 2 (dispatch Skill(prose-polish) in file mode with Language: = resolved language and no Model:), sub-step 3 (judge the verdict — done / no-change complete; error note-and-continue without retry; a Skill() call-failure retries once then appends prose-polish unavailable (prose polish pass) to bundle_skills_unavailable), and sub-step 4 (runs-once note) — is in references/step6.5-polish-prose.md; Read it and follow the procedure from top to bottom.

Return-point no-stall reminder: after Skill(prose-polish) returns (regardless of outcome — done / no-change / an error verdict / a call-failure skip, any non-error-stop result), the next action — Step 7's first tool call — must be issued in the next tool call. Do not insert an interstitial summary or acknowledgment turn.

Step 7: Check / Test (max 3 retries)

1. Run check_commands in order (always run all). On failure, fix and retry (do not proceed to test execution). Two step-internal USER-GATE stops apply here (the only non-completing exits from the check_commands phase): the pre-execution scope-narrowing stop (a check_commands entry assessed as a repo-wide auto-fix tool + the working tree has unrelated existing changes + narrowing is infeasible → stop and ask the user for direction — run full-width / skip / alternative scoped invocation) and the scope-drift stop (a command writes non-trivial changes outside the task-scope snapshot → warn and wait, leaving the tree as-is; trivial whitespace/comment drift ≤ 5 lines attributable to the formatter/linter that just ran proceeds automatically with a one-line note). The full procedures — the repo-wide-auto-fix assessment, the git diff --name-only <base-commit> task-scope snapshot mechanics, the three-condition trivial-drift auto-proceed criteria, and the Pre-existing vs regression discrimination (check_commands) bullet — are in references/step7-check-test.md; Read and apply them.

Concurrent launches (initial-pass optimization). After check_commands pass and before running test_commands, launch two read-only analyses as background subagents overlapping the test phase. Both use Agent with run_in_background: true, subagent_type: general-purpose, model: <subagent_model> (omit when inherit), a "run the callee on your own thread — do not nest a further Agent" payload note (the callee's resulting inline execution is intended), and apply no edits (the main thread applies fixes later). test_commands is never backgrounded. Launch only when background dispatch (Agent + run_in_background) is available — default to parallel in the common interactive session; treat as unavailable only when Agent is absent or the session offers no background-dispatch capability.

• Concurrent rules-review launch (initial pass): dispatch Skill(rules-review) --base-commit <sha> (+ the § Step 6 cross-layer review handoff ledger); collected at Step 7.5 sub-step 1. Skip when Step 7.5 is difficulty-skipped (Trivial / Simple) — no collector exists.
• Concurrent code review launch (initial pass): dispatch the Step 1-resolved Skill(<reviewer>) with the payload Step 8 sub-step 1 composes for the review pass (references/code-review-payload.md); collected at Step 8 sub-step 1. Skip when code_review_enabled is false (see Step 8's disabled-phase exception) — no collector exists.

Flag lifecycle contract (single source of truth — read by the Step 7.5 / Step 8 collects): rules_review_launched / rules_review_stale and code_review_launched / code_review_stale init false at every Step 7 entry (before the availability branch); set <x>_launched = true on a successful dispatch; set <x>_stale = true when a fix lands between launch and collect (a test_commands fix here sets both; a Step 7.5 fix additionally sets code_review_stale, whose collect point is later). A collect fires only when <x>_launched == true && <x>_stale == false, else the collector dispatches fresh — and a stale result is discarded whole: do not salvage any subset of its findings (e.g. the findings on paths the intervening fix did not touch). Setting _stale on a no-launch path is a safe no-op. Pass (the term the collects reference) = the initial Step 7 entry; both launches are initial-pass-only. The full dispatch procedure — the availability-detection criterion, the per-launch dispatch bullets, and the orphan-avoidance and staleness set-site rules — is in references/step7-check-test.md § Concurrent launches (full dispatch procedure); Read and apply it.

After launching (or skipping) both, run test_commands in the main thread per sub-step 2 below; the background launches proceed concurrently.

2. Iterate over test_commands in order. For each entry (which must be of the form Skill(<name>)), invoke that skill with --base-commit <sha> (from Step 2) via $ARGUMENTS. Each invocation must return a structured summary with one of three statuses (SUCCESS / TEST_FAILED / EXECUTION_ERROR); a TEST_FAILED or EXECUTION_ERROR from any entry halts the loop immediately and triggers the retry path in sub-step 3 — subsequent entries do not run on the failing pass. Each test skill handles scope decision and execution internally via subagent (when applicable). The test_commands self-check suite (Skill() call-failure fallback, environment sanity check, bulk-vs-split execution, shared-path re-run scope, cheap-diagnostic first pass, pre-existing-vs-regression discrimination, self-contamination discrimination, EXECUTION_ERROR + pre-declared degraded procedure, mock/replay-only coverage, downstream-artifact invalidation, red-before/green-after verification, environmental verification fidelity) is in references/step7-check-test.md; Read it and apply each.

3. After 3 retries, report to user and stop

Coverage note (TypeScript multi-tsconfig): For projects with Project References or multiple tsconfig*.json files, a single tsc --noEmit may miss changed files that belong to other tsconfigs. --init auto-registers a per-tsconfig tsc -p <path> --noEmit in this case (see references/init-mode.md for detection rules). If coverage still looks incomplete, re-run --init or append the missing command manually.

GATE: Verify Steps 2-7 are completed (check task status via TaskList; if status is inconsistent, verify actual completion by reviewing work done). Mark Step 7.5 as in_progress unless its row is already completed — in that case § Step 1 registration mechanics' Pre-completed row guard applies: skip straight to Step 8 (same already-completed-row handling as the Step 8 GATE's disabled-code-phase case). (If Step 7 launched a background rules-review, it may still be in flight — Step 7 is "complete" once the test phase passes; Step 7.5 sub-step 1 collects the rules-review result.)

Step 7.5: Rules Compliance Review

Dedicated rules compliance check, kept separate from code review (Step 8).

Difficulty exception. When Step 7.5: Rules Compliance Review's row is already completed on first arrival — from Step 7's GATE, the difficulty-skip matrix having pre-completed it — apply § Step 1 registration mechanics' Pre-completed row guard and proceed directly to Step 8 (Code Review). The guard does not cover a later re-entry that names this step for re-verification (references/crit-commit-review.md § Round re-verification weight's actual-code branch): that arrives with the row completed because the step already ran, and must run the procedure.

Read references/step7.5-rules-compliance.md and follow the procedure from top to bottom — it holds the Responsibility scope (Step 7.5 / Step 6 / Step 8 / Step 11 division of labor, including the rule-doc-drift routing to Step 11), the Step 7.5-vs-Step 8 double-review authority note, and sub-steps 1 (obtain the rules-review report — collect the Step 7 background launch when fresh, else invoke Skill(rules-review) --base-commit <sha> with Model: <subagent_model> when a model id; never substitute an inline rules-walk), 2 (semantic judge → nothing-actionable ends the pass), and 3 (fix all violations with pattern-class self-sweep, then stop — re-verification is deferred). The initial pass's own exit (the continuation point the reference's Caller-neutral exits paragraph leaves to each caller): mark Step 7.5: Rules Compliance Review completed and proceed to Step 8 (Code Review) — on sub-step 2's nothing-actionable judgment, or once sub-step 3(a)'s fixes land.

Where the re-verification went. The initial pass does not re-run Step 7 (Check / Test) or dispatch a 2nd-cycle rules-review: both belong to Step 8.5 (Deferred Verification), which runs that cycle once over the union of Step 7.5's and Step 8's fixes. The reference keeps sub-steps (b)–(d) and the fast run mode's 1-pass cap as the canonical bodies Step 8.5 reuses. Step 8.5 follows this step on every path.

Persistent-violations decision (sub-step 3(d)) is a USER APPROVAL GATE (enumerated in § No-Stall Principle) — the reference owns its presentation and wait mechanics.

Cross-step variable contract: sub-step 3(a) appends its edited files to review_fix_files (opening that accumulation window — § Step 1 sub-step 6's init table) and sets code_review_stale = true (so Step 8 sub-step 1 discards its now-stale background result and re-dispatches); the fast run mode's 1-pass cap appends Step 7.5 Rules Compliance Review re-verification skipped (fast mode; <site>) to fast_mode_skipped_steps from whichever reuse site ran (b)–(d), naming that site in the slot (see the cap paragraph's "One ledger string per firing site, with that site in its <site> slot" clause). All three transitions execute inside the reference procedure.

GATE: Verify Steps 2-7.5 are completed (check task status via TaskList; if status is inconsistent, verify actual completion by reviewing work done). Mark Step 8 as in_progress only when code_review_enabled; if it is false (see the disabled-phase exception below), Step 8 is already completed — do not re-mark it in_progress, skip straight to Step 8.5 (Deferred Verification). (If Step 7 launched a background code review, it may still be in flight — Step 8 sub-step 1 collects it.)

Step 8: Code Review

Always run this step even when tests pass cleanly.

Disabled-phase exception. When code_review_enabled is false this entire step is skipped. This is the closed list of causes (neither run-mode flag is among them — of the two review phases the axis reaches the plan one only):

• a Trivial task (Trivial disables both review phases, via Step 1.5's tier resolution);
• a configured code_review: false (§ Configuration's code_review bullet) — resolved at Step 1 sub-step 4's review-phase resolution, before Step 1.5's tier resolution runs, and never raised by it.

Either way the step's row is already completed on entry — marked by Step 1.5's tier resolution on the Trivial cause, and by the registration burst on the configured-false cause (§ Step 1 registration mechanics' disabled-phase clause). This skip is gated on code_review_enabled itself, not on task difficulty: a Simple / Moderate / Complex task whose configured code phase is false skips Step 8 too.

If code_review_enabled is false, skip this step entirely — its row is already completed, so do not re-mark it in_progress and proceed directly to Step 8.5 (Deferred Verification) — a separate row this skip does not touch. The following in_progress marking and review pass apply only when the phase is enabled.

Escalation pass (the one conditional second pass). Step 8 runs a single review pass, plus one escalation pass taken only when that pass reported at least one Critical finding. It is capped at one: a Critical finding in the escalation pass does not trigger a third. When it fires, register a Step 8-2: Code Review - escalation pass task row at that moment (the registration burst creates only Step 8-1).

Mark Step 8: Code Review as in_progress and mark Step 8-1 as in_progress. Run the review pass:

1. Obtain the reviewer report — collect the Step 7 background code-review launch when it is fresh (code_review_launched == true && code_review_stale == false), otherwise dispatch fresh the Step 1-resolved reviewer skill (e.g. Skill(ask-peer)). The collect path serves the review pass only; the escalation pass, when it fires, always dispatches fresh. When collecting: if the background subagent has not yet reported, wait for its completion notification before judging (a not-yet-arrived notification is never "No actionable findings", per the same non-stalling wait-boundary rule as Step 7.5 sub-step 1's collect); an error completion routes to fresh-dispatch (treat as not-launched; the route only redirects, it does not mutate the flags). subagent_model propagation applies to the inline fresh-dispatch path only (Claude-family reviewers). Pre-dispatch dispatch-boundary reminder: issue the Skill(<reviewer>) call in the same turn as any accompanying status prose — never a standalone status turn before the call (a stall point); reading the reviewer's SKILL.md is preparation, not dispatch. Both paths then judge and apply findings per sub-steps 2–3 (the collect path only substitutes the report's source). The reviewer-report payload — the single parametric source both this fresh-dispatch and the Step 7 code-review launch bake — is in references/code-review-payload.md § Sub-step 1 — reviewer report payload; Read and compose from it.

2. Judge the reviewer's response semantically: if the reviewer reports nothing actionable — no actionable findings, no bugs / convention violations / design issues raised, or any other "nothing to report" outcome regardless of exact wording — mark the pass's row completed, then fall through to the completion line below and on into Step 8.5 (Deferred Verification). No escalation pass fires. Do not jump to Step 9 (Completion Hooks) directly from here: Step 7.5 or this review pass may already have applied fixes (review_fix_files non-empty) that still owe Step 8.5's check/test + scoped rules-review (Step 8.5 is a no-op only when review_fix_files is empty — a no-findings review pass does not by itself make it one, since Step 7.5's fixes are in that set). Per the No-Stall Principle, do not wait for user input and do not rely on exact-phrase matching; trust semantic judgment — the reviewer skill's phrasing varies, and a free-form-prose reviewer's verdict is natural-language Markdown rather than a fixed token.

3. Otherwise: autonomously fix genuine issues or reject inapplicable points with reason — do not ask the user for judgment on individual review findings. Mark this pass's row as completed.

   • The fix-time self-checks — Rejection self-question (severity-label override), Class-level extension audit (post-Critical/Major-fix), Prose-integrity self-check (post-fix), Natural-language quality self-check (post-fix), Phrase-duplication sweep (post single-site fix), and Comment-verbosity self-check (post-fix) — are in references/step8-code-review.md; Read it and apply them after each fix per that reference.

   • If code was modified: do not re-run Step 7 or Step 7.5 here. Verification (check/test + rules-review) is deferred to Step 8.5 (Deferred Verification), which runs once after the review and escalation passes settle. Instead, append the repo-relative paths of the files this pass's fixes edited to review_fix_files (per its accumulation-window rule — see § Step 1 sub-step 6's init table). Because no Step 7 re-entry occurs, no background launch re-fires; an escalation pass therefore obtains its reviewer via sub-step 1's fresh-dispatch path (code_review_launched stays false). Accumulate every fixed file into review_fix_files, regardless of which layer, pass, or fix path produced it. The only pass that appends nothing is one that modified no code.

   • Escalation decision (evaluate once, after this pass's fixes land — first match wins): (a) this pass was itself the escalation pass → no further pass; (b) this pass reported no Critical finding → no further pass; (c) all points were rejected with no modifications → no further pass; (d) otherwise — a review pass that reported ≥ 1 Critical finding and applied at least one fix → fire the escalation pass: register the Step 8-2: Code Review - escalation pass row, mark it in_progress, and return to sub-step 1 for one fresh dispatch whose payload carries the continuation item and scope instruction per sub-step 1's definition. When no further pass fires, go to sub-step 4's unresolved-findings gate (a no-op when nothing is unresolved), then the completion line below and on into Step 8.5 (Deferred Verification).

   Return-point no-stall reminder: When the reviewer returns (regardless of outcome — findings reported, "No actionable findings", any non-error result), the next action — the escalation pass's fresh dispatch when the escalation decision selects branch (d), or sub-step 4's unresolved-findings gate followed by the transition into Step 8.5 (Deferred Verification) otherwise — must be issued in the next tool call. Do not insert an interstitial summary or acknowledgment turn at the pass boundary.

4. If actionable feedback still remains once the passes have settled, present the unresolved points to user for decision. Above the unresolved points, emit a summary preamble per references/plan-format.md § User-gate summary preamble. Render the findings following references/localization.md § Localization granularity in the resolved language. Any fix applied while resolving this gate appends its edited files to review_fix_files (§ Step 1 sub-step 6's accumulation-window rule) before Step 8.5 (Deferred Verification) runs.

Mark Step 8: Code Review as completed.

Step 8.5: Deferred Verification

The run's single post-fix cycle: the verification neither review layer performs for itself, run once over the union of both layers' fixes (review_fix_files) rather than once per layer.

Entry condition. Mark Step 8.5: Deferred Verification in_progress on arrival, then evaluate the two gates below. When review_fix_files is empty, neither gate fires: run nothing here and fall through to the "Mark Step 8.5: Deferred Verification as completed" line below, which marks the row and loads the finish phase — this no-op path takes that same exit rather than jumping to Step 9 (Completion Hooks) on its own. Arrival is unconditional and the row is never pre-completed, so § Step 1 registration mechanics' Pre-completed row guard never applies here.

Two gates, in order:

1. check/test — gate: review_fix_files non-empty. If either review layer applied at least one fix, run Step 7 (Check / Test) once against the current working tree. This is a plain check/test pass: it fires no concurrent background launches, and the Step 7 3-retry loop applies. Any test-failure fixes applied here append their edited files to review_fix_files (§ Step 1 sub-step 6's accumulation-window rule). This gate is not tier-gated — it runs on Simple tier too (only the rules-review gate below is tier-gated).

2. scoped rules-review — gate: review_fix_files non-empty AND the initial Step 7.5 pass actually ran. Neither leg reads code_review_enabled. When both hold, run the Step 7.5 procedure (references/step7.5-rules-compliance.md) — already in context, since that leg means it ran — once as a scoped re-check over Files: <review_fix_files>, reusing its sub-steps 2 / 3(a)–(d) + the fast run mode's 1-pass cap. The gate-2 detail — the direct Skill(rules-review) --base-commit <sha> invocation with Files: + a scope note that blocks a spurious file-crossing / paired-change flag, and the sub-step reuse deltas — is in references/step8-code-review.md § Deferred verification — gate 2 scoped rules-review detail; Read and apply it. Open that file here even when Step 8 already opened it for its fix-time self-checks: two paths reach this gate without it — a code_review_enabled: false run, and a review pass that exited at Step 8 sub-step 2's nothing-actionable judge.

   Where its exits go. Every exit in the reused bodies falls through to the "Mark Step 8.5: Deferred Verification as completed" line below, and sub-step (d)'s user gate holds that fall-through until the user answers.

Return-point no-stall reminder: when gate 1's check/test passes and when the gate-2 rules-review returns (regardless of outcome — violations fixed, nothing actionable, the --fast cap short-circuiting the 2nd cycle, any non-error result), the next action — the following gate, or the completion line below and the Step 9 (Completion Hooks) transition — must be issued in the next tool call. Do not insert an interstitial summary or acknowledgment turn.

Mark Step 8.5: Deferred Verification as completed, then Read references/finish-phase.md — the whole finish phase, § Step 9 through § Completion, is defined there. Load it here, at this unconditional exit, rather than at § Step 9 below. Load it even when hooks.on_complete is unset and even when interactive_commits is false — those skips are decided inside the file, and § Completion runs on every path.

Step 9: Completion Hooks

Defined in references/finish-phase.md, loaded at the Step 8.5 (Deferred Verification) exit above — follow that file from top to bottom. If it is somehow not in context on arrival here (a compaction between that exit and this point), Read it now before proceeding.

Input contract — the finish phase consumes the run's cross-step state, and every item of it is established before this boundary: the variables Step 1 sub-step 6's init table declares, as their writers left them, plus bundle_skills_unavailable from sub-step 3's ledger init; <base-commit> (Step 2) and <slug> (Step 4: Finalize Plan); implementation_diff_paths (Step 5 sub-step 9's implementation diff snapshot); the § Step 6 cross-layer review handoff ledger; the § Workflow artifacts (cross-step fixed exclusion) set; the resolved configuration; and the canonical state-file path from Step 1.5 (Task Decomposition) when a decomposition state file is in play. landed_count is the one exception — Step 10 initializes it on entry, inside the file.

Step 10: Interactive Commits

Defined in references/finish-phase.md, loaded at § Step 9's pointer above.

Step 11: Update Rules

Defined in references/finish-phase.md, loaded at § Step 9's pointer above.

Step 11.5: Self-Retrospective

Defined in references/finish-phase.md, loaded at § Step 9's pointer above.

Step 11.6: Workability Retrospective

Defined in references/finish-phase.md, loaded at § Step 9's pointer above.

Completion

Defined in references/finish-phase.md, loaded at § Step 9's pointer above.