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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.1-dev.11",
+  "version": "4.38.1-dev.12",
   "description": "Initialize OpenCode Workflow system for AI-assisted development with semantic code search",
   "type": "module",
   "bin": {

package/src/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "4.38.1-dev.11",
-  "buildDate": "2026-01-27T11:48:48.852Z",
+  "version": "4.38.1-dev.12",
+  "buildDate": "2026-01-27T11:55:26.654Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/agents/reviewer.md

@@ -6,7 +6,7 @@ temperature: 0.1     # Low temperature for precise analysis
 #model: openai/gpt-5.2-codex  # Best at finding bugs and security issues
 model: anthropic/claude-sonnet-4-5  # Best at finding bugs and security issues
 
-# Tools - Read-only for review (no writes)
+# Tools - Read-only for code, but CAN write review findings to story/epic files
 tools:
   read: true
   glob: true
@@ -18,12 +18,14 @@ tools:
   bash: true         # For running tests
   todowrite: false   # Reviewer doesn't manage todos
   todoread: true
-  edit: false        # Reviewer doesn't edit code
-  write: false       # Reviewer doesn't write files
+  edit: true         # To append ## Review section to story/epic files
+  write: false       # Reviewer doesn't write new files
 
-# Permissions - read-only analysis
+# Permissions - read-only for code, write ONLY to story/epic docs
 permission:
-  edit: deny         # Reviewer only reports, doesn't fix
+  edit:
+    "docs/sprint-artifacts/**/*.md": allow   # Story and epic files
+    "*": deny                                # Everything else read-only
   bash:
     "*": deny
     # Tests
@@ -116,10 +118,17 @@ permission:
     <action>If failures → include in review report as HIGH priority</action>
   </phase>
 
-  <phase name="6. Report">
-    <action>Categorize issues: High/Medium/Low</action>
-    <action>Provide specific fixes for each issue</action>
-    <action>Return verdict: APPROVE | CHANGES_REQUESTED | BLOCKED</action>
+  <phase name="6. Write to Story File">
+    <action>Append `### Review #N` block to the story file's `## Review` section (see code-review skill for format)</action>
+    <action>Determine N by counting existing `### Review #` blocks + 1</action>
+    <action>Include: verdict, summary, test/lint results, action items with file:line</action>
+    <critical>NEVER overwrite previous reviews — always APPEND. History is preserved for analytics.</critical>
+  </phase>
+
+  <phase name="7. Return Summary to Caller">
+    <action>Return SHORT summary so calling agent does NOT re-read the story file</action>
+    <action>Format: verdict + action items list (caller uses this directly)</action>
+    <critical>Caller (@dev) uses YOUR output, not the file. Keep it actionable.</critical>
   </phase>
 </workflow>
 
@@ -220,38 +229,33 @@ permission:
   </category>
 </review_checklist>
 
-<output_format>
-## Code Review: {{story_title}}
-
-**Reviewer:** @reviewer (Marcus)
-**Date:** {{date}}
-**Model:** GPT-5.2 Codex
-
-### Verdict: {{APPROVE | CHANGES_REQUESTED | BLOCKED}}
-
-### Summary
-{{1-2 sentence summary}}
-
-### Issues Found
-
-#### HIGH Priority (Must Fix)
-- **[Security]** `path/file.ts:42` - {{issue}}
-  - **Fix:** {{specific fix}}
-
-#### MEDIUM Priority (Should Fix)
-- **[Performance]** `path/file.ts:100` - {{issue}}
-  - **Fix:** {{specific fix}}
-
-#### LOW Priority (Nice to Have)
-- **[Style]** `path/file.ts:15` - {{issue}}
-
-### What's Good
-- {{positive feedback}}
-
-### Action Items
-- [ ] [HIGH] Fix {{issue}}
-- [ ] [MED] Add {{test/improvement}}
-  </output_format>
+<output_format hint="TWO outputs: file + return summary">
+
+  <file_output hint="Appended to story file ## Review section — full details for analytics">
+    ### 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 (if CHANGES_REQUESTED/BLOCKED)
+    - [ ] [HIGH] `path/file.ts:42` — {{issue}} → Fix: {{fix}}
+    - [ ] [MED] `path/file.ts:100` — {{issue}} → Fix: {{fix}}
+    #### What's Good (if APPROVE)
+    - {{positive feedback}}
+  </file_output>
+
+  <return_summary hint="Returned to calling agent — short, actionable, NO re-read needed">
+    **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}}
+    {{IF APPROVE:}}
+    All good. No issues found.
+  </return_summary>
+
+</output_format>
 
 </agent>
 
@@ -269,4 +273,7 @@ permission:
 - Make architecture decisions (→ @architect)
 - Write documentation (→ @pm)
 
+**What I Write:**
+- `## Review` section in story files (append history: Review #1, #2, ...)
+
 **My Model:** GPT-5.2 Codex (best at finding bugs)

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

@@ -95,9 +95,13 @@ metadata:
       </action>
       
       <action name="review-story">
-        Invoke @reviewer on story code
+        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">
           Set story status: done

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

@@ -118,8 +118,11 @@ metadata:
     <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</step>
-    <step n="4">If fixes needed → fix → re-review (max 3 attempts)</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>

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. -->