claude-code-workflows

Claude Code Development Workflows

Claude Code can explore a codebase deeply. On non-trivial work, the harder problem is convergence. 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.

claude-code-workflows keeps that work tied to an agreed result. It records the outcome and its exclusions, then creates only the design and verification artifacts the change needs. A separate review checks the finished implementation against that outcome, while Claude still decides how to get there from repository evidence.

Use Claude Code directly when the outcome and safe implementation boundary are already clear. Use these workflows when a change needs scope agreement, durable design decisions, a reliable handoff between contexts, or independent verification.

When is the workflow useful?

A focused fix, experiment, or prototype is usually faster to run directly. The workflow adds agent calls and artifacts, so it should earn that cost.

On a larger change, a real side finding can still be the wrong work for the current outcome. The workflow keeps the approved result and exclusions in view from design through final review.

Specialist agents contribute repository evidence and draft artifacts. The main session still owns the product scope: it applies findings needed to protect an approved requirement, contract, or observable behavior, and can decline findings that only add work. Product changes and major design changes return to the user. Reversible implementation choices remain with Claude.

Because the process is packaged as a Claude Code plugin, a team can apply the same boundaries across repositories without prescribing Claude's steps.

Quick Start

Requires a Claude Code release with plugin marketplace support.

Choose a path

Common setup

# 1. Start Claude Code
claude

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

Install one workflow plugin

Install the plugin that matches your project. If the install tells you to run /reload-plugins, do that before invoking the recipe.

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

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

# Full-stack
/plugin install dev-workflows-fullstack@claude-code-workflows
/recipe-fullstack-implement "Add user authentication with JWT + login form"

Install only one workflow plugin. dev-workflows-fullstack already contains the backend and frontend workflows. If you previously used full-stack recipes from dev-workflows, migrate to dev-workflows-fullstack.

/recipe-front-design stops after the applicable UI Spec and Design Doc are reviewed and approved. Run /recipe-front-plan and /recipe-front-build when you are ready to continue. For a backend or general change, /recipe-design, /recipe-plan, and /recipe-build provide the same staged path.

Team setup

Claude Code supports project-scoped marketplaces and plugins. Commit the resulting .claude/settings.json so contributors are prompted to use the same workflow plugin.

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

Replace dev-workflows-fullstack with the plugin that matches the repository. See the Claude Code plugin documentation for project and managed installation options.

How It Works

flowchart LR
    A[Request] --> B[Agree on outcome and exclusions]
    B --> C{Durable design needed?}
    C -->|No| F[Implement]
    C -->|Yes| D[Inspect and record needed decisions]
    D --> E[Approve product and major design boundaries]
    E --> F
    F --> G[Verify the approved outcome]
    G -->|In-scope gap| F
    G -->|Boundary changed| B
    G -->|Passed| H[Complete]

The number of product and design decisions determines the route. Small changes skip documents they do not need. Larger changes add codebase analysis and a Design Doc, plus a PRD, UI Spec, ADR, acceptance tests, or work plan only when required by the scope.

The main session owns convergence between phases. It carries forward only evidence that can change the next decision, resolves repository-local ambiguity, and keeps unaffected work moving. When implementation is complete, separate reviews provide evidence about design consistency, observable coverage, and security. Their findings are resolved against the approved outcome instead of becoming work automatically.

A handoff you can inspect

Fresh contexts only help if the handoff between them is concrete. The included Work Plan template requires every approved technical requirement from a Design Doc to have a covering task or an explicit gap. It does not turn every document section or review suggestion into a task. A gap means an approved requirement has no implementation or verification task yet.

| Design Doc | DD Section | DD Item | Category | Covered By Task(s) | Gap Status | Notes |
|---|---|---|---|---|---|---|
| docs/design/example.md | API contract | Preserve the error response shape | contract-change | Phase 2 Task 1 | covered | |
| docs/design/example.md | Verification | Exercise cache invalidation | verification | | gap | Add a covering task before approval |

The Task template then carries binding decisions and observable contract values into implementation, each with a yes-or-no compliance check. The final review reads the same source documents instead of relying on the implementation conversation.

A real workflow run

The incremental sync feature in mcp-local-rag was a 42-file change across filesystem scanning, storage, and both the CLI and MCP surfaces. An independent security review sent the implementation back twice. It caught file reads happening before validation and a path-containment escape through a symlinked parent.

The run began with an existing Work Plan that referred to an ADR and Design Doc that were not present, leaving the approved source for its technical decisions unclear. The user chose to treat the Work Plan as the source of truth, and the recipe divided it into 13 planned tasks. The final implementation included the changes needed to verify the approved behavior, while the PR records why watch mode and persistent jobs were left out.

What to inspect after the first run

After the first run, inspect the artifacts:

