@comfanion/workflow 4.37.2 → 4.38.1-dev.1

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

@@ -0,0 +1,110 @@
+---
+name: dev-epic
+description: Use when executing a full epic, including all stories, reviews, and tests, with auto-compaction.
+metadata:
+  domain: development
+  agents: [dev]
+  artifacts: epic state file, story files
+---
+
+# Dev Epic Skill
+
+<workflow name="dev-epic">
+
+  <phase name="1-context" title="Load Minimal Context">
+    <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>
+    </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>
+  </phase>
+
+  <phase name="2-init" title="Initialize Epic">
+    <step n="1">Parse epic file → extract story list</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:
+      ```
+      [ ] Story 1: [Title]
+      [ ] Review Story 1
+      [ ] Story 2: [Title]
+      [ ] Review Story 2
+      ...
+      [ ] Epic integration tests
+      [ ] Verify epic AC
+      ```
+    </step>
+    <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">
+    <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
+      </action>
+      
+      <action name="mark-done">
+        Mark story as completed in epic TODO
+      </action>
+      
+      <action name="review">
+        Mark "Review Story" as in_progress
+        Invoke @reviewer
+        <if condition="CHANGES_REQUESTED">
+          Add fix tasks → re-execute → re-review (max 3 attempts)
+        </if>
+        <if condition="APPROVED">
+          Mark "Review Story" as completed
+        </if>
+      </action>
+      
+      <action name="update-state">
+        Edit epic state file:
+        - Move story to completed_stories
+        - Increment current_story_index
+        - Set next_action to next story
+      </action>
+      
+      <action name="compact">
+        Mark next story as in_progress in TODO
+        Wait for auto-compaction
+        Plugin reads TODO + state → 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>
+  </phase>
+
+</workflow>
+
+<outputs>
+  - Implementation code for all stories
+  - Updated epic-XX-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>
+  <dont>Ask user for confirmation between stories — TODO is your guide</dont>
+  <dont>Proceed to next story if review fails — enter fix loop</dont>
+</rules>

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

@@ -0,0 +1,106 @@
+---
+name: dev-sprint
+description: Use when executing a full sprint, including all epics, stories, reviews, and tests, with auto-compaction.
+metadata:
+  domain: development
+  agents: [dev]
+  artifacts: sprint-status.yaml, epic state files, story files
+---
+
+# Dev Sprint Skill
+
+<workflow name="dev-sprint">
+
+  <phase name="1-context" title="Load Minimal Context">
+    <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>
+    </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>
+  </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:
+      ```
+      [ ] 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
+      ```
+    </step>
+    <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">
+    <for-each item="epic" in="pending_epics">
+      
+      <action name="execute-epic">
+        Follow dev-epic skill logic:
+        - Creates nested TODO for stories
+        - Executes all stories + reviews
+        - Clears epic TODO when done
+      </action>
+      
+      <action name="mark-done">
+        Mark epic as completed in sprint TODO
+      </action>
+      
+      <action name="epic-review">
+        Mark "Review Epic" as in_progress
+        Run epic integration tests
+        Mark "Review Epic" as completed
+      </action>
+      
+      <action name="update-state">
+        Edit sprint-status.yaml:
+        - Set completed epic status="done"
+        - Set next epic status="in-progress"
+      </action>
+      
+      <action name="compact">
+        Mark next epic as in_progress in TODO
+        Wait for auto-compaction
+        Plugin reads sprint TODO → 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>
+  </phase>
+
+</workflow>
+
+<outputs>
+  - Implementation code for all stories in sprint
+  - Updated sprint-status.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>
+  <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>
+</rules>

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

@@ -11,53 +11,71 @@ metadata:
 
 # Dev Story Skill
 
