@comfanion/workflow 4.38.0-dev.1 → 4.38.1-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.0-dev.1",
+  "version": "4.38.1-dev.2",
   "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.0-dev.1",
-  "buildDate": "2026-01-26T23:39:37.098Z",
+  "version": "4.38.1-dev.2",
+  "buildDate": "2026-01-27T01:09:08.937Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/commands/dev-epic.md

@@ -5,165 +5,15 @@ agent: dev
 
 # /dev-epic Command
 
-Implement entire epic by executing all stories with automatic compaction and context preservation.
+Implement an entire epic by following the `dev-epic` skill.
 
 ## Process
 
-### Phase 1: Epic Setup
-1. Find or load epic file (from path or sprint-status.yaml)
-2. Parse all story references from epic
-3. Load project context (CLAUDE.md, docs/prd.md, docs/architecture.md)
-4. **Create TODO list from epic** (critical for compaction!):
-   - Parse epic file, extract all stories
-   - For each story: read story file, count tasks
-   - Add stories to TODO with task counts
-   - Add epic-level tasks (integration tests, acceptance criteria)
-   ```
-   [ ] Story 1: User Registration (12 tasks)
-   [ ] Story 2: Login Flow (8 tasks)
-   [ ] Story 3: Password Reset (6 tasks)
-   [ ] Run epic integration tests
-   [ ] Verify all acceptance criteria
-   ```
-5. **Create epic state file:** `docs/sprint-artifacts/sprint-N/.sprint-state/epic-XX-state.yaml`
-6. Mark epic as `in-progress`
-
-### Phase 2: Story Execution Loop (for each story)
-
-7. **Mark story as `in_progress` in TODO** (e.g., "Story 1: User Registration")
-8. Execute story via `/dev-story` workflow:
-   - RED → GREEN → REFACTOR
-   - @coder implements tasks
-   - @reviewer validates (if auto_review: true)
-9. **Mark story as `completed` in TODO** (✓ Story 1: User Registration)
-10. **Update epic state file**:
-   - Move story from `pending_stories` → `completed_stories`
-   - Add metadata (tasks_completed, tests_added, review_status)
-   - Increment `current_story_index`
-   - Set `next_action: "Execute story-XX-XX.md"` (next story filename)
-   - Update `last_compaction` timestamp
-11. **Trigger compaction** (if `epic_workflow.auto_compact: true`)
-12. **After compaction:** 
-    - Plugin reads TODO → sees next pending story
-    - Plugin reads epic state → gets story path
-    - Agent continues next story automatically
-
-### Phase 3: Epic Completion
-
-13. All stories done → **mark integration test TODO as `in_progress`**
-14. Run epic integration tests (if configured)
-15. **Mark integration test TODO as `completed`**
-16. Update epic state: `status: "done"`
-17. **Clear TODO** (all tasks done)
-18. Generate epic summary
-
-## TODO List
-
-**Create at epic start:**
-```
-[ ] Story 1: User Registration
-[ ] Story 2: Login Flow  
-[ ] Story 3: Password Reset
-[ ] Run epic integration tests
-[ ] Verify acceptance criteria
-```
-
-**Update after each story:**
-- Mark story `completed` in TODO
-- Mark next story `in_progress` in TODO
-- TODO survives compaction - plugin shows it to agent
-
-## Epic State File Format
-
-**Location:** `docs/sprint-artifacts/sprint-N/.sprint-state/epic-XX-state.yaml`
-
-```yaml
-epic_id: "PROJ-E01"
-epic_title: "User Authentication"
-epic_path: "docs/sprint-artifacts/backlog/epic-01-user-auth.md"
-sprint: "sprint-1"
-status: "in-progress"
-
-current_story_index: 1
-total_stories: 3
-
-completed_stories:
-  - path: "docs/sprint-artifacts/sprint-1/stories/story-01-01-registration.md"
-    title: "User Registration"
-    tasks_completed: 12
-    tests_added: 45
-    review_status: "approved"
-    completed_at: "2026-01-27T10:15:00Z"
-
-pending_stories:
-  - path: "docs/sprint-artifacts/sprint-1/stories/story-01-02-login.md"
-    title: "Login Flow"
-  - path: "docs/sprint-artifacts/sprint-1/stories/story-01-03-password-reset.md"
-    title: "Password Reset"
-
-next_action: "Execute story-01-02-login.md"
-last_compaction: "2026-01-27T10:15:00Z"
-```
-
-## Compaction Strategy
-
-**After compaction, agent reads (minimal context):**
-1. Epic state file (progress + next action)
-2. Next story file (from `next_action`)
-3. CLAUDE.md, docs/prd.md, docs/architecture.md
-
-**Agent does NOT re-read:**
-- ❌ Epic file (info in state)
-- ❌ Completed stories
-- ❌ Previous tasks
-
-**Context savings: ~68% less than reading all files**
-
-## Configuration
-
-From `config.yaml → epic_workflow`:
-
-```yaml
-epic_workflow:
-  auto_compact: true              # Compact between stories
-  auto_fix: true                  # Auto-fix review issues
-  max_fix_attempts: 3             # Max fix attempts before HALT
-  pause_between_stories: false    # Continue automatically
-  test_after_each_story: false    # Skip per-story integration tests
-  test_after_epic: true           # Run epic integration tests at end
-```
+1.  **Load Skill**: Read and follow the instructions in `.opencode/skills/dev-epic/SKILL.md`.
+2.  **Initialize**: Create the epic-level TODO list and the epic state file as described in the skill.
+3.  **Execute**: Enter the story -> review -> compact -> loop until all stories in the TODO list are complete.
+4.  **Finalize**: Run final tests and report completion.
 
 ## IMPORTANT SKILLS TO LOAD
 
