spec-driven-implementation

Name: spec-driven-implementation
Author: warpdotdev

15kinstalls1forks

How to install spec-driven-implementation?

warpdotdev/common-skills/spec-driven-implementation

$npx -y skills add warpdotdev/common-skills --skill spec-driven-implementation

Installs into the current project.

Summary

Drive a spec-first workflow for substantial features by writing PRODUCT.md before implementation, writing TECH.md when warranted, and keeping both specs updated as implementation evolves. Use when starting a significant feature, planning agent-driven implementation, or when the u

Files · 1

View on GitHub

SKILL.md

1	# spec-driven-implementation
2
3	Drive a spec-first workflow for substantial features in Warp.
4
5	## Overview
6
7	Use this skill for significant features where a written spec will improve implementation quality, reduce ambiguity, or make review easier. Be pragmatic: not every change needs specs.
8
9	Specs should usually live in:
10
11	- `specs/<linear-ticket-number>/PRODUCT.md`
12	- `specs/<linear-ticket-number>/TECH.md`
13
14	For example:
15
16	- `specs/APP-1234/PRODUCT.md`
17	- `specs/APP-1234/TECH.md`
18
19	`specs/` should contain only ticket-named directories as direct children. Do not create engineer-named subdirectories or feature-slug directories there.
20
21	If a relevant Linear issue does not already exist, create one before writing specs. Use the Linear MCP tools directly:
22
23	- `list_teams` to find the appropriate team
24	- `list_issue_labels` to inspect the expected labels/tags
25	- `save_issue` to create the issue with the appropriate team and labels
26
27	If the correct team or labels are not obvious from the request and surrounding context, use `ask_user_question` to clarify rather than guessing.
28
29	These specs should largely be written by agents, not by hand, and should be checked into source control so they can be reviewed and kept current with the code.
30
31	## When specs are required
32
33	Strongly prefer specs when the change is substantial, such as:
34
35	- product or architectural ambiguity
36	- expected implementation size around 1k+ LOC
37	- deep or cross-cutting stack changes
38	- risky behavior changes where regressions would be expensive
39	- work where agent quality will improve materially from clearer inputs
40
41	Specs are often unnecessary for:
42
43	- small, local bug fixes
44	- straightforward refactors
45	- narrow UI tweaks with little ambiguity
46
47	For pure UI changes, the product spec is often useful while the tech spec may be unnecessary.
48
49	## Workflow
50
51	### 1. Decide whether the feature needs specs
52
53	Evaluate the size, ambiguity, and risk of the feature. If specs will not meaningfully improve execution or review, skip them and focus on verification instead.
54
55	### 2. Write the product spec first
56
57	Before implementation, create `PRODUCT.md` describing the desired user-facing behavior.
58
59	Use the `write-product-spec` skill to produce it. The product spec should define:
60
61	- what problem is being solved
62	- the desired user experience
63	- invariants and edge cases
64	- success criteria
65	- how the behavior will be validated
66
67	If the feature has UI or interaction design, ask for a Figma mock if one exists. If there is no mock, continue but call that out explicitly in the product spec.
68
69	Reference the Linear issue in the spec when one exists. Because specs live under `specs/<linear-ticket-number>/...`, this should usually be straightforward.
70
71	### 3. Write the tech spec when warranted
72
73	Use the `write-tech-spec` skill for substantial or ambiguous implementation work.
74
75	Prefer a tech spec when:
76
77	- the implementation spans multiple subsystems
78	- architecture or extensibility matters
79	- there are meaningful tradeoffs to document
80	- reviewers will benefit more from reviewing the plan than the raw code
81
82	It is acceptable to write the tech spec after an e2e prototype if that leads to a more accurate implementation plan. Do not force a premature tech spec when the implementation details are still too uncertain.
83
84	### 4. Implement approved specs
85
86	After the specs are approved, use the `implement-specs` skill to build from the approved `PRODUCT.md` and `TECH.md`.
87
88	The implementation can often be pushed in the same PR as the product and tech specs. As the engineer iterates, keep `PRODUCT.md`, `TECH.md`, code changes, and tests in that same PR so the review reflects the feature that will actually ship.
89
90	For large features, the implementer may optionally offer:
91
92	- `PROJECT_LOG.md` to track explored paths, checkpoints, and current implementation state
93	- `DECISIONS.md` to capture concrete product and technical decisions made during design and implementation
94
95	These are optional aids, not required outputs.
96
97	### 5. Keep specs current during implementation
98
99	If implementation changes from the spec, update the spec rather than leaving it stale.
100
101	Update `PRODUCT.md` when:
102
103	- user-facing behavior changes
104	- success criteria change
105	- UX details or edge cases change
106
107	Update `TECH.md` when:
108
109	- the implementation approach changes
110	- architectural boundaries move
111	- risks, dependencies, or rollout details change
112	- the testing or validation plan changes
113
114	The checked-in specs should describe the feature that actually ships, not just the initial intent. Keep those spec updates in the same PR as the related code changes whenever practical.
115
116	### 6. V

