dev-workflow

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 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 (Step 7.5) 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 (Step 6 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, still resolved as a Scalar via the compat mapping described 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; a key absent from a higher layer inherits from lower layers (see the inherit note below). When review_iterations carries a map value ({plan, code}) it is still a scalar key here — a higher layer's value replaces the lower layer's wholesale, with no per-key cross-layer merge (an absent map key is not back-filled from a lower layer; it falls to default 3 at resolution time). The subagent_model map ({<tier>: <model>}) is the same scalar/map class — a higher layer's map replaces the lower layer's wholesale (no per-key cross-layer merge), and an absent tier key falls to its built-in per-tier default at resolution time (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; -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: Step 4 approval surface — plan-mode / visual (default) / crit; the deprecated visual_plan_review boolean is still resolved via a compat mapping.
• commit_review_gate: Step 10 per-commit diff-review surface — diff (default) / crit; 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 (across two steps) — Step 7's two concurrent background launches (the initial-pass rules-review launch and the initial-pass code review; run_in_background dispatches for test-phase overlap — see Step 7's "Concurrent rules-review launch" and "Concurrent code review launch" paragraphs for why Agent rather than Skill()), and the shared session scan (one dispatch covering the rule-extraction, self-retrospective, and / or workability axes, performed once by whichever of Step 11 / Step 11.5 / Step 11.6 is the first participating step to dispatch — so the scan's host step varies across runs but the site count does not; see references/session-scan.md). Beyond these three fixed sites, two conditional delegations may fire: Step 2 MAY delegate read-only codebase research to a subagent when plan_review_gate is not plan-mode (fires only on the no-Plan-Mode path — visual or crit — when the task benefits from non-trivial research — see Step 2's sub-step 3 "Codebase-research delegation" guidance), and Step 5 MAY conditionally delegate a well-specified implementation unit to a task-effective subagent (under implementation_executor: "main" — the default — this remains the existing optional path; under implementation_executor: "subagent" it becomes the default route for each settled work unit per Step 5's sub-step 2 delegation guidance, still passing subagent_model; the external-CLI executor values instead route the same per-unit work through named Skill(ask-claude) / Skill(ask-codex) / Skill(ask-gemini) / Skill(ask-copilot) / Skill(ask-agy) calls, so they do not add new direct-Agent dispatch sites). Each of the three fixed sites — and the conditional Step 5 delegation when it fires — passes the Step 2-resolved subagent_model as the Agent model parameter (omitted when the resolution is inherit); the conditional Step 2 research delegation is the exception — it dispatches before Adjust N resolves the tier, so it always runs on the session model (subagent_model is still its inherit init) and is excluded from subagent_model governance. 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 Step 2 research delegation and the Step 5 implementation delegation above are the sanctioned exceptions, each scoped by its own guards). (The Step 3 / Step 8 inline reviewer's subagent_model propagation rides the named Skill(<reviewer>) call's Model: argument, and Step 6's tidy fallback propagation rides the named Skill(tidy) call's Model: argument — both are not direct Agent spawns and do not count against the three fixed dispatch sites above; Step 6.5's prose-polish file-mode callee and Step 4's plan-body prose-polish callee are likewise named-skill dispatches, not direct Agent spawns, and receive no propagated model per the subagent_model bullet.) The Step 4 plan-review gates (plan_review_gate: visual — Step 4 always runs the gate, which itself owns the browser-reachability determination and only launches serve.mjs when the local browser is reachable, see references/visual-plan-review.md; and plan_review_gate: crit, which likewise owns its own availability/reachability determination and only launches the crit CLI when reachable, see references/crit-plan-review.md), and Step 10's commit_review_gate: crit gate (which likewise owns its own once-per-run availability/reachability determination and only launches crit when reachable, see references/crit-commit-review.md), launch their external process via background Bash (run_in_background), not the Agent tool; none of them is a subagent dispatch, and none counts against the three fixed dispatch sites here.
• workability_retrospective: enabled (default false; experimental) gates Step 11.6; backlog_dir (default .claude/improvements) holds the "save to backlog" disposition's candidate files.

Mode Detection

• --init → Init Mode (-i / --iterations is ignored)
• --resume <state-file> → Execution Mode (Resume sub-mode; see Step 1.5)
• 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 N 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 itself creates and maintains as in-session state — plan documents under .claude/plans/, decomposition state files written by Step 1.5, Step 10, or Step 11.6, backlog files written by Step 11.6 under workability_retrospective.backlog_dir, the Step 4 visual-gate served plan file, its comments file, and its prev snapshot (.claude/plans/<slug>.plan-review.md / .claude/plans/<slug>.plan-review.comments.json / .claude/plans/<slug>.plan-review.prev.md), the Step 11 rule-extraction candidate file passed to extract-rules --apply-conversation-candidates (.claude/plans/<slug>.rule-candidates.md), and other workflow-internal staging artifacts placed under .claude/ by this skill — 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 Interactive Commits' commit grouping, sub-skill dispatch payloads, scope checks). The exclusion is structural — the workflow owns these files as its own operational substrate — and is not gated on whether the path appears in .gitignore, whether a formatter ignore-file aligns, or whether the user happens to be touching them in this run. Steps that build a changed-file set, a diff-scope set, or a commit grouping must apply this single shared exclusion rather than re-deriving the rationale per step against ad-hoc justifications. If a future change adds another in-session-state path, extend this canonical list once rather than threading the exclusion through per-step prose (for skill development this is the canonical workflow-artifact set; sub-skills the workflow dispatches 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. 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, regardless of whether it is the default ask-peer or a configured alternative — ask-peer is a dev-workflow-bundle sibling skill, independently installable and installed separately from dev-workflow itself (per .claude-plugin/marketplace.json, each is its own plugin entry in addition to the bundle), so it is not guaranteed present just because dev-workflow is: attempt Skill(<reviewer>) with a one-word probe request (e.g., ping); if the call fails, retry once. If still failing, and the resolved reviewer is ask-peer specifically (the bundle-member reviewer — see above), append ask-peer unavailable (reviewer, Step 3/8) to bundle_skills_unavailable. Either way, emit the three-option prompt defined in § Prerequisites' "Reviewer skill" bullet — do not block the run, present the options and let the user decide before the first review step begins.
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:
   1. 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)
   2. Else if config review_iterations is present:
      • scalar positive integer → set both N_plan and N_code to it
      • map ({plan, code}) → N_plan = plan if it is a positive integer else default 3; N_code = code if it is a positive integer else default 3 (per-key validation, independent per phase; warn on each absent/invalid key)
      • any other value (non-positive 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)
   3. 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.
5. 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.
6. 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)
7. 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) Tool availability (Task tools vs TodoWrite): these steps name the Task tools (TaskCreate / TaskUpdate / TaskList), the default since Claude Code v2.1.142. Where the Task tools are unavailable (e.g. the VSCode extension, or Claude Code before v2.1.142), use the equivalent TodoWrite operations instead — the status values (pending / in_progress / completed) and the register-all-upfront semantics are identical, and a TaskList-by-subject status read becomes a read of the TodoWrite list. allowed-tools grants both, so use whichever the environment exposes. Registration mechanics (Task tools): issue every TaskCreate in a single upfront burst (one tool-call batch) so all phases are registered before Step 2 begins. Two conditional cases: (i) conditionally-omitted phases (the list items above carrying a condition) are omitted by not issuing their TaskCreate; (ii) N-reduced excess iteration tasks (Step 3-x beyond resolved N_plan / Step 8-x beyond resolved N_code) are still TaskCreated here at the resolved ceiling (Step 3 ceiling = N_plan, Step 8 ceiling = N_code), then marked completed via TaskUpdate by Step 2's Adjust N by difficulty. Mark each task in_progress (via TaskUpdate {taskId, status}) when starting and completed when done. Task-handle resolution convention: every later "mark Step N as in_progress / completed" instruction in this skill is shorthand for resolve that Step's task — by its registration-time captured taskId, or by subject via TaskList — then TaskUpdate {taskId, status}; the per-step lines name tasks by their human-readable subject and do not restate this resolution path. Registering all phases upfront gives the user visibility into overall progress and prevents steps from being accidentally dropped. Phase-boundary self-audit: at every top-level Step transition (not the iteration sub-rows Step 3-i / Step 8-i, which are governed by the Return-point no-stall reminders below), before issuing the first tool call that advances into a new Step's procedure, name the Step number you are entering, resolve the prior Step's task by subject via TaskList, and verify it is completed — if it is still pending or in_progress, return to the unfinished Step first instead of advancing. This guards against silent phase-skipping (e.g. jumping from Step 5 Implement to Step 7 Check / Test without running Step 6 Tidy, only to discover the gap during a later phase) that the 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.
8. Context-compaction recovery: if the session context was compacted before reaching this step, re-read the configuration files from disk (not the compacted summary) to re-verify each step's skip conditions from the actual merged config. Full detail — 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.
9. Interruption re-anchoring: if this invocation is a user-prompted continuation of an interrupted prior session (connection error, browser refresh, etc. — distinct from compaction) and --resume <state-file> was not provided, re-establish position from the in_progress task + re-read config from disk, announce the resumption point, and proceed immediately (do not re-execute completed steps). Full detail in references/step1-load-settings.md § Sub-step 9 — Interruption re-anchoring.