-- `dev-story` - Story implementation workflow
-- `test-design` - Test writing patterns
-- `code-review` - Review and validation
-
-## Output
-
-- All story implementations (code + tests)
-- Epic state file (updated)
-- Updated epic file (stories marked `[x]`)
-- Epic summary report
-
-## HALT Conditions
-
-The workflow will HALT and ask for input when:
-- Story fails 3 times (implementation/tests)
-- Code review fails after max_fix_attempts
-- Missing dependencies
-- Ambiguous requirements
-- Integration tests fail
-
-## Epic Status Flow
-
-```
-ready-for-dev → in-progress → [story 1] → compact → [story 2] → compact → ... → done
-```
-
-## Next Steps After Completion
-
-- Epic marked `done` in epic state file
-- All stories marked `done`
-- If part of `/dev-sprint`: continue to next epic automatically
-- If standalone: ready for sprint review
+- `dev-epic` - The primary algorithm for this command.

package/src/opencode/commands/dev-sprint.md

@@ -5,174 +5,15 @@ agent: dev
 
 # /dev-sprint Command
 
-Implement entire sprint by executing all epics with automatic compaction.
+Implement an entire sprint by following the `dev-sprint` skill.
 
 ## Process
 
-### Phase 1: Sprint Setup
-1. Find sprint (from number or sprint-status.yaml)
-2. Read `sprint-status.yaml`
-3. Parse all epics in sprint
-4. Load project context (CLAUDE.md, docs/prd.md, docs/architecture.md)
-5. **Create TODO list from sprint** (critical for compaction!):
-   - Parse sprint-status.yaml, extract all epics
-   - For each epic: read epic file, count stories and tasks
-   - Add epics to TODO with story/task counts
-   - Add sprint-level tasks (integration tests, acceptance criteria, metrics)
-   ```
-   [ ] Epic 1: User Authentication (3 stories, 26 tasks)
-   [ ] Epic 2: Product Catalog (5 stories, 42 tasks)
-   [ ] Epic 3: Shopping Cart (4 stories, 31 tasks)
-   [ ] Run sprint integration tests
-   [ ] Verify sprint acceptance criteria
-   [ ] Generate sprint metrics
-   ```
-6. Mark sprint as `in-progress` in sprint-status.yaml
-
-### Phase 2: Epic Execution Loop (for each epic)
-
-7. **Mark epic as `in_progress` in TODO** (e.g., "Epic 1: User Authentication")
-8. Execute epic via `/dev-epic` workflow:
-   - Epic creates its own TODO for stories
-   - Epic executes all stories
-   - Auto-compacts between stories
-   - Auto-fixes code review issues
-9. **Mark epic as `completed` in TODO** (✓ Epic 1: User Authentication)
-10. **Update sprint-status.yaml**:
-    - Mark epic as `done`
-    - Update `stories_completed` count
-    - Find next epic
-11. **Trigger compaction** (if `epic_workflow.auto_compact: true`)
-12. **After compaction:** 
-    - Plugin reads TODO → sees next pending epic
-    - Plugin reads sprint-status.yaml → gets epic path
-    - Agent continues next epic automatically
-
-### Phase 3: Sprint Completion
-
-13. All epics done → **mark integration test TODO as `in_progress`**
-14. Run sprint integration tests (if configured)
-15. **Mark integration test TODO as `completed`**
-16. **Mark acceptance criteria TODO as `in_progress`**
-17. Verify sprint acceptance criteria
-18. **Mark acceptance criteria TODO as `completed`**
-19. **Mark metrics TODO as `in_progress`**
-20. Generate sprint metrics (velocity, completion rate, etc.)
-21. **Mark metrics TODO as `completed`**
-22. Update sprint-status.yaml: `status: "done"`
-23. **Clear TODO** (all tasks done)
-24. Generate sprint summary
-
-## TODO List
-
-**Create at sprint start:**
-```
-[ ] Epic 1: User Authentication (3 stories)
-[ ] Epic 2: Product Catalog (5 stories)
-[ ] Epic 3: Shopping Cart (4 stories)
-[ ] Run sprint integration tests
-[ ] Verify sprint acceptance criteria
-[ ] Generate sprint metrics
-```
-
-**Update after each epic:**
-- Mark epic `completed` in TODO
-- Mark next epic `in_progress` in TODO
-- TODO survives compaction - plugin shows it to agent
-
-**Note:** Each epic creates its own TODO for stories, clears it when done
-
-## Sprint State Tracking
-
-**Location:** `docs/sprint-artifacts/sprint-status.yaml`
-
-```yaml
-sprints:
-  - id: sprint-1
-    name: "Sprint 1 - Core Features"
-    status: in-progress
-    start_date: "2026-01-20"
-    end_date: "2026-02-03"
-    
-    epics:
-      - id: PROJ-E01
-        title: "User Authentication"
-        path: "docs/sprint-artifacts/backlog/epic-01-user-auth.md"
-        status: done
-        stories_completed: 3
-        stories_total: 3
-        
-      - id: PROJ-E02
-        title: "Product Catalog"
-        path: "docs/sprint-artifacts/backlog/epic-02-catalog.md"
-        status: in-progress  # ← Current epic
-        stories_completed: 2
-        stories_total: 5
-        
-      - id: PROJ-E03
-        title: "Shopping Cart"
-        path: "docs/sprint-artifacts/backlog/epic-03-cart.md"
-        status: ready-for-dev
-        stories_total: 4
-```
-
-Each epic also has state file in `.sprint-state/epic-XX-state.yaml`
-
-## Compaction Strategy
-
-**After compaction, agent reads:**
-1. sprint-status.yaml (knows which epic is next)
-2. Next epic file
-3. Next epic state file (if exists)
-4. CLAUDE.md, docs/prd.md, docs/architecture.md
-
-**Agent does NOT re-read:**
-- ❌ Completed epic files
-- ❌ Completed story files
-- ❌ Previous epic states
-
-## Configuration
-
-From `config.yaml → epic_workflow`:
-
-```yaml
-epic_workflow:
-  auto_compact: true              # Compact between epics
-  auto_fix: true                  # Auto-fix review issues
-  pause_between_stories: false    # Continue automatically
-```
+1.  **Load Skill**: Read and follow the instructions in `.opencode/skills/dev-sprint/SKILL.md`.
+2.  **Initialize**: Create the sprint-level TODO list and update `sprint-status.yaml` as described in the skill.
+3.  **Execute**: Enter the epic -> review -> compact -> loop until all epics in the TODO list are complete.
+4.  **Finalize**: Run final sprint tests and report completion.
 
 ## IMPORTANT SKILLS TO LOAD
 
