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.
- package/LICENSE +21 -21
- package/README.md +299 -270
- package/agents/architect.md +30 -30
- package/agents/backend-dev.md +29 -0
- package/agents/business-analyst.md +30 -0
- package/agents/code-reviewer.md +29 -29
- package/agents/design-evidence.md +29 -0
- package/agents/frontend-dev.md +29 -0
- package/agents/system-designer.md +30 -0
- package/agents/team-lead.md +65 -60
- package/agents/tech-writer.md +30 -30
- package/agents/test-engineer.md +30 -30
- package/agents/verifier.md +38 -33
- package/bin/cli.js +366 -364
- package/bin/moc +198 -198
- package/opencode.json +218 -170
- package/package.json +53 -51
- package/plugins/README.md +67 -67
- package/plugins/provider-profile.mjs +203 -194
- package/scripts/postinstall.js +202 -202
- package/scripts/validate-role-flow.mjs +90 -0
- 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/design-evidence/SKILL.md +56 -0
- package/skills/dev-flow/SKILL.md +126 -188
- package/skills/dev-flow/references/code-phase.md +35 -72
- package/skills/dev-flow/references/contract-phase.md +66 -81
- package/skills/dev-flow/references/verify-phase.md +70 -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 +63 -112
- package/skills/orchestrate/references/orchestration-patterns.md +49 -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
- package/agents/executor.md +0 -30
- package/agents/fullstack-dev.md +0 -57
- package/agents/spec-writer.md +0 -37
package/skills/dev-flow/SKILL.md
CHANGED
|
@@ -1,188 +1,126 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: dev-flow
|
|
3
|
-
description: |
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
-
|
|
121
|
-
-
|
|
122
|
-
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
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
|
+
Evidence-first development workflow: design evidence → business requirements → technical design → role contracts → sliced code → review → verify.
|
|
5
|
+
Use PROACTIVELY when implementing features, fixing bugs, refactoring, or making code changes.
|
|
6
|
+
Triggers on: "implement", "feature", "fix bug", "refactor", "add", "change", "build", "Figma", "screenshot"
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# Evidence-First Development Flow
|
|
10
|
+
|
|
11
|
+
The persistent feature artifact is the source of truth. Visual input becomes evidence first; business and technical decisions are made in separate layers; implementation is split into reviewable slices.
|
|
12
|
+
|
|
13
|
+
## Phase Overview
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
Feature Intake
|
|
17
|
+
│
|
|
18
|
+
▼
|
|
19
|
+
Design Evidence ──► Business Requirements (SA) ──► Technical Design (SD)
|
|
20
|
+
│
|
|
21
|
+
▼
|
|
22
|
+
Frontend / Backend Contracts
|
|
23
|
+
│
|
|
24
|
+
▼
|
|
25
|
+
Sliced Implementation + Review + Tests
|
|
26
|
+
│
|
|
27
|
+
▼
|
|
28
|
+
QA / Verification + Fix Loop
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Phase 0: Architecture (Optional)
|
|
32
|
+
|
|
33
|
+
Use `architect` before technical design when a choice has long-term impact, meaningful alternatives, or cross-team consequences. Record the decision in `docs/adr/` and reference it from the feature artifacts.
|
|
34
|
+
|
|
35
|
+
## Phase 1: Feature Intake and Design Evidence
|
|
36
|
+
|
|
37
|
+
When a feature has Figma, screenshot, wireframe, prototype, or other UI/UX input:
|
|
38
|
+
|
|
39
|
+
1. Delegate to `design-evidence`.
|
|
40
|
+
2. Create `docs/specs/<feature>/README.md` with feature ID, source/version, viewport, approval status, scope, owner, and status.
|
|
41
|
+
3. Create `evidence-pack.md` with stable `EVID-*` entries.
|
|
42
|
+
4. Separate `observed`, `inferred`, and `unknown`; attach source and confidence to every entry.
|
|
43
|
+
5. Mark screenshot-only or wireframe-only input as `prototype`.
|
|
44
|
+
|
|
45
|
+
For features without design input, record `Design Evidence: not applicable` and explain why.
|
|
46
|
+
|
|
47
|
+
## Phase 2: Business Requirements (SA)
|
|
48
|
+
|
|
49
|
+
Delegate to `business-analyst` after the evidence pack is complete. Write `business-requirements.md` containing:
|
|
50
|
+
|
|
51
|
+
- Problem, goal, actor, user role, use case, scope, and out of scope.
|
|
52
|
+
- `BR-*` business requirements and `BUS-*` business rules.
|
|
53
|
+
- Business states, transitions, preconditions, negative paths, and duplicate/retry behavior.
|
|
54
|
+
- Business data dictionary and sensitivity.
|
|
55
|
+
- `AC-*` acceptance intent.
|
|
56
|
+
|
|
57
|
+
Every business item MUST reference relevant `EVID-*` IDs. SA defines what the system must do; it does not choose API paths or database structures.
|
|
58
|
+
|
|
59
|
+
## Phase 3: Technical Design (SD)
|
|
60
|
+
|
|
61
|
+
Delegate to `system-designer` after business requirements are approved. Write:
|
|
62
|
+
|
|
63
|
+
- `technical-design.md`: boundaries, API operations, schemas, errors, auth, authorization, data, query, performance, audit, observability, migration, rollback, and compatibility.
|
|
64
|
+
- `frontend-contract.md`: routes, components, client state, API mapping, UI states, responsive behavior, accessibility, and visual acceptance.
|
|
65
|
+
- `backend-contract.md`: operations, validation, domain logic, persistence, query, authorization, integrations, observability, and test requirements.
|
|
66
|
+
|
|
67
|
+
Assign `API-*`, `DATA-*`, `NFR-*`, and `VER-*` IDs. Technical design MUST preserve SA business semantics and reference upstream IDs.
|
|
68
|
+
|
|
69
|
+
## Phase 4: Sliced Implementation
|
|
70
|
+
|
|
71
|
+
The `team-lead` splits work by screen, component, service, or upstream group. Every slice has:
|
|
72
|
+
|
|
73
|
+
- One owner (`frontend-dev` or `backend-dev`)
|
|
74
|
+
- One reviewer (`code-reviewer` or designated domain reviewer)
|
|
75
|
+
- Requirement, API/data, and verification IDs
|
|
76
|
+
- A bounded file and behavior scope
|
|
77
|
+
|
|
78
|
+
Frontend and backend slices may run in parallel after their contracts are ready. If implementation changes business semantics, API shape, or technical constraints, update the correct persistent artifact before changing code.
|
|
79
|
+
|
|
80
|
+
Use `test-engineer` to generate missing unit, integration, contract, UI, permission, and performance tests.
|
|
81
|
+
|
|
82
|
+
## Phase 5: Review and Verification
|
|
83
|
+
|
|
84
|
+
Run `code-reviewer` per slice, then `verifier` as the independent QA owner. Verification covers:
|
|
85
|
+
|
|
86
|
+
1. Business: use cases, rules, states, and acceptance intent.
|
|
87
|
+
2. Visual/Interaction: approved design, states, responsive behavior, keyboard/focus, and accessibility.
|
|
88
|
+
3. API/Data: schemas, error behavior, persistence, query patterns, and contract tests.
|
|
89
|
+
4. Security/Operations: authorization, scope, audit, performance, observability, and rollback.
|
|
90
|
+
5. Lint, typecheck, tests, and build.
|
|
91
|
+
|
|
92
|
+
The verifier returns `VER-*` results and blocked mappings. `team-lead` persists the final verification report in the feature artifact.
|
|
93
|
+
|
|
94
|
+
## Traceability Gate
|
|
95
|
+
|
|
96
|
+
Maintain `traceability.md` with at least:
|
|
97
|
+
|
|
98
|
+
```text
|
|
99
|
+
UI action → EVID-* → BR-* / BUS-* → API-* / DATA-* → AC-* / VER-*
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
An unmapped UI action, requirement, API, or verification item is a specification gap, not a reason to guess.
|
|
103
|
+
|
|
104
|
+
## Fix Loop
|
|
105
|
+
|
|
106
|
+
If review or verification fails:
|
|
107
|
+
|
|
108
|
+
1. Identify the failing ID and owning layer.
|
|
109
|
+
2. Update the relevant artifact when the contract is wrong.
|
|
110
|
+
3. Fix the implementation in a bounded slice.
|
|
111
|
+
4. Re-run review and verification.
|
|
112
|
+
|
|
113
|
+
Allow at most three fix attempts before reporting the blocker.
|
|
114
|
+
|
|
115
|
+
## Artifact Summary
|
|
116
|
+
|
|
117
|
+
| Artifact | Location | Owner | Persistence |
|
|
118
|
+
|---|---|---|---|
|
|
119
|
+
| Feature intake | `docs/specs/<feature>/README.md` | team-lead | committed |
|
|
120
|
+
| Design evidence | `docs/specs/<feature>/evidence-pack.md` | design-evidence | committed |
|
|
121
|
+
| Business requirements | `docs/specs/<feature>/business-requirements.md` | business-analyst | committed |
|
|
122
|
+
| Technical design | `docs/specs/<feature>/technical-design.md` | system-designer | committed |
|
|
123
|
+
| Role contracts | `docs/specs/<feature>/frontend-contract.md`, `backend-contract.md` | system-designer | committed |
|
|
124
|
+
| Traceability | `docs/specs/<feature>/traceability.md` | team-lead | committed |
|
|
125
|
+
| Verification report | `docs/specs/<feature>/verification-report.md` | team-lead | committed |
|
|
126
|
+
| Session handoff | `.handoffs/` | current agent | temporary |
|
|
@@ -1,72 +1,35 @@
|
|
|
1
|
-
# Code Phase
|
|
2
|
-
|
|
3
|
-
## Entry Conditions
|
|
4
|
-
|
|
5
|
-
-
|
|
6
|
-
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
- [ ]
|
|
32
|
-
- [ ]
|
|
33
|
-
- [ ]
|
|
34
|
-
- [ ]
|
|
35
|
-
- [ ] No secrets or
|
|
36
|
-
- [ ] Changes follow project conventions
|
|
37
|
-
|
|
38
|
-
### 6. Output Handoff
|
|
39
|
-
|
|
40
|
-
Write to `.handoffs/dev-flow/code.md`:
|
|
41
|
-
|
|
42
|
-
```markdown
|
|
43
|
-
# Code Changes: <title>
|
|
44
|
-
|
|
45
|
-
## Summary
|
|
46
|
-
<overview of what was changed>
|
|
47
|
-
|
|
48
|
-
## Files Changed
|
|
49
|
-
| File | Action | Description |
|
|
50
|
-
|------|--------|-------------|
|
|
51
|
-
| src/foo.ts | Modified | Added feature logic |
|
|
52
|
-
|
|
53
|
-
## Deviations from Plan
|
|
54
|
-
- <any changes from the original plan, with rationale>
|
|
55
|
-
|
|
56
|
-
## Pending Items
|
|
57
|
-
- <things that need attention before completion>
|
|
58
|
-
|
|
59
|
-
## Self-Review Checklist
|
|
60
|
-
- [ ] All changes tested locally
|
|
61
|
-
- [ ] No regressions introduced
|
|
62
|
-
- [ ] Code follows project conventions
|
|
63
|
-
```
|
|
64
|
-
|
|
65
|
-
## Anti-Patterns
|
|
66
|
-
|
|
67
|
-
- ❌ Modifying files without reading them first
|
|
68
|
-
- ❌ Copy-pasting code without understanding
|
|
69
|
-
- ❌ Leaving debug code, console.log, TODO comments
|
|
70
|
-
- ❌ Ignoring error handling
|
|
71
|
-
- ❌ Making unrelated changes
|
|
72
|
-
- ❌ Skipping the plan handoff read
|
|
1
|
+
# Sliced Code Phase
|
|
2
|
+
|
|
3
|
+
## Entry Conditions
|
|
4
|
+
|
|
5
|
+
- The feature artifacts exist under `docs/specs/<feature>/`.
|
|
6
|
+
- The relevant frontend or backend contract has been reviewed and approved.
|
|
7
|
+
- The slice has an owner, reviewer, bounded scope, and stable traceability IDs.
|
|
8
|
+
|
|
9
|
+
## Process
|
|
10
|
+
|
|
11
|
+
1. Read the feature intake, evidence pack, business requirements, technical design, and role contract.
|
|
12
|
+
2. Confirm the slice's `EVID-*`, `BR-*`, `API-*`, `DATA-*`, `AC-*`, and `VER-*` IDs.
|
|
13
|
+
3. Read every file before modifying it and follow existing project conventions.
|
|
14
|
+
4. Implement only the assigned screen, component, service, or upstream slice.
|
|
15
|
+
5. Add or update tests required by the contract.
|
|
16
|
+
6. Self-review for behavior, security, error paths, accessibility, and traceability.
|
|
17
|
+
7. Write a lightweight handoff to `.handoffs/dev-flow/code.md` with files, IDs, deviations, and pending items.
|
|
18
|
+
|
|
19
|
+
## Contract Change Rule
|
|
20
|
+
|
|
21
|
+
If implementation reveals that business semantics, API shape, data constraints, or non-functional requirements are wrong:
|
|
22
|
+
|
|
23
|
+
1. Stop the code change.
|
|
24
|
+
2. Update the owning persistent artifact.
|
|
25
|
+
3. Re-review the affected downstream contract.
|
|
26
|
+
4. Resume implementation only after the IDs and scope are consistent.
|
|
27
|
+
|
|
28
|
+
## Self-Review Checklist
|
|
29
|
+
|
|
30
|
+
- [ ] Slice matches the approved contract.
|
|
31
|
+
- [ ] No business or technical guesses were added from visual layout.
|
|
32
|
+
- [ ] Loading, empty, error, permission, retry, and duplicate paths are covered where applicable.
|
|
33
|
+
- [ ] Frontend accessibility/visual requirements or backend authorization/data requirements are covered.
|
|
34
|
+
- [ ] Tests and traceability IDs are reported.
|
|
35
|
+
- [ ] No debug code, secrets, or unrelated changes remain.
|
|
@@ -1,81 +1,66 @@
|
|
|
1
|
-
# Contract Phase
|
|
2
|
-
|
|
3
|
-
The
|
|
4
|
-
|
|
5
|
-
## Entry Conditions
|
|
6
|
-
|
|
7
|
-
- User request received
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
|
|
11
|
-
##
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
-
|
|
20
|
-
-
|
|
21
|
-
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
##
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
-
|
|
56
|
-
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|--------|-------------------|--------------------------|
|
|
68
|
-
| Location | `.handoffs/dev-flow/plan.md` | `docs/specs/<feature>/README.md` |
|
|
69
|
-
| Persistence | Temporary (gitignored) | Committed to repo |
|
|
70
|
-
| Audience | Next phase only | All current and future developers |
|
|
71
|
-
| Granularity | Implementation steps | Requirements + ACs + API |
|
|
72
|
-
| Parallel work | Not supported | Frontend/backend can work in parallel |
|
|
73
|
-
| ADR integration | None | Explicit reference |
|
|
74
|
-
|
|
75
|
-
## Anti-Patterns
|
|
76
|
-
|
|
77
|
-
- ❌ Writing contracts in `.handoffs/` instead of `docs/specs/`
|
|
78
|
-
- ❌ Over-specifying implementation details (that's for Code phase)
|
|
79
|
-
- ❌ Ignoring existing ADRs
|
|
80
|
-
- ❌ Writing contracts in a different doc per code phase (update the single contract)
|
|
81
|
-
- ❌ Skipping user review for complex features
|
|
1
|
+
# Layered Contract Phase
|
|
2
|
+
|
|
3
|
+
The contract phase produces persistent, committed artifacts. It does not use a temporary plan as the source of truth.
|
|
4
|
+
|
|
5
|
+
## Entry Conditions
|
|
6
|
+
|
|
7
|
+
- User request received.
|
|
8
|
+
- Relevant ADRs have been checked.
|
|
9
|
+
- Feature ID, source/version, owner, and scope are known or explicitly marked unknown.
|
|
10
|
+
|
|
11
|
+
## Artifact Set
|
|
12
|
+
|
|
13
|
+
Create `docs/specs/<feature>/` with:
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
README.md
|
|
17
|
+
evidence-pack.md
|
|
18
|
+
business-requirements.md
|
|
19
|
+
technical-design.md
|
|
20
|
+
frontend-contract.md
|
|
21
|
+
backend-contract.md
|
|
22
|
+
traceability.md
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Create `verification-report.md` at delivery time.
|
|
26
|
+
|
|
27
|
+
## Layer Rules
|
|
28
|
+
|
|
29
|
+
### Intake and Evidence
|
|
30
|
+
|
|
31
|
+
`README.md` records source type, source version, viewport, approval/prototype status, owner, scope, and out-of-scope items. `evidence-pack.md` contains stable `EVID-*` records with source, type, confidence, and separate observed/inferred/unknown fields.
|
|
32
|
+
|
|
33
|
+
### Business Requirements
|
|
34
|
+
|
|
35
|
+
`business-requirements.md` is owned by `business-analyst` and contains actors, goals, use cases, business rules, business states, business data meaning, and `AC-*` acceptance intent. Every item links to `EVID-*`.
|
|
36
|
+
|
|
37
|
+
### Technical Design
|
|
38
|
+
|
|
39
|
+
`technical-design.md` is owned by `system-designer` and contains boundaries, API, data, authorization, errors, performance, audit, observability, migration, rollback, and compatibility. It assigns `API-*`, `DATA-*`, and `NFR-*` IDs.
|
|
40
|
+
|
|
41
|
+
The same technical design produces `frontend-contract.md` and `backend-contract.md`; these are role views, not independent interpretations of the evidence.
|
|
42
|
+
|
|
43
|
+
### Traceability
|
|
44
|
+
|
|
45
|
+
`traceability.md` links at minimum:
|
|
46
|
+
|
|
47
|
+
```text
|
|
48
|
+
UI action → EVID-* → BR-* / BUS-* → API-* / DATA-* → AC-* / VER-*
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
## Review Gate
|
|
52
|
+
|
|
53
|
+
Before implementation, confirm:
|
|
54
|
+
|
|
55
|
+
- Evidence sources and confidence are recorded.
|
|
56
|
+
- Observations, inferences, and unknowns are separated.
|
|
57
|
+
- Business semantics are approved before API/data choices.
|
|
58
|
+
- Frontend and backend contracts reference the technical design.
|
|
59
|
+
- Every implementation slice has owner, reviewer, and stable IDs.
|
|
60
|
+
|
|
61
|
+
## Anti-Patterns
|
|
62
|
+
|
|
63
|
+
- Writing business or technical decisions into the evidence pack.
|
|
64
|
+
- Treating screenshot-only input as implementation-ready.
|
|
65
|
+
- Inventing permissions, API semantics, or database behavior from visual layout.
|
|
66
|
+
- Starting implementation without approved upstream artifact layers.
|