@comfanion/workflow 4.38.1-dev.9 → 4.38.2

package/src/opencode/skills/code-review/SKILL.md

@@ -16,6 +16,75 @@ How to perform thorough code reviews for implemented stories.
 
 Ensure code quality, correctness, and adherence to project standards before merging.
 
+---
+
+<workflow name="code-review">
+
+  <phase name="1-prepare" title="Preparation">
+    <action>Read the story file completely</action>
+    <action>Identify all acceptance criteria</action>
+    <action>Load docs/coding-standards/*.md for coding standards</action>
+    <action>Use search() to find similar patterns in codebase to compare against</action>
+    <action>Use search() in docs for architecture requirements</action>
+    <action>Review File List section for changed files</action>
+  </phase>
+
+  <phase name="2-security" title="Security Analysis (HIGH Priority)">
+    <critical>Security issues are ALWAYS high priority</critical>
+    <check>No hardcoded secrets, API keys, passwords</check>
+    <check>All user inputs validated and sanitized</check>
+    <check>Parameterized queries (no SQL injection)</check>
+    <check>Auth required on protected endpoints</check>
+    <check>Authorization checks before data access</check>
+    <check>Sensitive data not logged</check>
+    <check>Error messages don't leak internal details</check>
+  </phase>
+
+  <phase name="3-correctness" title="Correctness Analysis (HIGH Priority)">
+    <check>All acceptance criteria satisfied</check>
+    <check>Edge cases handled</check>
+    <check>Error scenarios have proper handling</check>
+    <check>No obvious logic errors</check>
+    <check>No race conditions</check>
+  </phase>
+
+  <phase name="4-tests" title="Testing Review (HIGH Priority)">
+    <check>Unit tests exist for new code</check>
+    <check>Tests cover happy path and errors</check>
+    <check>No flaky tests</check>
+    <check>Test names are descriptive</check>
+    <check>Run test suite: go test / npm test / pytest / cargo test</check>
+    <check>If failures → include in review report as HIGH priority</check>
+  </phase>
+
+  <phase name="5-quality" title="Code Quality (MEDIUM Priority)">
+    <check>Follows project architecture</check>
+    <check>Clear naming conventions</check>
+    <check>No code duplication</check>
+    <check>Functions are focused and small</check>
+    <check>Proper error wrapping</check>
+    <check>No N+1 query issues</check>
+    <check>Run linter: golangci-lint / eslint / ruff / cargo clippy</check>
+  </phase>
+
+  <phase name="6-write-file" title="Write Findings to Story File">
+    <critical>MANDATORY: Append review to story file for history/analytics</critical>
+    <step n="1">Read story file's ## Review section</step>
+    <step n="2">Count existing ### Review #N blocks → your review is N+1</step>
+    <step n="3">Append ### Review #N block with format below</step>
+    <step n="4">NEVER overwrite previous reviews — always APPEND</step>
+  </phase>
+
+  <phase name="7-return-summary" title="Return Summary to Caller">
+    <critical>Caller (@dev) uses YOUR output, not the file. Keep it actionable.</critical>
+    <step n="1">Return SHORT summary: verdict + action items</step>
+    <step n="2">Caller will use this directly without re-reading story file</step>
+  </phase>
+
+</workflow>
+
+---
+
 ## Review Process
 
 ### 1. Preparation
@@ -101,38 +170,82 @@ For each AC in the story:
 
 All criteria met. Code is ready to merge.
 
-```markdown
-### Review Outcome: Approve
-
-All acceptance criteria satisfied. Code follows project standards.
-Ready for merge.
-```
-
 ### 🔄 Changes Requested
 
 Issues found that need addressing.
 
+### ❌ Blocked
+
+Major issues that prevent approval.
+
+## Write Findings to Story File (MANDATORY)
+
+After completing the review, **append** your findings to the story file's `## Review` section.
+Each review round is a separate `### Review #N` block. NEVER overwrite previous reviews — always append.
+
+**How to determine review number:**
+1. Read the story file's `## Review` section
+2. Count existing `### Review #N` blocks
+3. Your review is `N + 1` (or `#1` if none exist)
+
+**Format to append at the end of the story file:**
+
 ```markdown
-### Review Outcome: Changes Requested
+### Review #{{N}} — {{YYYY-MM-DD}}
 
-**Action Items:**
-- [ ] [High] Fix missing error handling in X
-- [ ] [Med] Add unit test for edge case Y
-- [ ] [Low] Improve variable naming in Z
+**Verdict:** {{APPROVE | CHANGES_REQUESTED | BLOCKED}}
+**Reviewer:** @reviewer (Marcus)
+
+**Summary:** {{1-2 sentences}}
+
+**Tests:** {{PASS | FAIL — details}}
+**Lint:** {{PASS | FAIL — details}}
+
+{{IF issues found:}}
+#### Action Items
+- [ ] [HIGH] `path/file.ts:42` — {{issue}} → Fix: {{specific fix}}
+- [ ] [MED] `path/file.ts:100` — {{issue}} → Fix: {{specific fix}}
+- [ ] [LOW] `path/file.ts:15` — {{issue}}
+
+{{IF approve:}}
+#### What's Good
+- {{positive feedback}}
 ```
 
-### ❌ Blocked
+**Example — first review with issues:**
 
-Major issues that prevent approval.
+```markdown
+### Review #1 — 2026-01-27
+
+**Verdict:** CHANGES_REQUESTED
+**Reviewer:** @reviewer (Marcus)
+
+**Summary:** Missing error handling in CreateUser handler, no test for duplicate email.
+
+**Tests:** PASS (12/12)
+**Lint:** PASS
+
+#### Action Items
+- [ ] [HIGH] `internal/user/handler.go:42` — No error handling for DB timeout → Fix: wrap with domain error
+- [ ] [MED] `internal/user/handler_test.go` — Missing duplicate email test → Fix: add TestCreateUser_DuplicateEmail
+```
+
+**Example — second review after fixes:**
 
 ```markdown
-### Review Outcome: Blocked
+### Review #2 — 2026-01-27
+
+**Verdict:** APPROVE
+**Reviewer:** @reviewer (Marcus)
 
-**Blocking Issues:**
-1. Security vulnerability in authentication flow
-2. Missing critical test coverage
+**Summary:** All issues from Review #1 fixed. Error handling added, test coverage complete.
 
-Cannot proceed until blocking issues resolved.
+**Tests:** PASS (14/14)
+**Lint:** PASS
+
+#### What's Good
+- Clean error wrapping with domain errors
+- Good test coverage for edge cases
 ```
 
 ## Severity Levels
@@ -164,39 +277,53 @@ func foo() error { ... }
 
 ## Updating Story File
 
-After review, add to story file:
+**MANDATORY:** Use the format from "Write Findings to Story File" section above.
+Append `### Review #N` block to the `## Review` section at the end of the story file.
+NEVER overwrite previous reviews — history must be preserved for analytics.
 
-```markdown
-## Senior Developer Review (AI)
+## Return Summary to Caller (MANDATORY)
 
-### Review Date
-2024-01-15
+After writing to story file, return a SHORT summary to the calling agent (@dev).
+This prevents the caller from re-reading the story file.
 
-### Review Outcome
-Changes Requested
+**Format:**
 
-### Action Items
-- [ ] [High] Add error handling to CreateUser handler
-- [ ] [Med] Add unit test for duplicate email validation
-- [ ] [Low] Rename 'x' to 'userCount'
+```
+**VERDICT: {{APPROVE | CHANGES_REQUESTED | BLOCKED}}**
+
+{{IF CHANGES_REQUESTED or BLOCKED:}}
+Action items:
+- [HIGH] `path/file.ts:42` — {{issue}} → {{fix}}
+- [MED] `path/file.ts:100` — {{issue}} → {{fix}}
 
-### Detailed Comments
-[Include detailed review comments here]
+{{IF APPROVE:}}
+All good. No issues found.
 ```
 
-If changes requested, also add:
+**Example — Changes Requested:**
 
-```markdown
-### Review Follow-ups (AI)
+```
+**VERDICT: CHANGES_REQUESTED**
 
-- [ ] [AI-Review] [High] Add error handling to CreateUser handler
-- [ ] [AI-Review] [Med] Add unit test for duplicate email validation
+Action items:
+- [HIGH] `internal/user/handler.go:42` — No error handling for DB timeout → wrap with domain error
+- [MED] `internal/user/handler_test.go` — Missing duplicate email test → add TestCreateUser_DuplicateEmail
 ```
 
+**Example — Approve:**
+
+```
+**VERDICT: APPROVE**
+
+All good. No issues found. Clean error wrapping, good test coverage.
+```
+
+---
+
 ## Best Practices
 
 1. **Be specific** - Point to exact file and line
 2. **Suggest solutions** - Don't just criticize
 3. **Prioritize** - Focus on important issues first
 4. **Be constructive** - Phrase feedback positively
-5. **Use different LLM** - For fresh perspective
+5. **Use search()** - Find similar patterns before reviewing

package/src/opencode/skills/dev-epic/SKILL.md

@@ -78,6 +78,7 @@ metadata:
   </phase>
 
   <phase name="3-loop" title="Story Execution Loop">
+    <critical>Status flow: in_progress → review → done. NEVER mark done before review!</critical>
     <for-each item="story" in="pending_stories">
       
       <action name="execute-story">
@@ -86,21 +87,25 @@ metadata:
         - Execute tasks ONE BY ONE (or parallel if independent)
         - NEVER delegate entire story to @coder in one prompt
         - After each task: verify, mark done, next task
-        - Clear task TODO when story done
       </action>
       
-      <action name="mark-done">
-        Mark story as completed in epic TODO
+      <action name="story-to-review">
+        All tasks done → set story status: review
+        Mark story TODO as "review" (NOT "done" yet!)
       </action>
       
-      <action name="review">
-        Mark "Review Story" as in_progress
-        Invoke @reviewer
+      <action name="review-story">
+        Invoke @reviewer on story code.
+        Reviewer does TWO things:
+        1. WRITES findings to story file (## Review → ### Review #N) — for history
+        2. RETURNS summary to you — use THIS, do NOT re-read story file
         <if condition="CHANGES_REQUESTED">
-          Add fix tasks → re-execute → re-review (max 3 attempts)
+          Use reviewer's returned action items directly.
+          Create fix tasks from action items → execute → re-review (max 3 attempts).
         </if>
         <if condition="APPROVED">
-          Mark "Review Story" as completed
+          Set story status: done
+          Mark story TODO as completed
         </if>
       </action>
       
@@ -113,20 +118,22 @@ metadata:
       
       <action name="compact">
         Mark next story as in_progress in TODO
-        Wait for auto-compaction
-        Plugin reads TODO + state → resume
+        Wait for auto-compaction → resume
       </action>
       
     </for-each>
   </phase>
 
   <phase name="4-finalize" title="Finalize Epic">
-    <step n="1">Run epic integration tests (mark in TODO)</step>
-    <step n="2">Verify all AC from epic file (mark in TODO)</step>
-    <step n="3">Set state: status="done"</step>
-    <step n="4">Clear epic TODO list</step>
-    <step n="5">Update .opencode/session-state.yaml (next epic or done)</step>
-    <step n="6">Report completion with summary</step>
+    <critical>Epic also goes through review before done!</critical>
+    <step n="1">All stories done → set epic status: review</step>
+    <step n="2">Run epic integration tests (mark in TODO)</step>
+    <step n="3">Verify all AC from epic file (mark in TODO)</step>
+    <step n="4">If tests fail → fix → re-test</step>
+    <step n="5">All passed → set epic status: done</step>
+    <step n="6">Clear epic TODO list</step>
+    <step n="7">Update .opencode/session-state.yaml (next epic or done)</step>
+    <step n="8">Report completion with summary</step>
   </phase>
 
 </workflow>
@@ -172,6 +179,11 @@ This file survives compaction and tells the agent where to resume.
 <rules>
   <do>Create clean TODO list for each epic</do>
   <do>Update epic state file BEFORE compaction</do>
+  <do>Execute stories IN ORDER as planned in epic file</do>
+  <do>Execute tasks within story ONE BY ONE (or parallel if independent)</do>
   <dont>Ask user for confirmation between stories — TODO is your guide</dont>
   <dont>Proceed to next story if review fails — enter fix loop</dont>
+  <dont>Reorder, skip, merge, or "optimize" story execution order</dont>
+  <dont>Combine tasks from different stories into one batch</dont>
+  <dont>Delegate entire story to @coder in one prompt — task by task only</dont>
 </rules>

package/src/opencode/skills/dev-sprint/SKILL.md

@@ -90,6 +90,7 @@ metadata:
   </phase>
 
   <phase name="3-loop" title="Epic Execution Loop">
+    <critical>Status flow: in_progress → review → done. NEVER mark done before review!</critical>
     <for-each item="epic" in="pending_epics">
       
       <action name="execute-epic">
@@ -99,14 +100,20 @@ metadata:
         - Clears epic TODO when done
       </action>
       
-      <action name="mark-done">
-        Mark epic as completed in sprint TODO
+      <action name="epic-to-review">
+        All stories done → set epic status: review
+        Mark epic TODO as "review" (NOT "done" yet!)
       </action>
       
       <action name="epic-review">
-        Mark "Review Epic" as in_progress
         Run epic integration tests
-        Mark "Review Epic" as completed
+        <if condition="TESTS_FAIL">
+          Fix → re-test (max 3 attempts)
+        </if>
+        <if condition="TESTS_PASS">
+          Set epic status: done
+          Mark epic TODO as completed
+        </if>
       </action>
       
       <action name="update-state">
@@ -117,19 +124,21 @@ metadata:
       
       <action name="compact">
         Mark next epic as in_progress in TODO
-        Wait for auto-compaction
-        Plugin reads sprint TODO → resume
+        Wait for auto-compaction → resume
       </action>
       
     </for-each>
   </phase>
 
   <phase name="4-finalize" title="Finalize Sprint">
-    <step n="1">Run sprint integration tests (mark in TODO)</step>
-    <step n="2">Set sprint status="done" in sprint-status.yaml</step>
-    <step n="3">Clear sprint TODO list</step>
-    <step n="4">Update .opencode/session-state.yaml (done)</step>
-    <step n="5">Report completion with summary + metrics</step>
+    <critical>Sprint also goes through review before done!</critical>
+    <step n="1">All epics done → set sprint status: review</step>
+    <step n="2">Run sprint integration tests (mark in TODO)</step>
+    <step n="3">If tests fail → fix → re-test</step>
+    <step n="4">All passed → set sprint status: done in sprint-status.yaml</step>
+    <step n="5">Clear sprint TODO list</step>
+    <step n="6">Update .opencode/session-state.yaml (done)</step>
+    <step n="7">Report completion with summary + metrics</step>
   </phase>
 
 </workflow>
@@ -179,6 +188,12 @@ This file survives compaction and tells the agent where to resume.
 <rules>
   <do>Create ONE master TODO list for entire sprint at start</do>
   <do>Let dev-epic skill manage its own nested TODO</do>
+  <do>Execute epics IN ORDER as planned in sprint-status.yaml</do>
+  <do>Within each epic, execute stories IN ORDER as planned</do>
+  <do>Within each story, execute tasks ONE BY ONE (or parallel if independent)</do>
   <dont>Ask for confirmation between epics — sprint TODO is your guide</dont>
   <dont>Proceed to next epic if epic review fails — HALT and report</dont>
+  <dont>Reorder, skip, merge, or "optimize" epic/story execution order</dont>
+  <dont>Work on multiple stories or epics in parallel</dont>
+  <dont>Delegate entire story to @coder in one prompt — task by task only</dont>
 </rules>

package/src/opencode/skills/dev-story/SKILL.md

@@ -114,6 +114,19 @@ metadata:
     </parallel-rules>
   </phase>
 
+  <phase name="4-review" title="Review BEFORE Done">
+    <critical>Status flow: in_progress → review → done. NEVER skip review!</critical>
+    <step n="1">All tasks done → set story status: review</step>
+    <step n="2">Run all tests, verify AC</step>
+    <step n="3">If called from /dev-epic: invoke @reviewer.
+      Reviewer does TWO things:
+      1. WRITES findings to story file (## Review → ### Review #N) — for history
+      2. RETURNS summary to you — use THIS, do NOT re-read story file</step>
+    <step n="4">If CHANGES_REQUESTED: use reviewer's returned action items directly → fix → re-review (max 3 attempts)</step>
+    <step n="5">Review passed → set story status: done</step>
+    <step n="6">Update .opencode/session-state.yaml</step>
+  </phase>
+
 </workflow>
 
 ## Session State (MANDATORY)

package/src/opencode/skills/prd-writing/SKILL.md

@@ -255,11 +255,22 @@ Brief prose section with:
 - Each module gets its own FR table
 - Example: "Order Management Module" → FR-ORD-001, FR-ORD-002
 
-**Table format:**
+**Table format (with traceability):**
 
-| ID | Requirement | Priority |
-|----|-------------|----------|
-| FR-001 | {{requirement}} | P0 |
+| ID | Requirement | Priority | Module | Doc Section | Arch § | Epic | Status |
+|----|-------------|----------|--------|-------------|--------|------|--------|
+| FR-001 | {{requirement}} | P0 | {{module}} | → Unit: `{{name}}` | §{{N}} | → Epic: `{{file}}` | ⬜ |
+
+**Column filling:**
+- **@pm (you):** ID, Requirement, Priority, Module — filled when writing PRD
+- **@architect:** Doc Section, Arch § — filled when creating architecture/unit docs
+- **@pm:** Epic — filled when creating epics (`/epics`)
+- **@dev:** Status — marked ✅ when done
+
+**Doc Section format:**
+- Use `→ Unit: Name`, `→ Module: Name`, `→ Service: Name`, etc.
+- Examples: `→ Unit: Task`, `→ Module: Auth`, `→ Service: NotificationService`
+- Leave blank initially, @architect fills later
 
 With **Notes:** for business rules after each domain table.
 
@@ -272,10 +283,19 @@ FR-INV-001  # Inventory module
 
 ### 5. Non-Functional Requirements
 
-Tables for:
-- Performance (with metrics)
-- Security
-- Scalability
+**Table format (with traceability):**
+
+| ID | Requirement | Priority | Module | Doc Section | Arch § | Status |
+|----|-------------|----------|--------|-------------|--------|--------|
+| NFR-001 | {{requirement}} | P0 | — | — | §{{N}} | ⬜ |
+
+**Column filling:**
+- **@pm (you):** ID, Requirement, Priority, Module (if specific)
+- **@architect:** Doc Section (if specific), Arch §
+- **@dev:** Status
+
+**Optional details section:**
+Add Performance/Security/Scalability subsections if NFRs need detailed explanation.
 
 ### 6. Critical Business Rules
 

package/src/opencode/skills/prd-writing/template.md

@@ -117,18 +117,21 @@ TaskFlow is a B2B platform for managing distributed teams. The system handles ta
 
 ## Functional Requirements
 
+> **Traceability:** Each FR tracks Module, Unit, Architecture section, Epic, and Status.
+> **Maintained by:** @pm (Epic), @architect (Module/Unit/Arch §), @dev (Status).
+
 ### {{Domain_1}}
 
-| ID | Requirement | Priority |
-|----|-------------|----------|
-| FR-001 | {{requirement}} | P0 |
-| FR-002 | {{requirement}} | P0 |
-| FR-003 | {{requirement}} | P1 |
+| ID | Requirement | Priority | Module | Doc Section | Arch § | Epic | Status |
+|----|-------------|----------|--------|-------------|--------|------|--------|
+| FR-001 | {{requirement}} | P0 | {{module}} | → Unit: `{{name}}` | §{{N}} | → Epic: `{{file}}` | ⬜ |
+| FR-002 | {{requirement}} | P0 | {{module}} | → Module: `{{name}}` | §{{N}} | → Epic: `{{file}}` | ⬜ |
+| FR-003 | {{requirement}} | P1 | {{module}} | → Service: `{{name}}` | §{{N}} | → Epic: `{{file}}` | ⬜ |
 
-<!-- e.g.
-| FR-001 | User can create task with title, description, due date | P0 |
-| FR-002 | User can assign task to team member | P0 |
-| FR-003 | System sends notification on assignment | P1 |
+<!-- Example:
+| FR-001 | User can create task with title, description, due date | P0 | Task | → Unit: `Task` | §3.1 | → Epic: `epic-01-task-crud.md` | ✅ |
+| FR-002 | User can assign task to team member | P0 | Task | → Unit: `Task` | §3.1 | → Epic: `epic-01-task-crud.md` | ⬜ |
+| FR-003 | System sends notification on assignment | P1 | Notification | → Service: `NotificationService` | §3.3 | → Epic: `epic-03-notifications.md` | ⬜ |
 -->
 
 **Notes:**
@@ -136,24 +139,40 @@ TaskFlow is a B2B platform for managing distributed teams. The system handles ta
 
 ### {{Domain_2}}
 
-| ID | Requirement | Priority |
-|----|-------------|----------|
-| FR-010 | {{requirement}} | P0 |
+| ID | Requirement | Priority | Module | Doc Section | Arch § | Epic | Status |
+|----|-------------|----------|--------|-------------|--------|------|--------|
+| FR-010 | {{requirement}} | P0 | {{module}} | → Unit: `{{name}}` | §{{N}} | → Epic: `{{file}}` | ⬜ |
 
 ---
 
 ## Non-Functional Requirements
 
+> **Traceability:** NFRs also track Module (if specific), Architecture section, and Status.
+
+| ID | Requirement | Priority | Module | Doc Section | Arch § | Status |
+|----|-------------|----------|--------|-------------|--------|--------|
+| NFR-001 | {{requirement}} | P0 | — | — | §{{N}} | ⬜ |
+| NFR-002 | {{requirement}} | P0 | {{module}} | → Unit: `{{name}}` | §{{N}} | ⬜ |
+
+<!-- Example:
+| NFR-001 | API response time < 200ms (p95) | P0 | — | — | §5 Performance | ⬜ |
+| NFR-002 | Task data encrypted at rest | P0 | Task | → Unit: `Task` | §4 Security | ⬜ |
+-->
+
+---
+
+## Non-Functional Requirements (Details)
+
+> Optional: Add detailed notes for complex NFRs here.
+
 ### Performance
-| Metric | Target |
-|--------|--------|
-| {{metric}} | {{value}} |
+- {{details_if_needed}}
 
 ### Security
-- {{requirement}}
+- {{details_if_needed}}
 
 ### Scalability
-- {{requirement}}
+- {{details_if_needed}}
 
 ---
 

package/src/opencode/skills/story-writing/template.md

@@ -228,3 +228,11 @@ Before marking story as done, verify:
 - [ ] Tests pass
 - [ ] Code reviewed
 - [ ] No lint errors
+
+---
+
+## Review
+
+<!-- Reviewer (@reviewer) appends review rounds here. DO NOT edit manually.
+     Each review is appended as ### Review #N with verdict and action items.
+     History is preserved for analytics. -->