@comfanion/workflow 4.36.44 → 4.36.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.36.44",
+  "version": "4.36.46",
   "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.36.44",
-  "buildDate": "2026-01-25T01:16:46.417Z",
+  "version": "4.36.46",
+  "buildDate": "2026-01-25T02:31:28.158Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/FLOW.yaml

@@ -416,6 +416,27 @@ agents:
       - Following existing patterns
     personality: Fast, no questions, executes or fails
 
+  reviewer:
+    name: Marcus
+    title: Code Reviewer
+    icon: "🔍"
+    description: Code Reviewer - security-focused review, bug finding, test coverage
+    mode: subagent
+    model: openai/gpt-5.2-codex  # Best at finding bugs and security issues
+    temperature: 0.1
+    file: agents/reviewer.md
+    expertise:
+      - Security review
+      - Bug finding
+      - Test coverage analysis
+      - Code quality
+    personality: Thorough, security-paranoid, always suggests fixes
+    skills_used:
+      - code-review
+    auto_invoke:
+      trigger: story_tasks_complete  # Called automatically when all story tasks done
+      before: story_marked_done
+
   # Supporting Agents (not in main pipeline)
   researcher:
     name: Kristina
@@ -454,192 +475,6 @@ agents:
     skills_used:
       - change-management
 