-- `dev-story` - Story implementation workflow
-- `test-design` - Test writing patterns
-- `code-review` - Review and validation
-
-## Output
-
-- All epic implementations (code + tests)
-- Updated sprint-status.yaml
-- Sprint summary report
-- Sprint metrics (velocity, completion rate)
-
-## HALT Conditions
-
-The workflow will HALT and ask for input when:
-- Epic fails repeatedly (3+ failed stories)
-- Multiple stories rejected by @reviewer
-- Sprint deadline approaching (< 20% time, > 50% work)
-- Missing dependencies
-- Sprint integration tests fail
-
-## Sprint Status Flow
-
-```
-planned → in-progress → [epic 1] → compact → [epic 2] → compact → ... → done
-```
-
-## Next Steps After Completion
-
-- Sprint marked `done` in sprint-status.yaml
-- All epics and stories marked `done`
-- Ready for sprint review/retrospective
-- Run `/retrospective` to capture learnings
+- `dev-sprint` - The primary algorithm for this command.

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

@@ -13,8 +13,17 @@ Implement a story using red-green-refactor cycle with TODO tracking.
 1. Find or load story file
 2. Load project context (CLAUDE.md, docs/prd.md, docs/architecture.md)
 3. Use skill dev-story, test-design
-3. **Create TODO list from story tasks** (for progress tracking)
-4. Mark story as `in-progress`
+4. **Create TODO list for full scope of work** (tasks + tests + review):
+   - Parse story file, extract all tasks
+   - Add each task to TODO
+   - **If `config.yaml → development.auto_review: true`**: Add review task to TODO
+   ```
+   [ ] Task 1: Create User entity
+   [ ] Task 2: Add repository
+   [ ] Task 3: Write integration tests
+   [ ] Code review by @reviewer    ← if auto_review: true
+   ```
+5. Mark story as `in-progress`
 
 ### Phase 2: Implementation (for each task)
 5. **Mark task as `in_progress` in TODO**