People who liked this also viewed

6 picks

Type

spec-driven-implementation

15kinstalls1forks

View on GitHub

How to install spec-driven-implementation?

warpdotdev/common-skills/spec-driven-implementation

$npx -y skills add warpdotdev/common-skills --skill spec-driven-implementation

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# spec-driven-implementation
2
3	Drive a spec-first workflow for substantial features in Warp.
4
5	## Overview
6
7	Use this skill for significant features where a written spec will improve implementation quality, reduce ambiguity, or make review easier. Be pragmatic: not every change needs specs.
8
9	Specs should usually live in:
10
11	- `specs/<linear-ticket-number>/PRODUCT.md`
12	- `specs/<linear-ticket-number>/TECH.md`
13
14	For example:
15
16	- `specs/APP-1234/PRODUCT.md`
17	- `specs/APP-1234/TECH.md`
18
19	`specs/` should contain only ticket-named directories as direct children. Do not create engineer-named subdirectories or feature-slug directories there.
20
21	If a relevant Linear issue does not already exist, create one before writing specs. Use the Linear MCP tools directly:
22
23	- `list_teams` to find the appropriate team
24	- `list_issue_labels` to inspect the expected labels/tags
25	- `save_issue` to create the issue with the appropriate team and labels
26
27	If the correct team or labels are not obvious from the request and surrounding context, use `ask_user_question` to clarify rather than guessing.
28
29	These specs should largely be written by agents, not by hand, and should be checked into source control so they can be reviewed and kept current with the code.
30
31	## When specs are required
32
33	Strongly prefer specs when the change is substantial, such as:
34
35	- product or architectural ambiguity
36	- expected implementation size around 1k+ LOC
37	- deep or cross-cutting stack changes
38	- risky behavior changes where regressions would be expensive
39	- work where agent quality will improve materially from clearer inputs
40
41	Specs are often unnecessary for:
42
43	- small, local bug fixes
44	- straightforward refactors
45	- narrow UI tweaks with little ambiguity
46
47	For pure UI changes, the product spec is often useful while the tech spec may be unnecessary.
48
49	## Workflow
50
51	### 1. Decide whether the feature needs specs
52
53	Evaluate the size, ambiguity, and risk of the feature. If specs will not meaningfully improve execution or review, skip them and focus on verification instead.
54
55	### 2. Write the product spec first
56
57	Before implementation, create `PRODUCT.md` describing the desired user-facing behavior.
58
59	Use the `write-product-spec` skill to produce it. The product spec should define:
60
61	- what problem is being solved
62	- the desired user experience
63	- invariants and edge cases
64	- success criteria
65	- how the behavior will be validated
66
67	If the feature has UI or interaction design, ask for a Figma mock if one exists. If there is no mock, continue but call that out explicitly in the product spec.
68
69	Reference the Linear issue in the spec when one exists. Because specs live under `specs/<linear-ticket-number>/...`, this should usually be straightforward.
70
71	### 3. Write the tech spec when warranted
72
73	Use the `write-tech-spec` skill for substantial or ambiguous implementation work.
74
75	Prefer a tech spec when:
76
77	- the implementation spans multiple subsystems
78	- architecture or extensibility matters
79	- there are meaningful tradeoffs to document
80	- reviewers will benefit more from reviewing the plan than the raw code
81
82	It is acceptable to write the tech spec after an e2e prototype if that leads to a more accurate implementation plan. Do not force a premature tech spec when the implementation details are still too uncertain.
83
84	### 4. Implement approved specs
85
86	After the specs are approved, use the `implement-specs` skill to build from the approved `PRODUCT.md` and `TECH.md`.
87
88	The implementation can often be pushed in the same PR as the product and tech specs. As the engineer iterates, keep `PRODUCT.md`, `TECH.md`, code changes, and tests in that same PR so the review reflects the feature that will actually ship.
89
90	For large features, the implementer may optionally offer:
91
92	- `PROJECT_LOG.md` to track explored paths, checkpoints, and current implementation state
93	- `DECISIONS.md` to capture concrete product and technical decisions made during design and implementation
94
95	These are optional aids, not required outputs.
96
97	### 5. Keep specs current during implementation
98
99	If implementation changes from the spec, update the spec rather than leaving it stale.
100
101	Update `PRODUCT.md` when:
102
103	- user-facing behavior changes
104	- success criteria change
105	- UX details or edge cases change
106
107	Update `TECH.md` when:
108
109	- the implementation approach changes
110	- architectural boundaries move
111	- risks, dependencies, or rollout details change
112	- the testing or validation plan changes
113
114	The checked-in specs should describe the feature that actually ships, not just the initial intent. Keep those spec updates in the same PR as the related code changes whenever practical.
115
116	### 6. V

People who liked this also viewed

6 picks

Type