hiroro-work/claude-plugins/dev-workflow

Dev Workflow Lite

/dev-workflow --init                 # Detect check/test commands, write settings, generate run-tests
/dev-workflow [--fast|--deep] [--artifact off|share|review] [--mob] <task>                 # Run the workflow
/dev-workflow --resume <state-file> [--fast|--deep] [--artifact off|share|review] [--mob]  # Run the next subtask of a decomposed task

Nineteen phases, always in this order. § Difficulty and the skip table decides what is skipped and how Plan Review runs. User gates are listed in § User gates; nothing else asks the user a question.

Settings

Three files, YAML frontmatter only, merged lowest to highest: ~/.claude/dev-workflow.local.md, .claude/dev-workflow.md, .claude/dev-workflow.local.md. If none exists, tell the user to run --init and stop; a file with malformed frontmatter is skipped with a warning.

Merge rules per key, in order: null or an empty value in a higher layer clears the key; an absent key inherits; scalars replace; check_commands appends (lower first, duplicates removed); test_commands replaces as a whole list; hooks.on_complete appends.

language resolves as: merged settings → language in ~/.claude/settings.json → ja. Headings, phase names, commit messages, diffs, and paths stay as written; prose follows it, in plain words, one claim per sentence. Keys this skill does not read are named once at Load Settings and ignored.

Callee failure rule

When a Skill(...) call fails, retry once. If it fails again: for the reviewer skill, ask the user to pick switch reviewer / self-review inline / stop (a user gate); for any other skill, say so in one line, do that phase's work yourself, and continue; Skill(demo) is instead reported in its Demo line. Record skipped callees for Completion.

Difficulty and the skip table

The tier is assessed at Task Decomposition (references/tiers.md § Tier criteria) and re-checked at the end of Create Plan (its § Re-check after planning), where it can only rise. Trivial and Simple are the express lane; Moderate and Complex are the full lane.

Run mode comes from the flags: --fast, --deep, or neither (normal). Both flags together is a fatal error. normal: Plan Review runs in rules-only scope. deep: Plan Review runs in full scope. fast: Plan Review and Polish Prose are skipped. Nothing else reads the run mode.

No tier skips a phase absent from the table. A skipped phase is marked completed with the description skipped: <tier> tier, skipped: <key>: false, or skipped: fast mode.

User gates

The only places the workflow waits for the user:

• Task Decomposition: the split proposal (yes / adjust / no) and, on resume, the subtask picker when more than one is runnable.
• Plan Approval: the browser review (approve / revise with comments, and the branch choice) when a local browser is reachable; otherwise the chat replies Phase 5 (Plan Approval) lists, with the one-line read-back before a swap or rewrite is applied. A wrong-branch request waits for uncommitted changes to be committed or stashed. With plan_artifact: review, the wait for the team's review.
• Check / Test: after 3 failed fix rounds the workflow stops and reports; a check command that rewrote files outside the task beyond trivial formatting, or a test skill's EXECUTION_ERROR, stops for the user.
• Code Review: findings still unresolved after the passes, asked once.
• Verify Fixes: rule violations still present after the second scoped pass, asked once.
• Interactive Commits: the stashing-hook question when a pre-commit hook exists and the plan has two or more commits; the commit plan; then each commit (accept / adjust / cancel, or the crit browser's approve / comments); fold / defer when a pre-commit hook modified files; continue / stop when the user made a behavioral edit during a gate.
• Update Rules: the confirm-remaining-steps question covering the rule and retrospective phases, with the demo / no-demo question when demo is set up (then the demo skill's gates on demo), then the rule commit.
• PR Rule Extraction: which PR to read (an empty answer declines), then the rule commit.
• Self-Retrospective: the preview of the Findings before posting (approve / edit / skip).
• Workability Retrospective: the candidates' dispositions (apply / backlog / skip), then the commit of its results.
• Completion (decomposed runs only): the disposition of each work item left in prose, then the finished subtask's PR: an optional URL, or submit / later when stacked.

In mob mode, references/mob-mode.md § Learning stops adds the per-unit diff review, the plan-building checkpoints, and the post-commit-note question to this list. The collect wait of references/review-launch.md § Collect is a harness-tracked boundary, not a gate. Everywhere else, judge callee results yourself and issue the next tool call immediately. A question, a comment, or an instruction about how to run (including one to proceed without asking) is never approval: say what the gate needs and wait. No reply waives a later gate.

Timing

Phase starts, ends, and waits are marked per references/timing.md; Completion renders the table.

Workflow artifacts

Files this workflow writes as its own state are excluded from every diff, review payload, and commit: .claude/plans/**/<slug>.md (the plan), .claude/plans/dev-workflow.<slug>.md (decomposition state), .claude/plans/rules-candidates-<date>.md, .claude/plans/timing-*.jsonl, every other .claude/plans/<slug>.* staging file or directory (.plan-review.*, .figures.md, .story.json, .artifact.html, .dialogue.md, .absorb/, .retrospective.md), and the git-side state refs/dev-workflow/<slug>*, .git/dev-workflow.index, .git/dev-workflow.start.index, .git/dev-workflow-wt. Everything else under the working tree is the task's.

Mode detection

--init → read references/init-mode.md and follow it; the session ends there. --resume <state-file> → Resume sub-mode. Otherwise Normal sub-mode. Other flags combine with either sub-mode; --init ignores them.

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.

Phase 1: Load Settings

1. Run pwd; confirm the repository root. Abort if git symbolic-ref -q HEAD exits non-zero (detached HEAD). <base dir> = this skill's directory as the harness reports it; never hardcode it.
2. Start the timing log (references/timing.md § Events, --event start --new for this phase).
3. Record <base-commit> = git rev-parse HEAD. Every later diff is against it. When test -d .git fails (a linked worktree), the snapshot chain of references/snapshots.md is not built and no <start-tree> is recorded. Otherwise record <start-tree> = the working tree as it stands, in a throwaway index:

``bash GIT_INDEX_FILE=.git/dev-workflow.start.index git read-tree HEAD GIT_INDEX_FILE=.git/dev-workflow.start.index git add -A GIT_INDEX_FILE=.git/dev-workflow.start.index git write-tree # → <start-tree> ``

A non-zero exit anywhere records no <start-tree>: say so in one line and continue.

1. Load and merge the settings; resolve the run mode, the --artifact override, and mode; emit Output language: <value>, Run mode: <value>, and Mode: <value>. In mob mode, read references/mob-mode.md now; in solo mode never open it.
2. Register the nineteen phases with TaskCreate, subjects = the ## Phase N: headings below minus the prefix. Mark each in_progress on entry and completed on exit in the same tool-call burst as the phase's first or last action. Mark the phases skipped by settings or run mode completed here; tier-derived skips are marked at Task Decomposition. No TaskCreate → skip every row step; emit Phase: <name> on each entry.

Phase 2: Task Decomposition

• Resume sub-mode: read references/decomposition-state.md and follow its § Resume. The selected subtask becomes the effective task; read references/tiers.md and assess the tier from it.
• Normal sub-mode: read references/tiers.md and assess the tier. On the full lane, read references/decomposition.md and follow § Propose a split; on yes, take the first subtask as the effective task. On the express lane, or on no, the effective task is the request itself.

Emit one line: the tier and the phases it skips. Mark the skipped rows. Resolve <model> = subagent_model[tier] (unset → inherit). In mob mode, apply references/mob-mode.md § Other differences to the split proposal.

Phase 3: Create Plan

No code changes until Plan Approval passes.