spec-driven-development

Name: spec-driven-development
Author: jmxt3

32stars3forks

How to install spec-driven-development?

jmxt3/gitscape.ai/spec-driven-development

$npx -y skills add jmxt3/gitscape.ai --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. A spec answers three questions: what are we building, why are we building it, and how will we know it's done? Every hour spent on a spec saves multiple hours of rework. Never start implementation without a written, reviewed spec.
6
7	## When to Use
8
9	- Starting a new project, feature, or significant change
10	- Requirements are unclear, ambiguous, or stated as a vague idea
11	- Multiple possible approaches exist and the tradeoffs need documenting
12	- The change touches more than two files or crosses a system boundary
13
14	When NOT to use: Trivial bug fixes with a clear, single-line root cause, or changes where the spec already exists and is current.
15
16	## The Spec Process
17
18	### Step 1: Interview First (If the Ask Is Vague)
19
20	Before writing the spec, gather enough context to write it well:
21
22	- What problem does this solve for the user?
23	- Who are the users, and what do they currently do instead?
24	- What does success look like? How will we measure it?
25	- Are there any hard constraints (perf, security, compatibility, deadline)?
26	- What's explicitly out of scope?
27
28	Do not write the spec until you can answer these with confidence.
29
30	### Step 2: Write the Spec
31
32	A spec has six sections:
33
34	```markdown
35	# Spec: [Feature Name]
36
37	## Objective
38	One paragraph: what problem this solves and for whom. Include the measurable
39	success condition (e.g., "users can reset their password without contacting support").
40
41	## Commands / User Flows
42	The primary interactions from the user's point of view. Use imperative language:
43	- User navigates to /reset-password
44	- User enters email address and submits
45	- User receives email with a time-limited link
46	- User sets a new password via the link
47
48	## Project Structure
49	Which files and modules will change or be created. Group by layer (API, frontend, DB).
50	Note any new dependencies.
51
52	## Code Style and Patterns
53	- Which existing patterns to follow (e.g., "use the existing AuthService pattern")
54	- Naming conventions for new symbols
55	- Error handling approach
56
57	## Testing Strategy
58	- What will be unit tested
59	- What requires integration tests
60	- Any E2E coverage needed
61	- Edge cases to cover explicitly
62
63	## Boundaries
64	- Always: [things the implementation must always do]
65	- Ask first: [decisions that require human sign-off before proceeding]
66	- Never: [things the implementation must never do]
67	```
68
69	### Step 3: Review Before Coding
70
71	Before writing any code:
72
73	- [ ] Spec covers all six sections
74	- [ ] Objective includes a measurable success condition
75	- [ ] Boundaries list at least one "Never"
76	- [ ] Human has reviewed and approved the spec
77	- [ ] Open questions are resolved or explicitly parked
78
79	A spec that is "good enough to review" is good enough to start coding. Perfection is not the goal — clarity is.
80
81	### Step 4: Save and Reference
82
83	Save the spec as `SPEC.md` in the project root (or `docs/SPEC.md` for multi-project repos). Reference it in commits and PRs. When requirements change, update the spec first — the spec is the source of truth, not the code.
84
85	## Spec Quality Bar
86
87	A good spec:
88	- Defines done — a reader can verify completion without asking the author
89	- Surfaces trade-offs — records the decisions made and why alternatives were rejected
90	- Scopes explicitly — what is out of scope is as important as what is in scope
91	- Is short — a one-page spec is better than a ten-page spec. If the spec is long, break the work into multiple specs.
92
93	## Common Rationalizations
94
95	\| Rationalization \| Reality \|
96	\|---\|---\|
97	\| "I know what to build, I don't need a spec" \| The spec isn't for you — it's for the reviewer, the future maintainer, and your future self after a context switch. \|
98	\| "The requirements will change anyway" \| A spec makes changes visible. Without one, scope creep is invisible until it's a problem. \|
99	\| "Writing a spec takes too long" \| A vague spec takes 15 minutes. The rework it prevents takes hours. \|
100	\| "The ticket/issue is the spec" \| Issue trackers capture requests, not decisions. A spec captures what was decided and why. \|
101
102	## Red Flags
103
104	- Starting implementation without a written spec
105	- A spec with no measurable success condition
106	- A spec where "out of scope" is empty
107	- No human review before coding begins
108	- Spec is written after the code (post-hoc rationalization)
109
110	## Verification
111
112	Before writing code, confirm:
113
114	- [ ] Spec exists as a file (not just in your head)
115	- [ ] All six sections are present and non-empty
116	- [ ] The objective includes a measurable success condition
117	- [ ] At least one "Never" boundary is defined
118	- [ ] A human has read and approved the spec
119	- [ ] Open questions are explicitly tracked (not silently assumed)

People who liked this also viewed

