@comfanion/workflow 4.37.1 → 4.38.0-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.37.1",
+  "version": "4.38.0-dev.1",
   "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.37.1",
-  "buildDate": "2026-01-26T20:31:11.486Z",
+  "version": "4.38.0-dev.1",
+  "buildDate": "2026-01-26T23:39:37.098Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/FLOW.yaml

@@ -254,6 +254,83 @@ pipeline:
     # IMPLEMENTATION PHASE
     # =========================================================================
     
+    - id: dev-sprint
+      name: Sprint Implementation (Full Workflow)
+      description: Implement entire sprint - all epics with auto-compaction
+      phase: implementation
+      command: /dev-sprint [sprint-number]
+      agent: dev
+      skills:
+        - dev-story
+        - test-design
+        - code-review
+      artifacts:
+        input:
+          - docs/sprint-artifacts/sprint-status.yaml
+          - docs/sprint-artifacts/backlog/epic-*.md
+          - CLAUDE.md
+        output:
+          - All epic implementations
+          - Updated sprint-status.yaml
+          - Sprint summary report
+      workflow:
+        description: |
+          Execute all epics in sprint sequentially:
+          1. Read sprint-status.yaml, find epics
+          2. For each epic: /dev-epic → compact
+          3. Continue until all epics done
+          4. Run sprint integration tests
+      config:
+        auto_compact: "config.yaml → epic_workflow.auto_compact"
+        auto_fix: "config.yaml → epic_workflow.auto_fix"
+      next: dev-epic  # Can also run individual epics
+    
+    - id: dev-epic
+      name: Epic Implementation (Full Workflow)
+      description: Implement entire epic - all stories with auto-compaction
+      phase: implementation
+      command: /dev-epic [epic-path]
+      agent: dev
+      skills:
+        - dev-story
+        - test-design
+        - code-review
+      artifacts:
+        input:
+          - docs/sprint-artifacts/backlog/epic-*.md
+          - docs/sprint-artifacts/sprint-*/.sprint-state/epic-*-state.yaml
+          - CLAUDE.md
+        output:
+          - All story implementations
+          - Epic state file (updated)
+          - Epic summary report
+      workflow:
+        description: |
+          Execute all stories in epic sequentially:
+          1. Read epic file, find stories
+          2. For each story: /dev-story → @reviewer → compact
+          3. Auto-fix review issues (max 3 attempts)
+          4. Continue until all stories done
+          5. Run epic integration tests
+        state_management:
+          location: "docs/sprint-artifacts/sprint-N/.sprint-state/epic-XX-state.yaml"
+          preserves:
+            - Current story index
+            - Completed stories
+            - Pending stories
+            - Review status
+        compaction:
+          trigger: "After each story completion"
+          restores:
+            - Epic state file (progress)
+            - Next story file (what to do)
+            - CLAUDE.md, PRD, Architecture (context)
+      config:
+        auto_compact: "config.yaml → epic_workflow.auto_compact"
+        auto_fix: "config.yaml → epic_workflow.auto_fix"
+        max_fix_attempts: "config.yaml → epic_workflow.max_fix_attempts"
+      next: dev-story  # Can also run individual stories
+    
     - id: dev-story
       name: Story Implementation
       description: Implement story using red-green-refactor cycle

package/src/opencode/agents/architect.md

@@ -96,9 +96,31 @@ permission:
   <phase name="1. Discovery">
     <action>Search for related documents (search → then glob/grep if needed)</action>
     <action>Read existing architecture, PRD, related modules</action>
-    <action>If PRD exists: Read "Project Classification" section to understand size</action>
+    <action critical="MANDATORY">Read PRD "Project Classification" section (first section) to understand project size</action>
+    <action>If no PRD: Load skill `architecture-design` → check size guidelines table</action>
     <action>Identify what needs to be created/updated</action>
   </phase>
