Skip to content

Commit 1c2fdc1

Browse files
iobuhoviobuhov
committed
chore: add tdd template
1 parent af928f8 commit 1c2fdc1

5 files changed

Lines changed: 283 additions & 0 deletions

File tree

‎openspec/schemas/tdd/schema.yaml‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
name: tdd
2+
version: 1
3+
description: Test-driven development workflow - proposal → tests → implementation → docs
4+
artifacts:
5+
- id: proposal
6+
generates: proposal.md
7+
description: Initial proposal outlining the bug or feature
8+
template: proposal.md
9+
instruction: |
10+
Create the proposal document that establishes WHY this change is needed.
11+
12+
For bugs, focus on:
13+
- **Why**: What's broken? What's the observed vs. expected behavior?
14+
- **What Changes**: What will be fixed? Be specific about behavior changes.
15+
- **Impact**: Affected code, APIs, users, or systems.
16+
- **Root Cause** (if known): Technical reason for the bug.
17+
18+
For features, focus on:
19+
- **Why**: What problem does this solve? Why now?
20+
- **What Changes**: What new capability will exist?
21+
- **Impact**: Affected code, APIs, dependencies, or systems.
22+
23+
Keep it concise (1 page max). This is test-first, so focus on
24+
observable behavior that tests will verify.
25+
requires: []
26+
27+
- id: tests
28+
generates: tests.md
29+
description: Test specifications written before implementation
30+
template: tests.md
31+
instruction: |
32+
Define the tests that will verify the fix or feature BEFORE implementing.
33+
34+
Structure:
35+
- **Test Cases**: List each test case with:
36+
- Name/Description
37+
- Setup/Given conditions
38+
- Action/When trigger
39+
- Expected/Then outcome
40+
- Test type (unit/integration/e2e)
41+
- Status (pending/failing/passing)
42+
43+
Write tests at appropriate levels:
44+
- Unit tests for isolated logic
45+
- Integration tests for component interactions
46+
- E2E tests for user-facing behavior
47+
48+
Each test should be implementable and should FAIL initially.
49+
Tests define the contract - implementation must make them pass.
50+
51+
Use checkboxes to track test status:
52+
- [ ] Test name - pending (not written yet)
53+
- [x] Test name - written and status noted
54+
requires:
55+
- proposal
56+
57+
- id: implementation
58+
generates: implementation.md
59+
description: Implementation plan and code changes
60+
template: implementation.md
61+
instruction: |
62+
Document the implementation approach and track code changes.
63+
64+
Sections:
65+
- **Approach**: High-level technical strategy
66+
- **Changes**: File-by-file breakdown of modifications
67+
- **Decisions**: Key technical choices and rationale
68+
- **Test Status**: Track which tests pass/fail as you implement
69+
70+
Implementation follows TDD cycle:
71+
1. Write failing test
72+
2. Write minimal code to pass
73+
3. Refactor while keeping tests green
74+
4. Repeat
75+
76+
Implementation is DONE when all tests pass.
77+
Do not add features beyond what tests require.
78+
requires:
79+
- tests
80+
81+
- id: docs
82+
generates: docs.md
83+
description: Documentation updates for the change
84+
template: docs.md
85+
instruction: |
86+
Update relevant documentation after implementation is complete.
87+
88+
Include:
89+
- **API Changes**: Updated signatures, parameters, return values
90+
- **Behavior Changes**: How user-facing behavior differs
91+
- **Migration**: If breaking, how to migrate existing code
92+
- **Examples**: Updated code examples reflecting new behavior
93+
94+
Only document what changed - don't rewrite existing docs.
95+
Mark as "No documentation changes" if none are needed.
96+
requires:
97+
- implementation
98+
99+
apply:
100+
requires: [tests, implementation]
101+
tracks: tests.md
102+
instruction: |
103+
Follow TDD workflow:
104+
1. Review tests.md to understand what needs to pass
105+
2. Write failing tests first (mark status in tests.md)
106+
3. Implement minimal code to make tests pass
107+
4. Refactor while keeping tests green
108+
5. Update test status as tests pass
109+
110+
Mark test checkboxes as complete when tests are written and passing.
111+
Pause if blocked or need clarification.