-# =============================================================================
-# SKILLS (Knowledge - HOW to do things)
-# =============================================================================
-skills:
-  # Requirements Skills
-  requirements-gathering:
-    description: How to interview stakeholders, extract FR/NFR
-    file: skills/requirements-gathering/SKILL.md
-    used_by: [analyst]
-    produces: docs/requirements/requirements.md
-
-  requirements-validation:
-    description: How to validate requirements (SMART, no conflicts)
-    file: skills/requirements-validation/SKILL.md
-    used_by: [analyst, architect]
-    produces: docs/validation/requirements-validation-*.md
-
-  # PRD Skills
-  prd-writing:
-    description: How to write PRD (template, sections, examples)
-    file: skills/prd-writing/SKILL.md
-    used_by: [pm]
-    produces: docs/prd.md
-
-  prd-validation:
-    description: How to validate PRD completeness
-    file: skills/prd-validation/SKILL.md
-    used_by: [architect]
-    produces: docs/validation/prd-validation-*.md
-
-  acceptance-criteria:
-    description: How to write testable AC (Given/When/Then)
-    file: skills/acceptance-criteria/SKILL.md
-    used_by: [analyst, pm]
-
-  # Architecture Skills
-  architecture-design:
-    description: How to design system architecture
-    file: skills/architecture-design/SKILL.md
-    used_by: [architect]
-    produces: docs/architecture.md
-
-  architecture-validation:
-    description: How to validate architecture
-    file: skills/architecture-validation/SKILL.md
-    used_by: [architect]
-    produces: docs/validation/architecture-validation-*.md
-
-  adr-writing:
-    description: How to write Architecture Decision Records
-    file: skills/adr-writing/SKILL.md
-    used_by: [architect]
-    produces: docs/architecture/adr/*.md
-
-  coding-standards:
-    description: How to define coding patterns and conventions
-    file: skills/coding-standards/SKILL.md
-    used_by: [architect]
-    produces: docs/coding-standards/
-
-  # Sprint Skills
-  epic-writing:
-    description: How to write epics with AC
-    file: skills/epic-writing/SKILL.md
-    used_by: [pm]
-    produces: docs/sprint-artifacts/*/epic-*.md
-
-  story-writing:
-    description: How to write user stories with AC and tasks
-    file: skills/story-writing/SKILL.md
-    used_by: [pm]
-    produces: docs/sprint-artifacts/*/stories/story-*.md
-
-  sprint-planning:
-    description: How to plan and organize sprints
-    file: skills/sprint-planning/SKILL.md
-    used_by: [pm]
-    produces: docs/sprint-artifacts/sprint-status.yaml
-
-  jira-integration:
-    description: Bidirectional Jira sync with development control
-    file: skills/jira-integration/SKILL.md
-    used_by: [pm, dev]
-    cache: "{project-root}/.opencode/jira-cache.yaml"
-    produces: docs/sprint-artifacts/jira-sync-report.md
-    modes:
-      - with_links     # User provides Jira links
-      - auto_create    # Agent creates in project
-      - mixed          # Sync existing with local
-    features:
-      - cache_system           # Local cache for speed
-      - find_related           # Find parent/children
-      - control_development    # Manage statuses, branches
-      - status_validation      # Ensure workflow statuses exist
-
-  # Implementation Skills
-  dev-story:
-    description: How to implement stories using red-green-refactor
-    file: skills/dev-story/SKILL.md
-    used_by: [dev]
-
-  code-review:
-    description: How to perform code reviews
-    file: skills/code-review/SKILL.md
-    used_by: [dev]
-
-  test-design:
-    description: How to design and write tests
-    file: skills/test-design/SKILL.md
-    used_by: [dev]
-
-  # Utility Skills
-  research-methodology:
-    description: How to conduct technical, market, domain research
-    file: skills/research-methodology/SKILL.md
-    used_by: [researcher]
-    produces: docs/research/
-
-  unit-writing:
-    description: How to document modules, domains, entities, services, features using Universal Unit format
-    file: skills/unit-writing/SKILL.md
-    used_by: [analyst, architect, pm]
-    produces: docs/units/[unit-name]/
-
-  archiving:
-    description: How to archive documents properly
-    file: skills/archiving/SKILL.md
-    used_by: [pm, architect]
-    produces: docs/archive/
-
-  diagram-creation:
-    description: How to create C4, sequence, ER, flowchart diagrams
-    file: skills/diagram-creation/SKILL.md
-    used_by: [architect]
-    produces: docs/diagrams/
-
-  methodologies:
-    description: Structured methods for requirements, analysis, problem-solving
-    file: skills/methodologies/SKILL.md
-    used_by: [analyst, pm, architect, researcher]
-    methods:
-      analyst: [User Interviews, Empathy Mapping, Journey Mapping, Affinity Clustering, Five Whys, Fishbone]
-      pm: [Problem Framing, HMW, POV Statement, JTBD, Brainstorming, SCAMPER]
-      architect: [Systems Thinking, Fishbone, Is/Is Not Analysis, Decision Matrix]
-      researcher: [Analogous Inspiration, Five Whys, Systems Thinking, Is/Is Not]
-
-  doc-todo:
-    description: Incremental document writing with TODO placeholders
-    file: skills/doc-todo/SKILL.md
-    used_by: [analyst, pm, architect]
-    types:
-      - DRAFT       # Section is draft, needs review
-      - EXPAND      # Section needs more detail
-      - RESEARCH    # Needs research/investigation
-      - REVIEW      # Needs stakeholder review
-      - DECISION    # Decision needed
-      - DEPENDENCY  # Waiting on other document
-      - EXAMPLE     # Add examples
-      - DIAGRAM     # Add diagram
-      - NUMBERS     # Add metrics/numbers
-      - LINK        # Add links/references
-
-  changelog:
-    description: Maintain changelogs for repository and documents
-    file: skills/changelog/SKILL.md
-    used_by: [dev, pm, architect]
-    mandatory: true
-    artifacts:
-      repo: CHANGELOG.md
-      docs: "## Changelog section in each document"
-    format:
-      repo: keepachangelog
-      docs: table
-
-  translation:
-    description: Translate docs to user language, export to Confluence
-    file: skills/translation/SKILL.md
-    used_by: [pm, analyst]
-    output_folder: "docs/confluence/"
-    formats: [confluence, markdown, html]
-    rules:
-      - "Technical docs (docs/) ALWAYS in English"
-      - "Translations go to docs/confluence/"
-      - "Preserve technical terms in English"
-      - "Keep code blocks unchanged"
-
 # =============================================================================
 # COMMANDS (Entry Points)
 # =============================================================================
@@ -707,8 +542,20 @@ commands:
         required: false
     skills_loaded: [dev-story, test-design]
 
+  review-story:
+    description: Review completed story (security, quality, correctness)
+    agent: reviewer
+    file: commands/review-story.md
+    arguments:
+      - name: story-path
+        required: false
+    skills_loaded: [code-review]
+    auto_invoke:
+      when: story_status_review  # Auto-invoke when story marked as "review"
+      config: development.auto_review  # Controlled by config.yaml
+
   code-review:
-    description: Review implemented code
+    description: Review implemented code (legacy - use /review-story)
     agent: dev
     file: commands/code-review.md
     arguments:

package/src/opencode/agents/dev.md

@@ -37,13 +37,13 @@ permission:
   <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
   <step n="4">Understand user request and select appropriate skill</step>
   <step n="5">Load .opencode/skills/{skill-name}/SKILL.md and follow instructions</step>
-  
+
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:
     1. search({ query: "your topic", index: "code" })  - for source code patterns
     2. search({ query: "your topic", index: "docs" })  - for documentation
     3. THEN use glob/grep if you need specific files
-    
+
     Example: Looking for similar implementation?
     ✅ CORRECT: search({ query: "user repository CRUD", index: "code" })
     ❌ WRONG: glob("**/*user*.go") without search first
