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,188 +1,126 @@
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
+ 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 — Detailed Workflow
2
-
3
- ## Entry Conditions
4
-
5
- - Plan handoff exists at `.handoffs/dev-flow/plan.md`
6
- - Plan has been reviewed and approved by user
7
-
8
- ## Process
9
-
10
- ### 1. Read the Plan
11
- - Load `.handoffs/dev-flow/plan.md`
12
- - Understand the implementation steps
13
- - Note which files to modify and how
14
-
15
- ### 2. Setup
16
- - For each file to be modified, read the current content first
17
- - Understand the existing code structure
18
-
19
- ### 3. Implement Step by Step
20
- - Follow the implementation steps from the plan
21
- - After each step, verify the change is coherent
22
- - If you discover something the plan missed, note the deviation
23
-
24
- ### 4. Follow Project Conventions
25
- - Look at neighboring files for style/pattern reference
26
- - Match existing code style (naming, imports, formatting)
27
- - Follow the project's established patterns
28
-
29
- ### 5. Self-Review
30
- Before moving to Verify phase:
31
- - [ ] All planned changes implemented
32
- - [ ] No dead code or commented-out code
33
- - [ ] Error handling in place
34
- - [ ] Edge cases considered
35
- - [ ] No secrets or debug logs committed
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 — Detailed Workflow
2
-
3
- The Contract phase replaces the old Plan phase. It produces **persistent, committed** specification documents instead of temporary handoffs.
4
-
5
- ## Entry Conditions
6
-
7
- - User request received (feature, bug, refactor)
8
- - Dev-flow skill activated
9
- - Optional: ADRs exist in `docs/adr/` that constrain this feature
10
-
11
- ## Analysis Process
12
-
13
- ### 1. Understand the Request
14
- - Read the user's request carefully
15
- - Ask clarifying questions if ambiguous (one at a time, with rationale)
16
- - Identify the core goal, not just the surface request
17
-
18
- ### 2. Check Existing ADRs
19
- - Read `docs/adr/README.md` for index
20
- - Identify relevant ADRs that constrain or inform this feature
21
- - Reference ADR numbers in the contract document
22
-
23
- ### 3. Explore the Codebase
24
- - Read relevant files to understand current state
25
- - Use Grep/Glob to find related code
26
- - Identify patterns and conventions
27
-
28
- ### 4. Specify the Contract
29
-
30
- Write to `docs/specs/<feature>/README.md`:
31
-
32
- ```markdown
33
- # Feature: <title>
34
-
35
- ## Requirements
36
- FR-1: System MUST <behavior>
37
- FR-2: System SHOULD <behavior>
38
- FR-3: System MAY <behavior>
39
-
40
- ## Acceptance Criteria
41
- - GIVEN <context> WHEN <action> THEN <expected result>
42
-
43
- ## API Contract
44
- - POST /api/xxx
45
- Request: { field: type }
46
- Response: { field: type }
47
-
48
- ## Data Model
49
- | Entity | Field | Type | Constraints |
50
-
51
- ## Out of Scope
52
- - <explicit exclusions>
53
-
54
- ## Architecture References
55
- - ADR-001: <title>
56
- - ADR-003: <title>
57
- ```
58
-
59
- ### 5. User Review
60
- - Present contract to user
61
- - Ask: "Does this contract look correct? Ready to implement?"
62
- - Wait for approval before proceeding to Code phase
63
-
64
- ## Key Differences from Old Plan Phase
65
-
66
- | Aspect | Old Plan (handoff) | New Contract (persistent) |
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.