package/src/opencode/commands/quick.md

@@ -19,26 +19,23 @@ Automatically used when:
 - Single file or < 5 files affected
 - No new requirements needed
 - No architecture changes
-- Estimated time < 2 hours
+- T-shirt size: S or M
 
 ## Quick Workflow
 
 ```
 ┌────────────────────┐
-│ 1. Quick Doc       │  Create minimal change doc
-│    (2-5 min)       │
+│ 1. Quick Doc  [XS] │  Create minimal change doc
 └────────┬───────────┘
          │
          ▼
 ┌────────────────────┐
-│ 2. Implement       │  Make the change
-│    (varies)        │
+│ 2. Implement [S-M] │  Make the change
 └────────┬───────────┘
          │
          ▼
 ┌────────────────────┐
-│ 3. Test & Verify   │  Verify it works
-│    (5-10 min)      │
+│ 3. Test       [XS] │  Verify it works
 └────────┬───────────┘
          │
          ▼
@@ -119,7 +116,7 @@ For valid quick changes:
 ## Quick Change: [Title]
 
 **Scale:** L0 (Hotfix) / L1 (Small)
-**Estimated Time:** [X] minutes/hours
+**Size:** S / M
 
 ### Files to Modify
 

package/src/opencode/config.yaml

@@ -164,7 +164,6 @@ development:
   
   # Task structure
   task:
-    max_hours: 2           # Maximum hours per atomic task
     include_tests: true    # Each task includes test as validation
     require_interface: true # Interface defined before implementation
 

package/src/opencode/opencode.json

@@ -4,9 +4,7 @@
   "instructions": [
     "AGENTS.md",
     ".opencode/FLOW.yaml",
-    ".opencode/config.yaml",
-    "docs/prd.md",
-    "docs/architecture.md"
+    ".opencode/config.yaml"
   ],
   
   "agent": {

package/src/opencode/plugins/custom-compaction.ts

@@ -54,20 +54,18 @@ const BASE_FILES = [
 ]
 
 // Agent-specific file priorities (added to BASE_FILES)
+// These are OPTIONAL files for context, not mandatory
 const AGENT_FILES: Record<string, string[]> = {
   dev: [
     ...BASE_FILES,
     "docs/coding-standards/README.md",
     "docs/coding-standards/patterns.md",
-    "docs/coding-standards/testing.md",
-    "docs/prd.md",
-    "docs/architecture.md",
+    // NO prd.md, NO architecture.md - too large, story has context
     // story path added dynamically
   ],
   coder: [
     ...BASE_FILES,
     "docs/coding-standards/patterns.md",
-    "docs/coding-standards/testing.md",
   ],
   architect: [
     ...BASE_FILES,
@@ -111,20 +109,19 @@ const DEFAULT_FILES = [
 ]
 
 // Files agent MUST Read after compaction (commands generated)
+// MINIMAL CONTEXT: ~70KB for dev, not 200KB+
+// Note: coding-standards/README.md is standard path created by /coding-standards command
 const MUST_READ_FILES: Record<string, string[]> = {
   dev: [
     "AGENTS.md",
     "CLAUDE.md",
-    "docs/prd.md",
-    "docs/architecture.md",
-    // epic state path added dynamically (if in epic workflow)
-    // story path added dynamically
+    "docs/coding-standards/README.md",  // if exists
+    // story/epic state path added dynamically
   ],
   coder: [
     "AGENTS.md",
     "CLAUDE.md",
-    "docs/prd.md",
-    "docs/architecture.md",
+    "docs/coding-standards/README.md",
   ],
   architect: [
     "AGENTS.md",
@@ -136,7 +133,6 @@ const MUST_READ_FILES: Record<string, string[]> = {
     "AGENTS.md",
     "CLAUDE.md",
     "docs/prd.md",
-    "docs/architecture.md",
   ],
   analyst: [
     "AGENTS.md",
@@ -150,8 +146,6 @@ const MUST_READ_FILES: Record<string, string[]> = {
   default: [
     "AGENTS.md",
     "CLAUDE.md",
-    "docs/prd.md",
-    "docs/architecture.md",
   ],
 }
 

package/src/opencode/skills/coding-standards/SKILL.md

@@ -13,9 +13,26 @@ metadata:
 
 You are a Senior Staff Engineer specializing in establishing coding standards. You create **modular documentation** - multiple focused files (1-10 files), each under 2000 lines.
 
-## Core Principle: Modular Documentation
+## Core Principle: README.md is the Main File
 
-**CRITICAL RULE:** Each file MUST be under 2000 lines. Split into multiple files when needed.
+**CRITICAL:** During development, agents read ONLY `README.md` from coding-standards (to save context ~65KB).
+
+Therefore `README.md` MUST contain:
+- **ALL critical rules** (not just links!)
+- **Common patterns with examples**
+- **Naming conventions**
+- **Project structure overview**
+- Links to other files for deep dive
+
+Other files (testing.md, api.md, etc.) are for **deep dive only** - agents read them when story's "Required Reading" points to them.
+
+## Size Guidelines
+
+| File | Max Size | Purpose |
+|------|----------|---------|
+| README.md | 20-30KB | Main file, all critical rules |
+| Other files | 10-20KB each | Deep dive on specific topics |
+| Total | <2000 lines/file | Keep files readable |
 
 ## Documentation Structure
 
@@ -35,7 +52,7 @@ docs/coding-standards/
 
 ## File Templates
 
-### README.md (Index)
+### README.md (Main File - Agents Read This!)
 
 ```markdown
 # Coding Standards
