
dev-workflow
Guided development workflow: task decomposition, planning, peer plan review, browser plan approval, implementation, tidy, check/test, rules and code review, one commit per build step, rule updates, retrospectives, an optional demo; mob mode for a junior navigator
- version
- 2.17.0
- GitHub stars
- 47
Install
/plugin install dev-workflow@hiropon-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add hiroro-work/claude-plugins.
Contents
Discovered from sourceSkills 1
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> [--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.
| Key | Default | Meaning |
|---|---|---|
reviewer | ask-peer | Reviewer skill for Plan Review and Code Review. One of ask-peer / ask-claude / ask-codex / ask-gemini / ask-copilot / ask-agy; anything else uses ask-peer |
code_review | true | Whether Code Review runs |
polish_prose | true | Whether Polish Prose runs |
language | see below | Language of everything the user reads |
check_commands | none | Shell commands, run in order |
test_commands | ["Skill(run-tests)"] | Skill(<name>) entries, run in order |
hooks.on_complete | none | Skill(<name>) or shell command strings, run as Completion Hooks |
plan_artifact | off | off / share / review: publish the approved plan as a claude.ai artifact, along with the exchange that shaped it; review also waits for the team's comments. --artifact overrides per run |
commit_review_gate | diff | diff / crit: how each commit's diff is shown at Interactive Commits. crit opens the crit browser reviewer |
mode | solo | solo / mob. mob adds the stops and narration references/mob-mode.md defines for a junior navigator. --mob sets it for one run |
self_retrospective.feedback | none | Where Self-Retrospective posts its Findings: GitHub owner/repo, or a local directory path. Unset skips the phase |
timing.report_dir | none | Directory that also receives each run's timing report; the table is shown at Completion regardless |
subagent_model | {trivial: sonnet, simple: sonnet} | {tier: model} map; the resolved tier's entry becomes <model> for the reviewer, rules-review, tidy, demo, and background review agents. No entry → inherit |
workability_retrospective | enabled: true | enabled: false skips Workability Retrospective; backlog_dir (default .claude/improvements) holds its backlog files |
custom_instructions | none | Free-form development guidance followed at Create Plan, Implement, and Tidy and handed to both reviewers. .claude/rules/ and the user's explicit requests win on conflict |
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.
| Phase | Trivial | Simple | Moderate / Complex |
|---|---|---|---|
| Task Decomposition proposal | no | no | yes |
| Plan Review | skip | per run mode | per run mode |
| Tidy | skip | skip | run |
| Polish Prose | skip | skip | run (unless polish_prose: false or --fast) |
| Rules Compliance Review | skip | skip | run |
| Code Review | skip | run (unless code_review: false) | run (unless code_review: false) |
| Update Rules | gate only | gate only | run |
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 and, on resume, the subtask picker when more than one is runnable.
- Plan Approval: the browser review (
approve/revisewith 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. Withplan_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/deferwhen a pre-commit hook modified files;continue/stopwhen 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-demoquestion when demo is set up (then the demo skill's gates ondemo), 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/laterwhen 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> → 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
-
Run
pwd; confirm the repository root. Abort ifgit symbolic-ref -q HEADexits non-zero (detached HEAD).<base dir>= this skill's directory as the harness reports it; never hardcode it. -
Start the timing log (
references/timing.md§ Events,--event start --newfor this phase). -
Record
<base-commit>=git rev-parse HEAD. Every later diff is against it. Whentest -d .gitfails (a linked worktree), the snapshot chain ofreferences/snapshots.mdis not built and no<start-tree>is recorded. Otherwise record<start-tree>= the working tree as it stands, in a throwaway index: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. -
Load and merge the settings; resolve the run mode, the
--artifactoverride, andmode; emitOutput language: <value>,Run mode: <value>, andMode: <value>. In mob mode, readreferences/mob-mode.mdnow; in solo mode never open it. -
Register the nineteen phases with
TaskCreate, subjects = the## Phase N:headings below minus the prefix. Mark eachin_progresson entry andcompletedon exit in the same tool-call burst as the phase's first or last action. Mark the phases skipped by settings or run modecompletedhere; tier-derived skips are marked at Task Decomposition. NoTaskCreate→ skip every row step; emitPhase: <name>on each entry.
Phase 2: Task Decomposition
- Resume sub-mode: read
references/decomposition-state.mdand follow its § Resume. The selected subtask becomes the effective task; readreferences/tiers.mdand assess the tier from it. - Normal sub-mode: read
references/tiers.mdand assess the tier. On the full lane, readreferences/decomposition.mdand follow § Propose a split; once accepted, take the first subtask as the effective task. On the express lane, or onno, 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.
- Read the files the task touches. Use Glob / Grep / Read directly.
- Draft the plan per
references/plan-format.md: the body under## Plan, sections as###, in the orderreferences/plan-format.mddefines. Express-lane plans use the compact shape defined there. - Follow
custom_instructionswhen set. Simplicity self-audit: every element traces to an explicit requirement, a known bug or constraint, a rule under.claude/rules/, orcustom_instructions. Drop what does not, or add a one-line rationale. Verify every "already exists / reuses X" premise from the source. If the work splits into independently verifiable units and was not decomposed, say so in Risks. - Re-check the tier against the drafted plan (
references/tiers.md§ Re-check after planning): if it rises, say so in one line, reopen the rows the new tier runs, and re-resolve<model>. - Do not show the plan yet. In mob mode, this phase runs as
references/mob-mode.md§ Design dialogue and writes its § Plan shape.
Phase 4: Plan Review
Skipped on Trivial and in fast mode. One pass, no loop.
- Full scope (
deep): callSkill(<reviewer>)withModel: <model>, the full plan body,custom_instructionswhen set, the Decisions shape (Question / Recommendation / optional Alternative), and three review units: scope, feasibility, dependencies,.claude/rules/compliance (the reviewer lists and reads.claude/rules/**/*.md); the simplicity self-audit's conclusions; approach and alternatives, completeness, cross-section consistency. Ask the reviewer to report every finding it has, including uncertain or low-severity ones, each with a confidence level and a severity, and not to filter for importance itself; when it has none, the words "No actionable findings". Rules-only scope (normal): resolve the reading list yourself — every*.mddirectly under.claude/rules/plus subdirectory files whose domain the plan touches — and callSkill(<reviewer>)withModel: <model>, the plan body, that numbered list, and one unit:.claude/rules/compliance only, reading exactly the listed files and no other tool; anything it cannot confirm goes under an "unverified items" heading. If the glob finds no rule files, do not dispatch: say the review found no project rules to check and continue. - Apply findings you agree with; reject the rest with one line each. Do not ask the user about individual findings. Do not re-dispatch, with one exception: when Critical ≥ 3 or Critical + Major ≥ 10 and a finding proposes an approach-level alternative, rewrite the plan around it and dispatch one more pass.
- Unresolved points are carried to Plan Approval as a short list. In mob mode, review through
references/mob-mode.md§ Plan shape's lenses and explain applied findings.
Phase 5: Plan Approval
USER GATE. Read references/plan-approval.md.
- Write the plan to
.claude/plans/<slug>.md(mkdir -p .claude/plans). Slug: ASCII kebab-case of the effective task,-2,-3on collision with a prior run's file; resolved once per run. - Browser gate when
printenv CLAUDE_CODE_REMOTEis nottrue: followreferences/browser-gate.md. Itsapprove→ step 4;rewrite-approach→ rewrite the plan, re-run Plan Review once unless skipped this run, re-enter this phase;wrong-branch→ § Branch action's "Wrong branch" paragraph;fallback→ step 3. - Chat gate (remote sessions, or fallback): present the plan per § Chat gate unless fallback brought a reply. Classify the reply: approve → step 4. swap (named Decisions items) → read back in one line, wait, swap Recommendation and Alternative on those items, re-present. rewrite (Approach, Build order, or Scope changed) → read back, wait, rewrite the plan, re-run Plan Review once unless skipped this run, re-present. wrong branch (another branch to work on) → § Branch action's "Wrong branch" paragraph. withdraw → stop; leave the plan file. Anything else → ask; never advance.
- Plan artifact: when the resolved
plan_artifactisshareorreview, readreferences/plan-artifact.mdand follow it.reviewholds at its team-review gate (USER GATE) until the user says the team is done. - Run § Branch action, then Implement.
In mob mode, references/mob-mode.md § Plan Approval adds the plan narration.
Phase 6: Implement
- Before the first edit, list the plan's user-side manual actions (external config, keys, probes) in one block.
- Follow Build order in sequence, and
custom_instructionswhen set. Read each file immediately before editing it. Content the user deleted earlier in the session never comes back. - A write to a path not in
git ls-filesmust resolve inside the repository, under the directory the plan names for that kind of file; otherwise skip the edit with a one-line note. - If a file outside the plan must change, add it to Build order first, then edit, and say so in one line.
- After the last edit of each Build order step, take that step's snapshot per
references/snapshots.md§ Snapshot at a Build order step boundary (before step 1's snapshot, delete a leftoverrefs/dev-workflow/<slug>from an earlier run). - After the last edit,
git add -N -- <path>for each new file outside § Workflow artifacts.
In mob mode, each Build order step runs as a unit per references/mob-mode.md § Per-unit review, with its diff review after the snapshot.
Phase 7: Tidy
Express lane skips. Call Skill(simplify); if unavailable, Skill(tidy) with no base ref and Model: <model>; pass custom_instructions as context when set. Either edits the tree itself. Correcting a false comment means replacing it with the shorter true statement. From here on, no review layer grows a comment: a finding whose fix adds, lengthens, or restores a comment is rejected with that reason. In mob mode, explain any cleanup per references/mob-mode.md § Tidy.
Phase 8: Polish Prose
Express lane skips; polish_prose: false and fast mode skip. Run node "<base dir>/scripts/polish/changed-lines.mjs" --base <base-commit>; it prints File: and Changed lines: for this run's changes. If it prints nothing or fails, skip. Otherwise call Skill(prose-polish) with that output and Language: the resolved language. done / no-change / error all continue.
Phase 9: Check / Test
- The first time in this run, set
review_fix_files = ∅. - Run
check_commandsin order. The first failure in step 2 or 4 stops the pass. - The first time in this run they all pass (pre-existing failures aside), launch the reviews per
references/review-launch.md§ Launch, without waiting. - Run
test_commandsin order. ASkill(<name>)entry is called with--base-commit <base-commit>; it returns SUCCESS / TEST_FAILED / EXECUTION_ERROR. EXECUTION_ERROR uses no fix round: report its reason and wait (USER GATE) forretryorstop(ends the run as step 6 does). - Classify each failure. A failure whose failing test and failing code both lie outside the files changed since
<base-commit>is pre-existing: record it, do not fix it, do not count it. If the workflow's own fix (Tidy, a review fix) broke a test that passed before, correct that fix rather than the implementation. - Fix and rerun. At most 3 fix rounds per entry into this phase. After the third, stop: report the command, its last output, and that nothing was committed.
- When a check command rewrites files outside the task's changed set beyond trivial formatting (whitespace-only at any size, or ≤ 5 comment lines), warn and stop; never revert its output silently.
In mob mode, narrate every failure per references/mob-mode.md § Check / Test before fixing it.
Phase 10: Rules Compliance Review
Express lane skips. Take the background result per references/review-launch.md § Collect when it is fresh; otherwise call Skill(rules-review) with --base-commit <base-commit> and Model: <model>. Fix every reported violation; when a violation is a pattern rather than a one-off, grep the file for the defining token and fix every match. A rule-doc-drift classification gets no code fix; note it for Update Rules. Record edited files in review_fix_files. Do not rerun Check / Test here.
Phase 11: Code Review
Skipped on Trivial and when code_review: false. Take the background result per references/review-launch.md § Collect when it is fresh; otherwise run step 1.
- Call
Skill(<reviewer>)withModel: <model>,git diff <base-commit>, the content of untracked new files labeled as such,custom_instructionswhen set, Phase 7's no-comment rule as a standing rejection criterion, the three categories (correctness and edge cases; conventions and consistency including a light.claude/rules/check; simplicity and maintainability), the current subtask and its siblings when a decomposition state is active, and Plan Review's finding-reporting instruction. - Fix genuine findings; reject the rest with one line each. If the user would plausibly raise the point themselves, fix it. Duplicates of Rules Compliance findings are skipped. After a Critical fix, sweep the diff for the same defect class. Record edited files in
review_fix_files. - Escalation: exactly one more pass when this pass had at least one Critical finding and at least one fix was applied. The escalation pass scopes to the changes since the first pass. It never triggers a third.
- Findings still unresolved after the passes go to the user once (USER GATE). Fixes made there also enter
review_fix_files.
In mob mode, predict and cross-check per references/mob-mode.md § Code Review.
Phase 12: Verify Fixes
If review_fix_files is empty, skip this phase. Otherwise run Check / Test once (3 fix rounds apply; files they edit join review_fix_files). Then, if Rules Compliance Review ran, call Skill(rules-review) with --base-commit <base-commit>, Files: <review_fix_files>, and Model: <model>. Fix violations once; a second scoped pass over the newly fixed files is the last; violations still present go to the user (USER GATE).
Phase 13: Completion Hooks
Skipped when hooks.on_complete is unset, or with a one-line note when the tree has no task-derived changes. Run entries in list order: Skill(<name>) as a skill, anything else in Bash. When a decomposition state file is active, do not run an entry that would move or delete it; say so. A failing entry is reported and the rest still run. If any entry wrote to the tree, run check_commands once.
Phase 14: Interactive Commits
USER GATE. When the snapshot chain exists, first absorb the review layers' edits into it per references/snapshots.md § Absorb review fixes. Then read references/commits.md and follow § Procedure. Set landed_count = 0 on entry. Never git push.
In mob mode, add the per-commit note and the already-reviewed accept variant per references/mob-mode.md § Commits.
Post-commit verification: when gate adjustments edited any file, run Check / Test once after the last commit and offer those edits as one extra commit (pathspec = the edited paths minus § Workflow artifacts); skip it after a mid-loop cancel.
Phase 15: Update Rules
- USER GATE, on every tier. List the remaining enabled phases — this extraction (full lane only), Self-Retrospective, Workability Retrospective, PR Rule Extraction (always) — and ask
proceed/session-only/pr-only/skip(proceed/skipwhen only one side — session-derived or PR-derived — is listed).skipmarks all listed completed unrun;session-onlymarks PR Rule Extraction so;pr-onlymarks the session-derived ones so. If.claude/demo.mdor.claude/demo.local.mdexists, the gate also asksdemo/no-demo.demo, whatever the first answer, callsSkill(demo)withPlan:the plan's current path (.claude/plans/**/<slug>.md),Base ref: <base-commit>,Language:the resolved language,Model: <model>. Its Demo line for Completion:ok→ the URL or page path with the step and failed counts and any files it edited;skipped/error→ thereason; no parseable JSON block →no parseable result, without retry. Express lane: steps 2–3 do not run. - Call
Skill(extract-rules)with--from-conversation, unless ahooks.on_completeentry containsextract-rules(it already extracted). If the diff introduced a new framework, library, pattern, or API convention and no conversation extraction ran, use--updateinstead. If extract-rules is unavailable, write the session's reusable patterns to.claude/plans/rules-candidates-<YYYY-MM-DD>.mdand tell the user. - Rule commit (USER GATE): run the § Rule commit gate procedure of
references/commits.mdover uncommitted paths under.claude/rules/,.claude/rules-extras/,.claude/rules-staging/(or the dirs.claude/extract-rules.local.mdsets). Skip when there are none.
Phase 16: PR Rule Extraction
Skipped when the Update Rules gate skipped it. USER GATE. Ask which reviewed PR to extract rules from, naming the accepted forms (a number, owner/repo#N, a 100..110 range, a URL, several separated by spaces); an empty answer declines. On an answer, call Skill(extract-rules) with --from-pr <answer verbatim>. "Nothing qualified" and "no human comments" are success; a pre-flight error is noted and skipped. Then run the § Rule commit gate procedure again over what it wrote.
Phase 17: Self-Retrospective
Skipped when self_retrospective.feedback is unset or the Update Rules gate skipped it. Read references/self-retrospective.md and follow it; its preview is a USER GATE. Nothing here edits a skill.
Phase 18: Workability Retrospective
Skipped when workability_retrospective.enabled is false or the Update Rules gate skipped it. Read references/workability.md and follow it; its dispositions are a USER GATE.
Phase 19: Completion
- Summary in the resolved language: what was done, files changed, check/test result, review outcomes, rules updated, commits made, the Demo line when one exists, the Self-Retrospective and Workability lines, the timing table per
references/timing.md§ Report, and one line per phase skipped or stopped early. List skipped callees and any uncommitted rule files. - Decomposed runs: read
references/decomposition-state.mdand follow its § Finish a subtask; its PR question is a USER GATE. - In mob mode, add the learning summary and the paired resume commands per
references/mob-mode.md§ Completion. - Delete this run's staging state:
rm -feach existing staging file listed in § Workflow artifacts (named paths, no globs),rm -rf .claude/plans/<slug>.absorb, andgit update-ref -don eachrefs/dev-workflow/<slug>*ref. Never delete the plan file (hooks.on_completeowns archiving) or the decomposition state file (step 2 owns it).
Sponsors
Details
- Marketplace
- hiroro-work/claude-plugins
- Source
- skills/dev-workflow
- Author
- hiropon
- Category
- Workflow
More from hiroro-work/claude-plugins
All 22- dev-workflow-bundlev2.44.0
- extract-rulesv1.31.0
- furikaeriv1.0.2
- kabeuchiv3.1.1
- merge-rulesv2.1.3
- mobprov2.0.1
- peerv2.6.7
- prose-polishv1.9.0
- rules-reviewv1.8.8
- security-scannerv1.3.2
- tidyv1.6.4
- translatev1.1.2
- apply-rulesv2.1.3
- artifactorv1.1.3
- ask-agyv1.0.1
- ask-claudev1.1.4
- ask-codexv1.2.4
- ask-copilotv1.0.5
- ask-geminiv1.2.3
- caffeinatev1.0.0
- demov1.14.0