• Does the agreed approach extend what already exists and give evidence for each addition?
• Can you follow each requirement into a task and a verification method?
• Did implementation stay within the approved outcome and contracts while including required adjacent changes?
• Does the final report compare the finished code with the intended behavior and security requirements?

Typical Workflows

End-to-end backend or general development

/recipe-implement "Add rate limiting to the public API"

The recipe scopes the change, inspects the current implementation, creates only the documents required for its size, pauses when a decision is needed, and carries the plan through implementation and final review.

Design first, implement later

# Backend or general
/recipe-design "Design rate limiting for the public API"
/recipe-plan
/recipe-build

# React frontend
/recipe-front-design "Build a user profile dashboard"
/recipe-front-plan
/recipe-front-build

The design recipes inspect the existing code, confirm the scope, create the required documents, run an independent consistency review, and stop for approval. Planning and implementation can continue later, in a new context or by another contributor, from those approved artifacts.

The frontend path adds UI analysis and a UI Spec when UI structure or behavior remains to be designed, plus component architecture, React Testing Library, and TypeScript checks.

For example, two dashboard components may each handle loading correctly while the combined screen has no defined behavior when one is loading and the other has failed. The UI Spec records that state combination and traces it into design and test work before integration.

Full-stack development

/recipe-fullstack-implement "Add user authentication with JWT + React login form"

When the scale calls for a PRD, one document covers the whole feature. Backend and frontend design stay separate, design-sync checks the boundary between them, and the work plan uses vertical slices so integration is exercised before the end.

Use /recipe-fullstack-build to continue from an existing full-stack work plan. The full-stack plugin also includes the applicable backend and frontend recipes.

/recipe-review

/recipe-diagnose "API returns 500 on user login"

/recipe-reverse-engineer "src/auth module"

/recipe-front-adjust "Align the card spacing and actions with the design source"

Workflow Recipe Reference

All workflow entry points use the recipe- prefix. Type /recipe- and use tab completion to see what the installed plugin provides.

What the Plugins Include

Specialized agents keep analysis and design separate from execution and final review. Each plugin includes only the roles its workflows use; the full-stack plugin combines the backend and frontend roles. The complete role list is folded below.

/plugin install dev-skills@claude-code-workflows

# dev-skills -> dev-workflows
/plugin uninstall dev-skills@claude-code-workflows
/plugin install dev-workflows@claude-code-workflows

# dev-workflows -> dev-skills
/plugin uninstall dev-workflows@claude-code-workflows
/plugin install dev-skills@claude-code-workflows

/plugin install discover@claude-code-workflows
/plugin install metronome@claude-code-workflows
/plugin install linear-prism@claude-code-workflows
/plugin install pr-review@claude-code-workflows

FAQ

Q: What if there are errors?

A: The quality-fixer agents handle test, type, lint, and build failures within the approved outcome, including adjacent changes required by the same responsibility or contract.

The workflow stops only when a fix:

• changes the product outcome, an approved contract, or a major design decision;
• requires authority held by the user; or
• performs an irreversible external action that the existing approval does not cover.

Q: Is there a version for OpenAI Codex CLI?

A: Yes. codex-workflows provides the same workflow model, adapted to the Codex CLI environment.

Q: Should I commit the work plan and task files in docs/plans/?

A: No. Recipes treat docs/plans/ as ephemeral working state. Consumed task files and intermediate fix files are cleaned up after successful execution. The work plan may remain for review or a later build and can be deleted when it is no longer needed. Add the following line to your project's .gitignore so this working state stays out of git:

docs/plans/

PRDs, ADRs, UI Specs, and Design Docs live in their own directories (docs/prd/, docs/adr/, docs/ui-spec/, docs/design/) and are intended to be committed.

Contributing External Plugins

This marketplace supports the full lifecycle of building products with AI: product quality, discovery, implementation control, and verification. If your plugin helps developers build better products with AI coding agents, we'd like to hear from you.

See CONTRIBUTING.md for submission guidelines and acceptance criteria.

claude-code-workflows/
├── .claude-plugin/
│   └── marketplace.json        # Plugin definitions and per-plugin contents
├── agents/                     # Specialized analysis, design, execution, and review roles
├── skills/
│   ├── recipe-*/               # Workflow entry points
│   ├── documentation-criteria/ # Document rules and templates
│   ├── coding-principles/
│   ├── testing-principles/
│   ├── external-resource-context/
│   ├── llm-friendly-context/
│   └── ...
├── LICENSE
└── README.md

Design Rationale

• When Better Models Make Old Agent Workflows Worse: why the workflow is strict about boundaries and evidence without prescribing the route between them
• Reasoning Effort Is Not a Quality Setting: why broader exploration must still converge on the work the current outcome justifies

License

MIT License. Free to use, modify, and distribute.

See LICENSE for full details.

Built and maintained by @shinpr.