@@ -44,33 +61,72 @@ docs/coding-standards/
 **Tech Stack:** [languages, frameworks]
 **Last Updated:** YYYY-MM-DD
 
-## Quick Reference
+## Project Structure
+
+\`\`\`
+project/
+├── src/              # Source code
+│   ├── modules/      # Business modules (domain, service, handler)
+│   └── internal/     # Shared infrastructure
+├── docs/             # Documentation
+└── tests/            # Test files
+\`\`\`
+
+## Naming Conventions
+
+### Files
+- `snake_case` for files: `user_service.go`, `auth_handler.ts`
+- Test files: `*_test.go`, `*.test.ts`
+
+### Code
+- Types/Classes: `PascalCase` - `UserService`, `AuthHandler`
+- Functions: `camelCase` (TS) or `PascalCase` (Go exported)
+- Variables: `camelCase` - `userId`, `isValid`
+- Constants: `UPPER_SNAKE_CASE` - `MAX_RETRIES`
 
-| Topic | Document | Key Rules |
-|-------|----------|-----------|
-| Project Layout | [project-structure.md](./project-structure.md) | Modules, structure |
-| Go Code | [go-standards.md](./go-standards.md) | Naming, errors, imports |
-| Testing | [testing-standards.md](./testing-standards.md) | 80% coverage, table-driven |
-| API | [api-standards.md](./api-standards.md) | REST, error format |
-| Database | [database-standards.md](./database-standards.md) | Migrations, SQLC |
-| Security | [security-standards.md](./security-standards.md) | Input validation |
-| Libraries | [libraries.md](./libraries.md) | Approved list |
-| Git | [git-workflow.md](./git-workflow.md) | Conventional commits |
+## Common Patterns
+
+### Service Pattern
+[Example of service implementation in your language]
+
+### Repository Pattern
+[Example of repository implementation]
 
-## Critical Rules (MUST follow)
+### Error Handling
+[Example of error handling pattern]
 
-1. [Most important rule]
-2. [Second most important]
-3. [Third most important]
+## Critical Rules
 
-## Getting Started
+1. **No business logic in handlers** - handlers only validate input and call services
+2. **All errors must be wrapped** with context
+3. **No hardcoded values** - use config or constants
+4. **Tests required** for all business logic
 
-New to the project? Read in this order:
-1. [project-structure.md](./project-structure.md)
-2. [[language]-standards.md](./)
-3. [architecture-patterns.md](./architecture-patterns.md)
+## API Response Format
+
+### Success
+\`\`\`json
+{ "data": { ... } }
+\`\`\`
+
+### Error
+\`\`\`json
+{ "error": { "code": "VALIDATION_ERROR", "message": "..." } }
+\`\`\`
+
+## Deep Dive Documents
+
+| Topic | File | When to Read |
+|-------|------|--------------|
+| Testing | [testing.md](./testing.md) | Writing tests |
+| API Design | [api.md](./api.md) | Creating endpoints |
+| Database | [database.md](./database.md) | Schema changes |
+| Security | [security.md](./security.md) | Auth, validation |
+| Git | [git.md](./git.md) | Commits, PRs |
 ```
 