-How to transform story tasks into executable instructions for @coder.
-
-## Task Transformation
-
-Story task is specification with Approach steps. Transform it into executable instruction with full context.
-
-### Step 1: Read Required Reading
-
-Story has "Required Reading" and task has "Read First":
-1. Open each linked document
-2. Find the specific sections mentioned
-3. Extract patterns, signatures, constraints
-
-### Step 2: Find Existing Code
-
-From "Read First" paths:
-1. Read existing similar code (e.g., "existing service example")
-2. Note the structure, imports, error handling
-3. This becomes "Pattern Reference" for @coder
-
-### Step 3: Build Context
-
-@coder doesn't see story. Provide:
-- **Existing files** - actual paths with what they contain
-- **Patterns to follow** - link to existing similar code
-- **What was done** - results of previous tasks this depends on
-- **Imports** - what packages to use
-
-### Step 4: Add Direction
-
-Story has "Approach" with high-level steps. Expand with:
-- Interface signatures (method names, params, return types)
-- Error handling approach (what errors to return)
-- Validation rules (what to validate)
-- Constraints from documentation
-
-### Step 5: Make Verification Concrete
-
-Story has "Done when". Add:
-- Specific test commands to run
-- Files that must compile
-- Test coverage expectations
-
-## Formulating Task for @coder
-
-Structure:
-```
+<workflow name="dev-story">
+
+  <phase name="1-context" title="Load Minimal Context">
+    <read>
+      <file>CLAUDE.md</file>
+      <file>docs/coding-standards/README.md</file>
+      <file>docs/coding-standards/patterns.md</file>
+      <file>{story-file}</file>
+    </read>
+    <skip reason="too large, story has context">
+      <file>docs/prd.md</file>
+      <file>docs/architecture.md</file>
+    </skip>
+    <goal>~70KB context, not 200KB+</goal>
+  </phase>
+
+  <phase name="2-transform" title="Transform Story Task → Executable Instruction">
+    <step n="1" name="read-docs">
+      Story has "Required Reading", task has "Read First".
+      Open each → find sections → extract patterns, signatures, constraints.
+    </step>
+    <step n="2" name="find-patterns">
+      From "Read First" paths, find existing similar code.
+      Note structure, imports, error handling → becomes "Pattern Reference".
+    </step>
+    <step n="3" name="build-context">
+      @coder doesn't see story. Provide:
+      - Existing files (paths + what they contain)
+      - Patterns to follow (link to similar code)
+      - What was done (results of previous tasks)
+      - Imports (what packages to use)
+    </step>
+    <step n="4" name="add-direction">
+      Story has "Approach". Expand with:
+      - Interface signatures (method names, params, return types)
+      - Error handling (what errors to return)
+      - Validation rules
+    </step>
+    <step n="5" name="verification">
+      Story has "Done when". Add:
+      - Specific test commands
+      - Files that must compile
+      - Test coverage expectations
+    </step>
+  </phase>
+
+  <phase name="3-delegate" title="Delegate to @coder">
+    <action>Formulate task using template below</action>
+    <action>Call @coder with full context</action>
+    <rule>@coder writes code. Give direction, NOT solution.</rule>
+  </phase>
+
+  <phase name="4-verify" title="Verify & Mark Done">
+    <action>Run tests</action>
+    <action>Check "Done when" criteria</action>
+    <action>Mark task ✅ in story file</action>
+    <next>Next task or story complete</next>
+  </phase>
+
+</workflow>
+
+## Task Template for @coder
+
+<template name="coder-task">
+```markdown
 ## Task: [Name] (Task IDs)
 
 [One line goal]
@@ -66,89 +84,67 @@ Structure:
 - Use `doc-todo` for TODO comments
 
 ### Context
-- [Existing file]: [What it contains, what to use from it]
-- [Another file]: [Description]
-- Existing pattern: [Path to similar code to follow]
+- [Existing file]: [what to use from it]
+- Existing pattern: [path to similar code]
 
 ### Output Files
-- [Path to create/modify]
+- [path/to/create.ext]
 
 ### Requirements
-[Numbered list of what to implement with signatures/details]
+1. [What to implement with signatures]
+2. [Another requirement]
 
 ### Pattern Reference
-[Link to existing similar code to follow, NOT ready implementation]
+→ [path/to/similar/code.ext]
 
 ### Error Handling
 [How to handle errors]
 
 ### Done When
-- [ ] [Specific checkable item]
-- [ ] [Another item]
 - [ ] File compiles
 - [ ] Tests pass