Step 1.5: Task Decomposition

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

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:

   Variable	Init	Lifecycle
   difficulty_skipped_steps	[]	Records <step> skipped (<tier> tier); populated by Adjust N's difficulty-skip matrix; rendered by § Completion's difficulty-skip reminder. Stays [] when Adjust N is skipped or no tier qualifies
   fast_mode_skipped_steps	[]	Fast-mode counterpart of difficulty_skipped_steps (a distinct sub-condition per the warning-string differentiation rule); populated by every --fast skip/cap site — Adjust N's N-forcing + the Step 6.5-only skip (Step 2), the Step 7.5 1-pass cap, and Step 8's deferred gate-2 cap; rendered by § Completion's fast-mode-skip reminder
   step8_fix_files	[]	Single source of truth (kept inline): the set of repo-relative paths edited by any workflow fix applied after the initial Step 7.5 pass completes (path-independent). Accumulation window opens when the initial Step 7.5 pass is first marked completed (fixes before/during it are excluded — the initial full-scope Step 7.5 + Step 7 already verified them). Append sites (closed list): Step 8 sub-step 3 (code-review fixes), any fix applied while resolving Step 8 sub-step 4's unresolved-findings gate, the loop-exit check/test, and the deferred scoped rules-review's sub-step (a). Read: Step 8's "Deferred verification (Step 8 fix aggregate)" paragraph. Stays [] (deferred verification skipped) when Step 8 is skipped (N_code=0 / Trivial) or applies no fixes
   subagent_model	inherit	Resolved in Adjust N from the assessed tier (built-in tier → model map, § Configuration). inherit (the pre-assessment value, and the -i-path value) → every downstream Agent dispatch / Model: propagation omits the model (current behavior). Read sites: § Configuration's subagent_model bullet — except the conditional Step 2 research delegation (no-Plan-Mode path only), which consumes this inherit init directly (see Step 2 sub-step 3's "Codebase-research delegation" guidance)
   session_scan_dispatched / session_scan_result	false / null	Shared session-scan state (references/session-scan.md § Dispatch-once contract). Set by whichever of Step 11 / Step 11.5 / Step 11.6 performs the scan dispatch; read by the participating step(s) that consume their axis block. Set/read sites confined to Step 11 / Step 11.5 / Step 11.6

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

