spec-driven-development

Name: spec-driven-development
Author: addyosmani

16kinstalls8.6kforks

How to install spec-driven-development?

addyosmani/agent-skills/spec-driven-development

$npx -y skills add addyosmani/agent-skills --skill spec-driven-development

Installs into the current project.

Summary

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.

Files · 1

View on GitHub

SKILL.md

1	# Spec-Driven Development
2
3	## Overview
4
5	Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
6
7	## When to Use
8
9	- Starting a new project or feature
10	- Requirements are ambiguous or incomplete
11	- The change touches multiple files or modules
12	- You're about to make an architectural decision
13	- The task would take more than 30 minutes to implement
14
15	When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
16
17	## The Gated Workflow
18
19	Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
20
21	```
22	SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
23	│ │ │ │
24	▼ ▼ ▼ ▼
25	Human Human Human Human
26	reviews reviews reviews reviews
27	```
28
29	### Phase 1: Specify
30
31	Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
32
33	Surface assumptions immediately. Before writing any spec content, list what you're assuming:
34
35	```
36	ASSUMPTIONS I'M MAKING:
37	1. This is a web application (not native mobile)
38	2. Authentication uses session-based cookies (not JWT)
39	3. The database is PostgreSQL (based on existing Prisma schema)
40	4. We're targeting modern browsers only (no IE11)
41	→ Correct me now or I'll proceed with these.
42	```
43
44	Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.
45
46	Write a spec document covering these six core areas:
47
48	1. Objective — What are we building and why? Who is the user? What does success look like?
49
50	2. Commands — Full executable commands with flags, not just tool names.
51	```
52	Build: npm run build
53	Test: npm test -- --coverage
54	Lint: npm run lint --fix
55	Dev: npm run dev
56	```
57
58	3. Project Structure — Where source code lives, where tests go, where docs belong.
59	```
60	src/ → Application source code
61	src/components → React components
62	src/lib → Shared utilities
63	tests/ → Unit and integration tests
64	e2e/ → End-to-end tests
65	docs/ → Documentation
66	```
67
68	4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
69
70	5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.
71
72	6. Boundaries — Three-tier system:
73	- Always do: Run tests before commits, follow naming conventions, validate inputs
74	- Ask first: Database schema changes, adding dependencies, changing CI config
75	- Never do: Commit secrets, edit vendor directories, remove failing tests without approval
76
77	Spec template:
78
79	```markdown
80	# Spec: [Project/Feature Name]
81
82	## Objective
83	[What we're building and why. User stories or acceptance criteria.]
84
85	## Tech Stack
86	[Framework, language, key dependencies with versions]
87
88	## Commands
89	[Build, test, lint, dev — full commands]
90
91	## Project Structure
92	[Directory layout with descriptions]
93
94	## Code Style
95	[Example snippet + key conventions]
96
97	## Testing Strategy
98	[Framework, test locations, coverage requirements, test levels]
99
100	## Boundaries
101	- Always: [...]
102	- Ask first: [...]
103	- Never: [...]
104
105	## Success Criteria
106	[How we'll know this is done — specific, testable conditions]
107
108	## Open Questions
109	[Anything unresolved that needs human input]
110	```
111
112	Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:
113
114	```
115	REQUIREMENT: "Make the dashboard faster"
116
117	REFRAMED SUCCESS CRITERIA:
118	- Dashboard LCP < 2.5s on 4G connection
119	- Initial data load completes in < 500ms
120	- No layout shift during load (CLS < 0.1)
121	→ Are these the right targets?
122	```
123
124	This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
125
126	### Phase 2: Plan
127
128	With the validated spec, generate a technical implementation plan:
129
130	1. Identify the major components and their dependencies
131	2. Determine the implementation order (what must be built first)
132	3. Note risks and mitigation strategies
133	4. Identify what can be built in parallel vs. what must be sequential
134	5. Define verification checkpoints between phases
135
136	> Follow `planning-and-task-breakdown` for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, `planning-and-task-break

People who liked this also viewed

6 picks

Type

spec-driven-development

16kinstalls8.6kforks

View on GitHub

How to install spec-driven-development?

addyosmani/agent-skills/spec-driven-development

$npx -y skills add addyosmani/agent-skills --skill spec-driven-development

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Spec-Driven Development
2
3	## Overview
4
5	Write a structured specification before writing any code. The spec is the shared source of truth between you and the human engineer — it defines what we're building, why, and how we'll know it's done. Code without a spec is guessing.
6
7	## When to Use
8
9	- Starting a new project or feature
10	- Requirements are ambiguous or incomplete
11	- The change touches multiple files or modules
12	- You're about to make an architectural decision
13	- The task would take more than 30 minutes to implement
14
15	When NOT to use: Single-line fixes, typo corrections, or changes where requirements are unambiguous and self-contained.
16
17	## The Gated Workflow
18
19	Spec-driven development has four phases. Do not advance to the next phase until the current one is validated.
20
21	```
22	SPECIFY ──→ PLAN ──→ TASKS ──→ IMPLEMENT
23	│ │ │ │
24	▼ ▼ ▼ ▼
25	Human Human Human Human
26	reviews reviews reviews reviews
27	```
28
29	### Phase 1: Specify
30
31	Start with a high-level vision. Ask the human clarifying questions until requirements are concrete.
32
33	Surface assumptions immediately. Before writing any spec content, list what you're assuming:
34
35	```
36	ASSUMPTIONS I'M MAKING:
37	1. This is a web application (not native mobile)
38	2. Authentication uses session-based cookies (not JWT)
39	3. The database is PostgreSQL (based on existing Prisma schema)
40	4. We're targeting modern browsers only (no IE11)
41	→ Correct me now or I'll proceed with these.
42	```
43
44	Don't silently fill in ambiguous requirements. The spec's entire purpose is to surface misunderstandings before code gets written — assumptions are the most dangerous form of misunderstanding.
45
46	Write a spec document covering these six core areas:
47
48	1. Objective — What are we building and why? Who is the user? What does success look like?
49
50	2. Commands — Full executable commands with flags, not just tool names.
51	```
52	Build: npm run build
53	Test: npm test -- --coverage
54	Lint: npm run lint --fix
55	Dev: npm run dev
56	```
57
58	3. Project Structure — Where source code lives, where tests go, where docs belong.
59	```
60	src/ → Application source code
61	src/components → React components
62	src/lib → Shared utilities
63	tests/ → Unit and integration tests
64	e2e/ → End-to-end tests
65	docs/ → Documentation
66	```
67
68	4. Code Style — One real code snippet showing your style beats three paragraphs describing it. Include naming conventions, formatting rules, and examples of good output.
69
70	5. Testing Strategy — What framework, where tests live, coverage expectations, which test levels for which concerns.
71
72	6. Boundaries — Three-tier system:
73	- Always do: Run tests before commits, follow naming conventions, validate inputs
74	- Ask first: Database schema changes, adding dependencies, changing CI config
75	- Never do: Commit secrets, edit vendor directories, remove failing tests without approval
76
77	Spec template:
78
79	```markdown
80	# Spec: [Project/Feature Name]
81
82	## Objective
83	[What we're building and why. User stories or acceptance criteria.]
84
85	## Tech Stack
86	[Framework, language, key dependencies with versions]
87
88	## Commands
89	[Build, test, lint, dev — full commands]
90
91	## Project Structure
92	[Directory layout with descriptions]
93
94	## Code Style
95	[Example snippet + key conventions]
96
97	## Testing Strategy
98	[Framework, test locations, coverage requirements, test levels]
99
100	## Boundaries
101	- Always: [...]
102	- Ask first: [...]
103	- Never: [...]
104
105	## Success Criteria
106	[How we'll know this is done — specific, testable conditions]
107
108	## Open Questions
109	[Anything unresolved that needs human input]
110	```
111
112	Reframe instructions as success criteria. When receiving vague requirements, translate them into concrete conditions:
113
114	```
115	REQUIREMENT: "Make the dashboard faster"
116
117	REFRAMED SUCCESS CRITERIA:
118	- Dashboard LCP < 2.5s on 4G connection
119	- Initial data load completes in < 500ms
120	- No layout shift during load (CLS < 0.1)
121	→ Are these the right targets?
122	```
123
124	This lets you loop, retry, and problem-solve toward a clear goal rather than guessing what "faster" means.
125
126	### Phase 2: Plan
127
128	With the validated spec, generate a technical implementation plan:
129
130	1. Identify the major components and their dependencies
131	2. Determine the implementation order (what must be built first)
132	3. Note risks and mitigation strategies
133	4. Identify what can be built in parallel vs. what must be sequential
134	5. Define verification checkpoints between phases
135
136	> Follow `planning-and-task-breakdown` for the dependency-graph mapping and vertical-slicing mechanics behind these steps; it is the canonical source. The bullets above are a lightweight summary; if they ever diverge, `planning-and-task-break

People who liked this also viewed

6 picks

Type