shinpr/claude-code-workflows: a plugin that pins Claude Code to an agreed outcome

The convergence problem these workflows are aimed at

The README opens with a concrete failure: while designing an account-recovery flow, Claude may find a real inconsistency in token handling and spend most of the design on it, leaving the requested recovery behavior vague. That is not a capability problem. Claude Code already explores a codebase deeply. The harder problem, in the project's framing, is convergence. The workflow is a set of controls that keeps exploration pointed at an agreed result: outcome and exclusions are agreed before design, designs are checked against the repository, each task is verified before commit, and larger changes get an independent review of the finished implementation. The stated audience is anyone making a change that needs scope agreement, durable design decisions, a reliable handoff between contexts, or independent verification. The README is explicit about when not to use it, and that line is worth taking literally: use Claude Code directly when the outcome and the safe implementation boundary are already clear.

How the recipes route a change: decisions, not file count

The flow diagram in the README starts at a request, agrees on outcome and exclusions, then asks one question: is there one evident implementation path? If yes, the change runs a direct task cycle and completes. If no, the workflow inspects, designs and reviews, the user approves the implementation scope, and each task is implemented, verified, quality-checked and committed before an independent implementation and security review. That review can send work back to the task cycle, send it back to the outcome-agreement step when the boundary changed, or pass it. The routing table is the part worth reading twice: scale is determined by the number of product and design decisions, not by file count or the amount of implementation work. Small changes get the direct cycle plus focused and repository checks plus a security review. Medium changes get a reviewed Design Doc, a UI Spec or ADR when required, selected integration or E2E proof, a reviewed Work Plan, task cycles and a final review. Large changes add a reviewed PRD. UI Specs, ADRs and integration or E2E test skeletons appear only when their decisions or proof boundaries apply. One rule stands out because it constrains the agent rather than the user: generating an artifact does not advance the workflow on its own, and decision-changing design premises must be resolved with observable evidence before approval, using a bounded probe only when it is the smallest sufficient proof. Once scope is approved, Claude carries tasks through verification, quality checks, commits and final review without asking for routine implementation decisions, and asks the user only when the agreed product outcome or exclusions must change.

Installing the plugin and running a first recipe

The README states the requirement plainly: a Claude Code release with plugin marketplace support. Start Claude Code, add the marketplace, then install the plugin that matches your project. The install output may tell you to run /reload-plugins, and the README says to do that before invoking a recipe.

# 1. Start Claude Code
claude

# 2. Add the marketplace
/plugin marketplace add shinpr/claude-code-workflows

For a backend, API, CLI or general change, install dev-workflows and invoke the implement recipe with a description of the change. Install only one workflow plugin: dev-workflows-fullstack already contains the backend and frontend workflows, and the README says that if you previously used full-stack recipes from dev-workflows you should migrate to dev-workflows-fullstack.

/plugin install dev-workflows@claude-code-workflows
/recipe-implement "Add rate limiting to the public API"

Frontend work takes a different plugin and a staged path. /recipe-front-design stops after the UI Spec and Design Doc are reviewed and approved, and you run /recipe-front-plan and /recipe-front-build when you are ready to continue. The backend and general path has the same shape through /recipe-design, /recipe-plan and /recipe-build. For a combined change, install dev-workflows-fullstack and call /recipe-fullstack-implement.

/plugin install dev-workflows-frontend@claude-code-workflows
/recipe-front-design "Add account recovery screens"

For a team, the README gives project-scoped installation so contributors are prompted to use the same plugin, and says to commit the resulting .claude/settings.json. Replace dev-workflows-fullstack with the plugin that matches the repository.

claude plugin marketplace add shinpr/claude-code-workflows --scope project
claude plugin install dev-workflows-fullstack@claude-code-workflows --scope project

Other entry points are listed in the README's path table: /recipe-review and /recipe-front-review to review a completed implementation against the agreed outcome, /recipe-quality-profile to set repository-specific quality rules, /recipe-diagnose to investigate a problem before choosing a fix, and /recipe-reverse-engineer to document an existing system from its code.

Where this costs more than it returns

The README concedes the central trade-off: the workflow adds agent calls and artifacts, so it should earn that cost. That is a real constraint, not a disclaimer. Every reviewed Design Doc, Work Plan, PRD and test skeleton is an artifact someone has to read or approve, and the staged frontend path deliberately stops at design so a human can decide when to continue. For a one-line fix or a prototype, that overhead buys nothing, and the README's own answer is to skip it. The second limitation is environmental: the quick start requires a Claude Code release with plugin marketplace support, so anyone on an older build cannot follow it. The third is scope. The recipes are grouped as backend or general, React and TypeScript frontend, and full-stack. If your work is neither, the path table does not offer a matching plugin. The README also does not document rollback for a change that passes review and later turns out wrong; the review loop handles corrections before completion, and nothing in the published documentation describes what happens after.

How it differs from using Claude Code skills directly

The obvious alternative is assembling your own Claude Code setup from skills and instructions. The difference is where the control lives. A skill is content the model draws on when it is relevant; these workflows are a packaged sequence with approval gates, so the same controls can be applied across repositories without prescribing Claude's steps. The README frames the packaged form as the point: because the process ships as a plugin, a team gets the same outcome agreement, per-task verification and independent review in every repository. The second alternative is plain Claude Code with a well-written prompt. That is genuinely cheaper and the README does not argue against it for small work. What a prompt cannot give you is the routing rule and the review loop: a change with several independent product outcomes gets separate design decisions, and a finished implementation gets checked for delivering the agreed result, for unnecessary changes, and for serious functional, reliability or security problems. If your changes are usually one outcome following an existing pattern, the direct cycle is what you would get anyway.

Maintenance, licence and upgrade cost

The repository is not archived and the last push was on 2026-08-28, so this is current work rather than an abandoned experiment. Releases are frequent and fine-grained: v0.25.1, v0.25.0 and v0.24.10 all landed within three days of each other in late August 2026, which suggests the plugin surface is still moving. That frequency is also the upgrade cost. Because recipes are invoked by name (/recipe-implement, /recipe-front-design, /recipe-fullstack-implement), any rename or path change in a release reaches users through the plugin rather than through code they control. The README already documents one migration: full-stack recipes moved out of dev-workflows into dev-workflows-fullstack, and users are told to migrate. Expect that kind of churn again. The repository itself is a pnpm workspace with Node >=22, pinned to [email protected], using lefthook for git hooks and a sync script (scripts/sync-plugins.mjs) with a --check mode; that matters if you plan to fork and maintain your own copy rather than consume the published plugin. The licence is MIT, which permits commercial use and modification; the usual obligation is to keep the copyright and permission notice with copies or substantial portions. That is a summary, not legal advice.

Editorial conclusion

Adopt it when a change needs scope agreement before design and independent review after implementation, and your Claude Code release supports plugin marketplaces. Do not install it for throwaway experiments or prototypes; the README says to use Claude Code directly there. Before committing to it, verify that your Claude Code build accepts /plugin marketplace add, that only one workflow plugin is installed (dev-workflows-fullstack already contains the backend and frontend workflows), and that the project-scoped .claude/settings.json route works for your contributors.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes