spec-driven-development

Name: spec-driven-development
Author: pimenov

20stars2forks

How to install spec-driven-development?

pimenov/codex-first-skills-pack/spec-driven-development

$npx -y skills add pimenov/codex-first-skills-pack --skill spec-driven-development

Installs into the current project.

Summary

Defines the implementation contract before planning or coding so work is built against explicit goals, users, scope, non-goals, assumptions, acceptance criteria, and verification. Use when creating or changing a feature, product workflow, API, integration, migration, user-facing

Files · 1

View on GitHub

SKILL.md

1	# Spec-Driven Development
2
3	## Overview
4
5	Use this skill before planning or implementation when the contract is not already explicit. The output should make it clear what is being built, why, for whom, what counts as done, and what is intentionally out of scope.
6
7	Spec-driven development is a guard against technically clean work that solves the wrong problem.
8
9	## Relationship To Other Skills
10
11	- Use `context-engineering` first when the source of truth or current project state is unclear.
12	- Use `planning-and-task-breakdown` after the spec is accepted or the contract is clear.
13	- Use `incremental-implementation` after planning to execute the work in verified slices.
14	- Use `test-driven-development` to turn acceptance criteria into failing checks.
15	- Use `source-driven-development` when spec choices depend on current external API, SDK, framework, or platform behavior.
16	- Use `doubt-driven-review` before high-stakes specs involving production, auth, data, billing, security, or irreversible operations.
17
18	## Do Not Use
19
20	- Tiny implementation tasks with clear requirements and low risk.
21	- Pure bug reproduction where expected behavior is already obvious; use `debugging-and-error-recovery` and `test-driven-development`.
22	- Emergency incident stabilization before safe state is restored.
23	- Pure writing/copy tasks unless the acceptance criteria are unclear.
24	- Creating a durable spec artifact when a short chat contract is enough.
25
26	## Core Loop
27
28	```text
29	INTENT -> CONTRACT -> BOUNDARIES -> ACCEPTANCE -> STORAGE -> HANDOFF
30	```
31
32	### 1. INTENT: Name The Problem And Audience
33
34	Before writing tasks or code, answer:
35
36	- who is this for;
37	- what problem or job-to-be-done it addresses;
38	- what current pain or failure it removes;
39	- what will be different when it works;
40	- which source artifacts support this intent.
41
42	If the user intent is ambiguous, ask the smallest clarifying question or run read-only discovery. Do not fill product gaps with implementation guesses.
43
44	### 2. CONTRACT: Define The Desired Behavior
45
46	Write the behavior contract in concrete terms:
47
48	- primary scenarios;
49	- inputs and outputs;
50	- user/system actions;
51	- states and transitions;
52	- data or API contracts;
53	- permissions and roles;
54	- error and empty states;
55	- performance or reliability requirements when relevant;
56	- compatibility and migration expectations.
57
58	Prefer observable behavior over internal implementation details.
59
60	### 3. BOUNDARIES: State Scope And Non-Goals
61
62	A good spec says what not to do.
63
64	Include:
65
66	- in scope;
67	- explicitly out of scope;
68	- assumptions;
69	- dependencies;
70	- constraints;
71	- stop-lines;
72	- approval gates;
73	- risks and open questions.
74
75	If a hidden product decision appears, stop and mark it as an open question. Do not bury it inside implementation.
76
77	### 4. ACCEPTANCE: Make Done Testable
78
79	Acceptance criteria should be observable and verifiable.
80
81	Use this shape:
82
83	```text
84	Acceptance criteria:
85	- Given <state>, when <action>, then <observable result>.
86	- <System/API/data behavior> is true and verified by <test/check/smoke>.
87	- <Non-goal or excluded behavior> remains unchanged.
88	```
89
90	Map acceptance to proof:
91
92	- unit/integration/component test;
93	- typecheck/build/lint;
94	- browser/manual smoke;
95	- read-only live check;
96	- screenshots or artifacts;
97	- human approval when automation cannot verify the outcome.
98
99	If acceptance cannot be tested, the spec is not ready for implementation.
100
101	### 5. STORAGE: Choose The Right Artifact
102
103	Do not default to `SPEC.md`.
104
105	Choose the smallest durable layer that will actually be used:
106
107	\| Situation \| Artifact \|
108	\|---\|---\|
109	\| Small clear change \| Chat contract or issue comment \|
110	\| New product/user workflow \| Mini-PRD \|
111	\| Implementation-ready project work \| Work Packet \|
112	\| Execution across chats/people \| Linear document or issue \|
113	\| Human/client-facing explanation \| Notion \|
114	\| Technical contract owned by code \| Repo docs / ADR / spec file \|
115	\| Local sandbox or reusable process \| Local `RUNBOOK.md` / `SESSION_NOTES.md` \|
116
117	For user-facing durable prose, match the user's language. Keep commands, paths, package names, API identifiers, env vars, issue keys, and canonical product names exact.
118
119	### 6. HANDOFF: Prepare For Planning Or Implementation
120
121	A spec is ready to hand off when:
122
123	- intent is clear;
124	- scenarios are concrete;
125	- non-goals are explicit;
126	- acceptance criteria are testable;
127	- source of truth is named;
128	- risks and approval gates are visible;
129	- unresolved questions are separated from ready work.
130
131	Then route:
132
133	- read

