my-opencode 1.3.4 → 2.0.0

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.
Files changed (46) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +299 -270
  3. package/agents/architect.md +30 -30
  4. package/agents/backend-dev.md +29 -0
  5. package/agents/business-analyst.md +30 -0
  6. package/agents/code-reviewer.md +29 -29
  7. package/agents/design-evidence.md +29 -0
  8. package/agents/frontend-dev.md +29 -0
  9. package/agents/system-designer.md +30 -0
  10. package/agents/team-lead.md +65 -60
  11. package/agents/tech-writer.md +30 -30
  12. package/agents/test-engineer.md +30 -30
  13. package/agents/verifier.md +38 -33
  14. package/bin/cli.js +366 -364
  15. package/bin/moc +198 -198
  16. package/opencode.json +218 -170
  17. package/package.json +53 -51
  18. package/plugins/README.md +67 -67
  19. package/plugins/provider-profile.mjs +203 -194
  20. package/scripts/postinstall.js +202 -202
  21. package/scripts/validate-role-flow.mjs +90 -0
  22. package/skills/adr/SKILL.md +91 -91
  23. package/skills/adr/references/templates.md +100 -100
  24. package/skills/adr/scripts/README.md +5 -5
  25. package/skills/design-evidence/SKILL.md +56 -0
  26. package/skills/dev-flow/SKILL.md +126 -188
  27. package/skills/dev-flow/references/code-phase.md +35 -72
  28. package/skills/dev-flow/references/contract-phase.md +66 -81
  29. package/skills/dev-flow/references/verify-phase.md +70 -129
  30. package/skills/dev-flow/scripts/README.md +3 -3
  31. package/skills/docs-gen/SKILL.md +162 -162
  32. package/skills/docs-gen/references/doc-styles.md +216 -216
  33. package/skills/docs-gen/scripts/README.md +5 -5
  34. package/skills/orchestrate/SKILL.md +63 -112
  35. package/skills/orchestrate/references/orchestration-patterns.md +49 -56
  36. package/skills/pr-review/SKILL.md +110 -110
  37. package/skills/pr-review/references/review-dimensions.md +117 -117
  38. package/skills/pr-review/references/security-checklist.md +122 -122
  39. package/skills/pr-review/scripts/README.md +5 -5
  40. package/skills/test-gen/SKILL.md +143 -143
  41. package/skills/test-gen/references/framework-detection.md +105 -105
  42. package/skills/test-gen/references/test-patterns.md +260 -260
  43. package/skills/test-gen/scripts/README.md +5 -5
  44. package/agents/executor.md +0 -30
  45. package/agents/fullstack-dev.md +0 -57
  46. package/agents/spec-writer.md +0 -37
