version: "1.0.4" name: dev-workflow description: Guided development workflow that orchestrates planning, review, implementation, testing, and rule maintenance. Use this skill whenever the user wants to develop a feature, fix a bug, refactor code, or make any code changes following a structured process — even if they don't explicitly mention "workflow" and simply describe what they want built or fixed. allowed-tools: Agent, Read, Write, Edit, Glob, Grep, TaskCreate, TaskUpdate, TaskList, TodoWrite, EnterPlanMode, ExitPlanMode, AskUserQuestion, Skill(ask-peer), Skill(ask-claude), Skill(ask-codex), Skill(ask-gemini), Skill(ask-copilot), Skill(ask-agy), Skill(extract-rules), Skill(tidy), Skill(simplify), Skill(run-tests), Skill(rules-review), Skill(prose-polish), Bash(pwd), Bash(mkdir -p .claude/plans), Bash(rm -f .claude/plans/), Bash(pnpm run ), Bash(pnpm exec ), Bash(npm run ), Bash(yarn run ), Bash(bun run ), Bash(bundle exec ), Bash(make lint ), Bash(make format ), Bash(make test ), Bash(make typecheck ), Bash(make check ), Bash(python -m pytest ), Bash(poetry run ), Bash(uv run ), Bash(cargo test ), Bash(cargo clippy ), Bash(cargo fmt ), Bash(go test ), Bash(go vet ), Bash(git diff ), Bash(git status ), Bash(git rev-parse ), Bash(git symbolic-ref -q ), Bash(git merge-base ), Bash(git remote show ), Bash(git switch -c ), Bash(git add ), Bash(git commit ), Bash(git log ), Bash(git checkout HEAD -- ), Bash(git reset -- ), Bash(git write-tree), Bash(git commit-tree ), Bash(git ls-files ), Bash(grep -q ), Bash(test -f ), Bash(gh api --method POST /repos//issues ), Bash(gh auth status), Bash(jq ), Bash(node ), Bash(printenv CLAUDE_CODE_REMOTE), Bash(crit *)

Dev Workflow

Usage

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

Prerequisites

Per-skill detail (retry-once semantics, the reviewer three-option fallback protocol, the simplify→tidy resolution single source of truth, the polish_prose gating, and each skill's bundle_skills_unavailable append site) 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 4.
• 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. The reference bullet is the single source of truth for the simplify→tidy resolution.
• 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, review_iterations, subagent_model, implementation_executor, interactive_commits, compact_rules, plan_review_gate (+ its deprecated predecessor visual_plan_review, resolved as a Scalar via the compat mapping in the plan_review_gate bullet), commit_review_gate, polish_prose, confirm_remaining_steps, custom_instructions, language): higher layer wins (replaces) when the key is present; an absent key inherits from lower layers. The map-valued scalars review_iterations ({plan, code}) and subagent_model ({<tier>: <model>}) are 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 (review_iterations → 3 per phase; subagent_model → sonnet for trivial / simple, inherit for moderate / complex)
• List (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"
review_iterations: 3
subagent_model:
  trivial: sonnet
  simple: sonnet
implementation_executor: "main"   # main | subagent | ask-claude | ask-codex | ask-gemini | ask-copilot | ask-agy
interactive_commits: true
compact_rules: false
plan_review_gate: "visual"   # plan-mode | visual | crit
commit_review_gate: "diff"   # diff | crit
polish_prose: true
confirm_remaining_steps: false
custom_instructions: "Always use TDD. Write tests before implementation."
language: "ja"
check_commands:
  - "pnpm run lint:fix"
  - "pnpm run format"
  - "pnpm run typecheck"
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 (defaults, accepted values, behavior, opt-in / opt-out, behavior-change / History notes) 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).
• review_iterations: Max Plan Review (Step 3) / Code Review (Step 8) iterations (default 3); a scalar caps both phases, a {plan, code} map sets them independently; 0 turns a phase off; -i N overrides both.
• 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 in Step 2.
• 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).
• compact_rules: Whether Step 11 sub-step 3's Char-count compaction gate runs (default false; experimental).
• plan_review_gate: Plan approval surface — plan-mode / visual (default) / crit; Step 4's gate is one consumer. The deprecated visual_plan_review boolean is still resolved via a compat mapping.
• commit_review_gate: Code-diff review surface — diff (default) / crit; Step 10's per-commit gate is one consumer. Independent of plan_review_gate.
• polish_prose: Whether the two prose-polish passes (Step 4 plan-body + Step 6.5) run (default true).
• confirm_remaining_steps: Whether Step 11 asks before running the rule-maintenance / retrospective steps (default false; experimental; also fires under --fast).
• 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).
• check_commands: Static checks (lint / format / typecheck); all run in order during Step 7.
• 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 — run_in_background for test-phase overlap, see Step 7's "Concurrent rules-review launch" / "Concurrent code review launch" paragraphs for why Agent rather than Skill()), 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). Beyond these, two conditional delegations may fire: Step 2 MAY delegate read-only codebase research when plan_review_gate is not plan-mode (the visual / crit path, when the task benefits from non-trivial 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", still passing subagent_model; 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: each of the three fixed sites, and the Step 5 delegation when it fires, passes the Step 2-resolved subagent_model as the Agent model (omitted when inherit); the Step 2 research delegation is excluded — it dispatches before Adjust N resolves the tier, so it always runs on the session model (subagent_model still its inherit init). 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 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, per the subagent_model bullet). The Step 4 plan-review gates (visual / crit) and Step 10's `commit_review_gate: crit` gate each launch their external process via background Bash (run_in_background), not the Agent tool — each owns its own availability/reachability determination and only launches when reachable (see references/visual-plan-review.md / crit-plan-review.md / crit-commit-review.md) — so none is a subagent dispatch and none 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 3-1 / Step 8-1 iteration rows are internal identifiers — they exist for this file's cross-references and for resolving registered task rows. 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, so one step never acquires two descriptions — 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 …)), and expanding the two iteration templates one row at a time (Step 3-1: Plan Review - iteration 1) — 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 so parens do not nest (品質ゲート（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 — it leaves untouched the identifiers this file uses in its own cross-references, which 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 because § Completion renders that ledger verbatim. 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 (-i / --iterations is ignored)
• --resume <state-file> → Execution Mode (Resume sub-mode; see Step 1.5: Task Decomposition)
• Otherwise → Execution Mode (Normal sub-mode)

