spec-driven-development
Skill0 starsChanged 29 days agoMITView on GitHub
Creates specs before coding. Use when starting a new project, feature, or significant change and no specification exists yet. Use when requirements are unclear, ambiguous, or only exist as a vague idea.
- Reads credentials
109 other projects use a version of this, 19 of them edited.
Adopted by
Most recently taken up by
- wilco42/claude-skillstheir own version, first seen Nov 16, 2026
- hoshiori-dev/harness.mdtheir own version, first seen Nov 16, 2026
- zademy/lu-querytheir own version, first seen Nov 16, 2026
- fworks-tech/agenthoodtheir own version, first seen Nov 15, 2026
- modaal-agent/skillstheir own version, first seen Nov 15, 2026
- dvy1987/agent-loomtheir own version, first seen Nov 15, 2026
Used with
Projects with it also use using-agent-skills, shipping-and-launch and 7 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
LLl0k0laDSkillusing-agent-skills
Use when starting a session or when you need to discover which skill applies to the current task. This is the meta-skill that governs how all other skills are discovered and invoked.
Also in 44 projects that use this
LLl0k0laDSkillshipping-and-launch
Use when preparing to deploy to production. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.
Also in 53 projects that use this
MrCipherSmithSkillconstraint-driven-development
Use when a project needs a persistent, measurable quality bar — starting a project without documented standards, 'set up constraints', or when coverage/perf/a11y thresholds get re-debated per-PR. Produces CONSTRAINTS.md with enforceable numbers, ratchets, and a guard against silent weakening. NOT for throwaway prototypes or a one-off CI setup.
Also in 16 projects that use this
HK-hubSkillobservability-and-instrumentation
Instruments code so production behavior is visible and diagnosable. Use when adding logging, metrics, tracing, or alerting. Use when shipping any feature that runs in production and you need evidence it works. Use when production issues are reported but you can't tell what happened from the available data.
Also in 36 projects that use this
seikaikyoSkilldoubt-driven-development
對非平凡決策啟動新鮮 context 對抗審查(找碴不背書),在修正還便宜的時候抓出錯誤方向。適用:高風險改動(production、資安敏感邏輯、不可逆操作)、不熟的程式碼、要宣稱「這樣是安全的 / 可行的」之前。機械性操作與一行修改不適用。
Also in 44 projects that use this
- +4 more from LLl0k0laD
Other versions109 projects use a version of this.
Word for word · 0
None found.
Edited · 19
- shashankswe2020-ux/whoop-mcp★ 18111% same
- sampleXbro/agentsmesh★ 2710% same
- ishandutta2007/Awesome-Agent-Skills★ 2110% same
- lza6/claw-code-tingfeng★ 511% same
- PenceZHR/stagepass★ 410% same
- SrejonKhan/agent-skills★ 311% same
- huangzida/skills★ 211% same
- Minghou-Lei/codex-skills★ 211% same
- skytiger6724/qwen-skills★ 211% same
- joshydavid/agent-j★ 111% same
9 more not listed
Wrote their own version · 90
- addyosmani/agent-skills★ 118ksame name
- ollaya-dev/ollaya★ 1.4ksame name
- kdlbs/kandev★ 1.1ksame name
- jasonkneen/kiro★ 753same name
- magnus919/agent-skills★ 177same name
- FredAntB/Spec-Driven-Development★ 153same name
- tranhieutt/software_development_department★ 71same name
- drvoss/everything-copilot-cli★ 49same name
- vinvcn/addyosmani-agent-skills-zh★ 46same name
- krzysztofsurdy/code-virtuoso★ 36same name
80 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository21 other files it gives its agents.
- .codex/AGENTS.mdAGENTS.md
- .claude/CLAUDE.mdCLAUDE.md
- animate-expoSkill
- animateSkill
- break-uiSkill
- claritySkill
- code-reviewSkill
- code-simplificationSkill
- diagnoseSkill
- grill-with-docsSkill
- idea-refineSkill
- improve-codebase-architectureSkill
- incremental-implementationSkill
- interactive-test-planSkill
- manual-test-planSkill
- planning-and-task-breakdownSkill
- review-animationsSkill
- security-and-hardeningSkill
- tddSkill
- write-a-skillSkill
- zoom-outSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
13 rules. 0 are common, 10 are distinctive, and 3 are very specific to this project.
0
Common
Most of the 102 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Write a structured specification before writing any code.
- Very specific: line 22
Skip this section entirely when
repos=is absent: No discovery, no subagents, no extra spec sections — this is the most important rule. - Very specific: line 24
When repos=<path> appears in $ARGUMENTS:
- Distinctive: line 27
If the resolved path does not exist or contains no git repositories, skip discovery and continue as a single-repo run without failing.
- Very specific: line 29
Refuse: if the resolved path is /, $HOME, or a system root (/Users, /home, /root) — those resolve to an unbounded scan blast radius.
- Distinctive: line 39
No file contents from a non-primary repo may appear in the spec or any downstream artifact.
- Distinctive: line 41
If the candidate count exceeds 10, sort candidates lexicographically by directory name and scan the first 10.
- Distinctive: line 64
Always do: [non-negotiable rules]
- Distinctive: line 65
Ask first: [needs human approval]
- Distinctive: line 66
Never do: [hard constraints]
- Distinctive: line 69
When a Repo Allocation is present, tag acceptance criteria per repo so "done" is defined for each one.
- Distinctive: line 101
Update when decisions or scope change
- Distinctive: line 102
Commit the spec to version control
“Common” is measured: kept by at least 6 in 10 of the 102 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Spec-Driven Development
Write a structured specification before writing any code. The spec defines what we're building, why, and how we'll know it's done.
Gated Workflow
Four phases. Do not advance until current phase is validated by the user.
SPECIFY → PLAN → TASKS → IMPLEMENT
↓ ↓ ↓ ↓
Review Review Review ReviewCross-Repo Context (optional)
Skip this section entirely when repos= is absent. No discovery, no subagents, no extra spec sections — this is the most important rule.
When repos=<path> appears in $ARGUMENTS:
- Relative paths resolve against
$HOME(Development/tba→$HOME/Development/tba); absolute and~/-prefixed paths are used as-is. The path is used exactly as given — on case-sensitive filesystems the case must match exactly. - If the resolved path does not exist or contains no git repositories, skip discovery and continue as a single-repo run without failing.
- The primary repo root is resolved via
git rev-parse --show-toplevel; it is not overridable. - Refuse if the resolved path is
/,$HOME, or a system root (/Users,/home,/root) — those resolve to an unbounded scan blast radius. Echo the resolved absolute path and the full candidate list before scanning begins so scope is visible before any data is read. - Discover candidates: direct children of
<path>that have a.gitdirectory (not a file) at their own root. A.gitfile signals a submodule or linked worktree whosegitdir:pointer may redirect to a different repository — reject it.*.worktreesdirectories have no.gitat their own root and are excluded without special-casing. The primary repo root (resolved viagit rev-parse --show-toplevel) is always excluded from candidates — it always participates and is never dropped, even if anonescan verdict is returned. - Resolve each candidate with
realpath; display the resolved path at the spec checkpoint — symlinks must be transparent so the checkpoint shows where data is actually read from, not the alias. - Skip any candidate whose resolved absolute path contains a character outside
[A-Za-z0-9._/-]; list every skipped candidate at the spec checkpoint. Directory names are pasted verbatim into shell commands and cannot be safely quoted — rejection at discovery is the only safe gate.
Scan — up to 10 read-only subagents in parallel, on the cheap search tier:
- Pass feature keywords extracted from the user's request; each scanner greps for them. Keyword-scoped grep keeps output bounded — scanners do not summarise the whole repo.
- Scanners hard-exclude
.env*,*.pem,*.key,*.p12,*.pfx,id_rsa*,credentials,*.tfstate, and honour each repo's.gitignore— credential files are never read or reported on. - Each scanner returns: repo name, one-line purpose, stack, public surface (API routes, exported packages, published or consumed events), and a relevance verdict of
none/low/high. Evidence is file paths and symbol names only — never raw file content or matched lines. - No file contents from a non-primary repo may appear in the spec or any downstream artifact. Scanner evidence flows into the Repo Allocation and from there into the spec and PR body — the chain must carry no secrets.
- Drop
nonerepos immediately. They do not appear in the spec or any downstream phase. - If the candidate count exceeds 10, sort candidates lexicographically by directory name and scan the first 10; list the remainder as unscanned in the spec so the user sees them at the checkpoint — they are not silently dropped.
- Scanners are read-only: they report, they do not edit.
Phase 1: Specify
Surface assumptions immediately:
ASSUMPTIONS I'M MAKING:
1. This is a web application (not native mobile)
2. Authentication uses session-based cookies
3. Database is PostgreSQL (based on existing schema)
→ Correct me now or I'll proceed with these.Write a spec. Areas 1–7 always apply; include area 8 when repos= was supplied:
- Objective — What, why, for whom, success criteria
- Design — Components and their responsibilities, data flow between them, and error handling (what can fail, how it is detected, what the user or caller sees)
- Commands — Full executable commands (build, test, lint, dev)
- Project Structure — Where source, tests, and docs live
- Code Style — One real code snippet showing style beats paragraphs describing it
- Testing Strategy — Framework, locations, coverage expectations
- Boundaries:
- Always do: [non-negotiable rules]
- Ask first: [needs human approval]
- Never do: [hard constraints]
- Repo Allocation (when
repos=was supplied) — per participating repo: what changes there, why it belongs there rather than elsewhere, and the contract it exposes or consumes.
When a Repo Allocation is present, tag acceptance criteria per repo so "done" is defined for each one. The spec checkpoint is where the user confirms the allocation — it is the architectural decision in the change.
Reframe vague requirements as testable success criteria:
"Make the dashboard faster"
→ LCP < 2.5s on 4G, initial load < 500ms, CLS < 0.1
→ Are these the right targets?Phase 2: Plan
With validated spec, generate technical implementation plan:
- Major components and dependencies
- Implementation order
- Risks and mitigations
- What can parallelize vs. must be sequential
Phase 3: Tasks
Break plan into discrete tasks. Each task:
- Completable in one focused session
- Has acceptance criteria
- Has verification step
- Touches ~5 files or fewer
- Ordered by dependency
Phase 4: Implement
Execute tasks one at a time following the incremental-implementation and tdd skills. Load the right spec sections and source files at each step rather than flooding the context with the entire spec.
Keeping the Spec Alive
- Update when decisions or scope change
- Commit the spec to version control
- Reference spec sections in PRs
Red Flags
- Starting code without written requirements
- Implementing features not in any spec
- Making architectural decisions without documenting them
- Skipping the spec because "it's obvious"
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