@@ -1,260 +1,260 @@
1
- # Test Patterns — Language & Framework Specific
2
-
3
- ## TypeScript / JavaScript — Vitest
4
-
5
- ### Basic structure
6
- ```typescript
7
- import { describe, it, expect, beforeEach, vi } from 'vitest'
8
- import { userService } from './userService'
9
-
10
- describe('userService', () => {
11
- beforeEach(() => {
12
- vi.restoreAllMocks()
13
- })
14
-
15
- it('should create a user with valid data', async () => {
16
- const user = await userService.create({ name: 'Alice', email: 'alice@test.com' })
17
- expect(user).toMatchObject({ name: 'Alice' })
18
- expect(user.id).toBeDefined()
19
- })
20
-
21
- it('should reject duplicate emails', async () => {
22
- await userService.create({ name: 'Alice', email: 'dup@test.com' })
23
- await expect(userService.create({ name: 'Bob', email: 'dup@test.com' }))
24
- .rejects.toThrow('Email already exists')
25
- })
26
-
27
- it('should handle empty name', async () => {
28
- await expect(userService.create({ name: '', email: 'x@test.com' }))
29
- .rejects.toThrow('Name is required')
30
- })
31
- })
32
- ```
33
-
34
- ### Mocking external dependencies
35
- ```typescript
36
- import { describe, it, expect, vi } from 'vitest'
37
- import { sendEmail } from './emailService'
38
- import { emailClient } from './emailClient'
39
-
40
- vi.mock('./emailClient')
41
-
42
- it('should send welcome email', async () => {
43
- vi.mocked(emailClient.send).mockResolvedValue({ id: 'msg_123' })
44
- const result = await sendEmail('user@test.com', 'Welcome!')
45
- expect(result.success).toBe(true)
46
- expect(emailClient.send).toHaveBeenCalledWith(
47
- expect.objectContaining({ to: 'user@test.com' })
48
- )
49
- })
50
- ```
51
-
52
- ### Parametrized tests
53
- ```typescript
54
- it.each([
55
- { input: '', expected: false },
56
- { input: 'a@b', expected: true },
57
- { input: '@b.com', expected: false },
58
- ])('should validate email: $input', ({ input, expected }) => {
59
- expect(validateEmail(input)).toBe(expected)
60
- })
61
- ```
62
-
63
- ---
64
-
65
- ## TypeScript / JavaScript — Jest
66
-
67
- Same patterns as Vitest with these differences:
68
- - `jest.mock()` instead of `vi.mock()`
69
- - `jest.fn()` instead of `vi.fn()`
70
- - No built-in `it.each` (use `test.each` or `it.each` from `@jest/globals`)
71
-
72
- ```typescript
73
- jest.mock('./emailClient')
74
- jest.spyOn(console, 'error').mockImplementation(() => {})
75
- ```
76
-
77
- ---
78
-
79
- ## Python — Pytest
80
-
81
- ### Basic structure
82
- ```python
83
- import pytest
84
- from user_service import create_user
85
-
86
- def test_create_user_with_valid_data():
87
- user = create_user(name="Alice", email="alice@test.com")
88
- assert user.name == "Alice"
89
- assert user.id is not None
90
-
91
- def test_reject_duplicate_emails():
92
- create_user(name="Alice", email="dup@test.com")
93
- with pytest.raises(ValueError, match="Email already exists"):
94
- create_user(name="Bob", email="dup@test.com")
95
-
96
- def test_handle_empty_name():
97
- with pytest.raises(ValueError, match="Name is required"):
98
- create_user(name="", email="x@test.com")
99
- ```
100
-
101
- ### Fixtures
102
- ```python
103
- @pytest.fixture
104
- def db_session():
105
- session = create_test_session()
106
- yield session
107
- session.close()
108
-
109
- def test_user_query(db_session):
110
- users = db_session.query(User).all()
111
- assert len(users) > 0
112
- ```
113
-
114
- ### Parametrize
115
- ```python
116
- @pytest.mark.parametrize("email,expected", [
117
- ("", False),
118
- ("a@b", True),
119
- ("@b.com", False),
120
- ])
121
- def test_email_validation(email, expected):
122
- assert validate_email(email) == expected
123
- ```
124
-
125
- ### Mocking with mocker (pytest-mock)
126
- ```python
127
- def test_send_email(mocker):
128
- mock_client = mocker.patch("email_service.email_client.send")
129
- mock_client.return_value = {"id": "msg_123"}
130
- result = send_email("user@test.com", "Welcome!")
131
- assert result["success"] is True
132
- ```
133
-
134
- ---
135
-
136
- ## Python — unittest
137
-
138
- ```python
139
- import unittest
140
- from unittest.mock import patch
141
- from user_service import create_user
142
-
143
- class TestUserService(unittest.TestCase):
144
- def test_create_user_valid(self):
145
- user = create_user(name="Alice", email="alice@test.com")
146
- self.assertEqual(user.name, "Alice")
147
- self.assertIsNotNone(user.id)
148
-
149
- def test_reject_duplicate(self):
150
- create_user(name="Alice", email="dup@test.com")
151
- with self.assertRaises(ValueError):
152
- create_user(name="Bob", email="dup@test.com")
153
-
154
- @patch("email_service.email_client.send")
155
- def test_send_email(self, mock_send):
156
- mock_send.return_value = {"id": "msg_123"}
157
- result = send_email("user@test.com", "Welcome!")
158
- self.assertTrue(result["success"])
159
-
160
- if __name__ == "__main__":
161
- unittest.main()
162
- ```
163
-
164
- ---
165
-
166
- ## Rust
167
-
168
- ```rust
169
- #[cfg(test)]
170
- mod tests {
171
- use super::*;
172
-
173
- #[test]
174
- fn test_create_user_with_valid_data() {
175
- let user = User::new("Alice", "alice@test.com").unwrap();
176
- assert_eq!(user.name, "Alice");
177
- assert!(user.id.is_some());
178
- }
179
-
180
- #[test]
181
- fn test_reject_duplicate_emails() {
182
- User::new("Alice", "dup@test.com").unwrap();
183
- let result = User::new("Bob", "dup@test.com");
184
- assert!(result.is_err());
185
- assert_eq!(result.unwrap_err().to_string(), "Email already exists");
186
- }
187
-
188
- #[test]
189
- fn test_handle_empty_name() {
190
- let result = User::new("", "x@test.com");
191
- assert!(result.is_err());
192
- }
193
- }
194
- ```
195
-
196
- ---
197
-
198
- ## Go
199
-
200
- ```go
201
- package user
202
-
203
- import "testing"
204
-
205
- func TestCreateUser_ValidData(t *testing.T) {
206
- user, err := NewUser("Alice", "alice@test.com")
207
- if err != nil {
208
- t.Fatalf("unexpected error: %v", err)
209
- }
210
- if user.Name != "Alice" {
211
- t.Errorf("got name %q, want %q", user.Name, "Alice")
212
- }
213
- }
214
-
215
- func TestCreateUser_DuplicateEmail(t *testing.T) {
216
- NewUser("Alice", "dup@test.com")
217
- _, err := NewUser("Bob", "dup@test.com")
218
- if err == nil {
219
- t.Fatal("expected error for duplicate email")
220
- }
221
- }
222
-
223
- // Table-driven test
224
- func TestValidateEmail(t *testing.T) {
225
- tests := []struct {
226
- email string
227
- expected bool
228
- }{
229
- {"", false},
230
- {"a@b", true},
231
- {"@b.com", false},
232
- }
233
- for _, tc := range tests {
234
- got := ValidateEmail(tc.email)
235
- if got != tc.expected {
236
- t.Errorf("ValidateEmail(%q) = %v, want %v", tc.email, got, tc.expected)
237
- }
238
- }
239
- }
240
- ```
241
-
242
- ---
243
-
244
- ## Test Structure Decision Tree
245
-
246
- ```
247
- What kind of code?
248
- ├── Pure function / utility
249
- │ └── Unit test — test input/output pairs, edge cases
250
- ├── Service / business logic
251
- │ └── Unit test — mock external dependencies, test logic
252
- ├── API endpoint
253
- │ └── Integration test — hit the endpoint, check response
254
- ├── Database query
255
- │ └── Integration test — use test DB or in-memory DB
256
- ├── CLI command
257
- │ └── Integration test — invoke CLI, check output
258
- └── UI component
259
- └── Component test — render, interact, assert
260
- ```
1
+ # Test Patterns — Language & Framework Specific
2
+
3
+ ## TypeScript / JavaScript — Vitest
4
+
5
+ ### Basic structure
6
+ ```typescript
7
+ import { describe, it, expect, beforeEach, vi } from 'vitest'
8
+ import { userService } from './userService'
9
+
10
+ describe('userService', () => {
11
+ beforeEach(() => {
12
+ vi.restoreAllMocks()
13
+ })
14
+
15
+ it('should create a user with valid data', async () => {
16
+ const user = await userService.create({ name: 'Alice', email: 'alice@test.com' })
17
+ expect(user).toMatchObject({ name: 'Alice' })
18
+ expect(user.id).toBeDefined()
19
+ })
20
+
21
+ it('should reject duplicate emails', async () => {
22
+ await userService.create({ name: 'Alice', email: 'dup@test.com' })
23
+ await expect(userService.create({ name: 'Bob', email: 'dup@test.com' }))
24
+ .rejects.toThrow('Email already exists')
25
+ })
26
+
27
+ it('should handle empty name', async () => {
28
+ await expect(userService.create({ name: '', email: 'x@test.com' }))
29
+ .rejects.toThrow('Name is required')
30
+ })
31
+ })
32
+ ```
33
+
34
+ ### Mocking external dependencies
35
+ ```typescript
36
+ import { describe, it, expect, vi } from 'vitest'
37
+ import { sendEmail } from './emailService'
38
+ import { emailClient } from './emailClient'
39
+
40
+ vi.mock('./emailClient')
41
+
42
+ it('should send welcome email', async () => {
43
+ vi.mocked(emailClient.send).mockResolvedValue({ id: 'msg_123' })
44
+ const result = await sendEmail('user@test.com', 'Welcome!')
45
+ expect(result.success).toBe(true)
46
+ expect(emailClient.send).toHaveBeenCalledWith(
47
+ expect.objectContaining({ to: 'user@test.com' })
48
+ )
49
+ })
50
+ ```
51
+
52
+ ### Parametrized tests
53
+ ```typescript
54
+ it.each([
55
+ { input: '', expected: false },
56
+ { input: 'a@b', expected: true },
57
+ { input: '@b.com', expected: false },
58
+ ])('should validate email: $input', ({ input, expected }) => {
59
+ expect(validateEmail(input)).toBe(expected)
60
+ })
61
+ ```
62
+
63
+ ---
64
+
65
+ ## TypeScript / JavaScript — Jest
66
+
67
+ Same patterns as Vitest with these differences:
68
+ - `jest.mock()` instead of `vi.mock()`
69
+ - `jest.fn()` instead of `vi.fn()`
70
+ - No built-in `it.each` (use `test.each` or `it.each` from `@jest/globals`)
71
+
72
+ ```typescript
73
+ jest.mock('./emailClient')
74
+ jest.spyOn(console, 'error').mockImplementation(() => {})
75
+ ```
76
+
77
+ ---
78
+
79
+ ## Python — Pytest
80
+
81
+ ### Basic structure
82
+ ```python
83
+ import pytest
84
+ from user_service import create_user
85
+
86
+ def test_create_user_with_valid_data():
87
+ user = create_user(name="Alice", email="alice@test.com")
88
+ assert user.name == "Alice"
89
+ assert user.id is not None
90
+
91
+ def test_reject_duplicate_emails():
92
+ create_user(name="Alice", email="dup@test.com")
93
+ with pytest.raises(ValueError, match="Email already exists"):
94
+ create_user(name="Bob", email="dup@test.com")
95
+
96
+ def test_handle_empty_name():
97
+ with pytest.raises(ValueError, match="Name is required"):
98
+ create_user(name="", email="x@test.com")
99
+ ```
100
+
101
+ ### Fixtures
102
+ ```python
103
+ @pytest.fixture
104
+ def db_session():
105
+ session = create_test_session()
106
+ yield session
107
+ session.close()
108
+
109
+ def test_user_query(db_session):
110
+ users = db_session.query(User).all()
111
+ assert len(users) > 0
112
+ ```
113
+
114
+ ### Parametrize
115
+ ```python
116
+ @pytest.mark.parametrize("email,expected", [
117
+ ("", False),
118
+ ("a@b", True),
119
+ ("@b.com", False),
120
+ ])
121
+ def test_email_validation(email, expected):
122
+ assert validate_email(email) == expected
123
+ ```
124
+
125
+ ### Mocking with mocker (pytest-mock)
126
+ ```python
127
+ def test_send_email(mocker):
128
+ mock_client = mocker.patch("email_service.email_client.send")
129
+ mock_client.return_value = {"id": "msg_123"}
130
+ result = send_email("user@test.com", "Welcome!")
131
+ assert result["success"] is True
132
+ ```
133
+
134
+ ---
135
+
136
+ ## Python — unittest
137
+
138
+ ```python
139
+ import unittest
140
+ from unittest.mock import patch
141
+ from user_service import create_user
142
+
143
+ class TestUserService(unittest.TestCase):
144
+ def test_create_user_valid(self):
145
+ user = create_user(name="Alice", email="alice@test.com")
146
+ self.assertEqual(user.name, "Alice")
147
+ self.assertIsNotNone(user.id)
148
+
149
+ def test_reject_duplicate(self):
150
+ create_user(name="Alice", email="dup@test.com")
151
+ with self.assertRaises(ValueError):
152
+ create_user(name="Bob", email="dup@test.com")
153
+
154
+ @patch("email_service.email_client.send")
155
+ def test_send_email(self, mock_send):
156
+ mock_send.return_value = {"id": "msg_123"}
157
+ result = send_email("user@test.com", "Welcome!")
158
+ self.assertTrue(result["success"])
159
+
160
+ if __name__ == "__main__":
161
+ unittest.main()
162
+ ```
163
+
164
+ ---
165
+
166
+ ## Rust
167
+
168
+ ```rust
169
+ #[cfg(test)]
170
+ mod tests {
171
+ use super::*;
172
+
173
+ #[test]
174
+ fn test_create_user_with_valid_data() {
175
+ let user = User::new("Alice", "alice@test.com").unwrap();
176
+ assert_eq!(user.name, "Alice");
177
+ assert!(user.id.is_some());
178
+ }
179
+
180
+ #[test]
181
+ fn test_reject_duplicate_emails() {
182
+ User::new("Alice", "dup@test.com").unwrap();
183
+ let result = User::new("Bob", "dup@test.com");
184
+ assert!(result.is_err());
185
+ assert_eq!(result.unwrap_err().to_string(), "Email already exists");
186
+ }
187
+
188
+ #[test]
189
+ fn test_handle_empty_name() {
190
+ let result = User::new("", "x@test.com");
191
+ assert!(result.is_err());
192
+ }
193
+ }
194
+ ```
195
+
196
+ ---
197
+
198
+ ## Go
199
+
200
+ ```go
201
+ package user
202
+
203
+ import "testing"
204
+
205
+ func TestCreateUser_ValidData(t *testing.T) {
206
+ user, err := NewUser("Alice", "alice@test.com")
207
+ if err != nil {
208
+ t.Fatalf("unexpected error: %v", err)
209
+ }
210
+ if user.Name != "Alice" {
211
+ t.Errorf("got name %q, want %q", user.Name, "Alice")
212
+ }
213
+ }
214
+
215
+ func TestCreateUser_DuplicateEmail(t *testing.T) {
216
+ NewUser("Alice", "dup@test.com")
217
+ _, err := NewUser("Bob", "dup@test.com")
218
+ if err == nil {
219
+ t.Fatal("expected error for duplicate email")
220
+ }
221
+ }
222
+
223
+ // Table-driven test
224
+ func TestValidateEmail(t *testing.T) {
225
+ tests := []struct {
226
+ email string
227
+ expected bool
228
+ }{
229
+ {"", false},
230
+ {"a@b", true},
231
+ {"@b.com", false},
232
+ }
233
+ for _, tc := range tests {
234
+ got := ValidateEmail(tc.email)
235
+ if got != tc.expected {
236
+ t.Errorf("ValidateEmail(%q) = %v, want %v", tc.email, got, tc.expected)
237
+ }
238
+ }
239
+ }
240
+ ```
241
+
242
+ ---
243
+
244
+ ## Test Structure Decision Tree
245
+
246
+ ```
247
+ What kind of code?
248
+ ├── Pure function / utility
249
+ │ └── Unit test — test input/output pairs, edge cases
250
+ ├── Service / business logic
251
+ │ └── Unit test — mock external dependencies, test logic
252
+ ├── API endpoint
253
+ │ └── Integration test — hit the endpoint, check response
254
+ ├── Database query
255
+ │ └── Integration test — use test DB or in-memory DB
256
+ ├── CLI command
257
+ │ └── Integration test — invoke CLI, check output
258
+ └── UI component
259
+ └── Component test — render, interact, assert
260
+ ```
@@ -1,5 +1,5 @@
1
- # test-gen Scripts
2
-
3
- Placeholder for test generation utility scripts. Future candidates:
4
- - `detect-framework.py` — Detect project test framework from config files
5
- - `analyze-coverage.py` — Parse coverage report for untested areas
1
+ # test-gen Scripts
2
+
3
+ Placeholder for test generation utility scripts. Future candidates:
4
+ - `detect-framework.py` — Detect project test framework from config files
5
+ - `analyze-coverage.py` — Parse coverage report for untested areas
@@ -1,30 +0,0 @@
1
- ---
2
- name: executor
3
- description: Implement code changes following an approved contract. Use PROACTIVELY when a contract is ready and code needs to be written.
4
- tools: { read: true, write: true, edit: true, bash: true, grep: true, glob: true }
5
- color: success
6
- ---
7
-
8
- You are a focused coding executor. Your role is to implement changes according to an approved contract specification, following project conventions.
9
-
10
- ## Core Responsibilities
11
- - Read the contract from `docs/specs/<feature>/README.md`
12
- - Check referenced ADRs in `docs/adr/` for architectural constraints
13
- - Implement changes file by file
14
- - Follow project code style and conventions
15
- - Self-review before moving to verification
16
- - If the contract needs updating during implementation, update the contract first, then code
17
-
18
- ## Approach
19
- 1. Read the contract at `docs/specs/<feature>/README.md`
20
- 2. Read current files before modifying them
21
- 3. Implement changes step by step
22
- 4. After each file, verify the change is coherent
23
- 5. Write code handoff to `.handoffs/dev-flow/code.md`
24
- 6. Proceed to verification phase
25
-
26
- ## Key Principles
27
- - Read before write: always read a file before editing it
28
- - Follow conventions: match existing code style, naming, patterns
29
- - Self-review checklist: no dead code, no debug logs, error handling in place
30
- - Contract first: if implementation reveals issues with the contract, update `docs/specs/` before modifying code
@@ -1,57 +0,0 @@
1
- ---
2
- name: fullstack-dev
3
- description: Full-stack development agent that orchestrates contract-first development workflow. Use PROACTIVELY when the user says "implement", "build", "add feature", "fix bug", "refactor".
4
- tools: { read: true, write: true, edit: true, bash: true, grep: true, glob: true }
5
- color: primary
6
- ---
7
-
8
- You are a full-stack development agent. You orchestrate the contract-first development workflow using the dev-flow skill.
9
-
10
- ## Core Workflow
11
-
12
- ```
13
- User Request → [ADR] → Contract (persistent spec) → Code → Verify → Done
14
- ```
15
-
16
- ## Phases
17
-
18
- ### Phase 0: Architecture (Optional)
19
- If the feature requires an architectural decision:
20
- - Delegate to **architect** subagent via Task tool with `subagent_type: "architect"`
21
- - ADR is written to `docs/adr/NNNN-title.md`
22
-
23
- ### Phase 1: Contract
24
- 1. Delegate to **spec-writer** via Task tool with `subagent_type: "spec-writer"`
25
- 2. Read the resulting `docs/specs/<feature>/README.md`
26
- 3. **回報 contract 摘要給使用者**,包含:
27
- - 需求摘要與 Acceptance Criteria
28
- - API 變動(endpoints、請求/回應結構)
29
- - 資料模型變動
30
- - 受影響的檔案清單
31
- 4. **🛑 必須等待使用者明確確認(輸入 "go"、"proceed"、"繼續" 等)才能進入 Phase 2**
32
- 5. 如果使用者要求修改 → 更新 contract 後重新呈現再等確認
33
- 6. 只有在使用者說 go 之後,才能進入 Phase 2
34
-
35
- ### Phase 2: Code
36
- Delegate to the **executor** subagent:
37
- - Launch via Task tool with `subagent_type: "executor"`
38
- - Reference the contract in `docs/specs/<feature>/README.md`
39
- - After completion, read `.handoffs/dev-flow/code.md`
40
-
41
- ### Phase 3: Verify
42
- Delegate to the **verifier** subagent:
43
- - Launch via Task tool with `subagent_type: "verifier"`
44
- - Reference the contract for acceptance criteria
45
- - Read `.handoffs/dev-flow/verify.md`
46
- - If verification fails, delegate to executor for fix, then re-verify
47
- - Max 3 fix attempts
48
-
49
- ## Key Difference from Old Flow
50
- The contract in `docs/specs/` is the persistent source of truth.
51
- Handoffs in `.handoffs/` are temporary references to the contract, not full copies.
52
- If the contract needs updating during Code phase, update `docs/specs/<feature>/` first.
53
-
54
- ## When to Use This Flow
55
- - **Simple change (≤3 files, well-understood):** Quick contract → Code → Verify
56
- - **Complex change (new feature, large refactor):** Full contract with user review → Code → Verify
57
- - **Architecture-impacting change:** ADR → Contract → Code → Verify
@@ -1,37 +0,0 @@
1
- ---
2
- name: spec-writer
3
- description: Analyze requirements, explore codebase, and produce a contract specification. Use PROACTIVELY when a feature request needs structured specification before coding.
4
- tools: { read: true, grep: true, glob: true, bash: true, write: true, edit: true }
5
- color: info
6
- ---
7
-
8
- You are a specification architect. Your role is to analyze requirements and produce **contract documents** that serve as persistent, single-source-of-truth for implementation.
9
-
10
- ## Core Responsibilities
11
- - Analyze user requirements and break into logical specifications
12
- - Check existing ADRs in `docs/adr/` for architectural constraints
13
- - Explore the codebase to understand current state and find relevant code
14
- - Produce a structured contract document with requirements, ACs, API contract, and data model
15
- - Write everything to `docs/specs/<feature>/`
16
-
17
- ## Approach
18
- 1. Read and understand the user's request
19
- 2. Check `docs/adr/` for relevant architecture decisions — reference them in the contract
20
- 3. Ask clarifying questions if needed (one at a time)
21
- 4. Explore the codebase (read relevant files, grep for patterns)
22
- 5. Write contract to `docs/specs/<feature>/README.md`
23
- 6. Present the contract document for user approval
24
-
25
- ## Contract Document Sections
26
- - Requirements (RFC 2119: MUST/SHOULD/MAY)
27
- - Acceptance Criteria (GIVEN/WHEN/THEN)
28
- - API Contract (endpoints, request/response)
29
- - Data Model (entities, fields, types)
30
- - Out of Scope (explicit exclusions)
31
- - Architecture References (linked ADRs)
32
-
33
- ## Constraints
34
- - Write contracts to `docs/specs/`, NOT `.handoffs/`
35
- - Be specific: use concrete types, endpoint paths, field names
36
- - If requirements are ambiguous, ask one question per turn
37
- - Reference ADRs by number (e.g., `ADR-001: Use PostgreSQL`)