+  
+  <size-awareness critical="MANDATORY">
+    BEFORE writing architecture, you MUST know project size:
+    
+    1. Read PRD → "Project Classification" section
+    2. Note the size: TOY/SMALL/MEDIUM/LARGE/ENTERPRISE
+    3. Load skill: architecture-design → see size guidelines table
+    4. Adapt your architecture depth:
+       - TOY: 200-500 lines, simple diagram
+       - SMALL: 500-1000 lines, C4 Context+Container+Component
+       - MEDIUM: 1000-2000 lines, full C4 + break into MODULES
+       - LARGE: 2000-4000 lines, multiple files, DOMAINS
+       - ENTERPRISE: 4000+ lines, per-domain files
+    
+    Example:
+    - PRD says "TOY" → Write 350 lines, 3 components, NO modules
+    - PRD says "MEDIUM" → Write 1500 lines, 3 MODULES with Unit docs
+    
+    DON'T write 2000-line architecture for Tetris!
+    DON'T write 500-line architecture for E-commerce!
+  </size-awareness>
 
   <phase name="2. Planning">
     <action>Create tasklist with todowrite()</action>

package/src/opencode/agents/pm.md

@@ -148,8 +148,25 @@ permission:
   <instruction>BEFORE starting ANY work (PRD, epics, stories):</instruction>
   
   <step n="1">If PRD exists: Read "Project Classification" section (first section)</step>
-  <step n="2">If no PRD: Load skill `prd-writing` to understand size classification</step>
-  <step n="3">Adapt your approach based on size</step>
+  <step n="2">If no PRD yet: Load skill `prd-writing` → read "How to Classify Project Size" section</step>
+  <step n="3">Determine project size based on scope/complexity/data/integrations (NOT timeline!)</step>
+  <step n="4">If creating PRD: Fill "Project Classification" section FIRST before writing anything else</step>
+  <step n="5">Adapt your approach based on size</step>
+  
+  <classification-reminder>
+    When creating PRD, you MUST:
+    1. Load skill: prd-writing
+    2. Read the classification guide in the skill
+    3. Ask user about: scope, data model, integrations, team size
+    4. Classify: TOY/SMALL/MEDIUM/LARGE/ENTERPRISE
+    5. Fill Project Classification table in PRD (first section!)
+    6. Then write rest of PRD according to that size
+    
+    Example questions:
+    - "How many database tables do you expect?" (5-10 = SMALL, 20+ = MEDIUM)
+    - "How many external integrations?" (0-2 = SMALL, 3-5 = MEDIUM)
+    - "Is this a single app or multiple modules?" (single = SMALL, modules = MEDIUM)
+  </classification-reminder>
   
   <key-principle>
     TOY/SMALL → Flat structure, no modules

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

@@ -0,0 +1,169 @@
+---
+description: Execute full epic - implement all stories sequentially with auto-compaction between stories
+agent: dev
+---
+
+# /dev-epic Command
+
+Implement entire epic by executing all stories with automatic compaction and context preservation.
+
+## 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
+```
+
+## 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

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

@@ -0,0 +1,178 @@
+---
+description: Execute full sprint - implement all epics sequentially with auto-compaction between epics
+agent: dev
+---
+
+# /dev-sprint Command
+
+Implement entire sprint by executing all epics with automatic compaction.
+
+## 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
+```
+
+## 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

package/src/opencode/config.yaml

@@ -197,6 +197,53 @@ development:
         - NUMBERS     # Add metrics/numbers
         - LINK        # Add links/references
 
+# =============================================================================
+# EPIC WORKFLOW (/dev-epic command)
+# =============================================================================
+epic_workflow:
+  # Auto-compact between stories (saves context, continues next story)
+  # When true: story done → compact → restore context → next story
+  # When false: story done → ask user to continue
+  auto_compact: true
+  
+  # Auto-fix code review issues
+  # When true: review failed → @coder fixes → re-review → continue
+  # When false: review failed → HALT, ask user
+  auto_fix: true
+  
+  # Max fix attempts before HALT (prevents infinite loops)
+  max_fix_attempts: 3
+  
+  # Pause between stories for manual review
+  # When true: story done → show summary → ask to continue
+  # When false: story done → immediately start next story
+  pause_between_stories: false
+  
+  # Run integration tests after each story
+  # When true: story done → run integration tests → continue
+  # When false: skip per-story integration tests
+  test_after_each_story: false
+  
+  # Run integration tests after epic complete
+  # When true: all stories done → run epic integration tests
+  # When false: skip epic integration tests
+  test_after_epic: true
+  
+  # Compaction strategy
+  compaction:
+    # Save epic state to sprint-status.yaml
+    save_epic_state: true
+    
+    # Files to preserve in context after compaction
+    preserve_files:
+      - "CLAUDE.md"
+      - "AGENTS.md"
+      - "docs/prd.md"
+      - "docs/architecture.md"
+      - "docs/coding-standards/README.md"
+      - "docs/coding-standards/patterns.md"
+      # Epic file and next story added dynamically
+
 # =============================================================================
 # CHANGELOG
 # =============================================================================