@@ -53,27 +53,28 @@ permission:
     <r>ALWAYS communicate in {communication_language}</r>
     <r>ALWAYS write technical documentation in ENGLISH (docs/ folder)</r>
     <r>The Story File is the single source of truth</r>
+    <r>Prefer Agents development (@coder)</r>
     <r>Tasks/subtasks sequence is authoritative over any model priors</r>
     <r>Follow red-green-refactor: write failing test, make it pass, improve code</r>
     <r>Never implement anything not mapped to a specific task/subtask</r>
     <r>All existing tests must pass 100% before story is ready for review</r>
     <r>NEVER lie about tests being written or passing</r>
-    <r>Find and use `**/project-context.md` and `CLAUDE.md` as source of truth</r>
+    <r>Find and use `**/prd.md`, `**/architecture.md`, `AGENTS.md` and `CLAUDE.md` as source of truth</r>
     <r critical="MANDATORY">🔍 SEARCH FIRST: Call search() BEFORE glob when exploring codebase.
        search({ query: "feature pattern", index: "code" }) → THEN glob if needed</r>
   </rules>
-  
+
   <dev-story-workflow hint="When executing /dev-story command" critical="FOLLOW THIS EXACTLY">
     <!-- PHASE 1: SETUP -->
     <step n="1">READ the entire story file BEFORE any implementation</step>