6. No code changes in this phase
7. 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 1; Moderate → min(2, ·); Complex → unchanged. 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 force N_plan = 0, N_code = 1, appending Step 3 Plan Review skipped (fast mode) to fast_mode_skipped_steps). 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 (Step 8 still runs at N_code=1). 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.
8. 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 — either the task was assessed Trivial, or --fast forced N_plan=0 on a non-Trivial tier — 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.

Difficulty exception (Trivial or --fast / N_plan=0). When N_plan = 0 — either a Trivial task (Trivial zeroes both N_plan and N_code) or --fast forcing N_plan=0 on a non-Trivial tier (N_code stays ≥ 1 in that case) — this entire step is skipped: its task rows (top-level Step 3: Plan Review and every Step 3-x) were already marked completed by Step 2's Adjust N by difficulty. 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 difficulty 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 (Trivial, or --fast forcing N_plan=0 — see the Difficulty 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. Before presenting, verify via TaskList that Step 3: Plan Review and every Step 3-x iteration item are completed — presenting the plan for approval (the surface chosen in sub-step 2) is the effective end of internal review, so reaching it while any Step 3 item is still pending or in_progress skips the review entirely (on path (a) that presentation is ExitPlanMode, which is also the Plan Mode exit). If any Step 3 item is not completed, emit a one-line inline note to the user naming all incomplete items (e.g., Plan review found incomplete (Step 3-2 still pending) — running the remaining review pass before presenting the plan., substituting the actual incomplete iteration item label(s)) then return to Step 3 to process it (do not flip the row to completed without doing the review work). Exception: when N_plan=0 (a Trivial task, or --fast forcing N_plan=0 on a non-Trivial tier) — Step 2's Adjust N therefore pre-marked all Step 3 rows completed — that completed state is the intended skip, not an unrun-review bug, so proceed to the approval presentation normally. 1.5. Prose-language self-audit: Before presenting the plan for approval (the surface chosen in sub-step 2), verify that explanation prose in the plan body (Overview narrative, Decisions rationale, Design descriptions, Test plan steps, Risks/Unknowns paragraphs) is written in the resolved language. Schema tokens (Overview / Decisions / Design / Test plan / Risks / Unknowns), step labels, enum values, identifiers, and quoted code strings stay in their original form regardless of language. Audit both directions: (a) if any explanation sentences are in a different language than the resolved language, and (b) if concept words outside the verbatim-preserve scope — ordinary nouns, adjectives, conjunctions, verb phrases — are over-preserved in the source language rather than rendered in the resolved language (per references/plan-format.md § Localization granularity's Negative-direction rule). Revise any failures now per references/plan-format.md § Localization granularity before proceeding to sub-step 2. Re-entry coverage: this audit must re-run on every entry into Step 4 — both the initial entry and any re-entry triggered by sub-step 1's "return to Step 3" path or sub-step 3's material-change path — since revisions during Step 3 iteration may introduce prose in a language different from the resolved language.

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

3. 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 / Design / 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): add a new review iteration item (Step 3-(N_plan+1)), run the read-back sub-step below, return to Step 3 to re-review the modified plan, then re-enter Step 4 from sub-step 1 (so sub-step 1's task completion check on the new Step 3-(N_plan+1) item and sub-step 1.5's prose-language re-entry-coverage audit both run before re-presenting at sub-step 2). Exception — --fast-forced N_plan=0 (non-Trivial tier, N_code ≥ 1): skip the add-iteration-item and return-to-Step-3 legs above entirely — apply the revision to the plan document, run the read-back sub-step below to confirm it, then re-enter Step 4 directly from sub-step 1, since N_plan stays 0 through the rewrite (see the discriminator note at the end of this bullet for why). This exception does not apply to genuine Trivial (N_code=0 too); that case follows the reactivation below unchanged. Trivial (N_plan=0) re-activation: if the task had been assessed Trivial (N_plan=N_code=0) so Step 3 was skipped, an Approach-level material change means the task is no longer trivially self-evident — re-run Step 2's Adjust N by difficulty against the rewritten plan to re-derive the difficulty assessment itself (it will no longer be Trivial) and the effective N_plan / N_code (re-running the independent-cap logic on both values, not a single value). Updating the difficulty assessment — not just the counts — is required because every downstream gate keys on the assessment, not on a bare count: subagent_model and the Step 6/6.5/7.5 difficulty-skip matrix both key on the actual assessed tier, and references/plan-format.md's "N_plan=0 conditional (Trivial or --fast)" picks its replacement sentence based on whether the task is genuinely Trivial; leaving the stale Trivial label in place would keep all three reading a tier that no longer applies. Then re-mark the task rows for the re-derived difficulty: register Step 3-1 … Step 3-N_plan (and the Step 8-1 … Step 8-N_code rows) as fresh pending, and clear the previously-skip-completed top-level Step 8: Code Review row back to pending (this reactivation only reaches this point for a re-derived non-Trivial tier, so N_code ≥ 1 always holds here, whether tier-derived or --fast-forced). Clear the top-level Step 3: Plan Review row back to pending too — unless fast_mode_active and the "re-run Step 2's Adjust N" above already re-forced N_plan=0 for the newly re-derived non-Trivial tier (which re-marks Step 3: Plan Review completed and re-appends its fast_mode_skipped_steps entry as part of that same re-run — see the --fast N-forcing paragraph in Step 2's Adjust N): in that case leave Step 3's re-forced completed state in place instead of clearing it, so the two instructions in this bullet don't fight over the same row. The difficulty-skip matrix is re-derived in the same pass: reset difficulty_skipped_steps = [] and fast_mode_skipped_steps = [] (this reactivation only fires when N_code was 0 too, i.e. genuine Trivial, so fast_mode_skipped_steps is always empty here anyway — reset it for symmetry with difficulty_skipped_steps regardless), and re-run Adjust N, which recomputes which of Step 6: Tidy / Step 6.5: Polish Prose / Step 7.5: Rules Compliance Review the new tier skips and re-populates the ledger from scratch (no find-and-remove of individual records). Clear any previously-skip-completed Step 6 / Step 6.5 / Step 7.5 row back to pending when the higher tier no longer skips it — the same re-pending treatment applied to the Step 3 / Step 8 rows. Without this re-derivation the Step 3 entry-point guard would skip the new review item (it skips whenever N_plan=0), Step 4's completion check would loop on the unprocessed item, and a Step 6 / Step 6.5 / Step 7.5 row left stale-completed would silently skip a quality step the higher tier now requires. Why the exception above is safe: this reactivation's own trigger condition requires N_code=0 too (genuine Trivial), so it is already false whenever --fast forced N_plan=0 on a non-Trivial tier (N_code stayed ≥ 1) — fast mode's Step 3 skip is a deliberate mode-level choice, not a possibly-mistaken difficulty judgment, so an approach rewrite does not reopen it (this discriminator relies on the N_code=0 coupling stated in Step 2's Adjust N marking rule and the non-positive-value rejection in Step 1 sub-step 4's N resolution — no other path produces N_code=0). The --fast Step 6.5-only skip paragraph above is re-evaluated only when Adjust N actually re-runs (the genuine-Trivial reactivation case) — it is not re-evaluated when the exception above fires instead.
   • 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).

2. Follow the plan, track progress with the Task tools (TaskUpdate). When the Design is an ordered, numbered list of implementation steps (per references/plan-format.md § Template), you MAY register each step as an implementation sub-task and execute them in order, marking each completed as it lands — recommended for long ordered 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.

3. Implementation diff snapshot: at the conclusion of Step 5 (after all planned edits are applied and the derived-value claim deferral sub-step — sub-step 8, in references/step5-implement.md — completes), run git diff <base-commit> --name-only and store the result as implementation_diff_paths — the set of tracked paths changed by this task's implementation, recorded before any post-implementation review hook or automated fix tool runs. This snapshot is consumed by § 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 (Step 6.5) 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 "nested Agent unavailable — run the callee directly" payload note, and apply no edits (the main thread applies fixes later). test_commands is never backgrounded (run-tests lacks the nested-Agent-unavailable inline fallback that rules-review / ask-peer have). 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 (Trivial) — 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; 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.