People who liked this also viewed

6 picks

Type

spec-driven-development

20stars2forks

View on GitHub

How to install spec-driven-development?

pimenov/codex-first-skills-pack/spec-driven-development

$npx -y skills add pimenov/codex-first-skills-pack --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	Use this skill before planning or implementation when the contract is not already explicit. The output should make it clear what is being built, why, for whom, what counts as done, and what is intentionally out of scope.
6
7	Spec-driven development is a guard against technically clean work that solves the wrong problem.
8
9	## Relationship To Other Skills
10
11	- Use `context-engineering` first when the source of truth or current project state is unclear.
12	- Use `planning-and-task-breakdown` after the spec is accepted or the contract is clear.
13	- Use `incremental-implementation` after planning to execute the work in verified slices.
14	- Use `test-driven-development` to turn acceptance criteria into failing checks.
15	- Use `source-driven-development` when spec choices depend on current external API, SDK, framework, or platform behavior.
16	- Use `doubt-driven-review` before high-stakes specs involving production, auth, data, billing, security, or irreversible operations.
17
18	## Do Not Use
19
20	- Tiny implementation tasks with clear requirements and low risk.
21	- Pure bug reproduction where expected behavior is already obvious; use `debugging-and-error-recovery` and `test-driven-development`.
22	- Emergency incident stabilization before safe state is restored.
23	- Pure writing/copy tasks unless the acceptance criteria are unclear.
24	- Creating a durable spec artifact when a short chat contract is enough.
25
26	## Core Loop
27
28	```text
29	INTENT -> CONTRACT -> BOUNDARIES -> ACCEPTANCE -> STORAGE -> HANDOFF
30	```
31
32	### 1. INTENT: Name The Problem And Audience
33
34	Before writing tasks or code, answer:
35
36	- who is this for;
37	- what problem or job-to-be-done it addresses;
38	- what current pain or failure it removes;
39	- what will be different when it works;
40	- which source artifacts support this intent.
41
42	If the user intent is ambiguous, ask the smallest clarifying question or run read-only discovery. Do not fill product gaps with implementation guesses.
43
44	### 2. CONTRACT: Define The Desired Behavior
45
46	Write the behavior contract in concrete terms:
47
48	- primary scenarios;
49	- inputs and outputs;
50	- user/system actions;
51	- states and transitions;
52	- data or API contracts;
53	- permissions and roles;
54	- error and empty states;
55	- performance or reliability requirements when relevant;
56	- compatibility and migration expectations.
57
58	Prefer observable behavior over internal implementation details.
59
60	### 3. BOUNDARIES: State Scope And Non-Goals
61
62	A good spec says what not to do.
63
64	Include:
65
66	- in scope;
67	- explicitly out of scope;
68	- assumptions;
69	- dependencies;
70	- constraints;
71	- stop-lines;
72	- approval gates;
73	- risks and open questions.
74
75	If a hidden product decision appears, stop and mark it as an open question. Do not bury it inside implementation.
76
77	### 4. ACCEPTANCE: Make Done Testable
78
79	Acceptance criteria should be observable and verifiable.
80
81	Use this shape:
82
83	```text
84	Acceptance criteria:
85	- Given <state>, when <action>, then <observable result>.
86	- <System/API/data behavior> is true and verified by <test/check/smoke>.
87	- <Non-goal or excluded behavior> remains unchanged.
88	```
89
90	Map acceptance to proof:
91
92	- unit/integration/component test;
93	- typecheck/build/lint;
94	- browser/manual smoke;
95	- read-only live check;
96	- screenshots or artifacts;
97	- human approval when automation cannot verify the outcome.
98
99	If acceptance cannot be tested, the spec is not ready for implementation.
100
101	### 5. STORAGE: Choose The Right Artifact
102
103	Do not default to `SPEC.md`.
104
105	Choose the smallest durable layer that will actually be used:
106
107	\| Situation \| Artifact \|
108	\|---\|---\|
109	\| Small clear change \| Chat contract or issue comment \|
110	\| New product/user workflow \| Mini-PRD \|
111	\| Implementation-ready project work \| Work Packet \|
112	\| Execution across chats/people \| Linear document or issue \|
113	\| Human/client-facing explanation \| Notion \|
114	\| Technical contract owned by code \| Repo docs / ADR / spec file \|
115	\| Local sandbox or reusable process \| Local `RUNBOOK.md` / `SESSION_NOTES.md` \|
116
117	For user-facing durable prose, match the user's language. Keep commands, paths, package names, API identifiers, env vars, issue keys, and canonical product names exact.
118
119	### 6. HANDOFF: Prepare For Planning Or Implementation
120
121	A spec is ready to hand off when:
122
123	- intent is clear;
124	- scenarios are concrete;
125	- non-goals are explicit;
126	- acceptance criteria are testable;
127	- source of truth is named;
128	- risks and approval gates are visible;
129	- unresolved questions are separated from ready work.
130
131	Then route:
132
133	- read

People who liked this also viewed

6 picks

Type