.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
If you got here searching for the npm package @pimzino/claude-code-spec-workflow, here's the fact that matters before you install anything: that package is legacy. The repo isn't archived and the package still installs, but its own README says development focus has moved to the MCP (Model Context Protocol) successor, spec-workflow-mcp. Everything below sets up the successor, walks a real feature through it and finishes with my take on when this much process pays for itself. Tested on Ubuntu 24.04 with the 2.1 line of the Claude Code CLI.
What spec-driven development means with a coding agent
The default way people use a coding agent is one giant prompt: describe the feature, let it run, review whatever comes out. That works for small tasks and degrades badly as scope grows, because the agent makes a hundred small decisions you never saw, and by the time you disagree with one it's load-bearing.
Spec-driven development splits the work into phases with approval gates between them. First a requirements document: what the feature does, for whom, with acceptance criteria. Then a design document: how it fits your existing code, which modules change, what the data model looks like. Then a task list: small numbered implementation steps derived from the design. You approve each document before the next phase starts, so disagreements surface while they're still words on a page. The agent only writes code once all four of you agree, so to speak: you, the requirements, the design and the task list.
The honest downside is ceremony. Three documents and several approval clicks for a feature you could have described in two sentences is overhead with no return, which is why the last section of this article is about when to skip the whole thing.
The legacy package and spec-workflow-mcp
The original claude-code-spec-workflow project (around 3.8k GitHub stars) implemented this as slash commands installed into your project. It still works today, but treat it as frozen: the README redirects new effort toward the MCP version, and building a workflow on a package whose own author has moved on is how you end up maintaining a fork you never wanted.
The successor, spec-workflow-mcp (around 4.3k stars, GPL-3.0), reimplements the same Requirements, Design and Tasks flow as an MCP server, which is the right shape for it. Your agent gets tools for creating and querying specs, while approvals move to a web dashboard or a VS Code extension instead of living inside the chat. One caveat to price in before you adopt it: the maintainer has a note in the README about taking a break from the repo for personal reasons, with a stated intent to return. Development has paused before on this project and resumed, but a single-maintainer tool on hiatus is a real dependency risk, and I'd rather you read that in the second section than discover it in an unanswered issue.
Add spec-workflow-mcp to Claude Code
One command, verbatim from the repo's README:
claude mcp add spec-workflow npx @pimzino/spec-workflow-mcp@latest -- /path/to/your/projectSwap in the absolute path of the project you want specs for; the server is scoped to one project directory, which is also where your spec documents will live. Start a session afterward and run /mcp to confirm the server shows up as connected. By default claude mcp add registers servers at local scope, so if the team should share this setup, re-add it with project scope and commit the resulting .mcp.json; the scope mechanics are covered in the guide to Claude Code MCP configuration, and the general claude mcp add syntax is in the official MCP documentation.
The dashboard on localhost:5000
Approvals happen outside the chat, and that's the point: a requirements document deserves a better reading surface than a scrolling terminal. Start the dashboard as its own process:
npx -y @pimzino/spec-workflow-mcp@latest --dashboardIt serves on localhost port 5000 by default and shows every spec in the project with its phase, pending approvals and task progress, plus searchable implementation logs once tasks start executing. If you live in VS Code, the marketplace extension (published as Spec Workflow MCP, id Pimzino.spec-workflow-mcp) puts the same review-and-approve surface in a sidebar so you never leave the editor. I prefer the browser dashboard on a second monitor, but that's a seating preference, and the extension is the obvious pick on a laptop screen.
Walkthrough: A password reset feature
Here's the shape of a run on a realistic feature, a password reset flow for an existing Express API. In a Claude Code session with the server connected, the kickoff is plain language:
Create a spec for password resetThe agent drafts the requirements document first: reset request endpoint, token expiry, email delivery, what happens on reuse of a spent token. This is the highest-value review of the whole process, because it's where you catch the missing requirement (rate limiting on the request endpoint, in my case) while adding it costs one sentence. The document lands in the dashboard as a pending approval, where you approve it or send it back with feedback and get a revision.
Approve requirements and the design phase starts, this time grounded in your codebase: which existing modules handle mail, where the token table fits the schema, how the new endpoints slot into the router. Same gate again. Approve the design and the tasks phase breaks the work into small numbered items you can execute one at a time:
Execute task 1.2 in spec password-resetEach completed task updates the progress view in the dashboard. Running tasks individually feels slow for the first hour and then starts feeling like the point: every diff maps to one named task from a design you approved, which makes review nearly mechanical. Ask for List my specs whenever you lose track of where things stand across features.
Because specs are documents on disk rather than conversation history, they survive /clear, a reboot or a fresh session next Tuesday. That persistence is the practical difference from everything session-shaped; context evaporates, as the guide to Claude Code sessions explains, but a spec is still there when you come back.
Spec workflow vs plan mode vs CLAUDE.md
Claude Code already ships a planning gate: plan mode makes the agent propose before touching files, and for single-session work it covers most of what people want from process. The differences are persistence and audience. A plan is one approval, one session, then gone; a spec is a set of documents with a revision trail that a teammate (or you, three weeks later) can read without replaying a conversation. Plan mode asks "do you approve this approach"; the spec workflow asks it four times at increasing resolution.
Writing feature specs into CLAUDE.md is the other tempting shortcut, and it's the wrong tool. CLAUDE.md is standing context, loaded into every session whatever you're working on, so a per-feature spec in there taxes unrelated work and goes stale the day the feature ships. Conventions and commands belong in CLAUDE.md. Anything with a lifecycle belongs in a document that has one too.
When to use the spec workflow
My honest split, after running both ways: the spec workflow earns its overhead on features measured in days, on teams where someone other than the prompt author reviews the direction and anywhere an approval trail has value, like client work where "you signed off on the design" needs a timestamp. The gates convert vague disagreement into cheap, early, written disagreement, and on a multi-day feature that's worth every click.
For solo work measured in hours, plan mode alone is enough and the ceremony is pure drag. I'd also skip it on codebases you're still exploring, where the honest answer to "what are the requirements" is that you don't know yet. And if what you want is structured reasoning rather than structured documents, a lighter tool like the Sequential Thinking MCP server adds discipline to the model's thought process without putting gates in front of yours. Pick the heaviest process that still gets used; in my experience that's specs for features, plan mode for tasks and neither for typo fixes.