--fast is an Execution Mode modifier, not a fourth branch here — it combines with either Normal or Resume sub-mode (see Step 2's Adjust N by difficulty). Like -i, it is ignored under --init.

--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 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.

• Step 1.5 task-decomposition proposal dialogue — yes / adjust / no confirmation (Normal sub-mode; references/task-decomposition.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.md § A. Resume sub-mode)
• Step 4 plan approval (Step 4: Finalize Plan)
• Step 4 plan-review gate (`visual` / `crit`) — when plan_review_gate is visual / crit, a browser-based structured review replaces the text approval; each gate owns its own availability/reachability determination and returns approve / rewrite-approach / fallback (the browser submit is a harness-tracked background boundary — proceed on the process's exit notification, not a "type continue" pause; both run outside Plan Mode, so approve proceeds directly without ExitPlanMode; fallback chains crit → visual → chat; neither emits a § User-gate summary preamble). Defined in references/visual-plan-review.md / references/crit-plan-review.md
• 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 review cycle (Step 7.5: Rules Compliance Review; also fires when Step 8's "Deferred verification (Step 8 fix aggregate)" pass reuses Step 7.5 sub-step (d) at loop exit, there gating Step 8's completion)
• Step 8 unresolved-findings decision — reviewer-reported actionable findings still unresolved after the N_code-th iteration (Step 8: Code Review)
• Step 10 commit-plan approval gate — accept the proposed commit grouping (subjects + file lists); fires on the initial plan and re-fires whenever a Mid-loop adjust file-regrouping / split-adding branch rebuilds the un-landed plan (references/interactive-commits.md § Propose commit plan)
• Step 10 per-commit accept gate — accept each commit (subject / body / files / diff) before it lands; repeats N times (references/interactive-commits.md § Per-commit loop, judged per § Approval token closed list inside Step 10). Under commit_review_gate: "crit" (when available) the diff-review portion launches crit as a harness-tracked background boundary per references/crit-commit-review.md; only some of that reference's outcomes map directly to accept / adjust / cancel (the rest loop or fall back within that reference)
• Step 10 fold-or-defer gate — after a pre-commit hook auto-modifies the tree following a zero-exit commit, ask fold (amend the just-landed commit) vs defer (leave uncommitted); judged per the dedicated 5-branch → fold / defer / cancel / re-present-as-adjust classifier in references/interactive-commits.md § Post-commit auto-modify cycle bound (extends § Approval token closed list's 4 buckets with a defer-direction branch; cancel routes via Mid-loop cancel, ambiguous adjust via § Mid-loop adjust branch f)
• Step 10 ambiguous-adjust clarifier — when a Mid-loop adjust request cannot be classified into branches a–e, ask a clarifying question and re-enter the originating gate — itself branch f of Mid-loop adjust — closed-list branches (references/interactive-commits.md; categorization vocabulary depends on which gate originated the request)
• Step 11 compaction approval gate — on Skill(extract-rules) --compact returning status: "compacted", present the per-file diff per § User-gate summary preamble and wait for accept/reject/adjust/cancel (references/update-rules.md § Char-count compaction gate). cancel = Step 10's Mid-loop cancel semantic (no revert); adjust uses Step 11's own three-case closed list (per-file disposition / clarification / other), not Step 10's branch f
• Step 11 confirm-remaining-steps entry gate — at Step 11 entry (after the commit phase), ask whether to run the remaining rule-maintenance / retrospective steps (Step 11 / 11.5 / 11.6, whichever registered) or skip to Completion; binary proceed / skip (on skip, mark those steps completed without running them). Fires conditionally — Step 11's "Confirm remaining steps" gate is the single source of truth for the firing condition (confirm_remaining_steps: true, or fast_mode_active)
• Step 11 rule-update commit gate — when interactive_commits: true and Skill(extract-rules) wrote uncommitted changes under any of its three output directories, propose one commit (per-commit Present / accept / adjust(pathspec-narrow) / cancel mechanics, judged per § Approval token closed list); reuses references/interactive-commits.md § Post-commit auto-modify cycle bound (so the fold-or-defer sub-gate can fire), renders commit data verbatim, emits no § User-gate summary preamble (Step 11's "Commit rule updates" sub-step)
• Step 11.6 workability-candidate disposition gate — per-candidate 4-way disposition (act now / make a subtask / save to backlog / reject; ambiguous responses re-present the candidate), presented once with a § User-gate summary preamble; fires only when workability_retrospective.enabled and ≥ 1 candidate (references/workability-retrospective.md § 4. Disposition gate; the backlog-write / state-file-create failure classes are non-fatal — recorded and continued, per § 6)
• Completion execution-time deferral/exclusion gate — on a decomposed-subtask run with in-scope items excluded / deferred / discovered-unassigned, ask to promote each: (a) new pending subtask (with depends_on if sequencing matters), (b) fold into an existing pending subtask, or (c) accept as out of parent-task scope; fires conditionally (Completion's "Execution-time deferral/exclusion gate" paragraph)
• Completion subtask PR URL prompt — on a decomposed-subtask run, ask for the optional PR URL before resuming (Completion)

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. The No-Stall Principle governs successful step outcomes (including no-op successes); it does not force the agent to push through genuine errors.

At any point not listed above — including after Skill(simplify) / Skill(tidy), Skill(prose-polish), Skill(rules-review), Skill(extract-rules), Skill(run-tests), and reviewer skills 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, when the Step 4 visual or crit plan-review gate is active, its wait for the browser submit is a harness-tracked background boundary — proceed on the background serve.mjs / crit 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/crit gate's serve.mjs/crit 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 (the § Progress Visibility pre-call status line already covers this), 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 periodically re-invokes the agent before the completion notification arrives (e.g. a scheduled keep-alive restart) and no new information has arrived since the last turn, still issue the required tool call (e.g. reissue the same wait/monitor action) but omit any acknowledgment or status prose — a no-new-signal restart is not a decision moment, and prose around it is exactly the waiting-turn pattern this paragraph forbids.

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 iteration 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: Skill(ask-peer) / Skill(ask-claude) / Skill(ask-codex) / Skill(ask-gemini) / Skill(ask-copilot) / Skill(ask-agy) returning no actionable findings at Step 3 or Step 8 (at Step 8, whether returned inline or collected from the Step 7 background launch), Skill(simplify) / Skill(tidy) / Skill(prose-polish) returning no changes, Skill(rules-review) returning no violations (whether returned inline or collected from the Step 7 background launch), Skill(extract-rules) returning no new rules at Step 11, and any other sub-skill whose result is treated as success.

Callee verdict transcription is not a turn boundary. When a sub-skill (Skill(simplify) / Skill(tidy) / Skill(rules-review) / Skill(extract-rules) / Skill(run-tests) / reviewer skills / any other callee) 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" / "続けて". This rule extends the "no-summary turn" rule above to the case where the sub-skill returned an actionable result and the orchestrator's response carries the verdict's content forward — the verdict transcription itself is informational, not terminal. (For skill development this covers Pattern A iteration loop verdict returns where the orchestrator re-renders the JSON before re-dispatching, orchestrator multi-callee chains where one callee's verdict feeds the next callee dispatch, sequential sub-step completion marking, and hook-chain continuations.) 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 plan review (iteration 1 of N)…"), as prose in the same assistant turn that issues the tool call, not a separate preceding turn — so the user can distinguish active progress from a stall. 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, the single pre-call rule above does not cover the whole visibility window: 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 / prev files (.claude/plans/<slug>.plan-review.md / .plan-review.comments.json / .plan-review.prev.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 (the workflow owns these files as its operational substrate) — not gated on .gitignore presence, formatter-ignore alignment, or whether the user is touching them this run. Steps that build a changed-file set, diff-scope set, or commit grouping apply this single shared exclusion rather than re-deriving the rationale per step. If a future change adds another in-session-state path, extend this canonical list once rather than threading the exclusion through per-step prose (sub-skills that maintain their own in-session state under .claude/ follow the same convention).

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 (the single definition referenced by the Step 3 / Step 8 inline-reviewer subagent_model propagation): 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 — these run their own non-Claude models and are not subagent_model-controllable (never receive a propagated model). Initialize the bundle-unavailability ledger here: set bundle_skills_unavailable = [] — same cross-step-ledger mechanism as difficulty_skipped_steps (§ Completion's difficulty-skip reminder; declared here rather than there because this sub-step is the earliest site that may need to append to it). 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 — the reference files that append these records are shared with sibling workflows that number their phases differently). 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 — most of the five have exactly one call site, but prose-polish has two independent ones (Step 4 and Step 6.5) and may append one record for each if both fail; neither site is recorded twice. Probe the resolved reviewer's availability immediately — the default ask-peer is an independently-installable dev-workflow-bundle 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 review iteration counts — N_plan (Plan Review, Step 3) and N_code (Code Review, Step 8). A scalar config, the -i option, and the default all set both values equally; only the map config form makes them differ:
5. If -i / --iterations option is present and is a positive integer, set both N_plan and N_code to it (the option overrides both phases). `0` is deliberately not accepted here — turning a phase off is a project-level decision expressed in config (§ Configuration's review_iterations bullet), and an -i 0 run would carry no assessed tier for Step 4's rewrite-approach exceptions to key on, since -i skips Adjust N entirely. -i 0 therefore falls through to leg 2
6. Else if config review_iterations is present:

• scalar non-negative integer → set both N_plan and N_code to it
• map ({plan, code}) → N_plan = plan if it is a non-negative integer else default 3; N_code = code if it is a non-negative integer else default 3 (per-key validation, independent per phase; warn on each absent/invalid key)
• any other value (negative or non-integer scalar, list, string, or any non-map / non-scalar type) → warn and set both to default 3 (any map takes the map branch above — an empty map, or a map with no valid plan / code key, already resolves to default 3 per phase there)

1. Else use default 3 for both

Wherever a later step says "N" without a phase qualifier, Step 3 references resolve to N_plan and Step 8 references to N_code. A resolved `0` is a valid outcome, not a validation failure (§ Configuration's review_iterations bullet) — it routes the phase to the same skip the Trivial tier produces; see Step 3's and Step 8's N = 0 exception paragraphs.

1. Parse the remaining config keys and emit the Language checkpoint (Output language: <lang>). The full parse detail — hooks / custom_instructions / interactive_commits / compact_rules / plan_review_gate (+ the legacy visual_plan_review mapping) / commit_review_gate / implementation_executor (+ the --executor override) / polish_prose / confirm_remaining_steps / 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.
2. Determine execution sub-mode: Resume if --resume <state-file> was provided, otherwise Normal. Step 1.5 branches on this. Resolve fast_mode_active (boolean) from whether --fast was passed on this invocation — invocation-only, no config key (see Step 2's Adjust N by difficulty for its effect on N_plan/N_code, and § No-Stall Principle's confirm_remaining_steps entry gate bullet for its effect on Step 11)
3. Register all workflow phases with the Task tools, including review iterations — 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
• Step 3-1 through Step 3-N_plan: Plan Review - iteration 1 through N_plan (generate N_plan items based on resolved N_plan)
• 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
• Step 8-1 through Step 8-N_code: Code Review - iteration 1 through N_code (generate N_code items based on resolved N_code)
• 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 Step 2 difficulty assessment — see Step 11.6)

Step 1 registration mechanics: issue every TaskCreate in one upfront burst (before Step 2) so all phases register first; conditionally-omitted phases (list items above carrying a condition) are omitted by not issuing their TaskCreate; N-reduced excess iteration tasks (Step 3-x beyond N_plan / Step 8-x beyond N_code) are still created here at the resolved ceiling, then marked completed by Step 2's Adjust N by difficulty. `N = 0` clause: when Step 1 sub-step 4's N resolution already produced a phase's N of 0 (a configured review_iterations of 0), that ceiling is 0, so the phase gets no iteration rows at all and its top-level row (Step 3: Plan Review / Step 8: Code Review) is registered directly as completed — the skip is settled here rather than by Adjust N, which never raises a 0. Where the Task tools (TaskCreate / TaskUpdate / TaskList, the default since Claude Code v2.1.142) 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 iteration sub-rows Step 3-i / Step 8-i, 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 guards against silent phase-skipping (e.g. jumping Step 5 Implement → Step 7 Check / Test without running Step 6 Tidy) that task registration alone cannot prevent. Implementation sub-tasks in Step 5 are additions, not replacements. Note: Unless -i / --iterations was explicitly specified, Step 2 may reduce N_plan / N_code based on task difficulty.

1. 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 — including which skip conditions to re-verify and the fast_mode_active inference note — is in `references/step1-load-settings.md` § Sub-step 8 — Context-compaction recovery.
2. 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.

State-file semantics are critical (a malformed or mis-routed file silently corrupts subtask boundaries), so the full procedure lives in a dedicated reference. Dispatch:

• Resume sub-mode (--resume <state-file> was provided): read `references/task-decomposition.md` and follow section A. Resume sub-mode from top to bottom.
• Normal sub-mode: read `references/task-decomposition.md` and follow section B. Normal sub-mode.

EnterPlanMode is reserved for Step 2 (and only when plan_mode_active is true — i.e. plan_review_gate: "plan-mode"; on the visual / crit paths Step 2 skips Plan Mode, see § Configuration) — any decomposition proposal in Step 1.5 is a plain yes/no dialogue, not a plan.

After section A or B completes, 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. Initialize these cross-step variables at Step 2 entry, outside the -i-gated Adjust N sub-step below, so each is well-defined on every path (including the -i path, where Adjust N never runs); the hoist rationale is in `references/step2-create-plan.md` § Sub-step 1 — init narration:

1. Resolve `plan_mode_active`, then conditionally enter Plan Mode: set plan_mode_active = (plan_review_gate == "plan-mode") — a derived alias of the run-invariant plan_review_gate setting (read once, never reassigned — including on a Step 4 rewrite-approach re-entry). When plan_mode_active is true (plan_review_gate: "plan-mode"), call EnterPlanMode. When plan_mode_active is false (the default — plan_review_gate: "visual", or the opt-in "crit"), do not enter Plan Mode: Step 4's visual / crit gates and their no-Plan-Mode chat fallback perform non-read-only operations (writing the served plan file, launching node serve.mjs or the crit CLI) that Plan Mode's read-only restriction forbids, so these gates can only fire outside Plan Mode (see § Configuration's plan_review_gate bullet). In this no-Plan-Mode case the sub-step 6 "No code changes in this phase" rule is enforced by agent discipline alone, not by Plan Mode's read-only lock — hold to it through the Step 4 approval gate.

Sub-steps 3–5, sub-step 7's full body, and the sub-step 1 init narration 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, and the Codebase-research delegation guidance; sub-step 4 is the Simplicity self-audit; sub-step 5 the Plan self-check; sub-step 7's full body is the Adjust N by difficulty procedure. Sub-steps 1 (init table), 2, 6, and 8 stay inline; sub-step 7 keeps its label + resolved-state contract inline (below).

1. No code changes in this phase
2. Adjust N by difficulty — skipped when -i / --iterations was given, except the --fast Step 6.5-only skip (which always runs regardless of -i). Based on the plan, assess task difficulty (Trivial / Simple / Moderate / Complex) and cap N_plan / N_code independently (the configured value is a ceiling): Trivial → both 0 (Step 3 + Step 8 skipped entirely); Simple → both min(1, ·); Moderate → min(2, ·); Complex → unchanged. Every tier lowers, none raises — the min form is what makes that hold, so a configured 0 (§ Configuration's review_iterations bullet) stays 0 on every tier including Complex. This sub-step resolves the cross-step state later steps read: N_plan (Step 3) / N_code (Step 8); `subagent_model` (from the assessed tier — see § Configuration's subagent_model read-site list); the difficulty-skip matrix (on Trivial / Simple, mark Step 6: Tidy / Step 6.5: Polish Prose / Step 7.5: Rules Compliance Review completed and append to difficulty_skipped_steps); and `--fast` N-forcing (on a non-Trivial tier set N_plan = 0 and N_code = min(1, N_code), appending Step 3 Plan Review skipped (fast mode) to fast_mode_skipped_steps only when N_plan was ≥ 1 before the forcing — a plan phase already configured 0 was not skipped by fast mode). Step 9 (Completion Hooks) is never matrix-skipped. Mark excess iteration items (Step 3-x beyond N_plan, Step 8-x beyond N_code) completed; Trivial additionally marks the top-level Step 3: Plan Review / Step 8: Code Review rows completed (both skipped), while --fast-forced N_plan=0 on a non-Trivial tier marks only the Step 3 rows (--fast sets N_code = min(1, N_code), so Step 8 still runs unless the code phase is configured 0). The full tier criteria (including the external-library major-bump escalation that lifts Simple → Moderate), the row-marking mechanics, the subagent_model resolution, the difficulty log line, and the --fast Step 6.5-only skip are in `references/step2-create-plan.md` sub-step 7; Read it and follow it top to bottom.
3. Do not present the plan to the user or ask for approval/confirmation — presenting an unreviewed plan wastes user time and risks approval of a suboptimal approach. This 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 — these read as natural conversation but constitute the same approval-gate that wastes user attention on an unreviewed plan. 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 N_plan=0 — see Step 3's N = 0 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 — the reviewer refines the plan before the user sees it, so the user receives a higher-quality plan in Step 4. Do not present the plan to the user or ask for feedback during this step.

`N = 0` exception. When N_plan = 0 this entire step is skipped. This is the closed list of causes — append here when another is introduced:

• a Trivial task (Trivial zeroes both N_plan and N_code, via Step 2's Adjust N by difficulty);
• `--fast` forcing N_plan=0 on a non-Trivial tier (also via Adjust N; it leaves N_code at min(1, N_code) rather than zeroing it);
• a configured `review_iterations` of 0 for the plan phase (§ Configuration's review_iterations bullet) — resolved at Step 1 sub-step 4's N resolution, before Adjust N runs, and never raised by it.

Whichever cause applies, the step's rows are already completed on entry — marked by Adjust N on the first two causes, and by the registration burst on the configured-0 cause (§ Step 1 registration mechanics' N = 0 clause) — so do not re-mark them in_progress. This skip is gated on N_plan itself, not on the presence of user-provided analysis — the analysis-substitution prohibition below still applies in full to every task with N_plan ≥ 1.

Always run (for N_plan ≥ 1). 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. User-provided analysis is upstream planning content the user wrote — it is not an independent bias-free peer review pass and does not substitute for the reviewer dispatch. 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 N = 0 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.

The existing per-iteration "No actionable findings" semantic-judgment skip continues to work — that is a reviewer-side decision (the reviewer ran and returned no actionable feedback), not a Step-skip.

If N_plan = 0, skip this step entirely (see the N = 0 exception above) — its rows are already completed, so do not re-mark them in_progress and proceed directly to Step 4. The following in_progress marking and per-iteration processing apply only when N_plan ≥ 1.

Mark Step 3: Plan Review as in_progress. Process each pending iteration item (Step 3-1 through 3-N_plan) in order:

Read `references/step3-plan-review.md` and run its per-iteration procedure for each Step 3-x item in order — sub-step 1 (call the resolved reviewer with the six-category review payload — categories a–f, full rubric 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, mark this and remaining items completed and proceed to Step 4), sub-step 3 (apply improvements or reject with reason; the iter-1→2 approach-reconsideration self-audit and the prose-integrity self-check live there; re-review after any modification), and sub-step 4 (carry unresolved points to Step 4). The per-iteration Return-point no-stall reminder also lives in that reference — moved with the loop body, unlike Step 8's same-shape reminder which stays inline because Step 8's loop skeleton is inline; the two are functionally equivalent, so this placement asymmetry is not a sibling-symmetry defect.

Mark Step 3: Plan Review as completed.

Step 4: Finalize Plan (USER APPROVAL GATE)

1. Step 3-completion verification: before presenting (the surface chosen in sub-step 2), verify via TaskList that Step 3: Plan Review and every Step 3-x item are completed; if any is still pending / in_progress, note the incomplete items to the user and return to Step 3 before presenting (do not flip a row completed without doing the review). Exception: N_plan=0 (see Step 3's N = 0 exception) leaves all Step 3 rows completed — that is the intended skip, not an unrun-review bug. 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/plan-format.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.

1. Plan presentation — branch on `plan_mode_active` (resolved at Step 2 sub-step 2's conditional Plan-Mode entry). Sub-steps 1, 1.5, and 3 apply to every path unchanged.

The presentation body — the plan-body prose-polish pass (gated on polish_prose true + not fast_mode_active; the file-mode dispatch and its unavailability handling are in the reference), path (a) (plan_mode_active == true — write the full plan to the Plan Mode file, present the condensed chat view items a–e, then call ExitPlanMode in the same turn), and path (b) (plan_mode_active == false — establish .claude/plans/<slug>.md, then run the resolved plan_review_gate as a crit → visual → chat-approval fallback chain, each surface owning its own availability / reachability determination and returning approve / rewrite-approach / fallback) — is in `references/step4-finalize-plan.md`; Read it and follow the path applicable to the resolved plan_mode_active / plan_review_gate. On approve proceed to implementation (no ExitPlanMode on path (b)); on rewrite-approach handle per sub-step 3's rewrite-approach bucket.

1. Collaborate with the user to refine the plan as needed (normal Plan Mode interaction on path (a); normal chat / visual-gate interaction on path (b) — a swap-decisions / rewrite-approach re-presentation re-enters whichever surface this run uses: the ExitPlanMode modal on path (a), the relaunched visual/crit gate or the chat re-present on path (b)). 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 so partial-coverage misses cannot slip through.
• 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 adds a new review iteration item (Step 3-(N_plan+1)), 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`-forced-N_plan=0 exception (which a configured plan-phase `review_iterations` of `0` shares — the user turned the phase off, so a material change must not re-enable it), and the Trivial (N_plan=0) re-activation that re-derives the difficulty assessment, re-marks the Step 3 / Step 8 / Step 6 / Step 6.5 / Step 7.5 rows, and re-populates the `difficulty_skipped_steps` / `fast_mode_skipped_steps` ledgers. When `--fast`, a configured plan-phase `0`, or a Trivial (N_plan=0) task is in play, read [`references/step4-finalize-plan.md`](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 is the gate-of-origin's own resolution branch; do not nest a separate ExitPlanMode call inside 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. The read-back catches multi-Decisions instructions with partial coverage and Approach-level instructions that masquerade as Decisions swaps — both are common failure modes that silently lose user-specified scope when interpreted without read-back.

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–10. Sub-steps 1, 3–8, and 10 — the plan-entry manual-action check (1), prior-edit respect (3), and 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), and the side-effecting external-tool launch warning (10) — are in `references/step5-implement.md`; Read it and apply each sub-step in order. Sub-step 2 keeps its core directive + a delegation-route contract inline, and sub-step 9 is retained inline because other steps read them: sub-step 2's delegation-route contract defines the implementation_executor / subagent_model route (referenced by § Configuration's Agent tool usage bullet; the full delegation body is in the reference), and sub-step 9 records implementation_diff_paths (read by § Step 10's Post-hook attribution check).

1. 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-format.md` § Template), 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. This is consistent with Step 1's "Implementation sub-tasks in Step 5 are additions, not replacements" rule and does not change the Phase-boundary self-audit (which governs only top-level Step transitions). 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 two sanctioned Agent exceptions in § Configuration's Agent tool usage bullet (the other is the Step 2 research delegation) 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.

1. 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 § Step 10's "Post-hook attribution check" paragraph to identify on-disk changes introduced during the review-hook phase (Steps 6–9) that no review hook claimed responsibility for.

Step 6: Tidy

Implementation often introduces unnecessary complexity that's easier to spot in a dedicated pass after the code works.

Difficulty exception (difficulty-skip matrix). When Step 2 marked Step 6: Tidy completed under the difficulty-skip matrix (Trivial or Simple tier — see Step 2's Adjust N by difficulty), the row is already completed: do not re-mark it in_progress; proceed directly to Step 6.5. The Phase-boundary self-audit (§ Step 1 registration mechanics) treats this pre-completed row as the intended skip exactly as it does the Trivial Step 3 / Step 8 skips, not an unrun-step bug.

The Step 6 cleanup callee is resolved per the Cleanup skill bullet in § Prerequisites (built-in simplify preferred, bundled tidy as fallback). The phase is named "Tidy" after that in-house fallback skill; when simplify is available it — not tidy — is the primary callee.

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 — without a handoff, the same structural concern is re-raised and re-judged independently by each layer, and a finding one layer deferred or applied only partially resurfaces later as scattered per-site fixes. 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 (no prior layer deferred, applied, or left anything over), omit the ledger 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. It runs after Step 6 Tidy (Tidy's comment deletions land first, so prose-polish refines only the survivors) and before Step 7 (so Step 7 validates the polished result).

Difficulty exception (pre-completed row, two independent causes). When Step 6.5's row is already completed on entry, it is for one of two reasons — do not re-mark it in_progress; proceed directly to Step 7 either way: (a) the difficulty-skip matrix (Trivial or Simple tier, coupled with Step 6 Tidy and Step 7.5 in that case; see Step 2's Adjust N by difficulty), or (b) --fast's independent Step 6.5-only skip (Step 6 Tidy still runs in this case — see Step 2's Adjust N by difficulty). The Phase-boundary self-audit (§ Step 1 registration mechanics) treats this pre-completed row as the intended skip under either cause exactly as it does the Trivial Step 3 / Step 8 skips, not an unrun-step bug.

`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` — on Trivial / Simple the difficulty exception above already owns the skip and proceeded to Step 7, so the polish_prose note is not emitted there; the same applies when --fast's Step 6.5-only skip pre-completed the row on a Moderate / Complex tier. This gate's own 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; the abstract enumeration in § No-Stall Principle is intentionally duplicated here so the rule fires at the decision moment.

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, consistent with the No-Stall Principle's allowance for explicit step-defined stops): 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, optionally 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 (a caller-imposed nesting bound, not an availability claim), and apply no edits (the main thread applies fixes later). test_commands is never backgrounded (run-tests lacks the inline fallback that rules-review / ask-peer have for that nesting bound). 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 iteration 1; collected at Step 8 sub-step 1. Skip when N_code = 0 (see Step 8's N = 0 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), because staleness invalidates the entire report and only the fresh dispatch's result is valid. Setting _stale on a no-launch path is a safe no-op. Pass (the term the collects reference) = the only Step 7 entry a collect follows = the initial Step 7 entry; Step 8 defers verification to loop exit and never re-enters Step 7, so both launches are initial-pass-only. The full dispatch procedure (never-backgrounded rationale, the availability-detection criterion, the per-launch dispatch bullets, the orphan-avoidance and staleness set-site rationale) 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.

1. 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.

1. 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 Step 2 pre-completed it under the difficulty-skip matrix (Trivial or Simple tier) — in that case the row is already completed; do not re-mark it in_progress, skip straight to Step 8 (same already-completed-row handling as the Step 8 GATE's N_code=0 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, separate from code review (Step 8). This ensures rule enforcement gets focused attention rather than competing with correctness and design concerns.

Difficulty exception (difficulty-skip matrix). When Step 2 marked Step 7.5: Rules Compliance Review completed under the difficulty-skip matrix (Trivial or Simple tier — see Step 2's Adjust N by difficulty), the row is already completed: do not re-mark it in_progress; proceed directly to Step 8. The Phase-boundary self-audit (§ Step 1 registration mechanics) treats this pre-completed row as the intended skip exactly as it does the Trivial Step 3 / Step 8 skips, not an unrun-step bug.

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 → mark completed on nothing-actionable), and 3 (fix all violations with pattern-class self-sweep → re-run Step 7 → 2nd-cycle re-verify → persistent-violations gate) plus the --fast 1-pass cap. Mark Step 7.5: Rules Compliance Review completed only after all violations are resolved (or, under --fast, after the fix + Step 7 re-run land) or the user decides on remaining violations.

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) sets code_review_stale = true (so Step 8 sub-step 1 discards its now-stale background result and re-dispatches), and the --fast 1-pass cap appends Step 7.5 Rules Compliance Review re-verification skipped (fast mode) to fast_mode_skipped_steps — both transitions execute inside the reference procedure.

Reuse note: Step 8's "Deferred verification (Step 8 fix aggregate)" paragraph reuses `references/step7.5-rules-compliance.md`'s sub-steps 2 / 3(a)–(d) and the --fast 1-pass cap for its loop-exit scoped rules-review, remapping their exit targets (its "proceed to Step 8" / "mark Step 7.5 completed" / sub-step (d) wait) — see that paragraph's "Exit-target remap" closed list. When adding or changing an exit site in that reference, update the remap list too.

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 N_code ≥ 1; if N_code=0 (see the N = 0 exception below), Step 8 is already completed — do not re-mark it in_progress, skip straight to Step 9. (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

Code review catches bugs, convention violations, and design issues that tests alone miss — skipping it risks shipping preventable defects. Always run this step even when tests pass cleanly.

`N = 0` exception. When N_code = 0 this entire step is skipped. This is the closed list of causes (--fast is not among them — it caps the code phase at 1 rather than zeroing it) — append here when another is introduced:

• a Trivial task (Trivial zeroes both N_plan and N_code, via Step 2's Adjust N by difficulty);
• a configured `review_iterations` of 0 for the code phase (§ Configuration's review_iterations bullet) — resolved at Step 1 sub-step 4's N resolution, before Adjust N runs, and never raised by it.

Either way the step's rows (top-level Step 8: Code Review and every Step 8-x) are already completed on entry — marked by Adjust N on the Trivial cause, and by the registration burst on the configured-0 cause (§ Step 1 registration mechanics' N = 0 clause). This skip is gated on N_code itself, not on task difficulty: a Simple / Moderate / Complex task whose configured code phase is 0 skips Step 8 too.

If N_code = 0, skip this step entirely (see the N = 0 exception above) — its rows are already completed, so do not re-mark them in_progress and proceed directly to Step 9 (Completion Hooks). The following in_progress marking and per-iteration processing apply only when N_code ≥ 1.

Mark Step 8: Code Review as in_progress. Process each pending iteration item (Step 8-1 through 8-N_code) in order:

1. Mark the iteration item as in_progress. Obtain this iteration's 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 is initial-pass-only (iteration 1 collects at most once; iterations 2+ always dispatch fresh, since Step 8 defers verification to loop exit and never re-enters Step 7). 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, exactly as Step 3) — the background-launch path already carries it via the Step 7 launch's Agent model, so the two never double-apply. 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, covering the git diff <base-commit> + untracked-new-files inclusion, the .claude/rules/ safety-net note with its per-tier weighting, the three review categories (a. Correctness & edge cases / b. Conventions & consistency / c. Simplicity & maintainability, full rubric in `references/review-categories.md` § Code review categories), the custom_instructions inclusion, the state-file subtask-scope note, the cross-layer review handoff ledger, and the iteration-2+ continuation item + iteration-scope instruction — is in `references/step8-code-review.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 this and remaining iteration items as completed (skip), then proceed to the loop-exit Deferred verification (Step 8 fix aggregate) pass and the completion line below. Do not mark Step 8: Code Review completed or jump to Step 9 directly from here: an earlier iteration may have applied fixes (step8_fix_files non-empty) that still owe the deferred check/test + scoped rules-review (the deferred pass is a no-op when step8_fix_files is empty, e.g. a first-iteration no-findings exit). Per the No-Stall Principle, do not wait for user input and do not rely on exact-phrase matching; trust semantic judgment since the reviewer skill's phrasing varies (especially Skill(ask-peer) and other free-form-prose reviewers whose verdicts are 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 iteration item 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. Step 8 defers all per-iteration verification (check/test + rules-review) to a single pass at loop exit — see the Deferred verification (Step 8 fix aggregate) paragraph below. Instead: (i) append the repo-relative paths of the files this iteration's fixes edited to step8_fix_files (per its accumulation-window rule — see § Step 2's step8_fix_files init), and (ii) continue to the next pending iteration item (back to step 1). Because no Step 7 re-entry occurs, no background launch re-fires; the next iteration's reviewer is therefore obtained via Step 8 sub-step 1's fresh-dispatch path (code_review_launched stays false for the rest of the loop). Deferring per-iteration verification is deliberate (the user-approved design), not a short-circuit — the loop-exit pass verifies the aggregate of all Step 8 fixes once, which is exactly why accumulating every fixed file into step8_fix_files (regardless of which iteration or fix path produced it) is load-bearing. The only iteration that appends nothing is one that modified no code (handled by the next bullet).
• If all points were rejected (no modifications): mark remaining iteration items as completed (skip — there is nothing new for the next reviewer to look at)

Continue to the next pending iteration item; the next iteration's reviewer is dispatched fresh and composes its payload per sub-step 1's definition, continuation item and iteration-scope instruction included — not restated here.

Return-point no-stall reminder: At each iteration boundary (regardless of reviewer outcome — findings reported, "No actionable findings", any non-error result), the next action — the next iteration's fresh reviewer dispatch when more iteration items remain, or the loop-exit Deferred verification pass (then the Step 9 (Completion Hooks) transition) when this was the last iteration or "No actionable findings" was returned — must be issued in the next tool call. Do not insert an interstitial summary or acknowledgment turn between iterations; the abstract enumeration in § No-Stall Principle is intentionally duplicated here so the rule fires at the decision moment.

1. If all N_code iteration items are completed and actionable feedback still remains, 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/plan-format.md` § Localization granularity in the resolved language. Any fix applied while resolving this gate appends its edited files to step8_fix_files (§ Step 2's accumulation-window rule) before the Deferred verification pass below runs, so a user-directed fix here is still covered by the loop-exit check/test + scoped rules-review.

Deferred verification (Step 8 fix aggregate). After the Step 8 iteration loop settles (all iterations processed, an early "No actionable findings" / all-rejected exit, or sub-step 4's unresolved-findings gate resolved) and before marking Step 8 completed, run the verification the per-iteration re-runs no longer perform. Two gates, in order:

1. check/test — gate: `step8_fix_files` non-empty. If Step 8 applied at least one code fix, run Step 7 (Check / Test) once against the current working tree (the aggregate of all Step 8 fixes). This is a plain check/test pass: it fires no concurrent background launches (no pending Step 8 iteration will collect code-review, and any rules-review that follows runs inline), and the Step 7 3-retry loop applies. Any test-failure fixes applied here append their edited files to step8_fix_files (§ Step 2'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: `step8_fix_files` non-empty AND the initial Step 7.5 pass actually ran (i.e. Step 7.5 was not difficulty-skipped on Trivial / Simple — on Trivial, N_code=0 skips Step 8 entirely so this never arises (as does a configured code-phase 0, for the same reason); on Simple, the matrix skipped Step 7.5 and made Step 8 the primary rules-compliance defense, so this deferred rules-review is skipped too, tier semantics preserved and the check/test gate above having run). When both legs hold, run the Step 7.5 procedure (`references/step7.5-rules-compliance.md`) once as a scoped re-check over Files: <step8_fix_files>, reusing its sub-steps 2 / 3(a)–(d) + the --fast 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, the sub-step reuse deltas (scoped 2nd-cycle re-run; the differentiated Step 7.5 Rules Compliance Review deferred re-verification skipped (fast mode) ledger string), and the coverage tradeoff (Decision 3: a fix here is verified by its own scoped 2nd cycle + the Step 10 commit gate but not re-reviewed by code review) — is in `references/step8-code-review.md` § Deferred verification — gate 2 scoped rules-review detail; Read and apply it.

Exit-target remap (closed list of 3). The reused sub-steps hard-code exits toward Step 8; here they mean: (i) every "proceed to Step 8" → fall through to the "Mark `Step 8: Code Review` as `completed`" line below; (ii) every "mark Step 7.5: Rules Compliance Review as completed" → no-op (the row stays completed from the initial pass — do not re-flip it); (iii) sub-step (d)'s "Wait for user response before marking completed" gates Step 8's completion (→ Step 9) here.

When neither gate fires (step8_fix_files empty), proceed straight to the completion line.

Mark Step 8: Code Review as completed.

Step 9: Completion Hooks

Skip this step if hooks.on_complete is not configured. Mark Step 9: Completion Hooks as in_progress.

Task-derived-change gate: before executing any entry, check whether the tracked diff since <base-commit> (recorded in Step 2) contains changes produced by this task. When it does not — the tracked diff is empty or every changed path in it is pre-existing work unrelated to this task, and git status --porcelain=v1 --untracked-files=all shows no task-derived untracked files (gitignored paths never appear in that output, so the typical case — the task's only deliverables living under a gitignored directory — still skips) — skip the whole hooks.on_complete list, mark this step completed, and emit one line in the Completion summary naming the skip reason (e.g. hooks.on_complete skipped: no task-derived changes), then proceed to Step 10 (or directly to Step 11 when interactive_commits: false — per § Step 10). When an unrelated pre-existing diff exists, also add a warning line surfacing those paths (e.g. hooks.on_complete skip warning: pre-existing unrelated diff in <path>, <path>) so the user can notice unintended pre-run changes. Review-class hooks dispatched against an unrelated diff bind their findings to content the task never touched — a misleading record rather than a safety net; skipping the non-review entries along with them is likewise intended — with no task-derived changes there is no task output for any hook entry to act on. On any doubt about whether a changed path is task-derived, run the hooks as usual (the gate skips only when the absence of task-derived changes (tracked or untracked) is clear).

Step 9's procedure — sub-step 1 (classify each entry review-class / non-review-class; run review-class concurrently when background dispatch is available, else sequential; review-class write reconciliation), sub-step 2 (decomposed-run state-file guard), sub-step 3 (hook-failure handling), and sub-step 4 (post-hook check_commands re-run, then mark Step 9: Completion Hooks as completed and proceed to Step 10) — is in `references/step9-completion-hooks.md`; Read it and follow the procedure from top to bottom.

GATE: Verify Steps 2-9 are completed (check task status via TaskList; if status is inconsistent, verify actual completion by reviewing work done). Mark Step 10 as in_progress.

Step 10: Interactive Commits

After hooks.on_complete (which may itself modify the working tree, e.g. via auto-formatter or apply-edit hook entries), group the working-tree changes into commits and iterate with the user one commit at a time. Step 10 runs only when interactive_commits: true — Step 1's task registration omits the row otherwise and execution proceeds directly from Step 9 to Step 11. The git push is never performed by this step (or any other step): pushing commits to a remote is the user's responsibility.

Unexpected current branch is not itself a signal to investigate: if the current branch differs from earlier in the session, that is expected when the execution environment pre-creates or switches to a dedicated working branch before the first tool call. As long as the current branch's history contains <base-commit> (recorded in Step 2 — verify with git merge-base --is-ancestor <base-commit> HEAD; zero exit = it does), treat the difference as normal and skip any root-cause investigation. If that check exits non-zero, the branch does not descend from <base-commit> — not the expected pre-created-branch case: stop and surface the discrepancy to the user for direction (consistent with the No-Stall Principle's allowance for explicit step-defined stops) rather than investigating or switching branches unilaterally.

On entry to Step 10, initialize landed_count = 0 before running the procedure — so the value is well-defined for the Completion section even when the empty-output skip path in references/interactive-commits.md § Collect changes fires before its § Per-commit loop ever starts.

Post-hook attribution check: run git diff <base-commit> --name-only for all currently changed paths (step10_diff_paths). Compute hook_introduced_paths = step10_diff_paths − implementation_diff_paths (captured at § Step 5's "Implementation diff snapshot" paragraph) — paths that appeared during the review-hook phase (Steps 6–9), not during implementation. First subtract the § Workflow artifacts (cross-step fixed exclusion) set so workflow-owned in-session state is never flagged as unattributed. Cross-reference the remainder against the § Step 6 Cross-layer review handoff ledger's applied sites: any hook_introduced_paths entry NOT covered by a ledger applied-site is unattributed — a change no review hook claimed responsibility for. When unattributed paths exist, surface each with git diff <base-commit> -- <path> and require explicit resolution before commit grouping: (i) confirm as an expected side-effect (an auto-formatter the plan authorized, a hook's non-review output) and continue, or (ii) revert with git checkout HEAD -- <path>. When none exist (empty, or every entry ledger-covered), proceed directly to references/interactive-commits.md.

Read `references/interactive-commits.md` and follow the procedure from top to bottom — it is the single canonical home for Step 10's procedure body. The Approval token closed list and Localized summary tokens below stay defined in this file and are referenced from both that procedure and other Steps.

Approval token closed list (per § No-Stall Principle's "do not rely on exact-phrase matching" rule). The example phrases below are illustrative, not literal discriminators — categorize each user response into one of the four buckets via semantic judgment. When presenting an approval gate, include at least one short-form token from the accept bucket (e.g., "OK", "LGTM", "next") so users know brief responses are valid.

• accept: explicit affirmative — "OK" / "approve" / "next" / "LGTM" / "コミットして" / "進めて" / "いいよ" or any semantic equivalent
• adjust: specific revision request — "subject を ... に" / "this file should be in commit 2" / "split this commit" / any other concrete change demand
• cancel / stop: explicit halt — "stop" / "abort" / "やめる" / "中断"
• NOT approval: interrogative or non-committal — "look good?" / "どう？" / "これでいい？" / "OK ？". Treat as adjust and re-present (do not silently advance)

Localized summary tokens (per `references/plan-format.md` § Localization granularity). These tokens are defined here as the single source of truth — § Completion below references the same paired form rather than re-rendering it:

• language: ja: Step 10（Interactive Commits）部分完了: <N>/<total> コミット適用済み
• language: en: Step 10 (Interactive Commits) partial completion: <N>/<total> commits landed

§ Completion below emits the localized token whenever Step 10 ended via Mid-loop cancel (see references/interactive-commits.md § Mid-loop cancel). On a normal completion path (every commit landed, or the Mid-loop adjust un-landed-drops-to-zero / merge-absorbs-into-landed branches — see references/interactive-commits.md § Mid-loop adjust — closed-list branches), no partial-state line is needed.

Step 11: Update Rules

Confirm remaining steps (USER APPROVAL GATE — when `confirm_remaining_steps: true`, or when `fast_mode_active`). This gate is the single source of truth for the § No-Stall Principle's "Step 11 confirm-remaining-steps entry gate" bullet and for § Configuration's confirm_remaining_steps bullet. Present this gate when confirm_remaining_steps: true or fast_mode_active; otherwise (the default false, or a non-boolean that fell back to false, and --fast was not passed) skip this gate entirely and proceed to sub-step 1 — Step 11 / 11.5 / 11.6 run unconditionally as before. When presented, before running sub-step 1, ask in the resolved language whether to run the remaining rule-maintenance and retrospective steps — Step 11 (Update Rules), Step 11.5 (Self-Retrospective), Step 11.6 (Workability Retrospective), listing only the steps actually registered this run (each as number + name, per § Phase naming in user-facing output) — or skip them and go straight to Completion. Paired bilingual sample (runtime rendering demonstration):

• language: ja: 残りのステップ（<登録済みステップを番号 + 工程名で列挙>）を実施しますか？ 実施するなら「進める」、スキップして完了処理（Completion）へ移るなら「スキップ」と返してください。
• language: en: Run the remaining steps (<list the registered steps, each as number + phase name>)? Reply "proceed" to run them, or "skip" to go straight to Completion.

Classify the reply by semantic judgment per § No-Stall Principle's "do not rely on exact-phrase matching" rule (the example tokens are illustrative, not literal discriminators):

• proceed — affirmative ("proceed" / "進める" / "yes" / "実施" or any equivalent): the gate touches no state and falls through to sub-step 1 (rule extraction — the rule-extraction-active gate / shared session scan entry), exactly as the un-gated default.
• skip — decline ("skip" / "スキップ" / "不要" or any equivalent): mark the closed set {Step 11 (this step)} ∪ {Step 11.5 if registered} ∪ {Step 11.6 if registered} completed without running their procedures (Step 11 is always registered; Step 11.5 only when self_retrospective.feedback is set; Step 11.6 only when workability_retrospective.enabled: true). This is an intended skip, not an unrun-step bug — the Phase-boundary self-audit (§ Step 1 registration mechanics) treats these gate-marked rows like the difficulty-skip matrix's pre-completed rows (see Step 6 / 6.5 / 7.5's difficulty exception). Because sub-step 3's entry is bypassed, establish its cross-step variables at their initial values — compaction_applied_count = 0, below_threshold_failed_files = [] — so § Completion's compaction reminder reads them well-defined and is omitted (landed_count is Step 10's, untouched here). The shared session scan is not dispatched on skip — no participating step reaches its dispatch point, so session_scan_dispatched / session_scan_result stay at their Step 2-entry init (Completion does not read them). Emit a one-line skip note in the resolved language (immediately before Completion) so the skip is never silent (language: ja: confirm_remaining_steps: ユーザー選択により <登録済みステップを番号 + 工程名で列挙> を skip しました; language: en: confirm_remaining_steps: skipped <registered steps, each as number + phase name> per user choice — listing only the registered steps), then proceed to Completion.
• ambiguous (interrogative or non-committal — "どっち？" / "which?" / any non-decision): re-present the gate; do not silently pick a branch.

This gate emits no § User-gate summary preamble — it is a binary proceed / skip prompt with no structured content (see references/plan-format.md § User-gate summary preamble).

1. Rule extraction via the shared session scan → `Skill(extract-rules) --apply-conversation-candidates`. The prose coding-rule axis (.claude/rules/) is the rule-extraction axis of the shared conversation scan (references/session-scan.md): the shared scan produces a --- RULE-CANDIDATES --- block (the C4-equivalent candidates per references/rule-extraction-axis.md), and this sub-step hands that block to extract-rules Conversation Candidate Apply Mode (Step C5 only — dedup / route / write / promote / .examples.md / Security Self-Check; no jsonl re-parse). This is the apply half of a scan/apply split (the shared scan ingests the large session text once for all axes).

• `rule-extraction-active` gate: rule-extraction is inactive if (a) any entry in hooks.on_complete (as resolved in Step 1) contains the string extract-rules (direct invocation), OR (b) Step 9 executed at least one hook and its output (visible in this session's context) shows extract-rules --from-conversation ran this session (sufficient signal: output contains staged_count or promoted_count). When inactive, skip the rule-extraction work entirely — do not dispatch the shared scan on rule-extraction's behalf and do not call extract-rules. This single gate suppresses both conversation-derived extraction paths (the apply-only path below and its standalone fallback), preserving the staging double-count defense (running a conversation-derived extraction twice against one session would make the staged-promotion 1st→2nd-observation escalation miscount one session as two and prematurely promote candidates). When inactive but a retrospective axis is registered, Step 11 abstains and Step 11.5 / 11.6 dispatch the shared scan for their own axes (references/session-scan.md § Dispatch-once contract).
• When `rule-extraction-active`: dispatch the shared session scan (references/session-scan.md § Dispatch-once contract — first dispatch point when Step 11 is the earliest participating step; threads the Step 2-resolved subagent_model + resolved language), then consume the rule-extraction block and act on its disposition. Full dispatch procedure + the 4-case block disposition (well-formed → write .claude/plans/<slug>.rule-candidates.md + Skill(extract-rules) --apply-conversation-candidates; whole-scan Status: ERROR → skipped; per-axis malformed → standalone --from-conversation fallback; zero candidates → no-op) are in `references/update-rules.md` § Sub-step 1 — Rule-extraction dispatch & disposition.

Return-point no-stall reminder: after Skill(extract-rules) --apply-conversation-candidates (or the standalone --from-conversation fallback) returns — regardless of outcome (rules applied, nothing to apply, promoted / staged counts, any non-error result) — issue the next action (sub-step 2) in the next tool call. Do not insert an interstitial summary or "shall I proceed?" turn. See § No-Stall Principle.

1. Skill(extract-rules) with --update — skip if any conversation-derived extraction ran this session (sub-step 1's apply-only path, its standalone --from-conversation fallback, or a hook's extract-rules --from-conversation); else trigger only on significant structural / pattern changes to application code (not prose-only edits; a dependency major-bump alone triggers the extract-rules Update Mode operational-note reminder, not --update). Full skip / trigger detail in `references/update-rules.md` § Sub-step 2 — --update trigger.
2. Char-count compaction gate:

Skip condition: If compact_rules is not true (i.e. the default false, or any non-boolean value that fell back to false), skip this entire sub-step — do not invoke Skill(extract-rules) --compact, do not open the Step 11 compaction approval gate, and proceed directly to sub-step 4 (variable initialization is not skipped — it is governed by the State-variable contract below, which covers the skipped case). Emit a one-line informational note in the resolved language so the user has a visible signal that compaction is intentionally not running:

• language: ja: Step 11（Update Rules）のルールファイル圧縮を skip しました — \compact_rules: true\ が設定されていません（実験的機能 / デフォルト無効）
• language: en: Skipped the rule-file compaction in Step 11 (Update Rules) — \compact_rules: true\ is not set (experimental feature / disabled by default)

State-variable contract (cross-step declaration — § Completion reads both variables; the full 4-point lifecycle is specified in references/update-rules.md § Char-count compaction gate): at sub-step 3 entry, initialize compaction_applied_count = 0 and below_threshold_failed_files = []. When the skip condition above fired, both variables simply stay at these initial values (no advance ever runs), so § Completion's reads are well-defined and its compaction reminder is omitted.

When not skipped (compact_rules: true): read `references/update-rules.md` and follow § Char-count compaction gate from top to bottom — it is the single canonical home for this sub-step's procedure body, including the Step 11 compaction approval gate (USER APPROVAL GATE).

1. If extract-rules is unavailable: before skipping, save any reusable patterns or insights that surfaced during the workflow to .claude/plans/rules-candidates-<YYYY-MM-DD>.md (append if the file already exists) so the knowledge is not silently lost and can be handed off to a later manual Skill(extract-rules) run. Inform the user that extract-rules is unavailable and point to the saved candidates file, and append extract-rules unavailable (rule update) to bundle_skills_unavailable (§ Step 1 sub-step 3's "Initialize the bundle-unavailability ledger here" bullet).
2. Commit rule updates (USER APPROVAL GATE): run this only when interactive_commits is true and there are uncommitted changes under any of extract-rules' three output directories — output_dir (default .claude/rules/), examples_output_dir (default .claude/rules-extras/), and staging_output_dir (default .claude/rules-staging/) — each resolved from .claude/extract-rules.local.md's frontmatter when that field is set, else its default. These are typically the rule files, .examples.md files, and staged 1st-observation candidates Skill(extract-rules) just wrote in sub-steps 1–3, including any accepted compaction edits from sub-step 3. Detect via git status --porcelain=v1 --untracked-files=all -z filtered to the union of the three resolved directories, with the § Workflow artifacts set subtracted (the default dirs are disjoint from the workflow-artifact paths under .claude/plans/ and the backlog dir, but subtract explicitly so a non-default config that points an output dir at a workflow-artifact location stays safe; a project that gitignores staging_output_dir / examples_output_dir naturally excludes those, since gitignored paths never appear in the porcelain output). If interactive_commits is false or no such changes exist, skip this sub-step entirely (no-op — the Completion rule-update / examples-dir / staging-dir reminders cover any remaining uncommitted changes). Otherwise propose a single commit of the uncommitted changes across the three directories:

• The Present / Stage / Commit / retry / post-commit-auto-modify mechanics (diff base = HEAD; this commit does not increment landed_count; pathspec restricted to the three output dirs so declined Step 10 production changes are not swept in; user-facing framing in the resolved language), the output-class labeling of each proposed file (confirmed rule change / example / unreviewed 1st-observation staging candidate), the subject drafting, and the accept / adjust(pathspec-narrow) / cancel response judging are in `references/update-rules.md` § Sub-step 5 — Commit rule updates (procedure); Read it and follow it.

Return-point no-stall reminder: at the gate decision (accept / adjust resolution / cancel — any non-error result), the next action (sub-step 6) must be issued in the next tool call. Do not insert an interstitial summary or acknowledgment turn. See § No-Stall Principle.

1. After the rule-update commit gate above resolves (or was skipped) — regardless of whether new rules were added, the report indicated nothing changed, or extract-rules was unavailable — mark Step 11: Update Rules as completed and proceed automatically. Per the No-Stall Principle, do not wait for user input.

Step 11.5: Self-Retrospective

Emit a sanitized improvement signal for the dev-workflow-bundle skills (dev-workflow, ask-peer, extract-rules, rules-review) to a user-configured destination. Raw conversation jsonl stays in-session; only abstracted, project-agnostic text leaves.

Skip this step if self_retrospective.feedback is unset/invalid (Step 1 did not register the row). Otherwise read `references/self-retrospective.md` and follow it top to bottom — the difficulty assessment does not gate this step. The jsonl scan is the shared session scan (`references/session-scan.md` § Dispatch-once contract). Reaching this dispatch point presupposes Step 11.5's §1 pre-flight (gh-auth / repo accessibility — a runtime gate, distinct from the Step-1 feedback registration gate) passed; on pre-flight failure Step 11.5 aborts here and Step 11.6 becomes the dispatcher. At the dispatch point: if session_scan_dispatched is already true (Step 11 dispatched when rule-extraction-active), consume the self-retrospective block from session_scan_result (§ Consuming a block) — the block Step 11 may have included speculatively before this pre-flight, now validated; if false (Step 11 abstained), Step 11.5 dispatches the shared scan for the still-active axes (self-retrospective ∪ workability when workability_retrospective.enabled), stores the return in session_scan_result, and consumes the self-retrospective block (§ Consuming a block). Thread the Step 2-resolved subagent_model + resolved language into the scan (references/session-scan.md § Inputs sets the scan subagent's Agent model from subagent_model, omitted when inherit).

Step 11.6: Workability Retrospective

Detect this session's project-tooling workability improvements — reusable manual procedures that could become a .claude/skills/<name>/ skill (skill-candidate) and mechanically-enforceable conventions that could become a linter-config / check_commands addition (lint-rule-candidate) — and offer a per-candidate 4-way disposition gate (act now / make a subtask / save to backlog / reject). The detection runs via the shared session scan (references/session-scan.md) — the same single jsonl parse that serves Step 11 (rule-extraction) and Step 11.5; raw conversation stays in-session. This is the project-tooling retrospective axis, distinct from Step 11's prose-rule axis (extract-rules) and Step 11.5's bundle-skill axis (self-retrospective).

Skip this step if workability_retrospective.enabled is not true (Step 1 did not register the row). Otherwise read `references/workability-retrospective.md` and follow it top to bottom — the difficulty assessment does not gate this step (mirrors Step 11.5). The jsonl scan is the shared session scan (`references/session-scan.md` § Dispatch-once contract). At the dispatch point: if session_scan_dispatched is already true (Step 11 and/or Step 11.5 dispatched with the workability axis active), consume the workability block from session_scan_result (§ Consuming a block); if false (no earlier step dispatched — Step 11 abstained and Step 11.5 was unregistered or pre-flight-aborted), dispatch the shared scan for the workability axis and consume its block. When dispatching, thread the Step 2-resolved subagent_model + resolved language (references/session-scan.md § Inputs sets the scan subagent's Agent model from subagent_model, omitted when inherit).

Completion

Derived staging artifact cleanup: before reporting summary, delete this run's per-agent staging documents (<slug>-agent-*.md), the Step 4 visual-gate served / comments / prev files, and the Step 11 rule-candidates file via two separate `rm -f` commands (fixed-name files first, the agent-staging glob last with || true), never touching the main plan document (<slug>.md) or any decomposition state file. The full procedure — the exact commands and the load-bearing zsh nomatch glob-isolation rationale — is in `references/completion.md` § Derived staging artifact cleanup; Read it and follow it.

Report summary: tasks completed, files modified, test results, review outcomes, rules updated. Output in the resolved language following `references/plan-format.md` § Localization granularity.

Step 11 extract-rules output reminders (division of labor): Step 11's "Commit rule updates" gate proposes committing changes across all three extract-rules output directories (output_dir / examples_output_dir / staging_output_dir). Resolve those three directories once and run a single git status --porcelain=v1 --untracked-files=all -z scan at Completion, partitioning its output into uncommitted_rule_changes (output_dir, default .claude/rules/) / uncommitted_examples_changes (examples_output_dir, default .claude/rules-extras/) / uncommitted_staging_changes (staging_output_dir, default .claude/rules-staging/) — each changed path lands in exactly one set via the two-stage partition (directory membership, then a filename-class tie-break when dirs collapse to one path) in `references/completion.md` § Partition — Step 11 extract-rules output sets. The three Step 11 rule-update / examples-dir / staging-dir reminders (rendered from `references/completion.md` § Completion reminders) read these partitioned sets; none re-resolves or re-scans.

Completion reminders — the render bodies, language: ja / language: en samples, and firing conditions for all eight reminders are in `references/completion.md` § Completion reminders (one flat section — read once). Emit each whose condition holds, in the resolved language, in this order: Difficulty-skip (reads difficulty_skipped_steps), Fast-mode-skip (reads fast_mode_skipped_steps), Bundle-skill availability (reads bundle_skills_unavailable), Step 10 partial-state line (reads the Step 10 Mid-loop cancel localized token), then the four that read the uncommitted_rule_changes / uncommitted_examples_changes / uncommitted_staging_changes sets produced by the partition paragraph above plus compaction_applied_count / below_threshold_failed_files (Step 11 sub-step 3 / Step 2 inits): Step 11 rule-update, examples-dir, staging-dir, and the two-clause compaction reminder (commit clause + below-threshold follow-up). Omit each when its condition is not met.

If this run was executing a subtask from a decomposition state file, also do the following (all reads/writes target the canonical state-file path recorded in Step 1.5):

Execution-time deferral/exclusion gate: before marking the subtask as completed, check whether any in-scope work items were excluded, deferred, or discovered as unassigned during implementation or testing. Items recorded only in prose (Risks entries, inline notes) are invisible to --resume and will be silently skipped — each such item must be promoted to a tracked subtask entry in the state file before completion is declared. For each uncovered item, get user approval on one of: (a) add as a new pending subtask with a depends_on link if sequencing matters, (b) fold into an existing pending subtask's scope, or (c) explicitly accept as permanently out of parent-task scope. The completion report must confirm that no goal-required items remain in untracked prose form.

1. Mark the current subtask's status as completed in the canonical state file and write back
2. Ask the user for an optional PR URL for this subtask. On a non-empty answer, set the subtask's pr field and write back; otherwise leave it null
3. Refresh the parent-task progress row's <done>/<total> count
4. Find the next runnable subtask (smallest-id pending with all depends_on completed)
5. If a next subtask exists: branch on whether Step 10 actually landed any commits this run (use the landed_count from Step 10 — taking the config flag alone would mis-route the case where interactive_commits: true met the Step 10 skip conditions and exited at zero commits):

• landed_count > 0: tell the user the current subtask's changes have already been committed by Step 10 (Interactive Commits) — open a PR for those commits, then start a new session with /dev-workflow --resume <slug> once the PR is up
• landed_count == 0 (either because interactive_commits: false or because Step 10 was skipped): tell the user to commit the current subtask's changes and open a PR before resuming, then start a new session with /dev-workflow --resume <slug>. Explain why this matters: the next run records a fresh base-commit from HEAD, so uncommitted changes would leak into the next subtask's diff

In both branches, if any of extract-rules' three output directories (output_dir / examples_output_dir / staging_output_dir) have uncommitted residue (i.e., any of the Step 11 rule-update / examples-dir / staging-dir reminders in `references/completion.md` § Completion reminders fired), tell the user to commit those writes manually before resuming — otherwise they leak into the next subtask's diff the same way uncommitted feature changes would. When Step 11's "Commit rule updates" gate already committed all of them (no residue in any of the three dirs), omit this instruction — the changes are committed and will not leak. (This warning overlaps the per-dir reminders above on the same residue by design — both are prose nudges, no double-count.) The "no push" invariant for both branches is stated at § Step 10's preamble

1. If no next subtask exists (all subtasks completed): delete the canonical state file via rm -f <canonical-path>, remove the parent-task progress row, and include every subtask's title and recorded pr (if any) in the parent-task completion summary