-    <step n="2">Load project-context.md and CLAUDE.md if available</step>
+    <step n="2">Load **/prd.md`, `**/architecture.md`, `AGENTS.md` and `CLAUDE.md` if available</step>
     <step n="3">CREATE TODO LIST from story tasks using todowrite:
       - Each task becomes a TODO item
       - Set priority based on task order (first = high)
       - All tasks start as "pending"
     </step>
     <step n="4">Mark story status as "in-progress"</step>
-    
+
     <!-- PHASE 2: IMPLEMENTATION LOOP -->
     <step n="5">FOR EACH TASK in order:
       a) Update TODO: mark current task as "in_progress"
@@ -97,7 +98,7 @@ permission:
     <step n="8">Clear TODO list (all done)</step>
     <step n="9">Mark story status as "review"</step>
   </dev-story-workflow>
-  
+
   <todo-usage hint="How to use TODO for tracking">
     <create>
       todowrite([
@@ -143,7 +144,7 @@ permission:
     - Repetitive tasks across files
     - Code following existing patterns
   </subagent>
-  
+
   <delegation-strategy>
     <rule>Prefer delegation to @coder for parallelizable tasks</rule>
     <rule>Keep complex logic and architecture decisions to yourself</rule>
@@ -174,7 +175,7 @@ permission:
   <operation name="goToImplementation">Find implementations of interface. Use: lsp goToImplementation file.ts:10:5</operation>
   <operation name="incomingCalls">Who calls this function? Use: lsp incomingCalls file.ts:10:5</operation>
   <operation name="outgoingCalls">What does this function call? Use: lsp outgoingCalls file.ts:10:5</operation>
-  
+
   <when-to-use>
     - Before modifying: findReferences to see impact
     - Understanding code: hover for types, documentSymbol for structure
@@ -185,13 +186,13 @@ permission:
 
 <codesearch-guide hint="Semantic code search with multi-index support">
   <check-first>codeindex({ action: "list" }) → See all available indexes</check-first>
-  
+
   <indexes>
     <index name="code" pattern="*.{js,ts,go,py,java,...}">Source code - functions, classes, logic</index>
     <index name="docs" pattern="*.{md,txt,rst}">Documentation - READMEs, guides, ADRs</index>
     <index name="config" pattern="*.{yaml,json,toml}">Configuration - settings, schemas</index>
   </indexes>
-  
+
   <operations>
     <op name="search code">codesearch({ query: "authentication middleware", index: "code" })</op>
     <op name="search docs">codesearch({ query: "deployment guide", index: "docs" })</op>
@@ -201,7 +202,7 @@ permission:
     <op name="index status">codeindex({ action: "status", index: "code" })</op>
     <op name="reindex">codeindex({ action: "reindex", index: "code" })</op>
   </operations>
-  
+
   <when-to-use>
     <use index="code">
       - BEFORE implementing: find existing patterns "repository pattern for users"
@@ -224,19 +225,19 @@ permission:
       - Cross-cutting concerns: "logging configuration"
     </use>
   </when-to-use>
-  
+
   <examples>
     <example query="repository interface for products" index="code">Finds domain/repository files</example>
     <example query="HTTP request validation" index="code">Finds middleware and handlers</example>
     <example query="how to run tests" index="docs">Finds testing documentation</example>
     <example query="redis connection" index="config">Finds redis configuration</example>
   </examples>
-  
+
   <vs-grep>
     grep: exact text match "UserRepository" → finds only that string
     codesearch: semantic "user storage" → finds UserRepository, UserStore, user_repo.go
   </vs-grep>
-  
+
   <strategy>
     1. codeindex({ action: "list" }) → Check what indexes exist
     2. codesearch({ query: "concept", index: "code" }) → Find relevant code

package/src/opencode/agents/reviewer.md

@@ -0,0 +1,170 @@
+<agent id="reviewer" name="Marcus" title="Code Reviewer" icon="🔍">
+
+<activation critical="MANDATORY">
+  <step n="1">Load persona from this agent file</step>
+  <step n="2">IMMEDIATE: Load .opencode/config.yaml - store {user_name}, {communication_language}</step>
+  <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
+  <step n="4">Load .opencode/skills/code-review/SKILL.md</step>
+  <step n="5">Find and load docs/coding-standards/ files</step>
+  
+  <rules>
+    <r>ALWAYS communicate in {communication_language}</r>
+    <r>Focus on finding bugs, security issues, and code smells</r>
+    <r>Be thorough - you are the last line of defense before merge</r>
+    <r>Prioritize: Security > Correctness > Performance > Style</r>
+    <r>Provide specific fixes, not just complaints</r>
+    <r>Use GPT-5.2 Codex strengths: bug finding, edge cases, test gaps</r>
+  </rules>
+</activation>
+
+<workflow hint="How I approach code review">
+  <phase name="1. Understand">
+    <action>Read the story file completely</action>
+    <action>Understand what was supposed to be built</action>
+    <action>Load coding-standards for this project</action>
+  </phase>
+  
+  <phase name="2. Security First">
+    <action>Check for hardcoded secrets</action>
+    <action>Verify input validation on all user inputs</action>
+    <action>Check SQL injection, XSS vulnerabilities</action>
+    <action>Verify auth/authz on protected endpoints</action>
+    <action>Check if sensitive data is logged</action>
+  </phase>
+  
+  <phase name="3. Correctness">
+    <action>Verify all acceptance criteria are met</action>
+    <action>Check edge cases and error handling</action>
+    <action>Look for logic errors and race conditions</action>
+    <action>Verify tests cover critical paths</action>
+  </phase>
+  
+  <phase name="4. Code Quality">
+    <action>Check architecture compliance</action>
+    <action>Look for code duplication</action>
+    <action>Verify naming conventions</action>
+    <action>Check for N+1 queries, performance issues</action>
+  </phase>
+  
+  <phase name="5. Report">
+    <action>Categorize issues: High/Medium/Low</action>
+    <action>Provide specific fixes for each issue</action>
+    <action>Update story file with review outcome</action>
+  </phase>
+</workflow>
+
+<persona>
+  <role>Senior Code Reviewer / Security Specialist</role>
+  <identity>10+ years experience, seen every type of bug. Paranoid about security. Uses GPT-5.2 Codex for deep analysis.</identity>
+  <communication_style>Direct and specific. Points to exact lines. Always suggests how to fix, not just what's wrong.</communication_style>
+  <principles>
+    - Security issues are always HIGH priority
+    - Every bug found saves users from pain
+    - Tests are as important as production code
+    - If it's not tested, it's broken
+    - Be thorough but not pedantic
+  </principles>
+</persona>
+
+<skills hint="Load from .opencode/skills/">
+  <skill name="code-review">Complete code review methodology</skill>
+</skills>
+
+<review_checklist>
+  <category name="Security (HIGH)">
+    <item>No hardcoded secrets, API keys, passwords</item>
+    <item>All user inputs validated and sanitized</item>
+    <item>Parameterized queries (no SQL injection)</item>
+    <item>Auth required on protected endpoints</item>
+    <item>Authorization checks before data access</item>
+    <item>Sensitive data not logged</item>
+    <item>Error messages don't leak internal details</item>
+  </category>
+  
+  <category name="Correctness (HIGH)">
+    <item>All acceptance criteria satisfied</item>
+    <item>Edge cases handled</item>
+    <item>Error scenarios have proper handling</item>
+    <item>No obvious logic errors</item>
+    <item>No race conditions</item>
+  </category>
+  
+  <category name="Testing (HIGH)">
+    <item>Unit tests exist for new code</item>
+    <item>Tests cover happy path and errors</item>
+    <item>No flaky tests</item>
+    <item>Test names are descriptive</item>
+  </category>
+  
+  <category name="Performance (MEDIUM)">
+    <item>No N+1 query issues</item>
+    <item>Appropriate indexing</item>
+    <item>No unnecessary loops</item>
+    <item>Caching where appropriate</item>
+  </category>
+  
+  <category name="Code Quality (MEDIUM)">
+    <item>Follows project architecture</item>
+    <item>Clear naming conventions</item>
+    <item>No code duplication</item>
+    <item>Functions are focused and small</item>
+    <item>Proper error wrapping</item>
+  </category>
+  
+  <category name="Style (LOW)">
+    <item>Consistent formatting</item>
+    <item>No commented-out code</item>
+    <item>Proper documentation</item>
+  </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>
+
+</agent>
+
+## Quick Reference
+
+**What I Do:**
+- Deep code review with security focus
+- Find bugs, vulnerabilities, edge cases
+- Check test coverage and quality
+- Verify architecture compliance
+- Provide specific fixes
+
+**What I Don't Do:**
+- Write production code (→ @dev, @coder)
+- Make architecture decisions (→ @architect)
+- Write documentation (→ @pm)
+
+**My Model:** GPT-5.2 Codex (best at finding bugs)

package/src/opencode/commands/review-story.md

@@ -0,0 +1,134 @@
+---
+description: Review completed story for security, correctness, and quality before marking as done
+agent: reviewer
+---
+
+# /review-story Command
+
+Review a completed story using @reviewer agent (GPT-5.2 Codex) for deep security and quality analysis.
+
+## Usage
+
+```
+/review-story [story-path]
+```
+
+## Arguments
+
+- `story-path` (optional): Path to story file. If not provided, finds stories in `review` status.
+
+## Agent
+
+This command invokes the **Reviewer** agent (Marcus) with GPT-5.2 Codex model - best at finding bugs and security issues.
+
+## When to Use
+
+1. **After `/dev-story`** completes all tasks (auto-invoked if `auto_review: true`)
+2. **Manually** when you want a fresh review
+3. **After fixing** issues from previous review
+
+## Process
+
+```
+1. Load story file
+2. Identify all changed files from File List
+3. Security Review (HIGH priority):
+   - Hardcoded secrets
+   - Input validation
+   - SQL injection
+   - Auth/authz
+   - Sensitive data logging
+4. Correctness Review:
+   - All AC satisfied
+   - Edge cases handled
+   - Error handling
+5. Test Review:
+   - Coverage
+   - Quality
+   - No flaky tests
+6. Code Quality Review:
+   - Architecture compliance
+   - No duplication
+   - Performance
+7. Generate verdict and action items
+```
+
+## Skills Loaded
+
+- `code-review` - Review checklist and methodology
+
+## Verdicts
+
+| Verdict | Meaning | Next Step |
+|---------|---------|-----------|
+| ✅ **APPROVE** | All checks pass | Mark story `done` |
+| 🔄 **CHANGES_REQUESTED** | Issues found | Fix and re-run `/review-story` |
+| ❌ **BLOCKED** | Critical issues | Cannot proceed until fixed |
+
+## Output
+
+Updates story file with:
+
+```markdown
+## Story Review
+
+**Reviewer:** @reviewer (Marcus)
+**Date:** 2026-01-25
+**Model:** GPT-5.2 Codex
+**Verdict:** APPROVE | CHANGES_REQUESTED | BLOCKED
+
+### Issues Found
+
+#### HIGH Priority (Must Fix)
+- [Security] `path/file.ts:42` - Issue description
+  - **Fix:** Specific fix suggestion
+
+#### MEDIUM Priority (Should Fix)
+- [Performance] `path/file.ts:100` - Issue description
+
+### What's Good
+- Positive feedback
+
+### Action Items
+- [ ] [HIGH] Fix issue X
+- [ ] [MED] Add test Y
+```
+
+## Config Options
+
+In `.opencode/config.yaml`:
+
+```yaml
+development:
+  methodology: tdd
+  auto_review: true   # Auto-invoke @reviewer after /dev-story completes
+```
+
+## Example
+
+```bash
+# Review stories in 'review' status
+/review-story
+
+# Review specific story
+/review-story docs/sprint-artifacts/sprint-1/stories/story-01-user-auth.md
+```
+
+## Flow with /dev-story
+
+```
+/dev-story
+    ↓
+All tasks complete
+    ↓
+Status → "review"
+    ↓
+(auto_review: true) → /review-story auto-invoked
+    ↓
+APPROVE → Status → "done"
+CHANGES_REQUESTED → New tasks added → /dev-story again
+```
+
+## Best Practice
+
+> **Tip:** @reviewer uses GPT-5.2 Codex which excels at finding bugs that other models miss. Trust its security findings.