/spec: a spec-driven workflow for Claude Code and Cursor
/spec is the skill I use to plan and ship features with coding agents. It runs the same workflow in Claude Code and in Cursor: you plan a change into a short spec folder, hand it to one fresh agent session per pull request, release it, and learn from it. The video walks through a real feature from start to finish.
Why I built it
Planning features with agents kept failing in the same few ways:
- Answers to my questions arrived after the design, and threw away work that was already done.
- Facts showed up late: a deprecated app, missing access, how much risk the team would accept.
- The briefs were too long and too vague to execute without coming back with questions.
- The same decision was written in several files, and the copies drifted apart.
So the skill asks early and asks few. Every fact has one home. Briefs stay short. Scripts check everything that can be checked, and a reviewer with fresh context checks the rest.
How it works
You type /spec <phase> <ticket or title>, one phase at a time:
| Phase | What happens |
|---|---|
| intake | at most 8 questions, each with a recommended default; picks a size (S, M or L) and creates the folder |
| research | a read-only sweep of the code, for M and L |
| intent | acceptance criteria, what is out of scope, and questions for stakeholders |
| design | architecture and decisions; you sign every decision that is hard to undo |
| handoff | one short brief per pull request, read cold by a fresh agent before it is locked |
| execute | a fresh session per pull request, in its own worktree, that stops instead of guessing |
| release and close | checks before merge, then what to change in the kit next time |
Each phase ends with a gate you can check by running a script: spec-lint, drift, preflight and status. They need Node 20 and nothing else. You decide at four points; between them, the agents only come back to you when they hit a stop point.
Install
You need Node 20 or newer and git:
git clone https://github.com/YosefBlandin/spec-skill.git ~/spec-skill
cd ~/spec-skill
./install.shThe installer only creates symlinks in ~/.claude, which Claude Code and Cursor both read. Then open a project and run /spec intake with a small ticket. If the project has no spec-profile.md yet, the skill drafts one and asks you to confirm it.
It's free and MIT-licensed. If you try it, I'd like to hear what broke: open an issue or write to me on LinkedIn.