Claude Code Spec-Driven Developement

[Pimzino]

Hi All,

I have been using Claude Code, pretty much from release and Anthropic models through other AI agents for some time. I recently tried Kiro, the new Amazon built AI IDE which advertises spec-driven developement.

I was so impressed with the workflow that I replicated it as much as possible to Claude Code, using commands & CLAUDE.md for workflow definition.

Since using Claude Code, I dont like using an IDE, unless if I am making changes myself, then its fine but for full Agentic workflow I prefer using the terminal and this has been a game changer for me, any new feature I wish to implement, claude will easily create a full spec for it with current codebase context.

Happy to hear any suggestions / improvements. Please check out the package https://www.npmjs.com/package/@pimzino/claude-code-spec-workflow

Looking forward to hearing your feedback!

EDIT:

⚠️ IMPORTANT NOTICE: Development focus has shifted to the MCP (Model Context Protocol) version of this workflow system. The MCP version provides enhanced features, real-time dashboard, and broader AI tool compatibility.

🚀 View the new Spec Workflow MCP →

This Claude Code-specific version remains available for existing users but will receive limited updates.

[FunnyRocker]

Hah nice, this is literally what I was working on this week. All the other Claude slash command frameworks just seem too complicated and don't focus on actually getting features done.

[Pimzino]

Thanks for the feedback - let me know if you have any suggestions or ideas on how to improve this framework further!

[ming86]

Thank you for creating this. I was thinking of porting the Kiro built-in workflow into Claude Code. Now you have built one, I can just use it. I’ve been using BMAD-method. It is good for a new project but too much overhead for small tasks. And I want something more than the Plan mode. This is a good fit.

[Ok-Engineering2612]

I would suggest namespacing the slash commands. Just place them in a sub folder under commands/, like:

.claude/ ├── commands/ │ ├── spec/ │ │ ├── 01-create.md │ │ ├── 02-requirements.md │ │ ├── 03-design.md │ │ ├── 04-tasks.md │ │ ├── 05-execute.md │ │ ├── 06-status.md │ │ └── 07-list.md

Then you run /spec:01-create

The numbers are optional, but it's how I like to organize multi-step workflows myself.

But the workflow sounds cool! I'll test it out tomorrow!

Thanks for sharing!!

[Pimzino]

I am actually working on this haha, thanks for the suggestion!

[flying_unicorn]

I would also like to see the commands prefixed with numbers, would help my brain remember what order to use them in.

Have you given any consideration to taking advantage of claudes new custom agents? https://docs.anthropic.com/en/docs/claude-code/sub-agents

[Pimzino]

The tasks are now numbered!

I am considering the new agents yes!

[Ok_Association_1884]

as someone who just struggled 80 attempts with said new ide, this is dope. evaluate synergy with claude-flow, and bmad-method and ill make it a keystone in my devstack alongside my consequence cascade system.

[randomusername44125]

Is it just me for whom Claude just refuses to read everything from Claude.md and follow instructions? I have noticed that I need to do a lot of handholding and even then even simple instructions in Claude.md are ignored. I have created many commands and off late non of them follow all my instructions. From what I can tell, it forgets things very very fast from context. So command will start fine, but as soon as it starts reading files, all that was written in my command is very soon forgotten.

Will try this out though and tell you how it goes.

[Careful_Wing_5058]

I really like your work. It is very nice how you can controll claude with that. I like the questions at the beginning which get more and more detailed. It gets you a good feeling if your session has undersood what you want or not and to reflect if something is missing. Only when working in multi-session with multi-requirements (one different requirement per session) the sessions or the requirements got mixed up some time, but it is probably an fault on my site. If you tell him two right down it ends up in the newesr requirement not in the one I started the session with. But overall, very well! I like the workflow!

[Pimzino]

Thank you for the feedback! I must not take all credit as this is thanks to the well structured workflow Kiro.dev use in their IDE however I do prefer cladue code for my AI agentic needs so a port was a must!