+- [ ] [Specific criterion]
 ```
-
-## Parallel Tasks
-
-When delegating multiple tasks in one message:
-1. Each task gets full context (don't assume @coder remembers)
-2. Clearly separate tasks with headers
-3. No shared state between parallel tasks
-4. Tasks must work on different files
-
-## Task Boundaries
-
-**Good task:**
-- Logically complete unit (service, handler, entity, feature)
-- Clear single responsibility
-- Can be tested independently
-
-**Consider splitting when:**
-- Multiple unrelated responsibilities
-- No logical connection between parts
-
-**Consider combining when:**
-- Tasks too granular to be meaningful
-- Same file, same concern
-
-## Common Patterns
-
-### New Service
-Context: domain entities, repository interface, existing service example
-Requirements: interface, constructor, methods
-Pattern: existing service structure
-
-### New Handler
-Context: service interface, DTOs, existing handler example
-Requirements: handler struct, methods, error mapping
-Pattern: existing handler structure
-
-### New Tests
-Context: code to test, existing test examples
-Requirements: test scenarios, mocks
-Pattern: existing test structure
-
-## Implementation is @coder's Job
-
-**DO NOT give ready code. Give direction.**
-
-✅ **DO provide:**
-- Links to existing code as pattern reference
-- Interface signatures (method names, params, return types)
-- Requirements (what logic to implement)
-- Error handling approach
-- Validation rules
-
-❌ **DO NOT provide:**
-- Full method implementations
-- Ready-to-copy code blocks
-- Complete structs with all logic
-
-**@coder writes the implementation.** Give direction, not solution.
-
-## Methodology
-
-Include in task based on config.yaml:
-- **TDD**: "Write failing test first, then implement"
-- **STUB**: "Create stub first, write tests, then real implementation"
+</template>
+
+<rules name="delegation">
+  <rule name="parallel">
+    Each task gets full context. No shared state. Different files only.
+  </rule>
+  <rule name="no-code">
+    Give direction, NOT solution. @coder writes implementation.
+  </rule>
+  <rule name="methodology">
+    TDD: "Write failing test first, then implement"
+    STUB: "Create stub first, write tests, then implement"
+  </rule>
+</rules>
+
+<task-boundaries>
+  <good>Logically complete unit (service, handler, entity). Single responsibility. Testable independently.</good>
+  <split-when>Multiple unrelated responsibilities. No logical connection.</split-when>
+  <combine-when>Too granular. Same file, same concern.</combine-when>
+</task-boundaries>
+
+<patterns>
+  <pattern name="new-service">
+    Context: domain entities, repository interface, existing service
+    Requirements: interface, constructor, methods
+    Pattern: existing service structure
+  </pattern>
+  <pattern name="new-handler">
+    Context: service interface, DTOs, existing handler
+    Requirements: handler struct, methods, error mapping
+    Pattern: existing handler structure
+  </pattern>
+  <pattern name="new-tests">
+    Context: code to test, existing test examples
+    Requirements: test scenarios, mocks
+    Pattern: existing test structure
+  </pattern>
+</patterns>
+
+<critical>
+  ✅ PROVIDE: pattern references, interface signatures, requirements, error approach
+  ❌ DO NOT: full implementations, ready-to-copy code, complete structs
+</critical>

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

@@ -183,6 +183,8 @@ Table + dependency diagram:
 | S01-01 | Task Domain | M | → Unit: `Task` | ⬜ |
 | S01-02 | Task Repository | M | → Unit: `Task` | ⬜ |
 
+**Size Guide:** Prefer S→M or M. (S=2-4 tasks, M=4-8 tasks, L=8+ tasks)
+
 ```
 S01 ──► S02 ──► S03
 ```

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

@@ -70,7 +70,7 @@ Use template at: `@.opencode/skills/story-writing/template.md`
 id: {{PREFIX}}-S{{E}}-{{N}}
 epic: {{PREFIX}}-E{{E}}
 status: draft | ready | in_progress | review | done
-size: S | M | L
+size: S | M | L   # Prefer S→M or M. S=2-4 tasks, M=4-8 tasks, L=8+ tasks
 ```
 
 ### 2. Goal