my-opencode 1.1.0 → 1.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -21
- package/README.md +180 -180
- package/agents/architect.md +30 -30
- package/agents/code-reviewer.md +29 -29
- package/agents/executor.md +30 -30
- package/agents/fullstack-dev.md +57 -53
- package/agents/spec-writer.md +37 -37
- package/agents/team-lead.md +60 -60
- package/agents/tech-writer.md +30 -30
- package/agents/test-engineer.md +30 -30
- package/agents/verifier.md +33 -33
- package/bin/cli.js +311 -311
- package/opencode.json +167 -164
- package/package.json +48 -48
- package/scripts/postinstall.js +182 -182
- package/skills/adr/SKILL.md +91 -91
- package/skills/adr/references/templates.md +100 -100
- package/skills/adr/scripts/README.md +5 -5
- package/skills/dev-flow/SKILL.md +188 -188
- package/skills/dev-flow/references/code-phase.md +72 -72
- package/skills/dev-flow/references/contract-phase.md +81 -81
- package/skills/dev-flow/references/verify-phase.md +129 -129
- package/skills/dev-flow/scripts/README.md +3 -3
- package/skills/docs-gen/SKILL.md +162 -162
- package/skills/docs-gen/references/doc-styles.md +216 -216
- package/skills/docs-gen/scripts/README.md +5 -5
- package/skills/orchestrate/SKILL.md +112 -112
- package/skills/orchestrate/references/orchestration-patterns.md +56 -56
- package/skills/pr-review/SKILL.md +110 -110
- package/skills/pr-review/references/review-dimensions.md +117 -117
- package/skills/pr-review/references/security-checklist.md +122 -122
- package/skills/pr-review/scripts/README.md +5 -5
- package/skills/test-gen/SKILL.md +143 -143
- package/skills/test-gen/references/framework-detection.md +105 -105
- package/skills/test-gen/references/test-patterns.md +260 -260
- package/skills/test-gen/scripts/README.md +5 -5
|
@@ -1,100 +1,100 @@
|
|
|
1
|
-
# ADR Templates
|
|
2
|
-
|
|
3
|
-
## Standard (Michael Nygard)
|
|
4
|
-
|
|
5
|
-
```markdown
|
|
6
|
-
# ADR-NNN: <short title>
|
|
7
|
-
|
|
8
|
-
**Date:** YYYY-MM-DD
|
|
9
|
-
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
|
|
10
|
-
|
|
11
|
-
## Context
|
|
12
|
-
<What is the issue motivating this decision?
|
|
13
|
-
What forces are at play (technical, political, social)?
|
|
14
|
-
Mention specific constraints, requirements, or tradeoffs.>
|
|
15
|
-
|
|
16
|
-
## Decision
|
|
17
|
-
<What is the change being proposed or made?
|
|
18
|
-
Be specific — technology name, version, pattern.>
|
|
19
|
-
|
|
20
|
-
## Consequences
|
|
21
|
-
<What becomes easier or harder?
|
|
22
|
-
List positive and negative outcomes.>
|
|
23
|
-
|
|
24
|
-
## Alternatives
|
|
25
|
-
<What other options were considered, and why were they rejected?
|
|
26
|
-
Keep brief — 1-2 sentences per alternative.>
|
|
27
|
-
```
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## MADR (Markdown ADR) — More Structured
|
|
32
|
-
|
|
33
|
-
```markdown
|
|
34
|
-
# ADR-NNN: <short title>
|
|
35
|
-
|
|
36
|
-
**Date:** YYYY-MM-DD
|
|
37
|
-
**Status:** Proposed
|
|
38
|
-
|
|
39
|
-
## Context and Problem Statement
|
|
40
|
-
<Describe the problem in 2-3 sentences.>
|
|
41
|
-
|
|
42
|
-
## Decision Drivers
|
|
43
|
-
- <driver 1>
|
|
44
|
-
- <driver 2>
|
|
45
|
-
|
|
46
|
-
## Considered Options
|
|
47
|
-
- Option A: <summary>
|
|
48
|
-
- Option B: <summary>
|
|
49
|
-
- Option C: <summary>
|
|
50
|
-
|
|
51
|
-
## Decision Outcome
|
|
52
|
-
Chosen option: <option>, because <justification>.
|
|
53
|
-
|
|
54
|
-
## Pros and Cons of Options
|
|
55
|
-
|
|
56
|
-
### Option A
|
|
57
|
-
- Good: <point>
|
|
58
|
-
- Bad: <point>
|
|
59
|
-
|
|
60
|
-
### Option B
|
|
61
|
-
- Good: <point>
|
|
62
|
-
- Bad: <point>
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
---
|
|
66
|
-
|
|
67
|
-
## Lightweight (for quick decisions, 5 min write)
|
|
68
|
-
|
|
69
|
-
```markdown
|
|
70
|
-
# ADR-NNN: <short title>
|
|
71
|
-
|
|
72
|
-
We chose **<decision>** over **<alternatives>** because
|
|
73
|
-
<primary reason>.
|
|
74
|
-
|
|
75
|
-
## Context
|
|
76
|
-
<1-2 sentences>
|
|
77
|
-
|
|
78
|
-
## Consequences
|
|
79
|
-
<bullet points>
|
|
80
|
-
```
|
|
81
|
-
|
|
82
|
-
---
|
|
83
|
-
|
|
84
|
-
## ADR Index (`docs/adr/README.md`)
|
|
85
|
-
|
|
86
|
-
```markdown
|
|
87
|
-
# Architecture Decision Records
|
|
88
|
-
|
|
89
|
-
| ADR | Title | Status | Date |
|
|
90
|
-
|-----|-------|--------|------|
|
|
91
|
-
| 001 | Use PostgreSQL for primary DB | Accepted | 2026-05-01 |
|
|
92
|
-
| 002 | API versioning via URL prefix | Proposed | 2026-05-15 |
|
|
93
|
-
```
|
|
94
|
-
|
|
95
|
-
When superseding, update the old ADR's status and add the link:
|
|
96
|
-
|
|
97
|
-
```markdown
|
|
98
|
-
## Status
|
|
99
|
-
Superseded by [ADR-005: New Caching Strategy](005-new-caching.md)
|
|
100
|
-
```
|
|
1
|
+
# ADR Templates
|
|
2
|
+
|
|
3
|
+
## Standard (Michael Nygard)
|
|
4
|
+
|
|
5
|
+
```markdown
|
|
6
|
+
# ADR-NNN: <short title>
|
|
7
|
+
|
|
8
|
+
**Date:** YYYY-MM-DD
|
|
9
|
+
**Status:** Proposed | Accepted | Deprecated | Superseded by ADR-NNN
|
|
10
|
+
|
|
11
|
+
## Context
|
|
12
|
+
<What is the issue motivating this decision?
|
|
13
|
+
What forces are at play (technical, political, social)?
|
|
14
|
+
Mention specific constraints, requirements, or tradeoffs.>
|
|
15
|
+
|
|
16
|
+
## Decision
|
|
17
|
+
<What is the change being proposed or made?
|
|
18
|
+
Be specific — technology name, version, pattern.>
|
|
19
|
+
|
|
20
|
+
## Consequences
|
|
21
|
+
<What becomes easier or harder?
|
|
22
|
+
List positive and negative outcomes.>
|
|
23
|
+
|
|
24
|
+
## Alternatives
|
|
25
|
+
<What other options were considered, and why were they rejected?
|
|
26
|
+
Keep brief — 1-2 sentences per alternative.>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## MADR (Markdown ADR) — More Structured
|
|
32
|
+
|
|
33
|
+
```markdown
|
|
34
|
+
# ADR-NNN: <short title>
|
|
35
|
+
|
|
36
|
+
**Date:** YYYY-MM-DD
|
|
37
|
+
**Status:** Proposed
|
|
38
|
+
|
|
39
|
+
## Context and Problem Statement
|
|
40
|
+
<Describe the problem in 2-3 sentences.>
|
|
41
|
+
|
|
42
|
+
## Decision Drivers
|
|
43
|
+
- <driver 1>
|
|
44
|
+
- <driver 2>
|
|
45
|
+
|
|
46
|
+
## Considered Options
|
|
47
|
+
- Option A: <summary>
|
|
48
|
+
- Option B: <summary>
|
|
49
|
+
- Option C: <summary>
|
|
50
|
+
|
|
51
|
+
## Decision Outcome
|
|
52
|
+
Chosen option: <option>, because <justification>.
|
|
53
|
+
|
|
54
|
+
## Pros and Cons of Options
|
|
55
|
+
|
|
56
|
+
### Option A
|
|
57
|
+
- Good: <point>
|
|
58
|
+
- Bad: <point>
|
|
59
|
+
|
|
60
|
+
### Option B
|
|
61
|
+
- Good: <point>
|
|
62
|
+
- Bad: <point>
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Lightweight (for quick decisions, 5 min write)
|
|
68
|
+
|
|
69
|
+
```markdown
|
|
70
|
+
# ADR-NNN: <short title>
|
|
71
|
+
|
|
72
|
+
We chose **<decision>** over **<alternatives>** because
|
|
73
|
+
<primary reason>.
|
|
74
|
+
|
|
75
|
+
## Context
|
|
76
|
+
<1-2 sentences>
|
|
77
|
+
|
|
78
|
+
## Consequences
|
|
79
|
+
<bullet points>
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## ADR Index (`docs/adr/README.md`)
|
|
85
|
+
|
|
86
|
+
```markdown
|
|
87
|
+
# Architecture Decision Records
|
|
88
|
+
|
|
89
|
+
| ADR | Title | Status | Date |
|
|
90
|
+
|-----|-------|--------|------|
|
|
91
|
+
| 001 | Use PostgreSQL for primary DB | Accepted | 2026-05-01 |
|
|
92
|
+
| 002 | API versioning via URL prefix | Proposed | 2026-05-15 |
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
When superseding, update the old ADR's status and add the link:
|
|
96
|
+
|
|
97
|
+
```markdown
|
|
98
|
+
## Status
|
|
99
|
+
Superseded by [ADR-005: New Caching Strategy](005-new-caching.md)
|
|
100
|
+
```
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
# adr Scripts
|
|
2
|
-
|
|
3
|
-
Placeholder for ADR utility scripts. Future candidates:
|
|
4
|
-
- `adr-init.py` — Initialize `docs/adr/` with README index
|
|
5
|
-
- `adr-list.py` — List all ADRs with status
|
|
1
|
+
# adr Scripts
|
|
2
|
+
|
|
3
|
+
Placeholder for ADR utility scripts. Future candidates:
|
|
4
|
+
- `adr-init.py` — Initialize `docs/adr/` with README index
|
|
5
|
+
- `adr-list.py` — List all ADRs with status
|
package/skills/dev-flow/SKILL.md
CHANGED
|
@@ -1,188 +1,188 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dev-flow
|
|
3
|
-
description: |
|
|
4
|
-
Contract-first development workflow: contract → code → verify → fix (loop).
|
|
5
|
-
Drives development from persistent specifications, enabling parallel frontend/backend work.
|
|
6
|
-
Use PROACTIVELY when implementing features, fixing bugs, refactoring, or making code changes.
|
|
7
|
-
Triggers on: "implement", "feature", "fix bug", "refactor", "add", "change", "build"
|
|
8
|
-
---
|
|
9
|
-
|
|
10
|
-
# Development Flow
|
|
11
|
-
|
|
12
|
-
Contract-first development workflow. Writes persistent specifications before coding, so frontend and backend can work in parallel from the same contract.
|
|
13
|
-
|
|
14
|
-
## When to Use
|
|
15
|
-
|
|
16
|
-
- Implementing a new feature
|
|
17
|
-
- Fixing a bug
|
|
18
|
-
- Refactoring existing code
|
|
19
|
-
- Making any non-trivial code change
|
|
20
|
-
|
|
21
|
-
## Phase Overview
|
|
22
|
-
|
|
23
|
-
```
|
|
24
|
-
[Phase 0: Architecture — ADR (optional)]
|
|
25
|
-
│
|
|
26
|
-
v
|
|
27
|
-
Phase 1: Contract ──→ docs/specs/<feature>/ (persistent, committed)
|
|
28
|
-
│ Frontend & Backend can start in parallel
|
|
29
|
-
v
|
|
30
|
-
Phase 2: Code
|
|
31
|
-
│
|
|
32
|
-
v
|
|
33
|
-
Phase 3: Verify ──→ against acceptance criteria from Phase 1
|
|
34
|
-
│
|
|
35
|
-
v
|
|
36
|
-
[Fix loop] → back to Phase 2 (max 3 retries)
|
|
37
|
-
```
|
|
38
|
-
|
|
39
|
-
## Phase 0: Architecture (Optional)
|
|
40
|
-
|
|
41
|
-
**When:** An architectural decision needs recording (tech choice, structural change, cross-team impact).
|
|
42
|
-
|
|
43
|
-
**Output:** `docs/adr/NNNN-title.md` — Architecture Decision Record
|
|
44
|
-
|
|
45
|
-
**Agent:** architect
|
|
46
|
-
|
|
47
|
-
See `skills/adr/SKILL.md` for ADR workflow and template.
|
|
48
|
-
|
|
49
|
-
→ Then proceed to Phase 1 with the ADR as architectural context.
|
|
50
|
-
|
|
51
|
-
## Phase 1: Contract
|
|
52
|
-
|
|
53
|
-
**Goal:** Produce a persistent specification that records consensus and enables parallel implementation.
|
|
54
|
-
|
|
55
|
-
**Output (persistent, committed to repo):**
|
|
56
|
-
```
|
|
57
|
-
docs/specs/<feature>/
|
|
58
|
-
├── README.md # Requirements, ACs, API contract, data model
|
|
59
|
-
├── api-spec.yaml # OpenAPI spec (if applicable)
|
|
60
|
-
└── data-model.md # Schema definitions (if applicable)
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
### Steps
|
|
64
|
-
1. **Analyze** — Read relevant files, existing ADRs, understand context
|
|
65
|
-
2. **Check ADRs** — Are there existing ADRs that constrain this feature? Reference them.
|
|
66
|
-
3. **Specify** — Write the contract document:
|
|
67
|
-
- Functional requirements (RFC 2119: MUST/SHOULD/MAY)
|
|
68
|
-
- Acceptance criteria (GIVEN/WHEN/THEN)
|
|
69
|
-
- API contract (endpoints, request/response schemas)
|
|
70
|
-
- Data model (entities, fields, types, constraints)
|
|
71
|
-
- Out of scope (explicit exclusions)
|
|
72
|
-
4. **Review** — Present contract to user for approval
|
|
73
|
-
|
|
74
|
-
### Contract Document Template
|
|
75
|
-
```markdown
|
|
76
|
-
# Feature: <title>
|
|
77
|
-
|
|
78
|
-
## Requirements
|
|
79
|
-
FR-1: System MUST <behavior>
|
|
80
|
-
|
|
81
|
-
## Acceptance Criteria
|
|
82
|
-
- GIVEN <context> WHEN <action> THEN <result>
|
|
83
|
-
|
|
84
|
-
## API Contract
|
|
85
|
-
POST /api/xxx
|
|
86
|
-
Request: { field: type }
|
|
87
|
-
Response: { field: type }
|
|
88
|
-
|
|
89
|
-
## Data Model
|
|
90
|
-
| Entity | Field | Type | Constraints |
|
|
91
|
-
|
|
92
|
-
## Out of Scope
|
|
93
|
-
- <explicit exclusions>
|
|
94
|
-
|
|
95
|
-
## Architecture
|
|
96
|
-
References: ADR-001, ADR-003
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
### Agent: spec-writer
|
|
100
|
-
- Tools: Read, Grep, Glob, Bash, Write, Edit
|
|
101
|
-
- Writes to `docs/specs/<feature>/`, NOT to `.handoffs/`
|
|
102
|
-
|
|
103
|
-
See `references/contract-phase.md` for detailed contract workflow.
|
|
104
|
-
|
|
105
|
-
## Phase 2: Code
|
|
106
|
-
|
|
107
|
-
**Goal:** Implement the contract. Frontend and backend can proceed independently.
|
|
108
|
-
|
|
109
|
-
### Steps
|
|
110
|
-
1. **Read contract** — Load `docs/specs/<feature>/README.md` and referenced ADRs
|
|
111
|
-
2. **Implement** — Write code following the contract and project conventions
|
|
112
|
-
3. **Self-review** — Verify code matches the contract before moving on
|
|
113
|
-
|
|
114
|
-
### Key Principle
|
|
115
|
-
The contract in `docs/specs/` is the source of truth. If implementation reveals
|
|
116
|
-
issues with the contract, update the contract first, then code.
|
|
117
|
-
|
|
118
|
-
### Handoff (`.handoffs/dev-flow/code.md`)
|
|
119
|
-
Lightweight — references contract rather than duplicating it:
|
|
120
|
-
- Files changed
|
|
121
|
-
- Deviations from contract (with rationale)
|
|
122
|
-
- Pending items
|
|
123
|
-
|
|
124
|
-
### Agent: executor
|
|
125
|
-
- Tools: Read, Write, Edit, Bash, Grep, Glob
|
|
126
|
-
- Full read/write access
|
|
127
|
-
|
|
128
|
-
See `references/code-phase.md` for detailed coding workflow.
|
|
129
|
-
|
|
130
|
-
## Phase 3: Verify
|
|
131
|
-
|
|
132
|
-
**Goal:** Verify implementation against the acceptance criteria from Phase 1.
|
|
133
|
-
|
|
134
|
-
### Steps
|
|
135
|
-
1. **Lint** — Run linter
|
|
136
|
-
2. **Typecheck** — Run type checker if applicable
|
|
137
|
-
3. **Test** — Run tests, verify acceptance criteria are met
|
|
138
|
-
4. **Build** — Verify project builds
|
|
139
|
-
|
|
140
|
-
If any step fails → enter fix loop (back to Phase 2).
|
|
141
|
-
|
|
142
|
-
### Handoff (`.handoffs/dev-flow/verify.md`)
|
|
143
|
-
- Lint/typecheck/test/build results
|
|
144
|
-
- Acceptance criteria pass/fail from contract
|
|
145
|
-
- Final verdict: pass / needs fix
|
|
146
|
-
|
|
147
|
-
### Agent: verifier
|
|
148
|
-
- Tools: Read, Grep, Glob, Bash
|
|
149
|
-
- Read-only + execute tests
|
|
150
|
-
|
|
151
|
-
See `references/verify-phase.md` for detailed verification workflow.
|
|
152
|
-
|
|
153
|
-
## Fix Loop
|
|
154
|
-
|
|
155
|
-
If verification fails:
|
|
156
|
-
1. Read contract and verification output to understand failures
|
|
157
|
-
2. Fix issues (Phase 2)
|
|
158
|
-
3. Re-verify (Phase 3)
|
|
159
|
-
4. Max 3 iterations
|
|
160
|
-
|
|
161
|
-
## Quick Start
|
|
162
|
-
|
|
163
|
-
**Simple change (≤3 files, well-understood):**
|
|
164
|
-
```
|
|
165
|
-
Phase 0: Skip (no ADR needed)
|
|
166
|
-
Phase 1: Quick contract → Phase 2: Code → Phase 3: Verify
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
**Complex change (new feature, architectural impact):**
|
|
170
|
-
```
|
|
171
|
-
Phase 0: ADR first → Phase 1: Full contract with user review
|
|
172
|
-
→ Phase 2: Code (frontend + backend parallel) → Phase 3: Verify
|
|
173
|
-
```
|
|
174
|
-
|
|
175
|
-
## Artifact Summary
|
|
176
|
-
|
|
177
|
-
| Artifact | Location | Persistent | Purpose |
|
|
178
|
-
|----------|----------|------------|---------|
|
|
179
|
-
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
180
|
-
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API contract |
|
|
181
|
-
| Code handoff | `.handoffs/dev-flow/code.md` | ❌ Temporary | Implementation notes |
|
|
182
|
-
| Verify report | `.handoffs/dev-flow/verify.md` | ❌ Temporary | Verification results |
|
|
183
|
-
|
|
184
|
-
## Related Skills
|
|
185
|
-
|
|
186
|
-
- `adr` — Architecture Decision Records (Phase 0)
|
|
187
|
-
- `test-gen` — Generate tests from acceptance criteria
|
|
188
|
-
- `pr-review` — Review code against the contract
|
|
1
|
+
---
|
|
2
|
+
name: dev-flow
|
|
3
|
+
description: |
|
|
4
|
+
Contract-first development workflow: contract → code → verify → fix (loop).
|
|
5
|
+
Drives development from persistent specifications, enabling parallel frontend/backend work.
|
|
6
|
+
Use PROACTIVELY when implementing features, fixing bugs, refactoring, or making code changes.
|
|
7
|
+
Triggers on: "implement", "feature", "fix bug", "refactor", "add", "change", "build"
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Development Flow
|
|
11
|
+
|
|
12
|
+
Contract-first development workflow. Writes persistent specifications before coding, so frontend and backend can work in parallel from the same contract.
|
|
13
|
+
|
|
14
|
+
## When to Use
|
|
15
|
+
|
|
16
|
+
- Implementing a new feature
|
|
17
|
+
- Fixing a bug
|
|
18
|
+
- Refactoring existing code
|
|
19
|
+
- Making any non-trivial code change
|
|
20
|
+
|
|
21
|
+
## Phase Overview
|
|
22
|
+
|
|
23
|
+
```
|
|
24
|
+
[Phase 0: Architecture — ADR (optional)]
|
|
25
|
+
│
|
|
26
|
+
v
|
|
27
|
+
Phase 1: Contract ──→ docs/specs/<feature>/ (persistent, committed)
|
|
28
|
+
│ Frontend & Backend can start in parallel
|
|
29
|
+
v
|
|
30
|
+
Phase 2: Code
|
|
31
|
+
│
|
|
32
|
+
v
|
|
33
|
+
Phase 3: Verify ──→ against acceptance criteria from Phase 1
|
|
34
|
+
│
|
|
35
|
+
v
|
|
36
|
+
[Fix loop] → back to Phase 2 (max 3 retries)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Phase 0: Architecture (Optional)
|
|
40
|
+
|
|
41
|
+
**When:** An architectural decision needs recording (tech choice, structural change, cross-team impact).
|
|
42
|
+
|
|
43
|
+
**Output:** `docs/adr/NNNN-title.md` — Architecture Decision Record
|
|
44
|
+
|
|
45
|
+
**Agent:** architect
|
|
46
|
+
|
|
47
|
+
See `skills/adr/SKILL.md` for ADR workflow and template.
|
|
48
|
+
|
|
49
|
+
→ Then proceed to Phase 1 with the ADR as architectural context.
|
|
50
|
+
|
|
51
|
+
## Phase 1: Contract
|
|
52
|
+
|
|
53
|
+
**Goal:** Produce a persistent specification that records consensus and enables parallel implementation.
|
|
54
|
+
|
|
55
|
+
**Output (persistent, committed to repo):**
|
|
56
|
+
```
|
|
57
|
+
docs/specs/<feature>/
|
|
58
|
+
├── README.md # Requirements, ACs, API contract, data model
|
|
59
|
+
├── api-spec.yaml # OpenAPI spec (if applicable)
|
|
60
|
+
└── data-model.md # Schema definitions (if applicable)
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Steps
|
|
64
|
+
1. **Analyze** — Read relevant files, existing ADRs, understand context
|
|
65
|
+
2. **Check ADRs** — Are there existing ADRs that constrain this feature? Reference them.
|
|
66
|
+
3. **Specify** — Write the contract document:
|
|
67
|
+
- Functional requirements (RFC 2119: MUST/SHOULD/MAY)
|
|
68
|
+
- Acceptance criteria (GIVEN/WHEN/THEN)
|
|
69
|
+
- API contract (endpoints, request/response schemas)
|
|
70
|
+
- Data model (entities, fields, types, constraints)
|
|
71
|
+
- Out of scope (explicit exclusions)
|
|
72
|
+
4. **Review** — Present contract to user for approval
|
|
73
|
+
|
|
74
|
+
### Contract Document Template
|
|
75
|
+
```markdown
|
|
76
|
+
# Feature: <title>
|
|
77
|
+
|
|
78
|
+
## Requirements
|
|
79
|
+
FR-1: System MUST <behavior>
|
|
80
|
+
|
|
81
|
+
## Acceptance Criteria
|
|
82
|
+
- GIVEN <context> WHEN <action> THEN <result>
|
|
83
|
+
|
|
84
|
+
## API Contract
|
|
85
|
+
POST /api/xxx
|
|
86
|
+
Request: { field: type }
|
|
87
|
+
Response: { field: type }
|
|
88
|
+
|
|
89
|
+
## Data Model
|
|
90
|
+
| Entity | Field | Type | Constraints |
|
|
91
|
+
|
|
92
|
+
## Out of Scope
|
|
93
|
+
- <explicit exclusions>
|
|
94
|
+
|
|
95
|
+
## Architecture
|
|
96
|
+
References: ADR-001, ADR-003
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
### Agent: spec-writer
|
|
100
|
+
- Tools: Read, Grep, Glob, Bash, Write, Edit
|
|
101
|
+
- Writes to `docs/specs/<feature>/`, NOT to `.handoffs/`
|
|
102
|
+
|
|
103
|
+
See `references/contract-phase.md` for detailed contract workflow.
|
|
104
|
+
|
|
105
|
+
## Phase 2: Code
|
|
106
|
+
|
|
107
|
+
**Goal:** Implement the contract. Frontend and backend can proceed independently.
|
|
108
|
+
|
|
109
|
+
### Steps
|
|
110
|
+
1. **Read contract** — Load `docs/specs/<feature>/README.md` and referenced ADRs
|
|
111
|
+
2. **Implement** — Write code following the contract and project conventions
|
|
112
|
+
3. **Self-review** — Verify code matches the contract before moving on
|
|
113
|
+
|
|
114
|
+
### Key Principle
|
|
115
|
+
The contract in `docs/specs/` is the source of truth. If implementation reveals
|
|
116
|
+
issues with the contract, update the contract first, then code.
|
|
117
|
+
|
|
118
|
+
### Handoff (`.handoffs/dev-flow/code.md`)
|
|
119
|
+
Lightweight — references contract rather than duplicating it:
|
|
120
|
+
- Files changed
|
|
121
|
+
- Deviations from contract (with rationale)
|
|
122
|
+
- Pending items
|
|
123
|
+
|
|
124
|
+
### Agent: executor
|
|
125
|
+
- Tools: Read, Write, Edit, Bash, Grep, Glob
|
|
126
|
+
- Full read/write access
|
|
127
|
+
|
|
128
|
+
See `references/code-phase.md` for detailed coding workflow.
|
|
129
|
+
|
|
130
|
+
## Phase 3: Verify
|
|
131
|
+
|
|
132
|
+
**Goal:** Verify implementation against the acceptance criteria from Phase 1.
|
|
133
|
+
|
|
134
|
+
### Steps
|
|
135
|
+
1. **Lint** — Run linter
|
|
136
|
+
2. **Typecheck** — Run type checker if applicable
|
|
137
|
+
3. **Test** — Run tests, verify acceptance criteria are met
|
|
138
|
+
4. **Build** — Verify project builds
|
|
139
|
+
|
|
140
|
+
If any step fails → enter fix loop (back to Phase 2).
|
|
141
|
+
|
|
142
|
+
### Handoff (`.handoffs/dev-flow/verify.md`)
|
|
143
|
+
- Lint/typecheck/test/build results
|
|
144
|
+
- Acceptance criteria pass/fail from contract
|
|
145
|
+
- Final verdict: pass / needs fix
|
|
146
|
+
|
|
147
|
+
### Agent: verifier
|
|
148
|
+
- Tools: Read, Grep, Glob, Bash
|
|
149
|
+
- Read-only + execute tests
|
|
150
|
+
|
|
151
|
+
See `references/verify-phase.md` for detailed verification workflow.
|
|
152
|
+
|
|
153
|
+
## Fix Loop
|
|
154
|
+
|
|
155
|
+
If verification fails:
|
|
156
|
+
1. Read contract and verification output to understand failures
|
|
157
|
+
2. Fix issues (Phase 2)
|
|
158
|
+
3. Re-verify (Phase 3)
|
|
159
|
+
4. Max 3 iterations
|
|
160
|
+
|
|
161
|
+
## Quick Start
|
|
162
|
+
|
|
163
|
+
**Simple change (≤3 files, well-understood):**
|
|
164
|
+
```
|
|
165
|
+
Phase 0: Skip (no ADR needed)
|
|
166
|
+
Phase 1: Quick contract → Phase 2: Code → Phase 3: Verify
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Complex change (new feature, architectural impact):**
|
|
170
|
+
```
|
|
171
|
+
Phase 0: ADR first → Phase 1: Full contract with user review
|
|
172
|
+
→ Phase 2: Code (frontend + backend parallel) → Phase 3: Verify
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
## Artifact Summary
|
|
176
|
+
|
|
177
|
+
| Artifact | Location | Persistent | Purpose |
|
|
178
|
+
|----------|----------|------------|---------|
|
|
179
|
+
| ADR | `docs/adr/NNNN-title.md` | ✅ Committed | Architecture decisions |
|
|
180
|
+
| Contract | `docs/specs/<feature>/` | ✅ Committed | Requirements, ACs, API contract |
|
|
181
|
+
| Code handoff | `.handoffs/dev-flow/code.md` | ❌ Temporary | Implementation notes |
|
|
182
|
+
| Verify report | `.handoffs/dev-flow/verify.md` | ❌ Temporary | Verification results |
|
|
183
|
+
|
|
184
|
+
## Related Skills
|
|
185
|
+
|
|
186
|
+
- `adr` — Architecture Decision Records (Phase 0)
|
|
187
|
+
- `test-gen` — Generate tests from acceptance criteria
|
|
188
|
+
- `pr-review` — Review code against the contract
|