+**Note:** This README should be 20-30KB with real examples, not placeholders.
+
 ### project-structure.md
 
 ```markdown

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

@@ -0,0 +1,122 @@
+---
+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
+
+## 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} — ONE only!</file>
+    </read>
+    <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="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,120 @@
+---
+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
+
+## 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} — ONE only!</file>
+      <file>{current-story-file} — ONE only!</file>
+    </read>
+    <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:
+      ```
+      [ ] 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,82 @@ metadata:
 
 # Dev Story Skill
 
-How to transform story tasks into executable instructions for @coder.
+## CRITICAL: Context Rules
 
-## Task Transformation
+**READ ONLY (max ~70KB):**
+- `CLAUDE.md`
+- `docs/coding-standards/README.md`
+- `docs/coding-standards/patterns.md`
+- Story file
 
-Story task is specification with Approach steps. Transform it into executable instruction with full context.
+**❌ DO NOT READ — WASTES CONTEXT:**
+- ❌ `docs/prd.md` — story already has context
+- ❌ `docs/architecture.md` — too large, coding-standards has patterns
 
-### 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">
+    <critical>DO NOT read prd.md or architecture.md!</critical>
+    <read>
+      <file>CLAUDE.md</file>
+      <file>docs/coding-standards/README.md</file>
+      <file>docs/coding-standards/patterns.md</file>
+      <file>{story-file}</file>
+    </read>
+    <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 +95,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