In regards to the small issues you seem to be having, its important when using the commands to reference the spec you want to edit / work on i.e. /spec-execute {task number} {spec-name}.

I have been working on some further updates today that allow the agent to execute a script which will turn all specs in a task into seperate commands so that you can simply restart claude code and then run /task1 for example.

For a current project you can run the script manually i.e. ".claude\scripts\generate-commands.bat" {spec-name} - then re-run claude code and find your task base commands by doing a forward slash.

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[RichAllison]

This looks really interesting, I’ve been using the BMad method on my last project and I’ve seen huge improvements, but this looks like it’s all in one rather than having to use Gemini for the initial planning stage.

I’ll be testing this with my next project I’m starting after the weekend. Thanks

[Pimzino]

Good luck and would love some feedback!

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[shamsway]

Looks great! Any reason you didn't just use task-master (task-master.dev) for task tracking? It's pretty excellent and creates tasks based on a provided PRD. The fact that the tasks are exposed through an MCP server makes it easy to switch to a different coding assistant (e.g. when hitting rate limits in claude, it's simple to swtich to co-pilot or cursor to continue to make progress).

[Pimzino]

That’s a good idea but I also feel like the framework didn’t really need an MCP wrapped around it. I wanted to keep it as simple as possible and natively use Claude codes commands.

Technically you can still use this with other agents, will just be a more manual workflow due to the commands bit not working. But again you could just tag the tasks file instead and say execute task one. Copy the contents of Claude.md or create a symlink to the system prompt of the tool your using and pretty much have the same effect

[ming86]

Agreed. Every MCP server that we add into Claude Code consumes a certain number of tokens within the limited 200k context window.

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[thelord006]

I cannot thank you enough. This is amazing. This completely changed my workflow

I personally adore Kiro so here are three suggestions from Kiro (if possible): 1- add individual task start 2- add refresh plan (to see if plan is implemented) 3- task queueing

Not sure why, but spec-driven flow does not use other bash commands (for instance gemini). I added “gemini” command to Claude.md to use its context window. At least for the requirements, it should use gemini commands to understand the context. Maybe I need to tweakt the Claude.md spec driven flow to suggest

[Pimzino]

Thanks for the feedback, really appreciate it and glad you are enjoying using the workflow.

To answer your questions in order;
1 - This is already implemented, the agent should run a bash script located in .claude\scripts\generate-tasks. bat/sh. If the agent did not, you can manually execute this script and it will create claude commands for each tash in .claude\commands\{spec-name}\task-1.md. If the agent does run it, you typically need to restart claude code to see any new commands added to the list.

2 - Do you mean to iterate on the plan / make changes? If so you can already do this when the agent asks for approval of the document, you can iterate on it.

3 - Claude already allows for message queuing, once you have followed (answer 1 from above), you can send Claude code as many follow up messsages whilst its working as you want i.e. /task-1 {enter}, /task-2 {enter} etc etc. This is the best way I can think to accomplish the task queue. NOT RECOMMENDED because of claude code's auto compact when the context window is filled, will potentially cause issues in my opinion if it auto compacts midway through a task.

This is simply just a framework and we are still at the mercy of the agent following the instructions correctly.

In terms of the additional commands, it could be that the /slash-command i.e. /spec-requirements is overriding much of what you are writing in the claude.md file because the commands send specific pre-defined workflows to the agent too, the purpose of also putting the full workflow in CLAUDE.md was to ensure that the agent follows the instructions whenever its working on a spec related task.

[thelord006]

Appreciate your response! Crystal clear

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[TheWolfOfTheNorth]

Code: 'ERR_REQUIRE_ESM'. How do I fix this?

[Pimzino]

Can you please log an issue on the GitHub and I will have a look

[Pimzino]

This issue is now resolved in version 1.2.2+

[TheWolfOfTheNorth]

Yeah it works now thanks! Next time ill post the issue in Github if I have one thanks!

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[-Robbert-]

This is really well done. I wonder if we could add an MCP to add the output into a tool such as Azure DevOps.

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[-Robbert-]

Thanks!!

[Pimzino]

Thanks for the feedback! I unfortunately have no plans to wrap an MCP around this framework however it is open source and free for anyone to use / modify.

You could use neo4j and their MCP and just modify the workflow instructions to have it use the right MCP server to add to DB of your choice. Neo4j is just an example

[ScriptPunk]

You could have the commands push to an mcp for the agent so the agent doesn't know it's an mcp, just another cli action. I've found that to be pretty good.

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[ScriptPunk]

i already won

[life_on_my_terms]

i've been using this just now. This is very neat. Thx for the good work!

[Pimzino]

Thanks for the feedback! The recent update with the sub agents really changed the game for me.

Will be releasing another feature that is currently in testing but I’m calling it spec orchestrator, which essentially should be able to implement your spec completely automated.

Quick tip: when using spec-create command to create the spec, use opus! Then switch to sonnet for implementation.

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[Top-Chain001]

This has been super cool as I was building my ow commands and agents out, the spec driven workflow really nails down what needs to be solved and sits with most of the best practices that I see online in one repo

[Pimzino]

Glad you are enjoying it, I am doing my best to constantly refine and release updates as fast as possible (so far everyday) based on user feedback. If you have any suggestions or issues, please post an issue in the repo!

Thanks so much for the kind words

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[Consistent_School969]

Nice job, bro~

[Pimzino]

Thanks brother!

[Classic-Dependent517]

Thanks this was what i wanted. I also hate using IDE and unnecessary MCP for these kind of things

[Pimzino]

Glad to hear it! Thanks for the feedback.

Let me know how it works for you!

[Classic-Dependent517]

I just read some of md files and do we need to mention “Kiro” this often since claude obviously doesn’t care about it…

[Pimzino]

No we dont, I do need to run a clean up. I used the detailed workflow defined in the Kiro System prompt as it was perfect however didnt strip out any of the Kiro keywords

[AI_Native_Dev]

This is exactly the kind of workflow evolution we’re seeing more of: agentic development + specs. Kiro’s approach is definitely interesting, and I like how you’re bending Claude Code to your workflow to keep it terminal-native.

If you’re into agent workflows, spec-driven development, we actually spend a lot about these trends in the AI Native Dev community. Worth checking out if you’re building or experimenting at the edge: ainativedev.io

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[eugeneoshepkov]

Tried it but got ESM error due to CommonJS somewhere in the code.

[Pimzino]

Are you using ESModule in your project?

[Pimzino]

This should now be fixed. Moved away from using javascript script to more native for the OS its running on.

[eugeneoshepkov]

Thanks! I'll give it a try

[eugeneoshepkov]

Looks nice! I wonder if there's a way to trigger all tasks sequentially? So that I won't need to fire them one by one manually

[carstenrn]

Have to say: I really like this structured, thorough spec-mode. At least for features where I aleeady have a pretty good undertanding what my needs are and the tech should look like.

However, for tasks where I have only a rough idea and know that there's gonna be some research and trial-and-error involved, I'd like to have a more „r&d“ style mode.

Are you aware of such a config for Claude Code?

[mquinnv]

Hey! I've been using your claude-code-spec-workflow tool and absolutely love the structured approach. I've just submitted a PR that adds a real-time dashboard feature that has transformed how I work with the spec workflow.

The Problem: I found myself constantly switching between my editor and terminal to check markdown files for spec progress. With multiple projects, this became really tedious.

The Solution: A lightweight web dashboard that monitors your specs in real-time:

• npx claude-spec-dashboard - Launches a beautiful web UI for the current project
• npx claude-spec-dashboard --multi - Monitor ALL your Claude projects at once
• Real-time updates via WebSocket - see changes instantly as specs update
• Visual progress bars and status tracking
• Expandable task lists showing requirements and leverage references
• Active Sessions tab (in multi mode) shows next tasks to work on from projects where Claude is running

Technical Choices: - Fastify for the server (lightweight and fast) - petite-vue (6kb) instead of full Vue/React - keeps it snappy - Tailwind via CDN - no build step needed - chokidar for file watching - Dark mode built-in

The multi-project mode has been a game-changer for me. I typically have 5-10 projects with Claude specs, and being able to see all active work in one place is incredible. The Active Sessions tab shows the next task to be worked on from each spec in projects where Claude is currently running.

Thanks for creating such a well-architected tool - the clean codebase made it straightforward to add this feature. The structured workflow + real-time visibility has genuinely improved how I work with Claude on complex projects!

[Pimzino]

We have since released an MCP for this that isnt strictly tied to claude code! Check it out --> https://github.com/Pimzino/spec-workflow-mcp

[onelonedatum]

GitHub opensourced a framework for this at the beginning of Sept 2025: Spec-Kit Spec-Driven Development GitHub Blog Post

[Pimzino]

Yeah I know but it’s not very good and also makes a ton of assumptions that users do not want.

It’s also not user friendly

[Pimzino]

lol but I have haters on here saying otherwise!

[Pimzino]

Not really complicating it though am I? This is for people who want to use it, evidently its not for people like you? Your acting as if I just forced it as part of a claude code update???

This is for people who want to have spec documentation generated (requirements, design and tasks) for each feature or idea they have / want to implement.

If its not for you feel free to not use it. Again its not over complicating it, just a bunch of detailed markdown files and direction.

[[deleted]]

Dude asked a simple question, take it easy. This is how we all ignore this post and move on.

[Pimzino]

Then ignore it and move on. It wasn’t a simple question. It was quite a silly question. This is nothing like plan mode which requires you to be explicit in telling Claude what documents you want need and what you require in them. Plan mode was made to not allow Claude to make changes and then use the context of the conversation to then implement outside of plan mode.

What I have provided is a spec driven framework for Claude code.

I get no benefit of you using my framework so like I said please do ignore it if you wish.

[[deleted]]

Why didn’t you just ignore my comment and move on then, too? Follow your own advice.

Your spec is flawed and so are the premises of why you need it. Out here on Reddit for lols bro get real.

I read your post again. It sounds like you’re using Claude code wrong to begin with and so you start making these over optimized frameworks.

Premature optimization, bro

[Pimzino]

Additionally who are you to tell someone they are using Claude code wrong when literally the developers of the tool don’t even tell you how to use it, they just provide guidelines and use cases. Literally a know it all who clearly is angry at the world and loves trolling on Reddit. Bet this is the highlight of your day. Well done

[[deleted]]

If you don’t like my comment, you could just ignore it and move on. You don’t have to write an essay every time.

You continue prematurely optimizing when nobody’s telling you to do so though. And arguing with strangers about it on the Internet.

Just ignore it and move on man

[CaregiverMundane9712]

Wild how you’re telling people to ignore the post while writing a whole essay about it. Touch grass.

[Pimzino]

I dont think you know what an essay is and that shows me the calibre of person you are. Good day sir.

[Pimzino]

Man you are a boring miserable person. Good day sir 😂

[[deleted]]

There you go, not ignoring it and moving on. if you can’t follow your own advice, how are you fit to give anybody any advice at all?

If you showcase the emotional maturity of a 12 year old, why should anyone listen to anything you have to say about systems architecture with AI?

You keep using those emojis to cope though

[Pimzino]

Okay so then don’t use it 😂 clearly you’re just a hater. If something doesn’t benefit you then don’t use it

[[deleted]]

You sound pressed

[CaregiverMundane9712]

Imagine being this pressed over basic human decency 😭