@comfanion/workflow 4.38.1-dev.1 → 4.38.1-dev.12

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

@@ -101,38 +101,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}}
+
+**Verdict:** {{APPROVE | CHANGES_REQUESTED | BLOCKED}}
+**Reviewer:** @reviewer (Marcus)
+
+**Summary:** {{1-2 sentences}}
+
+**Tests:** {{PASS | FAIL — details}}
+**Lint:** {{PASS | FAIL — details}}
 
-**Action Items:**
-- [ ] [High] Fix missing error handling in X
-- [ ] [Med] Add unit test for edge case Y
-- [ ] [Low] Improve variable naming in Z
+{{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
 
-**Blocking Issues:**
-1. Security vulnerability in authentication flow
-2. Missing critical test coverage
+**Verdict:** APPROVE
+**Reviewer:** @reviewer (Marcus)
 
-Cannot proceed until blocking issues resolved.
+**Summary:** All issues from Review #1 fixed. Error handling added, test coverage complete.
+
+**Tests:** PASS (14/14)
+**Lint:** PASS
+
+#### What's Good
+- Clean error wrapping with domain errors
+- Good test coverage for edge cases
 ```
 
 ## Severity Levels
@@ -164,34 +208,9 @@ func foo() error { ... }
 
 ## Updating Story File
 
-After review, add to story file:
-
-```markdown
-## Senior Developer Review (AI)
-
-### Review Date
-2024-01-15
-
-### Review Outcome
-Changes Requested
-
-### Action Items
-- [ ] [High] Add error handling to CreateUser handler
-- [ ] [Med] Add unit test for duplicate email validation
-- [ ] [Low] Rename 'x' to 'userCount'
-
-### Detailed Comments
-[Include detailed review comments here]
-```
-
-If changes requested, also add:
-
-```markdown
-### Review Follow-ups (AI)
-
-- [ ] [AI-Review] [High] Add error handling to CreateUser handler
-- [ ] [AI-Review] [Med] Add unit test for duplicate email validation
-```
+**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.
 
 ## Best Practices
 

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

@@ -9,64 +9,103 @@ metadata:
 
 # Dev Epic Skill
 
+## CRITICAL: Context Rules
+
+**READ ONLY (max ~70KB):**
+- `CLAUDE.md`
+- `docs/coding-standards/README.md`
+- `docs/coding-standards/patterns.md`
+- Epic file (ONE)
+- Current story file (ONE at a time)
+
+**❌ DO NOT READ — WASTES CONTEXT:**
+- ❌ `docs/prd.md` — epic/story already has context
+- ❌ `docs/architecture.md` — too large, coding-standards has patterns
+- ❌ All stories at once — read ONE, execute, then next
+
+---
+
 <workflow name="dev-epic">
 
   <phase name="1-context" title="Load Minimal Context">
+    <critical>DO NOT read prd.md, architecture.md, or all stories!</critical>
     <read>
       <file>CLAUDE.md</file>
       <file>docs/coding-standards/README.md</file>
       <file>docs/coding-standards/patterns.md</file>
       <file>{epic-file}</file>
-      <file>{current-story-file}</file>
+      <file>{current-story-file} — ONE only!</file>
     </read>
-    <skip reason="too large, epic/story has context">
-      <file>docs/prd.md</file>
-      <file>docs/architecture.md</file>
-      <file>all stories at once</file>
-    </skip>
-    <goal>~70KB per story</goal>
+    <goal>~70KB per story, NOT 200KB+</goal>
   </phase>
 
   <phase name="2-init" title="Initialize Epic">
-    <step n="1">Parse epic file → extract story list</step>
+    <step n="1">Parse epic file → "Story Tasks" section has all stories + tasks (no need to read story files yet)</step>
     <step n="2">Create epic state: docs/sprint-artifacts/sprint-N/.sprint-state/epic-XX-state.yaml</step>
-    <step n="3">Create TODO list:
+    <step n="3">Create TODO list with IDs — stories, their tasks, and reviews:
       ```
-      [ ] Story 1: [Title]
-      [ ] Review Story 1
-      [ ] Story 2: [Title]
-      [ ] Review Story 2
+      [ ] E{N}-S01: {story title}
+        [ ] E{N}-S01-T01: {task title}
+        [ ] E{N}-S01-T02: {task title}
+        [ ] E{N}-S01-Review: run tests, verify AC
+      [ ] E{N}-S02: {story title}
+        [ ] E{N}-S02-T01: {task title}
+        [ ] E{N}-S02-T02: {task title}
+        [ ] E{N}-S02-Review: run tests, verify AC
       ...
-      [ ] Epic integration tests
-      [ ] Verify epic AC
+      [ ] E{N}-Integration: run epic integration tests
+      [ ] E{N}-AC: verify epic acceptance criteria
       ```
     </step>
+    <example>
+      ```
+      [ ] E04-S01: Merge Domain Logic
+        [ ] E04-S01-T01: MergeResult value object
+        [ ] E04-S01-T02: Merge service — primary selection
+        [ ] E04-S01-T03: Unit tests
+        [ ] E04-S01-Review: run tests, verify AC
+      [ ] E04-S02: Auto Merge on Link
+        [ ] E04-S02-T01: Event handler for link
+        [ ] E04-S02-T02: Best-effort merge logic
+        [ ] E04-S02-T03: Integration tests
+        [ ] E04-S02-Review: run tests, verify AC
+      [ ] E04-Integration: run epic integration tests
+      [ ] E04-AC: verify epic acceptance criteria
+      ```
+    </example>
     <step n="4">Set state: status="in-progress", next_action="Execute [first-story.md]"</step>
     <step n="5">Mark first story as in_progress in TODO</step>
   </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">
         Follow /dev-story logic:
-        - Create nested TODO for tasks
-        - Implement all tasks (RED/GREEN/REFACTOR)
-        - Clear task TODO when done
+        - Read ONE story file
+        - 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
       </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>
       
@@ -79,32 +118,72 @@ 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">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>
 
+## Session State (MANDATORY)
+
+After each story/task completion, update `.opencode/session-state.yaml`:
+
+```yaml
+# .opencode/session-state.yaml — AI writes, compaction plugin reads
+command: /dev-epic
+agent: dev
+
+epic:
+  id: PROJ-E01
+  title: Epic Title
+  file: docs/sprint-artifacts/sprint-1/epic-01-desc.md
+  progress: "3/5 stories"
+
+story:
+  id: PROJ-S01-03
+  title: Current Story Title
+  file: docs/sprint-artifacts/sprint-1/stories/story-01-03-desc.md
+  current_task: T2
+  completed_tasks: [T1]
+  pending_tasks: [T2, T3]
+
+next_action: "Continue T2 of story S01-03"
+
+key_decisions:
+  - "Decision 1"
+```
+
+This file survives compaction and tells the agent where to resume.
+
 <outputs>
   - Implementation code for all stories
   - Updated epic-XX-state.yaml
+  - Updated .opencode/session-state.yaml
   - Clean TODO list (all completed)
 </outputs>
 
 <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

@@ -9,46 +9,88 @@ metadata:
 
 # Dev Sprint Skill
 
+## CRITICAL: Context Rules
+
+**READ ONLY (max ~70KB):**
+- `CLAUDE.md`
+- `docs/coding-standards/README.md`
+- `docs/coding-standards/patterns.md`
+- `sprint-status.yaml`
+- Current epic file (ONE)
+- Current story file (ONE at a time)
+
+**❌ DO NOT READ — WASTES CONTEXT:**
+- ❌ `docs/prd.md` — epic/story already has context
+- ❌ `docs/architecture.md` — too large, coding-standards has patterns
+- ❌ All epics at once — read ONE, execute, then next
+- ❌ All stories at once — read ONE, execute, then next
+
+---
+
 <workflow name="dev-sprint">
 
   <phase name="1-context" title="Load Minimal Context">
+    <critical>DO NOT read prd.md, architecture.md, or all epics/stories!</critical>
     <read>
       <file>CLAUDE.md</file>
       <file>docs/coding-standards/README.md</file>
       <file>docs/coding-standards/patterns.md</file>
       <file>sprint-status.yaml</file>
-      <file>{current-epic-file}</file>
-      <file>{current-story-file}</file>
+      <file>{current-epic-file} — ONE only!</file>
+      <file>{current-story-file} — ONE only!</file>
     </read>
-    <skip reason="too large, epic/story has context">
-      <file>docs/prd.md</file>
-      <file>docs/architecture.md</file>
-      <file>all epics/stories at once</file>
-    </skip>
-    <goal>~70KB per story</goal>
+    <goal>~70KB per story, NOT 200KB+</goal>
   </phase>
 
   <phase name="2-init" title="Initialize Sprint">
     <step n="1">Parse sprint-status.yaml → extract epic list for target sprint</step>
-    <step n="2">Create master TODO list:
+    <step n="2">Create master TODO list with IDs — epics, stories, tasks, and reviews:
       ```
-      [ ] Epic 1: [Title]
-      [ ] Story 1-1: [Title]
-      [ ] Review Story 1-1
-      [ ] Story 1-2: [Title]
-      [ ] Review Story 1-2
-      [ ] Review Epic 1
-      [ ] Epic 2: [Title]
-      [ ] Story 2-1: [Title]
-      ...
-      [ ] Sprint integration tests
+      [ ] E{N1}: {epic title}
+        [ ] E{N1}-S01: {story title}
+          [ ] E{N1}-S01-T01: {task title}
+          [ ] E{N1}-S01-T02: {task title}
+          [ ] E{N1}-S01-Review: run tests, verify AC
+        [ ] E{N1}-S02: {story title}
+          [ ] E{N1}-S02-T01: {task title}
+          [ ] E{N1}-S02-Review: run tests, verify AC
+        [ ] E{N1}-Integration: epic integration tests
+      [ ] E{N2}: {epic title}
+        [ ] E{N2}-S01: {story title}
+          [ ] E{N2}-S01-T01: {task title}
+          [ ] E{N2}-S01-Review: run tests, verify AC
+        [ ] E{N2}-Integration: epic integration tests
+      [ ] Sprint-Integration: run sprint integration tests
       ```
     </step>
+    <example>
+      ```
+      [ ] E04: Identity Merge
+        [ ] E04-S01: Merge Domain Logic
+          [ ] E04-S01-T01: MergeResult value object
+          [ ] E04-S01-T02: Merge service
+          [ ] E04-S01-T03: Unit tests
+          [ ] E04-S01-Review: run tests, verify AC
+        [ ] E04-S02: Auto Merge on Link
+          [ ] E04-S02-T01: Event handler
+          [ ] E04-S02-T02: Integration tests
+          [ ] E04-S02-Review: run tests, verify AC
+        [ ] E04-Integration: epic integration tests
+      [ ] E06: Team Management
+        [ ] E06-S01: Team CRUD
+          [ ] E06-S01-T01: Domain model
+          [ ] E06-S01-T02: Handler
+          [ ] E06-S01-Review: run tests, verify AC
+        [ ] E06-Integration: epic integration tests
+      [ ] Sprint-Integration: run sprint integration tests
+      ```
+    </example>
     <step n="3">Set sprint status="in-progress" in sprint-status.yaml</step>
     <step n="4">Mark first epic as in_progress in TODO</step>
   </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">
@@ -58,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">
@@ -76,31 +124,76 @@ 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">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>
 
+## Session State (MANDATORY)
+
+After each epic/story/task completion, update `.opencode/session-state.yaml`:
+
+```yaml
+# .opencode/session-state.yaml — AI writes, compaction plugin reads
+command: /dev-sprint
+agent: dev
+
+sprint:
+  number: 2
+  status: in-progress
+
+epic:
+  id: PROJ-E04
+  title: Current Epic Title
+  file: docs/sprint-artifacts/sprint-2/epic-04-desc.md
+  progress: "3/5 stories"
+
+story:
+  id: PROJ-S04-03
+  title: Current Story Title
+  file: docs/sprint-artifacts/sprint-2/stories/story-04-03-desc.md
+  current_task: T2
+  completed_tasks: [T1]
+  pending_tasks: [T2, T3]
+
+next_action: "Continue T2 of story S04-03"
+
+key_decisions:
+  - "Decision 1"
+```
+
+This file survives compaction and tells the agent where to resume.
+
 <outputs>
   - Implementation code for all stories in sprint
   - Updated sprint-status.yaml
+  - Updated .opencode/session-state.yaml
   - Clean TODO list (all completed)
 </outputs>
 
 <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>