package/src/opencode/plugins/README.md

@@ -52,10 +52,11 @@ Checks for updates and shows a toast notification if a newer version is availabl
 
 ### custom-compaction.ts
 
-Intelligent session compaction that preserves flow context.
+Intelligent session compaction that preserves flow context with epic workflow support.
 
 **Features:**
 - Tracks todo list and story task status
+- **Epic workflow state preservation** (new!)
 - Identifies critical documentation files for context
 - Generates smart continuation prompts
 - Differentiates between completed and interrupted tasks
@@ -68,8 +69,31 @@ Intelligent session compaction that preserves flow context.
 |----------|-------------------|
 | **Task Completed** | Summary of completed work, next steps, validation reminders |
 | **Task Interrupted** | Current task, what was done, resume instructions, file list |
+| **Epic in Progress** | Epic state file, current story, next action, minimal context |
+
+**Epic Workflow Support:**
+
+When `/dev-epic` is running, the plugin:
+1. Finds active epic state file in `sprint-N/.sprint-state/epic-XX-state.yaml`
+2. Reads current story from epic state
+3. Generates minimal read commands:
+   - Epic state file (progress tracking)
+   - Next story file (what to do)
+   - CLAUDE.md, PRD, Architecture (context)
+4. Agent resumes automatically without re-reading completed stories
+
+**Epic State File Location:**
+```
+docs/sprint-artifacts/
+  sprint-1/
+    .sprint-state/
+      epic-01-state.yaml    # Tracks epic-01 progress
+      epic-02-state.yaml    # Tracks epic-02 progress
+```
 
 **Critical Files Passed to Context:**
+
+**For regular /dev-story:**
 - `CLAUDE.md` - Project coding standards
 - `AGENTS.md` - Agent definitions
 - `project-context.md` - Project overview
@@ -79,6 +103,13 @@ Intelligent session compaction that preserves flow context.
 - `docs/coding-standards/*.md` - Coding patterns
 - Active story file (if in progress)
 
+**For /dev-epic workflow:**
+- Epic state file (e.g., `sprint-1/.sprint-state/epic-01-state.yaml`)
+- Next story file (from epic state)
+- `CLAUDE.md`, `AGENTS.md`, `docs/prd.md`, `docs/architecture.md`
+- ❌ **NOT** completed story files (saves context!)
+- ❌ **NOT** epic file (info in state file)
+
 ## Installation
 
 Plugins in `.opencode/plugins/` are automatically loaded by OpenCode.

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

@@ -44,6 +44,7 @@ interface SessionContext {
   story: StoryContext | null
   relevantFiles: string[]
   activeAgent: string | null
+  activeCommand: string | null  // /dev-story, /dev-epic, /dev-sprint
 }
 
 // Base files ALL agents need after compaction (to remember who they are)