6 picks

Type

spec-driven-development

32stars3forks

View on GitHub

How to install spec-driven-development?

jmxt3/gitscape.ai/spec-driven-development

$npx -y skills add jmxt3/gitscape.ai --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. A spec answers three questions: what are we building, why are we building it, and how will we know it's done? Every hour spent on a spec saves multiple hours of rework. Never start implementation without a written, reviewed spec.
6
7	## When to Use
8
9	- Starting a new project, feature, or significant change
10	- Requirements are unclear, ambiguous, or stated as a vague idea
11	- Multiple possible approaches exist and the tradeoffs need documenting
12	- The change touches more than two files or crosses a system boundary
13
14	When NOT to use: Trivial bug fixes with a clear, single-line root cause, or changes where the spec already exists and is current.
15
16	## The Spec Process
17
18	### Step 1: Interview First (If the Ask Is Vague)
19
20	Before writing the spec, gather enough context to write it well:
21
22	- What problem does this solve for the user?
23	- Who are the users, and what do they currently do instead?
24	- What does success look like? How will we measure it?
25	- Are there any hard constraints (perf, security, compatibility, deadline)?
26	- What's explicitly out of scope?
27
28	Do not write the spec until you can answer these with confidence.
29
30	### Step 2: Write the Spec
31
32	A spec has six sections:
33
34	```markdown
35	# Spec: [Feature Name]
36
37	## Objective
38	One paragraph: what problem this solves and for whom. Include the measurable
39	success condition (e.g., "users can reset their password without contacting support").
40
41	## Commands / User Flows
42	The primary interactions from the user's point of view. Use imperative language:
43	- User navigates to /reset-password
44	- User enters email address and submits
45	- User receives email with a time-limited link
46	- User sets a new password via the link
47
48	## Project Structure
49	Which files and modules will change or be created. Group by layer (API, frontend, DB).
50	Note any new dependencies.
51
52	## Code Style and Patterns
53	- Which existing patterns to follow (e.g., "use the existing AuthService pattern")
54	- Naming conventions for new symbols
55	- Error handling approach
56
57	## Testing Strategy
58	- What will be unit tested
59	- What requires integration tests
60	- Any E2E coverage needed
61	- Edge cases to cover explicitly
62
63	## Boundaries
64	- Always: [things the implementation must always do]
65	- Ask first: [decisions that require human sign-off before proceeding]
66	- Never: [things the implementation must never do]
67	```
68
69	### Step 3: Review Before Coding
70
71	Before writing any code:
72
73	- [ ] Spec covers all six sections
74	- [ ] Objective includes a measurable success condition
75	- [ ] Boundaries list at least one "Never"
76	- [ ] Human has reviewed and approved the spec
77	- [ ] Open questions are resolved or explicitly parked
78
79	A spec that is "good enough to review" is good enough to start coding. Perfection is not the goal — clarity is.
80
81	### Step 4: Save and Reference
82
83	Save the spec as `SPEC.md` in the project root (or `docs/SPEC.md` for multi-project repos). Reference it in commits and PRs. When requirements change, update the spec first — the spec is the source of truth, not the code.
84
85	## Spec Quality Bar
86
87	A good spec:
88	- Defines done — a reader can verify completion without asking the author
89	- Surfaces trade-offs — records the decisions made and why alternatives were rejected
90	- Scopes explicitly — what is out of scope is as important as what is in scope
91	- Is short — a one-page spec is better than a ten-page spec. If the spec is long, break the work into multiple specs.
92
93	## Common Rationalizations
94
95	\| Rationalization \| Reality \|
96	\|---\|---\|
97	\| "I know what to build, I don't need a spec" \| The spec isn't for you — it's for the reviewer, the future maintainer, and your future self after a context switch. \|
98	\| "The requirements will change anyway" \| A spec makes changes visible. Without one, scope creep is invisible until it's a problem. \|
99	\| "Writing a spec takes too long" \| A vague spec takes 15 minutes. The rework it prevents takes hours. \|
100	\| "The ticket/issue is the spec" \| Issue trackers capture requests, not decisions. A spec captures what was decided and why. \|
101
102	## Red Flags
103
104	- Starting implementation without a written spec
105	- A spec with no measurable success condition
106	- A spec where "out of scope" is empty
107	- No human review before coding begins
108	- Spec is written after the code (post-hoc rationalization)
109
110	## Verification
111
112	Before writing code, confirm:
113
114	- [ ] Spec exists as a file (not just in your head)
115	- [ ] All six sections are present and non-empty
116	- [ ] The objective includes a measurable success condition
117	- [ ] At least one "Never" boundary is defined
118	- [ ] A human has read and approved the spec
119	- [ ] Open questions are explicitly tracked (not silently assumed)

People who liked this also viewed

6 picks

Type