Skip to content
Back to search

Spec-Driven-Development

A Claude skill that keeps your AI coding tools from contradicting each other. Generates requirements.md, design.md, and tasks.md before any code is written — then creates matching config files for Claude Code, Cursor, Copilot, Windsurf, and Aider.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/fredantb--spec-driven-development/badge.svg)](/listings/fredantb--spec-driven-development)

HTML

<a href="/listings/fredantb--spec-driven-development"><img src="/api/listings/fredantb--spec-driven-development/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install the skill, then start a conversation with any of these:

"I want to start a new project"
"my AI keeps going off script, help"
"I already have a codebase, no specs yet"
"set up cursor and claude code for my team project"

Claude will ask a few short questions and generate your spec files. No configuration needed.

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 434 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: spec-driven-development
  3. version: 1.0.0
  4. description: >
  5. Use this skill to scaffold Spec Driven Development: requirements.md, design.md, tasks.md, and cross-compatible AI config files (CLAUDE.md, .cursorrules, .windsurfrules, .github/copilot-instructions.md). Triggers: 'requirements', 'spec', 'design doc', 'tasks', 'CLAUDE.md', 'cursorrules', 'SDD', 'spec driven', 'AI configuration', 'cross-AI', 'multi-agent', 'agent setup'. Also trigger for: 'set up my AI tools', 'keep agents consistent', 'stop AI going off-script', 'plan before coding', 'structure project for AI'. Retrofit triggers: 'document my system', 'document my codebase', 'describe my architecture', 'write up what we built', 'add specs to existing project', 'no specs yet', 'help me document', 'I already have a codebase'. Use whenever a user wants to start a project, configure coding agents, create spec docs, or prevent AI agents from drifting, hallucinating scope, or producing inconsistent implementations.
  6. ---
  7. # Spec Driven Development Skill
  8. This skill guides the user through creating a complete Spec Driven Development environment:
  9. - `requirements.md` — what the system must do
  10. - `design.md` — how it will be built
  11. - `tasks.md` — atomic, ordered implementation steps
  12. - AI agent configuration files for Claude Code, Cursor, Windsurf, GitHub Copilot, and Aider
  13. **Reference files** (read when needed):
  14. - `references/sdd-curriculum.md` — full teaching curriculum, newbie to hero
  15. - `references/capabilities-and-cross-ai.md` — Claude Code capabilities, limitations, cross-AI strategy
  16. - `references/templates.md` — all spec file and AI config templates
  17. ---
  18. ## When to Read Reference Files
  19. | Situation | Read |
  20. |---|---|
  21. | User is new to SDD and needs explanation | `sdd-curriculum.md` Levels 1–3 |
  22. | User asks about Claude Code + SDD specifics | `capabilities-and-cross-ai.md` Part 1 |
  23. | User wants cross-AI config files | `capabilities-and-cross-ai.md` Part 2–3 |
  24. | You need template content to generate files | `templates.md` |
  25. ---
  26. ## Workflow: First Run (New Project)
  27. ### Step 1: Interview the User
  28. **Conversational rule (non-negotiable):** Ask exactly ONE question, wait for the answer, then ask the next. Never present questions as a numbered list or bullet list — that feels like a form, not a conversation. A newbie who sees three bullets may answer only the first or feel overwhelmed.
  29. **The four required answers before any file is generated:**
  30. 1. What the project does and who uses it
  31. 2a. Tech stack (language, framework, database)
  32. 2b. Deployment target (Railway, Fly.io, AWS, Vercel, etc. — offer to suggest if unknown)
  33. 3. Which AI coding tools they use (Claude Code, Cursor, Windsurf, Copilot, Aider, other)
  34. Stack and deployment are separate required answers because one does not imply the other. "Node.js" tells you nothing about deployment. "Railway" tells you nothing about the language. Both must be known independently before generation proceeds.
  35. **If the user's opening message already answers some but not all of these**, acknowledge what you know and ask only for what's missing — still one question at a time.
  36. **Optional follow-ups** (ask only when the user's answer raises real ambiguity):
  37. - "Are there performance, security, or accessibility constraints?"
  38. - "What is explicitly out of scope for this first version?"
  39. Example of correct pacing:
  40. > User: "I want to start a new project"
  41. > Claude: "Happy to help you spec it out. What does the project do — who are its users and what's the core job it performs?"
  42. > User: "It's a task manager for small dev teams"
  43. > Claude: "Got it. What's your tech stack — language, framework, database?"
  44. > User: "Node.js, Express, PostgreSQL"
  45. > Claude: "And where are you planning to deploy? (Railway, Fly.io, AWS — or I can suggest one)"
  46. > User: "Railway"
  47. > Claude: "Last thing — which AI coding tools do you use? (Claude Code, Cursor, Copilot, Windsurf, something else?)"
  48. Example of partial-answer handling:
  49. > User: "I'm building a task management API in Node.js"
  50. > Claude: "Good start — Node.js noted. What database are you planning to use?"
  51. > User: "PostgreSQL"
  52. > Claude: "And where are you deploying? (Railway, Fly.io, AWS — or I can suggest one)"
  53. > User: "Railway"
  54. > Claude: "Last thing — which AI coding tools do you use?"
  55. > *(stack partially given — ask for each missing part one at a time, never bundle them)*
  56. ### Generation Gate (enforced between Step 1 and Step 2)
  57. **HARD RULE: No file of any kind may be generated until all four interview answers are in hand.**
  58. This gate applies to every output path — `requirements.md`, `design.md`, `tasks.md`, `.cursorrules`, `CLAUDE.md`, and all other config files. There are no exceptions, including when:
  59. - The user says "create requirements for X" (X is a product category, not a full description)
  60. - The user says "make a cursorrules file" (a concrete deliverable name is not permission to skip the interview)
  61. - The user says "set up Cursor and Claude Code" (naming tools is not the same as providing project context)
  62. - The user gives a partial stack answer like "Node.js" (stack ≠ deployment — both are required separately)
  63. - The user provides some but not all of the four required answers (ask for the rest one at a time)
  64. If any answer is missing, ask for it conversationally before proceeding. Do not generate placeholder files with `{{UNFILLED}}` tokens. Do not generate plausible-sounding fake requirements from a product category alone.
  65. **Gate check before generating any file:**
  66. ```
  67. □ Do I know what the project does and who uses it? → if not, ask first
  68. □ Do I know the tech stack (language/framework/db)? → if not, ask first
  69. □ Do I know the deployment target? → if not, ask first
  70. □ Do I know which AI tools the user uses? → if not, ask first
  71. Only when all four are ✓ → proceed to Step 2
  72. ```
  73. ---
  74. ### Step 2: Generate `requirements.md`
  75. Read `references/templates.md` for the template. Fill in all `{{PLACEHOLDERS}}`.
  76. **Quality rules for requirements.md:**
  77. - Every functional requirement uses "shall" language (REQ-xxx: Actor shall verb object)
  78. - Every requirement has a concrete acceptance criterion
  79. - NFRs have a measurable metric (not "fast" — use "< 200ms at p95")
  80. - Out of scope section is non-empty (if user didn't provide it, infer likely assumptions)
  81. - Requirement IDs are sequential starting at REQ-001
  82. **Output:** Create `requirements.md` in the project root (or ask for path if ambiguous).
  83. ---
  84. ### Step 3: Generate `design.md`
  85. Read `references/templates.md` for the template.
  86. **Quality rules for design.md:**
  87. - Every REQ-xxx must map to at least one data model field, endpoint, or component
  88. - Data model fields have explicit types and constraints (not just "string" — use VARCHAR(255) or TEXT with reasoning)
  89. - API endpoints reference the REQ they satisfy
  90. - File structure section shows at minimum the top 2 levels of the project tree
  91. - Open Questions section captures anything the user hasn't decided yet — do not guess, ask
  92. **Output:** Create `design.md` in the project root.
  93. ---
  94. ### Step 4: Generate `tasks.md`
  95. Read `references/templates.md` for the template.
  96. **Quality rules for tasks.md:**
  97. - Tasks are ordered: infrastructure → data layer → business logic → API layer → tests → validation
  98. - Every task references at least one REQ or NFR **inline on the checkbox line** using the format `**TASK-{{id}}** [REQ-xxx, NFR-xxx]` — not only on a separate `_Refs_:` line. This makes references machine-checkable by static tools and CI scripts.
  99. - Every task has an explicit verification step (a test command, a manual check, a metric measurement)
  100. - Tasks are atomic — one task should not produce more than ~200 lines of new code
  101. - Phase goals are stated in plain English
  102. **Output:** Create `tasks.md` in the project root.
  103. ---
  104. ### Step 5: Generate AI Agent Configuration Files
  105. Ask the user which agents they use (if not already answered in the interview).
  106. For each selected agent, generate the appropriate config file. Read `references/capabilities-and-cross-ai.md` Part 2 for the per-agent templates.
  107. **Always generate:**
  108. - `CLAUDE.md` (for Claude Code) — even if user didn't ask, this is the baseline
  109. **Generate based on user's tools:**
  110. | Tool | File | Location |
  111. |---|---|---|
  112. | Cursor | `.cursorrules` | Project root |
  113. | Windsurf | `.windsurfrules` | Project root |
  114. | GitHub Copilot | `.github/copilot-instructions.md` | `.github/` directory |
  115. | Aider | `.aider.conf.yml` | Project root |
  116. **Quality rules for AI config files:**
  117. - The Universal Instruction Block is IDENTICAL in content across all files (same constraints, same protocol) — only the agent-specific additions differ
  118. - The block references the actual spec file names (`requirements.md`, `design.md`, `tasks.md`)
  119. - Agent-specific additions are minimal — no more than 5 lines of agent-specific rules
  120. - Config files include the project name and spec version in the header
  121. **Output:** Create all requested config files in their correct locations.
  122. ---
  123. ## Workflow: Existing Project (Retrofit)
  124. Triggered by: "I already have a codebase, no specs yet", "document what my system does", "describe my architecture", "help me document", "write up what we built", "add specs to my project", or any similar phrase implying an existing system without written specs.
  125. ### Retrofit Interview (ask one question at a time, conversationally)
  126. The retrofit interview is different from the new project interview — you are discovering truth from existing code, not designing from scratch. Ask these in order:
  127. 1. "What does the system do today — describe it as if explaining to a new teammate?"
  128. 2. "What's the tech stack? (language, framework, database, deployment)"
  129. 3. "Which AI tools do you use on this project?"
  130. 4. "Are there parts of the codebase you'd like to share so I can read the actual structure? (key files, folder tree, or a README)"
  131. 5. "What's the next feature or phase of work you're planning? (This determines what tasks.md covers)"
  132. Question 4 is important — retrofitting from code is more accurate than retrofitting from memory. Offer to read files if they can share them.
  133. ### Retrofit Generation Process
  134. **Step 1 — Reverse-engineer `requirements.md`**
  135. - Ask "What does this system do today?" and turn the description into REQ-xxx statements
  136. - Use past tense internally to distinguish discovered requirements from new ones
  137. - Flag every behavior you infer that the user didn't explicitly confirm: "I'm inferring REQ-004 from what you described — does the system actually enforce this?"
  138. - Add an Out of Scope section based on what's absent from their description
  139. - Mark the version as `v0-retrofit` to distinguish it from a forward-looking spec
  140. **Step 2 — Reverse-engineer `design.md`**
  141. - If files were shared, read the actual folder structure and data models
  142. - If no files were shared, produce a design.md skeleton and mark every section with `[TO VERIFY]`
  143. - Never invent a data model — if you don't know the schema, list the entities and mark fields as `[unknown]`
  144. - Capture the real endpoints or interfaces if available, otherwise list them as open questions
  145. **Step 3 — Generate `tasks.md` for the NEXT phase only**
  146. - Do not create tasks for work already done — that history is in git, not tasks.md
  147. - The first phase should be "Spec Verification": tasks to confirm that requirements.md and design.md actually match the live codebase
  148. - The second phase covers the next feature or planned work the user described in question 5
  149. **Step 4 — Generate AI config files as normal**
  150. - Apply the same generation gate: all three interview answers required first
  151. - The Universal Instruction Block must reference the real spec files by name
  152. ### Retrofit Gap Flagging
  153. After generating each file, explicitly list every assumption made:
  154. > "I made the following assumptions — please verify each one:
  155. > - REQ-003: I assumed authentication uses JWT because you mentioned tokens, but I didn't see the auth code
  156. > - design.md § Data Models: The `users` table fields are marked [TO VERIFY] — share the schema migration or model file to confirm"
  157. This is the most important difference between retrofit and new-project workflows. In a new project, the spec is the truth. In a retrofit, the code is the truth and the spec must be verified against it.
  158. ---
  159. ## Workflow: Updating Specs (Change Request)
  160. When the user wants to add a feature or change existing behavior:
  161. ### Spec Presence Check (run before anything else)
  162. When a feature request arrives without explicit spec context in the conversation, do not implement it. Instead, check:
  163. > "Before I add dark mode — do you have a `requirements.md` for this project? If so, I'll check whether it's in scope and add it properly. If not, let's create one first so this change has a home."
  164. A feature request without spec context is one of three situations:
  165. - **Specs exist, in scope** → update requirements.md first, then design.md, then tasks.md, then implement
  166. - **Specs exist, out of scope** → flag the conflict, ask whether to expand scope formally before touching code
  167. - **No specs exist** → route to the Retrofit workflow, build the spec, then handle the feature
  168. Never implement a feature request by jumping straight to code, even if the request seems small. "Add dark mode" or "add a search bar" always has spec implications.
  169. ### Change Request Process (when specs are confirmed to exist)
  170. 1. Identify which spec file(s) are affected
  171. 2. Propose the minimal change to `requirements.md` first (new REQ-xxx or modified acceptance criterion)
  172. 3. Show impact on `design.md` (new model fields, endpoints, components, or files)
  173. 4. Add new tasks to `tasks.md` in a new phase
  174. 5. Remind the user to regenerate AI config files if the project name or version changed
  175. **Never update `design.md` before `requirements.md` is updated first.** The requirement is the authority.
  176. ### Task closing protocol ("update my tasks.md")
  177. When a user asks to mark a task done, close it or update tasks.md,
  178. follow this exact two-step sequence — never bundle both steps into
  179. one message:
  180. **Step 1 — Identify the task first:**
  181. Ask which task was completed. Wait for the answer.
  182. > "Which task did you just finish? Give me the TASK-id or a brief description."
  183. **Step 2 — Divergence check after identification:**
  184. Only once the specific task is named, ask whether design.md needs updating.
  185. > "Before I mark TASK-007 `[x]` — did the implementation match `design.md`
  186. > exactly, or did anything diverge? If anything drifted, we update
  187. > design.md first, then close the task."
  188. **Why the order matters:** The divergence question only makes sense in
  189. the context of a specific task. Asking both at once forces the user to
  190. hold two things in mind before answering either. Always identify first,
  191. then check divergence.
  192. ---
  193. ## Session Management — CONTEXT.md
  194. ### The problem this solves
  195. A project's three spec files answer *what to build* and *how to build it*.
  196. They do not answer *where we are right now*. When a user starts a new chat
  197. session — because the context window filled, because they want an isolated
  198. session for a new task, or because a day passed — Claude has no way to know
  199. which task is active, what decisions were made mid-session, or why the code
  200. looks the way it does.
  201. `CONTEXT.md` is the session journal. It bridges instances.
  202. ### What CONTEXT.md contains
  203. - **Resume block** — the single most important section: active task ID,
  204. current phase, status, and any blocker. Claude reads this first and
  205. resumes without asking.
  206. - **Session log** — one row per session: date, one-line summary, files changed.
  207. Never transcripts — always summaries.
  208. - **Key decisions** — decisions that aren't obvious from the spec files
  209. (why JWT over sessions, why PostgreSQL over MongoDB, why soft-delete).
  210. - **Open questions** — unresolved items that haven't made it into design.md yet.
  211. - **Divergences** — places where implementation differs from design.md pending
  212. a formal update.
  213. ### When to create CONTEXT.md
  214. Generate CONTEXT.md as part of the initial spec setup (Step 2–4) or when
  215. a user first asks to resume work in a new session on an existing project.
  216. The file starts minimal — just the resume block and an empty session log.
  217. It grows through use.
  218. ### Rules for updating CONTEXT.md
  219. **At the end of any session where work was done:**
  220. 1. Add a row to the session log (date, one-line summary, files changed)
  221. 2. Update the resume block with the next active task
  222. 3. Move any resolved open questions to design.md
  223. 4. Record any divergences from design.md that are pending update
  224. **At the start of any session:**
  225. 1. Read CONTEXT.md first — before requirements.md, design.md, or tasks.md
  226. 2. Announce: "Session [N] resuming. Last worked on: [task]. Picking up at: [task]."
  227. 3. If CONTEXT.md does not exist yet, offer to create it
  228. **Never:**
  229. - Record conversation transcripts in CONTEXT.md — only outcomes
  230. - Let the session log grow beyond the last 10 sessions without archiving
  231. older entries to a `CONTEXT_ARCHIVE.md`
  232. - Update the session log mid-session — only at natural stopping points
  233. ### When CONTEXT.md is present — modified startup behavior
  234. When a user starts a session on a project that already has CONTEXT.md,
  235. Claude's opening move changes:
  236. **Without CONTEXT.md:**
  237. > "What are we working on today?"
  238. **With CONTEXT.md:**
  239. > "Session 4 resuming. Last session we completed TASK-005 and TASK-006
  240. > (JWT middleware). Active task is TASK-007 — POST /tasks implementation.
  241. > Ready to continue, or do you want to start something different?"
  242. This is the entire value of CONTEXT.md: the user says nothing and work
  243. continues exactly where it left off.
  244. ### Output quality check for CONTEXT.md
  245. Before presenting a generated or updated CONTEXT.md:
  246. - [ ] Resume block has a specific task ID — not "continue development"
  247. - [ ] Session log row added for the current session
  248. - [ ] No conversation transcripts — only outcomes
  249. - [ ] Open questions are questions, not tasks (tasks go in tasks.md)
  250. - [ ] No {{PLACEHOLDER}} tokens remain
  251. ---
  252. ## Output Quality Checklist
  253. Before presenting any generated file to the user, verify:
  254. **CONTEXT.md** (when generated or updated)
  255. - [ ] Resume block has a specific task ID and status
  256. - [ ] Session log has a row for the current session
  257. - [ ] No conversation transcripts — summaries only
  258. - [ ] Open questions are actual questions, not tasks
  259. - [ ] No `{{PLACEHOLDER}}` tokens
  260. - [ ] All functional requirements use "shall" language
  261. - [ ] All REQ-xxx IDs are unique and sequential
  262. - [ ] Every requirement has an acceptance criterion
  263. - [ ] NFRs have measurable targets
  264. - [ ] Out of scope section is present
  265. **design.md**
  266. - [ ] Every REQ maps to a design element
  267. - [ ] Data model has typed fields with constraints
  268. - [ ] Endpoints reference REQs
  269. - [ ] File structure is present
  270. - [ ] Open questions are captured, not assumed
  271. **tasks.md**
  272. - [ ] Tasks are ordered logically
  273. - [ ] Every task has a REQ/NFR reference
  274. - [ ] Every task has a verification step
  275. - [ ] No single task is too large (> 200 lines of new code is a smell)
  276. **AI config files**
  277. - [ ] Universal Instruction Block is present and complete
  278. - [ ] Content is consistent across all generated config files
  279. - [ ] Agent-specific additions are minimal and non-contradictory
  280. - [ ] Files are in the correct locations
  281. ---
  282. ## Metrics: Evaluating SDD Health
  283. Read `references/capabilities-and-cross-ai.md` Part 3 for the full metrics table.
  284. Quick summary:
  285. | Signal | Green | Yellow | Red |
  286. |---|---|---|---|
  287. | Spec coverage | > 95% code has REQ link | 80–95% | < 80% |
  288. | Task link rate | 100% tasks have REQ ref | 90–99% | < 90% |
  289. | Ambiguity escalations | < 2 per task | 2–5 | > 5 |
  290. | Design drift rate | 0 per sprint | 1–2 | > 2 |
  291. | Requirement creep | 0 undocumented features | — | Any |
  292. ---
  293. ## Teaching Mode
  294. If the user is new to SDD, offer to explain concepts using `references/sdd-curriculum.md`:
  295. - **"What is SDD?"** → Summarize sdd-curriculum.md introduction + Level 1
  296. - **"How do I write requirements?"** → Walk through Level 2.1
  297. - **"How do I use AI with specs?"** → Summarize Level 3
  298. - **"How do I set up multiple AI tools?"** → Level 4 + capabilities-and-cross-ai.md Part 2
  299. Always offer to generate the actual files after explaining — teaching and doing go together.
  300. ---
  301. ## Common Mistakes to Prevent
  302. Actively flag these anti-patterns if you see them in user inputs:
  303. | Anti-pattern | What to say |
  304. |---|---|
  305. | "Just start coding and we'll spec later" | "Let's take 10 minutes to write requirements.md first — it will save hours of rework." |
  306. | Requirements with no acceptance criteria | "How will we know this requirement is satisfied? Let's add a concrete test." |
  307. | Tasks that span multiple days | "This task is very large. Let's break it into smaller atomic steps." |
  308. | Design decisions before requirements | "Let's lock requirements first so the design has a foundation." |
  309. | AI config files that differ from each other | "I'll make sure all your AI agents get the same instruction block." |
  310. | Out of scope section missing | "What won't this version do? Stating it prevents scope creep." |
  311. | Feature request with no spec context | "Before I add that — do you have a requirements.md? I want to make sure this lands in the right place." |
  312. | Generating config files before spec exists | Never produce CLAUDE.md, .cursorrules, or similar until requirements.md is at least drafted. |
  313. | Filling placeholders with invented content | If interview answers are missing, ask — never fabricate plausible requirements from a product category. |
README.md · README · 401 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # spec-driven-development
  2. > Claude, Cursor, and Copilot all read the same plan before touching your code.
  3. A Claude skill that writes your specs before you write code — interviews you,
  4. generates `requirements.md`, `design.md`, and `tasks.md`, then creates matching
  5. config files for every AI tool you use so they can't contradict each other.
  6. [![Version](https://img.shields.io/badge/version-1.0--beta-blue)](https://github.com/FredAntB/spec-driven-development/releases/tag/v1.0-beta)
  7. [![CI](https://github.com/FredAntB/spec-driven-development/actions/workflows/ci.yml/badge.svg)](https://github.com/FredAntB/spec-driven-development/actions/workflows/ci.yml)
  8. [![Phase 2A](https://img.shields.io/badge/static%20assertions-67%2F67-brightgreen)](phase2a/assertions.md)
  9. [![Phase 2B](https://img.shields.io/badge/behavioral%20tests-15%2F15-brightgreen)](phase2b/eval_session.md)
  10. [![Phase 2C](https://img.shields.io/badge/generation%20quality-53%2F53-brightgreen)](phase2c/eval_flows.md)
  11. [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
  12. ---
  13. ## The problem this solves
  14. You open Claude Code and ask it to build a feature. An hour later it's
  15. done something technically impressive that isn't quite what you wanted.
  16. You ask Cursor to fix it. It contradicts what Claude Code did. You ask
  17. Copilot to clean up. It invents a third interpretation.
  18. The root cause is always the same: your AI agents have no shared source
  19. of truth. They fill every gap with their own assumptions.
  20. This skill fixes that by creating three files before any code is written:
  21. | File | Answers |
  22. |---|---|
  23. | `requirements.md` | What the system must do |
  24. | `design.md` | How it will be built |
  25. | `tasks.md` | What to build next, in order |
  26. Here's what those files actually look like:
  27. **`requirements.md`** — every requirement is traceable and testable:
  28. ```markdown
  29. - **REQ-001**: Users shall log time entries against a client project.
  30. - _Acceptance_: POST /entries returns 201 with entry id, duration, and project_id
  31. - **REQ-002**: Users shall generate a monthly invoice from logged entries.
  32. - _Acceptance_: GET /invoices/:month returns PDF with line items summing to total
  33. ```
  34. **`tasks.md`** — every task links back to its requirement:
  35. ```markdown
  36. - [ ] **TASK-003** [REQ-001]: Implement POST /entries with validation
  37. - _Output_: Route handler + duration schema validation
  38. - _Verify_: POST /entries returns 201 with all required fields
  39. ```
  40. Every AI tool reads from these files before touching code. Drift stops.
  41. ---
  42. ## Quick start
  43. Install the skill, then start a conversation with any of these:
  44. ```
  45. "I want to start a new project"
  46. "my AI keeps going off script, help"
  47. "I already have a codebase, no specs yet"
  48. "set up cursor and claude code for my team project"
  49. ```
  50. Claude will ask a few short questions and generate your spec files.
  51. No configuration needed.
  52. ---
  53. ## Installation
  54. ### Claude.ai / Claude desktop app (Chat tab)
  55. 1. Download [`spec-driven-development-v1.0.skill`](releases/latest)
  56. 2. In Claude settings → Skills → Install from file
  57. Or via CLI:
  58. ```bash
  59. claude plugin install FredAntB/spec-driven-development
  60. ```
  61. ### Claude Code (Code tab)
  62. ```bash
  63. git clone https://github.com/FredAntB/spec-driven-development
  64. ```
  65. Open the folder in the Code tab. The `CLAUDE.md` file is auto-read
  66. at session start and bootstraps the skill.
  67. **Windows note:** Git must be installed for the Code tab to work
  68. with local folders. Download from [git-scm.com](https://git-scm.com).
  69. ---
  70. ## What you get
  71. ### For a new project (greenfield)
  72. Claude interviews you in 4 short questions — one at a time,
  73. conversationally — then generates:
  74. ```
  75. your-project/
  76. ├── requirements.md ← what the system must do
  77. ├── design.md ← how it will be built
  78. ├── tasks.md ← atomic ordered implementation steps
  79. └── CLAUDE.md ← Claude Code reads this automatically
  80. ```
  81. **requirements.md** uses `shall` language and REQ-xxx IDs so every
  82. requirement is traceable:
  83. ```markdown
  84. ## Functional Requirements
  85. ### Tasks
  86. - **REQ-001**: Users shall create tasks with a title, description,
  87. due date, and assignee.
  88. - _Acceptance_: POST /tasks returns 201 with the created task object
  89. - **REQ-002**: Users shall update only tasks they created or are
  90. assigned to.
  91. - _Acceptance_: PATCH /tasks/:id returns 403 for unauthorized users
  92. ```
  93. **tasks.md** links every task back to its requirement inline:
  94. ```markdown
  95. ## Phase 2: Core endpoints
  96. - [ ] **TASK-007** [REQ-001]: Implement POST /tasks with validation
  97. - _Output_: Route handler + request schema validation
  98. - _Verify_: POST /tasks returns 201 with all fields present
  99. ```
  100. ### For an existing codebase (retrofit)
  101. Same result, reverse-engineered from what you describe:
  102. ```
  103. your-project/
  104. ├── requirements.md ← v0-retrofit: discovered from existing code
  105. ├── design.md ← with [TO VERIFY] on every inferred field
  106. └── tasks.md ← Phase 1 is spec verification, not new code
  107. ```
  108. ### For cross-AI teams
  109. Generates identical instruction blocks across every tool your team uses:
  110. ```
  111. your-project/
  112. ├── CLAUDE.md ← Claude Code
  113. ├── .cursorrules ← Cursor
  114. ├── .windsurfrules ← Windsurf
  115. ├── .github/copilot-instructions.md ← GitHub Copilot
  116. └── .aider.conf.yml ← Aider
  117. ```
  118. Each file contains the same Universal Instruction Block — agents read
  119. the same mandate, cite the same spec files, follow the same divergence
  120. protocol. The only differences are tool-specific additions.
  121. ---
  122. ## Supported AI tools
  123. | Tool | Config file | Status |
  124. |---|---|---|
  125. | Claude Code | `CLAUDE.md` | ✓ Tested |
  126. | Cursor | `.cursorrules` | ✓ Tested |
  127. | Windsurf | `.windsurfrules` | ✓ Tested |
  128. | GitHub Copilot | `.github/copilot-instructions.md` | ✓ Tested |
  129. | Aider | `.aider.conf.yml` | ✓ Generated |
  130. ---
  131. ## The Universal Instruction Block
  132. Every AI config file contains this block, with only the project name
  133. and spec version filled in:
  134. ```
  135. ═══════════════════════════════════════════════════════════
  136. SPEC DRIVEN DEVELOPMENT — PROJECT CONSTITUTION
  137. Project: Your Project Name
  138. Version: 1.0
  139. ═══════════════════════════════════════════════════════════
  140. This project uses Spec Driven Development. All work is
  141. governed by three source-of-truth files:
  142. requirements.md — What the system must do
  143. design.md — How the system is structured
  144. tasks.md — The ordered implementation plan
  145. MANDATORY BEFORE ANY ACTION:
  146. 1. Read requirements.md in full
  147. 2. Read design.md in full
  148. 3. Read tasks.md — identify the next incomplete [ ] task
  149. HARD CONSTRAINTS:
  150. ✗ Never implement requirements not in requirements.md
  151. ✗ Never alter the data model without updating design.md first
  152. ✗ Never create files not listed or implied in design.md
  153. ✗ Never mark a task [x] without verifying its acceptance criterion
  154. ✗ Never guess when a requirement is ambiguous — ask instead
  155. DIVERGENCE PROTOCOL:
  156. If implementation must deviate from design.md:
  157. → Stop immediately
  158. → Describe the conflict clearly
  159. → Wait for explicit user approval
  160. → Update design.md BEFORE writing code
  161. ═══════════════════════════════════════════════════════════
  162. ```
  163. ---
  164. ## Test suite & CI
  165. This skill ships with a complete, runnable test suite — 135 assertions
  166. across three phases. A GitHub Actions workflow runs the automatable
  167. checks on every push and pull request.
  168. ### GitHub Actions workflow (`.github/workflows/ci.yml`)
  169. Four jobs run on every push to `main`/`master` and on every PR:
  170. | Job | What it does | Required to pass? |
  171. |---|---|---|
  172. | `phase2a` | Runs 67 static assertions via Python | Yes — hard gate |
  173. | `phase2c` | Runs 53 generation quality checks against committed fixtures | Yes if fixtures present |
  174. | `phase2b-notice` | Prints instructions for running behavioral tests manually | Informational only |
  175. | `all-checks` | Aggregates results — reference this in branch protection rules | Yes |
  176. **Branch protection setup** — in your repo settings, add `all-checks`
  177. as the single required status check. This means one rule covers all
  178. automated phases now and any you add later.
  179. ### Running locally
  180. ```bash
  181. # Phase 2A — static assertions (67 checks)
  182. python3 phase2a/run_assertions.py
  183. # Windows — if python3 not on PATH or encoding errors occur
  184. PYTHONUTF8=1 python phase2a/run_assertions.py
  185. # Phase 2C — generation quality (53 checks, requires fixture files)
  186. python3 phase2c/check_outputs.py
  187. ```
  188. Or paste the KICKOFF.md for each phase into the Claude Code tab
  189. for a zero-setup run from any machine.
  190. ### Running in Claude Code (Code tab)
  191. | Phase | Paste this | Output |
  192. |---|---|---|
  193. | 2A | `phase2a/KICKOFF.md` | Runs script, explains any failures |
  194. | 2B | `phase2b/KICKOFF.md` | 15 behavioral tests → `eval_report.md` |
  195. | 2C | `phase2c/KICKOFF.md` | 3 flows → files → `eval_report_2c.md` |
  196. ### Phase 2C fixtures
  197. Phase 2C requires Claude Code to generate real spec files, which are
  198. then committed to the repo as fixtures that CI checks on every push.
  199. To regenerate fixtures after a significant skill change:
  200. 1. Open the repo folder in the Code tab
  201. 2. Paste `phase2c/KICKOFF.md`
  202. 3. Commit the files Claude Code writes to `phase2c/flow_a/`,
  203. `phase2c/flow_b/`, and `phase2c/flow_c/`
  204. CI will automatically pick up the new fixtures on the next push.
  205. ### Current test results
  206. | Phase | Type | Assertions | CI |
  207. |---|---|---|---|
  208. | 2A | Static file checks | 67 / 67 ✓ | Automated |
  209. | 2B | Behavioral (live session) | 15 / 15 ✓ | Manual |
  210. | 2C | Generation quality | 53 / 53 ✓ | Automated (fixtures required) |
  211. ---
  212. ## Trigger phrases
  213. The skill activates on a wide vocabulary. A sample:
  214. **Starting a project:**
  215. `"I want to start a new project"` · `"help me plan before I code"` ·
  216. `"set up SDD for my project"` · `"I need a spec"`
  217. **AI tool setup:**
  218. `"set up cursor and claude code"` · `"make a cursorrules file"` ·
  219. `"my AI keeps going off script"` · `"keep my agents consistent"`
  220. **Existing codebase:**
  221. `"I already have a codebase, no specs yet"` ·
  222. `"help me document what my system does"` ·
  223. `"describe my architecture"` · `"add specs to existing project"`
  224. **Feature requests:**
  225. `"add dark mode"` → triggers spec presence check before any code
  226. `"just start coding"` → triggers anti-pattern warning
  227. ---
  228. ## Anti-patterns the skill prevents
  229. | Anti-pattern | What the skill does |
  230. |---|---|
  231. | "just start coding" | Pushes back with concrete reasons, asks for spec |
  232. | Feature request without spec context | Checks for requirements.md before proceeding |
  233. | Generating config files before spec exists | Hard gate — interview required first |
  234. | AI guessing at ambiguous requirements | Asks for clarification, never fabricates |
  235. | Out of scope missing from requirements | Flags it and asks what won't be in v1 |
  236. ---
  237. ## Community beta — we need testers
  238. This skill is in **public beta**. It has passed 135 automated
  239. assertions and 3 end-to-end generation flows, but it has not yet
  240. been tested by strangers using natural language.
  241. We need 5 testers matching these profiles:
  242. - A complete beginner starting their first real project
  243. - A solo developer with an active side project (greenfield or partial)
  244. - A team lead whose team uses multiple AI tools
  245. - A developer with an existing codebase and no written specs
  246. - A developer who actively uses 3+ AI coding tools simultaneously
  247. **To volunteer:** Open an issue titled `[Beta] I'd like to test`
  248. and describe which profile fits you best.
  249. All you need to do is use the skill naturally for your real work
  250. and file issues when something doesn't work. That's it.
  251. ---
  252. ## Contributing
  253. 1. Fork the repo
  254. 2. Make your change to `SKILL.md` or the reference files
  255. 3. Run the Phase 2A assertion suite: `python3 phase2a/run_assertions.py`
  256. 4. If assertions fail, fix them before filing a PR
  257. 5. If your change adds new behavior, add a corresponding assertion
  258. New assertions go in `phase2a/assertions.md` (human-readable spec)
  259. and `phase2a/run_assertions.py` (machine-executable check).
  260. ---
  261. ## Skill structure
  262. ```
  263. spec-driven-development/
  264. ├── SKILL.md ← the skill (install this)
  265. ├── CLAUDE.md ← Code tab bootstrap
  266. ├── references/
  267. │ ├── sdd-curriculum.md ← newbie-to-hero teaching guide
  268. │ ├── capabilities-and-cross-ai.md ← Claude Code + cross-AI strategy
  269. │ └── templates.md ← spec file + UIB templates
  270. ├── phase2a/
  271. │ ├── assertions.md ← human-readable test spec
  272. │ └── run_assertions.py ← static assertion runner
  273. ├── phase2b/
  274. │ ├── eval_session.md ← behavioral test definitions
  275. │ └── KICKOFF.md ← Code tab eval kickoff
  276. ├── phase2c/
  277. │ ├── eval_flows.md ← end-to-end flow definitions
  278. │ ├── check_outputs.py ← generation quality checker
  279. │ └── KICKOFF.md ← Code tab eval kickoff
  280. └── beta/
  281. ├── BETA_PLAN.md ← 5-person beta plan
  282. ├── TESTER_BRIEF.md ← tester onboarding guide
  283. └── ISSUE_TEMPLATES.md ← feedback issue templates
  284. ```
  285. ---
  286. ## License
  287. MIT — use freely, attribution appreciated.
  288. ---
  289. ## Acknowledgements
  290. Built and tested using the Claude skill framework. Test suite
  291. methodology adapted from the skill-creator eval harness. All
  292. 135 assertions were written before the corresponding fixes —
  293. test-first, always.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.