@@ -116,6 +117,7 @@ const MUST_READ_FILES: Record<string, string[]> = {
     "CLAUDE.md",
     "docs/prd.md",
     "docs/architecture.md",
+    // epic state path added dynamically (if in epic workflow)
     // story path added dynamically
   ],
   coder: [
@@ -173,13 +175,28 @@ export const CustomCompactionPlugin: Plugin = async (ctx) => {
   /**
    * Generate Read commands that agent MUST execute after compaction
    */
-  function generateReadCommands(agent: string | null, story: StoryContext | null): string {
+  async function generateReadCommands(agent: string | null, story: StoryContext | null, activeCommand: string | null): Promise<string> {
     const agentKey = (typeof agent === 'string' ? agent.toLowerCase() : null) || "default"
     const filesToRead = [...(MUST_READ_FILES[agentKey] || MUST_READ_FILES.default)]
     
-    // For dev/coder: add story file if active
-    if ((agentKey === "dev" || agentKey === "coder") && story) {
-      filesToRead.unshift(story.path)  // Story first!
+    // For dev/coder: add command file first
+    if ((agentKey === "dev" || agentKey === "coder") && activeCommand) {
+      const commandFile = activeCommand.replace("/", "") + ".md"
+      filesToRead.unshift(`.opencode/commands/${commandFile}`)
+    }
+    
+    // For dev/coder: add epic state file if in epic workflow
+    if ((agentKey === "dev" || agentKey === "coder")) {
+      const epicState = await getActiveEpicState()
+      if (epicState) {
+        // Epic state file (has all context)
+        filesToRead.unshift(epicState.statePath.replace(directory + "/", ""))
+      }
+      
+      // Then story file if active
+      if (story) {
+        filesToRead.unshift(story.path)  // Story first!
+      }
     }
     
     const commands = filesToRead.map((f, i) => `${i + 1}. Read("${f}")`).join("\n")
@@ -203,8 +220,158 @@ DO NOT skip this step. DO NOT ask user what to do. Just read these files first.`
     }
   }
 
+  interface EpicState {
+    statePath: string
+    epicId: string
+    epicTitle: string
+    status: string
+    currentStoryIndex: number
+    totalStories: number
+    nextAction: string | null
+    nextStoryPath: string | null
+    completedCount: number
+    pendingCount: number
+  }
+
+  async function getActiveEpicState(): Promise<EpicState | null> {
+    try {
+      // Search for epic state files in all sprint folders
+      const sprintArtifactsPath = join(directory, "docs", "sprint-artifacts")
+      const entries = await readdir(sprintArtifactsPath)
+      
+      for (const entry of entries) {
+        if (entry.startsWith("sprint-")) {
+          const statePath = join(sprintArtifactsPath, entry, ".sprint-state")
+          try {
+            const stateFiles = await readdir(statePath)
+            for (const stateFile of stateFiles) {
+              if (stateFile.endsWith("-state.yaml")) {
+                const fullPath = join(statePath, stateFile)
+                const content = await readFile(fullPath, "utf-8")
+                
+                // Check if this epic is in-progress
+                if (content.includes("status: \"in-progress\"") || content.includes("status: in-progress")) {
+                  // Parse epic state
+                  const epicIdMatch = content.match(/epic_id:\s*["']?([^"'\n]+)["']?/i)
+                  const epicTitleMatch = content.match(/epic_title:\s*["']?([^"'\n]+)["']?/i)
+                  const statusMatch = content.match(/status:\s*["']?([^"'\n]+)["']?/i)
+                  const currentIndexMatch = content.match(/current_story_index:\s*(\d+)/i)
+                  const totalStoriesMatch = content.match(/total_stories:\s*(\d+)/i)
+                  const nextActionMatch = content.match(/next_action:\s*["']?([^"'\n]+)["']?/i)
+                  
+                  // Count completed/pending stories
+                  const completedSection = content.match(/completed_stories:([\s\S]*?)(?=pending_stories:|$)/i)
+                  const pendingSection = content.match(/pending_stories:([\s\S]*?)(?=\n\w+:|$)/i)
+                  
+                  const completedCount = completedSection 
+                    ? (completedSection[1].match(/- path:/g) || []).length 
+                    : 0
+                  const pendingCount = pendingSection 
+                    ? (pendingSection[1].match(/- path:/g) || []).length 
+                    : 0
+                  
+                  // Extract next story path from next_action
+                  let nextStoryPath: string | null = null
+                  if (nextActionMatch) {
+                    const actionText = nextActionMatch[1]
+                    const storyFileMatch = actionText.match(/story-[\w-]+\.md/i)
+                    if (storyFileMatch) {
+                      // Find full path in pending_stories
+                      const pathMatch = content.match(new RegExp(`path:\\s*["']?([^"'\\n]*${storyFileMatch[0]}[^"'\\n]*)["']?`, 'i'))
+                      if (pathMatch) {
+                        nextStoryPath = pathMatch[1]
+                      }
+                    }
+                  }
+                  
+                  return {
+                    statePath: fullPath.replace(directory + "/", ""),
+                    epicId: epicIdMatch?.[1] || "unknown",
+                    epicTitle: epicTitleMatch?.[1] || "Unknown Epic",
+                    status: statusMatch?.[1] || "in-progress",
+                    currentStoryIndex: currentIndexMatch ? parseInt(currentIndexMatch[1]) : 0,
+                    totalStories: totalStoriesMatch ? parseInt(totalStoriesMatch[1]) : 0,
+                    nextAction: nextActionMatch?.[1] || null,
+                    nextStoryPath,
+                    completedCount,
+                    pendingCount
+                  }
+                }
+              }
+            }
+          } catch {
+            // No .sprint-state folder in this sprint
+          }
+        }
+      }
+      return null
+    } catch {
+      return null
+    }
+  }
+
   async function getActiveStory(): Promise<StoryContext | null> {
     try {
+      // First, try to find epic state file
+      const epicState = await getActiveEpicState()
+      if (epicState) {
+        // Parse epic state to get current story
+        const storyPathMatch = epicState.content.match(/next_action:\s*["']?Execute\s+(.+?)["']?$/m)
+        if (storyPathMatch) {
+          const storyFileName = storyPathMatch[1]
+          // Find story file
+          const sprintMatch = epicState.statePath.match(/sprint-(\d+)/)
+          if (sprintMatch) {
+            const storyPath = `docs/sprint-artifacts/sprint-${sprintMatch[1]}/stories/${storyFileName}`
+            const storyContent = await readFile(join(directory, storyPath), "utf-8")
+            
+            const titleMatch = storyContent.match(/^#\s+(.+)/m)
+            const statusMatch = storyContent.match(/\*\*Status:\*\*\s*(\w+)/i)
+            
+            const completedTasks: string[] = []
+            const pendingTasks: string[] = []
+            let currentTask: string | null = null
+            
+            // Parse tasks with more detail
+            const taskRegex = /- \[([ x])\]\s+\*\*T(\d+)\*\*[:\s]+(.+?)(?=\n|$)/g
+            let match
+            while ((match = taskRegex.exec(storyContent)) !== null) {
+              const [, checked, taskId, taskName] = match
+              const taskInfo = `T${taskId}: ${taskName.trim()}`
+              if (checked === "x") {
+                completedTasks.push(taskInfo)
+              } else {
+                if (!currentTask) currentTask = taskInfo
+                pendingTasks.push(taskInfo)
+              }
+            }
+            
+            // Parse acceptance criteria
+            const acceptanceCriteria: string[] = []
+            const acSection = storyContent.match(/## Acceptance Criteria[\s\S]*?(?=##|$)/i)
+            if (acSection) {
+              const acRegex = /- \[([ x])\]\s+(.+?)(?=\n|$)/g
+              while ((match = acRegex.exec(acSection[0])) !== null) {
+                const [, checked, criteria] = match
+                acceptanceCriteria.push(`${checked === "x" ? "✅" : "⬜"} ${criteria.trim()}`)
+              }
+            }
+
+            return {
+              path: storyPath,
+              title: titleMatch?.[1] || "Unknown Story",
+              status: statusMatch?.[1] || "unknown",
+              currentTask,
+              completedTasks,
+              pendingTasks,
+              acceptanceCriteria,
+              fullContent: storyContent
+            }
+          }
+        }
+      }
+      
+      // Fallback: try old sprint-status.yaml format
       const sprintStatusPath = join(directory, "docs", "sprint-artifacts", "sprint-status.yaml")
       const content = await readFile(sprintStatusPath, "utf-8")
       
@@ -300,21 +467,72 @@ DO NOT skip this step. DO NOT ask user what to do. Just read these files first.`
     return relevantPaths
   }
 
+  async function detectActiveCommand(todos: TaskStatus[], epicState: EpicState | null): Promise<string | null> {
+    // Detect command from TODO structure
+    if (todos.length === 0) return null
+    
+    // Check if TODOs are epics (sprint mode)
+    const hasEpicTodos = todos.some(t => t.content.toLowerCase().includes("epic"))
+    if (hasEpicTodos) return "/dev-sprint"
+    
+    // Check if TODOs are stories (epic mode)
+    const hasStoryTodos = todos.some(t => t.content.toLowerCase().includes("story"))
+    if (hasStoryTodos || epicState) return "/dev-epic"
+    
+    // Regular story mode
+    return "/dev-story"
+  }
+
   async function buildContext(agent: string | null): Promise<SessionContext> {
     const [todos, story] = await Promise.all([
       getTodoList(),
       getActiveStory()
     ])
     
+    const epicState = await getActiveEpicState()
     const relevantFiles = await getRelevantFiles(agent, story)
+    const activeCommand = await detectActiveCommand(todos, epicState)
 
-    return { todos, story, relevantFiles, activeAgent: agent }
+    return { todos, story, relevantFiles, activeAgent: agent, activeCommand }
   }
 
-  function formatDevContext(ctx: SessionContext): string {
+  async function formatDevContext(ctx: SessionContext): Promise<string> {
     const sections: string[] = []
     
-    if (ctx.story) {
+    // Check if we're in epic workflow
+    const epicState = await getActiveEpicState()
+    
+    if (epicState) {
+      // Epic/Sprint workflow mode - show epic progress
+      const progress = epicState.totalStories > 0 
+        ? ((epicState.completedCount / epicState.totalStories) * 100).toFixed(0) 
+        : 0
+
+      sections.push(`## 🎯 Epic Workflow: ${epicState.epicTitle}
+
+**Epic ID:** ${epicState.epicId}
+**Epic State:** \`${epicState.statePath}\` ← READ THIS FIRST
+**Progress:** ${progress}% (${epicState.completedCount}/${epicState.totalStories} stories)
+
+### Next Action (DO THIS NOW)
+\`\`\`
+${epicState.nextAction || "All stories complete - run epic integration tests"}
+\`\`\`
+
+${epicState.nextStoryPath ? `**Next Story:** \`${epicState.nextStoryPath}\` ← READ THIS SECOND` : ""}
+
+### Epic Progress
+**Completed Stories:** ${epicState.completedCount}
+**Pending Stories:** ${epicState.pendingCount}
+**Current Index:** ${epicState.currentStoryIndex}
+
+---
+
+💡 **Note:** If this is part of /dev-sprint, after epic completes:
+1. Update sprint-status.yaml (mark epic done)
+2. Continue to next epic automatically`)
+    } else if (ctx.story) {
+      // Regular story mode
       const s = ctx.story
       const total = s.completedTasks.length + s.pendingTasks.length
       const progress = total > 0 ? (s.completedTasks.length / total * 100).toFixed(0) : 0
@@ -433,13 +651,13 @@ ${ctx.relevantFiles.map(f => `- \`${f}\``).join("\n")}`)
     return sections.join("\n\n---\n\n")
   }
 
-  function formatContext(ctx: SessionContext): string {
+  async function formatContext(ctx: SessionContext): Promise<string> {
     const agent = ctx.activeAgent?.toLowerCase()
     
     switch (agent) {
       case "dev":
       case "coder":
-        return formatDevContext(ctx)
+        return await formatDevContext(ctx)
       case "architect":
         return formatArchitectContext(ctx)
       case "pm":
@@ -453,12 +671,15 @@ ${ctx.relevantFiles.map(f => `- \`${f}\``).join("\n")}`)
     }
   }
 
-  function formatInstructions(ctx: SessionContext): string {
+  async function formatInstructions(ctx: SessionContext): Promise<string> {
     const agent = ctx.activeAgent?.toLowerCase()
     const hasInProgressTasks = ctx.todos.some(t => t.status === "in_progress")
     const hasInProgressStory = ctx.story?.status === "in-progress"
+    
+    // Check if we're in epic workflow
+    const epicState = await getActiveEpicState()
 
-    if (!hasInProgressTasks && !hasInProgressStory) {
+    if (!hasInProgressTasks && !hasInProgressStory && !epicState) {
       return `## Status: COMPLETED ✅
 
 Previous task was completed successfully.
@@ -469,7 +690,67 @@ Previous task was completed successfully.
 3. Ask user for next task`
     }
 
-    // Dev-specific instructions
+    // Sprint workflow instructions
+    if (ctx.activeCommand === "/dev-sprint" && (agent === "dev" || agent === "coder")) {
+      const nextEpicTodo = ctx.todos.find(t => t.status === "in_progress" && t.content.toLowerCase().includes("epic"))
+      return `## Status: SPRINT IN PROGRESS 🔄
+
+**Active Command:** ${ctx.activeCommand}
+**Active Agent:** @${agent}
+**Next Epic:** ${nextEpicTodo?.content || "check TODO"}
+
+### Resume Protocol (AUTOMATIC - DO NOT ASK USER)
+1. **Read command:** \`.opencode/commands/dev-sprint.md\`
+2. **Read sprint-status.yaml**
+3. **Find next epic** from TODO or sprint-status.yaml
+4. **Execute epic** via /dev-epic workflow
+5. **After epic done:**
+   - Update sprint-status.yaml (mark epic done)
+   - Update TODO (mark epic completed, next epic in_progress)
+   - Continue next epic automatically
+
+### DO NOT
+- Ask user what to do (TODO + sprint-status.yaml tell you)
+- Re-read completed epics
+- Wait for confirmation between epics (auto-continue)
+
+### IMPORTANT
+This is /dev-sprint autopilot mode. Execute epics sequentially until sprint done.`
+    }
+
+    // Epic workflow instructions
+    if ((ctx.activeCommand === "/dev-epic" || epicState) && (agent === "dev" || agent === "coder")) {
+      return `## Status: EPIC IN PROGRESS 🔄
+
+**Active Command:** ${ctx.activeCommand || "/dev-epic"}
+**Active Agent:** @${agent}
+**Epic:** ${epicState?.epicTitle || "check epic state"}
+**Next Action:** ${epicState?.nextAction || "check TODO"}
+
+### Resume Protocol (AUTOMATIC - DO NOT ASK USER)
+1. **Read command:** \`.opencode/commands/dev-epic.md\`
+2. **Read epic state:** \`${epicState?.statePath || "find in .sprint-state/"}\`
+3. **Read next story:** \`${epicState?.nextStoryPath || "check epic state"}\`
+4. **Load skill:** \`.opencode/skills/dev-story/SKILL.md\`
+5. **Execute story** following /dev-story workflow
+6. **After story done:**
+   - Update epic state file (move story to completed)
+   - Update TODO (mark story completed, next story in_progress)
+   - Increment current_story_index
+   - Set next_action to next story
+   - Continue next story automatically
+
+### DO NOT
+- Ask user what to do (epic state + TODO tell you)
+- Re-read completed stories
+- Re-read epic file (info in state)
+- Wait for confirmation between stories (auto-continue)
+
+### IMPORTANT
+This is /dev-epic autopilot mode. Execute stories sequentially until epic done.`
+    }
+
+    // Dev-specific instructions (regular story)
     if ((agent === "dev" || agent === "coder") && ctx.story) {
       return `## Status: IN PROGRESS 🔄
 
@@ -554,9 +835,9 @@ Previous task was completed successfully.
       await log(directory, `  todos: ${ctx.todos.length}`)
       await log(directory, `  relevantFiles: ${ctx.relevantFiles.length}`)
       
-      const context = formatContext(ctx)
-      const instructions = formatInstructions(ctx)
-      const readCommands = generateReadCommands(agent, ctx.story)
+      const context = await formatContext(ctx)
+      const instructions = await formatInstructions(ctx)
+      const readCommands = await generateReadCommands(agent, ctx.story, ctx.activeCommand)
 
       // Agent identity reminder
       const agentIdentity = agent