‎openspec/schemas/tdd/templates/docs.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
## Documentation Changes
2+
3+
<!--
4+
Update relevant documentation after implementation is complete.
5+
If no documentation changes are needed, state "No documentation changes" and explain why.
6+
-->
7+
8+
## API Changes
9+
10+
<!--
11+
If APIs changed:
12+
- Updated function signatures
13+
- New parameters or return values
14+
- Deprecated methods
15+
-->
16+
17+
## Behavior Changes
18+
19+
<!--
20+
How does user-facing behavior differ?
21+
What will users notice?
22+
-->
23+
24+
## Migration
25+
26+
<!--
27+
If this is a breaking change:
28+
- What breaks?
29+
- How to migrate existing code
30+
- Deprecation timeline (if applicable)
31+
-->
32+
33+
## Examples
34+
35+
<!--
36+
Updated code examples reflecting the new behavior:
37+
38+
Before:
39+
```
40+
// old way
41+
```
42+
43+
After:
44+
```
45+
// new way
46+
```
47+
-->
48+
49+
## Internal Documentation
50+
51+
<!--
52+
Updates needed for:
53+
- README files
54+
- Code comments
55+
- Architecture docs
56+
- Inline documentation
57+
-->

‎openspec/schemas/tdd/templates/implementation.md‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
## Approach
2+
3+
<!--
4+
High-level technical strategy for the implementation.
5+
How will you make the tests pass?
6+
-->
7+
8+
## Changes
9+
10+
<!--
11+
File-by-file breakdown of modifications:
12+
13+
- `path/to/file.ts`:
14+
- What changed and why
15+
- Key functions/classes modified
16+
17+
Keep this updated as you implement.
18+
-->
19+
20+
## Decisions
21+
22+
<!--
23+
Key technical choices and rationale:
24+
25+
- **Decision**: Choice made
26+
- **Rationale**: Why this approach?
27+
- **Alternatives**: What else was considered?
28+
- **Trade-offs**: What are the downsides?
29+
-->
30+
31+
## Test Status
32+
33+
<!--
34+
Track test progress through TDD cycle:
35+
36+
Red → Green → Refactor
37+
38+
Update as tests pass:
39+
- [x] Test name - passing after [change description]
40+
- [ ] Test name - still failing, need to implement X
41+
42+
Implementation is DONE when all tests pass.
43+
-->
44+
45+
## TDD Cycle Log
46+
47+
<!--
48+
Optional: Track your red-green-refactor cycles:
49+
50+
1. Red: Wrote failing test for X
51+
2. Green: Made test pass by Y
52+
3. Refactor: Cleaned up Z
53+
-->

‎openspec/schemas/tdd/templates/proposal.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
## Why
2+
3+
<!--
4+
For bugs: What's broken? What's the observed vs. expected behavior?
5+
For features: What problem does this solve? Why now?
6+
-->
7+
8+
## What Changes
9+
10+
<!--
11+
Be specific about what will be fixed or added.
12+
Mark breaking changes with **BREAKING**.
13+
Focus on observable behavior that tests will verify.
14+
-->
15+
16+
## Impact
17+
18+
<!--
19+
Affected code, APIs, users, or systems.
20+
Who needs to know about this change?
21+
-->
22+
23+
## Root Cause
24+
25+
<!--
26+
Optional: For bugs, explain the technical reason if known.
27+
This helps with the fix and prevents similar issues.
28+
-->

‎openspec/schemas/tdd/templates/tests.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
## Test Cases
2+
3+
<!--
4+
List each test case that will verify the fix or feature.
5+
Write these BEFORE implementing - they define the contract.
6+
7+
Use checkboxes to track progress:
8+
- [ ] Test name - not written yet
9+
- [x] Test name - written (note status below)
10+
11+
For each test include:
12+
- Name/Description
13+
- Setup (Given)
14+
- Action (When)
15+
- Expected outcome (Then)
16+
- Test type (unit/integration/e2e)
17+
- Status (pending/failing/passing)
18+
-->
19+
20+
### Example Test Structure
21+
22+
- [ ] **Test name**: Description
23+
- **Type**: unit/integration/e2e
24+
- **Given**: Initial conditions and setup
25+
- **When**: Action or trigger
26+
- **Then**: Expected outcome
27+
- **Status**: pending/failing/passing
28+
29+
## Test Implementation Notes
30+
31+
<!--
32+
Track which tests have been written and their current status.
33+
Update this section as you work through the TDD cycle.
34+
-->

0 commit comments

Comments
 (0)