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

package/package.json

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

package/src/build-info.json

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

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

@@ -39,9 +39,20 @@ interface StoryContext {
   fullContent: string
 }
 
+interface SessionState {
+  command: string | null       // /dev-sprint, /dev-epic, /dev-story
+  agent: string | null
+  sprint: { number: number; status: string } | null
+  epic: { id: string; title: string; file: string; progress: string } | null
+  story: { id: string; title: string; file: string; current_task: string | null; completed_tasks: string[]; pending_tasks: string[] } | null
+  next_action: string | null
+  key_decisions: string[]
+}
+
 interface SessionContext {
   todos: TaskStatus[]
   story: StoryContext | null
+  sessionState: SessionState | null
   relevantFiles: string[]
   activeAgent: string | null
   activeCommand: string | null  // /dev-story, /dev-epic, /dev-sprint
@@ -169,7 +180,7 @@ export const CustomCompactionPlugin: Plugin = async (ctx) => {
   /**
    * Generate Read commands that agent MUST execute after compaction
    */
-  async function generateReadCommands(agent: string | null, story: StoryContext | null, activeCommand: string | null): Promise<string> {
+  async function generateReadCommands(agent: string | null, story: StoryContext | null, activeCommand: string | null, sessionState: SessionState | null): Promise<string> {
     const agentKey = (typeof agent === 'string' ? agent.toLowerCase() : null) || "default"
     const filesToRead = [...(MUST_READ_FILES[agentKey] || MUST_READ_FILES.default)]
     
@@ -179,17 +190,23 @@ export const CustomCompactionPlugin: Plugin = async (ctx) => {
       filesToRead.unshift(`.opencode/commands/${commandFile}`)
     }
     
-    // For dev/coder: add epic state file if in epic workflow
+    // For dev/coder: add session-state.yaml as priority read
     if ((agentKey === "dev" || agentKey === "coder")) {
-      const epicState = await getActiveEpicState()
-      if (epicState) {
-        // Epic state file (has all context)
-        filesToRead.unshift(epicState.statePath.replace(directory + "/", ""))
-      }
+      // Session state is most important — has everything
+      filesToRead.unshift(".opencode/session-state.yaml")
       
-      // Then story file if active
-      if (story) {
-        filesToRead.unshift(story.path)  // Story first!
+      // Then story file (from session state or StoryContext)
+      const storyFile = sessionState?.story?.file || story?.path
+      if (storyFile) {
+        filesToRead.unshift(storyFile)  // Story first!
+      }
+
+      // Epic state as backup (only if no session state)
+      if (!sessionState) {
+        const epicState = await getActiveEpicState()
+        if (epicState) {
+          filesToRead.unshift(epicState.statePath.replace(directory + "/", ""))
+        }
       }
     }
     
@@ -304,85 +321,113 @@ DO NOT skip this step. DO NOT ask user what to do. Just read these files first.`
     }
   }
 
+  /**
+   * PRIMARY source: session-state.yaml written by AI agent.
+   * Falls back to getActiveEpicState() + getActiveStory() if missing.
+   */
+  async function getSessionState(): Promise<SessionState | null> {
+    try {
+      const statePath = join(directory, ".opencode", "session-state.yaml")
+      const content = await readFile(statePath, "utf-8")
+      await log(directory, `  session-state.yaml found, parsing...`)
+
+      // Simple regex YAML parser for flat/nested fields
+      const str = (key: string): string | null => {
+        const m = content.match(new RegExp(`^${key}:\\s*["']?(.+?)["']?\\s*$`, 'm'))
+        return m ? m[1].trim() : null
+      }
+      const nested = (parent: string, key: string): string | null => {
+        const section = content.match(new RegExp(`^${parent}:\\s*\\n((?:  .+\\n?)*)`, 'm'))
+        if (!section) return null
+        const m = section[1].match(new RegExp(`^\\s+${key}:\\s*["']?(.+?)["']?\\s*$`, 'm'))
+        return m ? m[1].trim() : null
+      }
+      const list = (parent: string, key: string): string[] => {
+        const val = nested(parent, key)
+        if (!val) return []
+        // Handle [T1, T2] or T1, T2
+        const clean = val.replace(/^\[/, '').replace(/\]$/, '')
+        return clean.split(',').map(s => s.trim()).filter(Boolean)
+      }
+
+      // Parse key_decisions as list
+      const decisions: string[] = []
+      const decMatch = content.match(/^key_decisions:\s*\n((?:\s+-\s*.+\n?)*)/m)
+      if (decMatch) {
+        const items = decMatch[1].matchAll(/^\s+-\s*["']?(.+?)["']?\s*$/gm)
+        for (const item of items) {
+          decisions.push(item[1])
+        }
+      }
+
+      const state: SessionState = {
+        command: str('command'),
+        agent: str('agent'),
+        sprint: nested('sprint', 'number') ? {
+          number: parseInt(nested('sprint', 'number') || '0'),
+          status: nested('sprint', 'status') || 'unknown'
+        } : null,
+        epic: nested('epic', 'id') ? {
+          id: nested('epic', 'id') || '',
+          title: nested('epic', 'title') || '',
+          file: nested('epic', 'file') || '',
+          progress: nested('epic', 'progress') || ''
+        } : null,
+        story: nested('story', 'id') ? {
+          id: nested('story', 'id') || '',
+          title: nested('story', 'title') || '',
+          file: nested('story', 'file') || '',
+          current_task: nested('story', 'current_task'),
+          completed_tasks: list('story', 'completed_tasks'),
+          pending_tasks: list('story', 'pending_tasks')
+        } : null,
+        next_action: str('next_action'),
+        key_decisions: decisions
+      }
+
+      await log(directory, `  parsed: command=${state.command}, epic=${state.epic?.id}, story=${state.story?.id}`)
+      return state
+    } catch {
+      await log(directory, `  session-state.yaml not found, using fallback`)
+      return null
+    }
+  }
+
   async function getActiveStory(): Promise<StoryContext | null> {
     try {
-      // First, try to find epic state file
+      let storyPath: string | null = null
+
+      // First, try epic state file for story path
       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()}`)
-              }
-            }
+      if (epicState?.nextStoryPath) {
+        storyPath = epicState.nextStoryPath
+      }
 
-            return {
-              path: storyPath,
-              title: titleMatch?.[1] || "Unknown Story",
-              status: statusMatch?.[1] || "unknown",
-              currentTask,
-              completedTasks,
-              pendingTasks,
-              acceptanceCriteria,
-              fullContent: storyContent
-            }
+      // Fallback: try sprint-status.yaml
+      if (!storyPath) {
+        try {
+          const sprintStatusPath = join(directory, "docs", "sprint-artifacts", "sprint-status.yaml")
+          const content = await readFile(sprintStatusPath, "utf-8")
+          const inProgressMatch = content.match(/status:\s*in-progress[\s\S]*?path:\s*["']?([^"'\n]+)["']?/i)
+          if (inProgressMatch) {
+            storyPath = inProgressMatch[1]
           }
+        } catch {
+          // No sprint-status.yaml
         }
       }
-      
-      // Fallback: try old sprint-status.yaml format
-      const sprintStatusPath = join(directory, "docs", "sprint-artifacts", "sprint-status.yaml")
-      const content = await readFile(sprintStatusPath, "utf-8")
-      
-      const inProgressMatch = content.match(/status:\s*in-progress[\s\S]*?path:\s*["']?([^"'\n]+)["']?/i)
-      if (!inProgressMatch) return null
 
-      const storyPath = inProgressMatch[1]
+      if (!storyPath) return null
+
+      // Parse story file
       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) {
@@ -395,8 +440,7 @@ DO NOT skip this step. DO NOT ask user what to do. Just read these files first.`
           pendingTasks.push(taskInfo)
         }
       }
-      
-      // Parse acceptance criteria
+
       const acceptanceCriteria: string[] = []
       const acSection = storyContent.match(/## Acceptance Criteria[\s\S]*?(?=##|$)/i)
       if (acSection) {
@@ -478,31 +522,118 @@ DO NOT skip this step. DO NOT ask user what to do. Just read these files first.`
   }
 
   async function buildContext(agent: string | null): Promise<SessionContext> {
+    // PRIMARY: try session-state.yaml (written by AI agent)
+    const sessionState = await getSessionState()
+    
     const [todos, story] = await Promise.all([
       getTodoList(),
-      getActiveStory()
+      // If session state has story path, use it; otherwise parse files
+      sessionState?.story?.file 
+        ? readStoryFromPath(sessionState.story.file)
+        : getActiveStory()
     ])
     
     const epicState = await getActiveEpicState()
     const relevantFiles = await getRelevantFiles(agent, story)
-    const activeCommand = await detectActiveCommand(todos, epicState)
+    
+    // Command: from session state or detected from TODOs
+    const activeCommand = sessionState?.command || await detectActiveCommand(todos, epicState)
 
-    return { todos, story, relevantFiles, activeAgent: agent, activeCommand }
+    return { todos, story, sessionState, relevantFiles, activeAgent: agent, activeCommand }
+  }
+
+  /** Read and parse a story file by path */
+  async function readStoryFromPath(storyPath: string): Promise<StoryContext | null> {
+    try {
+      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
+
+      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)
+        }
+      }
+
+      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
+      }
+    } catch {
+      return null
+    }
   }
 
   async function formatDevContext(ctx: SessionContext): Promise<string> {
     const sections: string[] = []
-    
-    // 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
+    const ss = ctx.sessionState
+
+    // SESSION STATE available — use it (primary source)
+    if (ss) {
+      let header = `## 🎯 Session State (from session-state.yaml)\n`
+      header += `**Command:** ${ss.command || "unknown"}\n`
+      
+      if (ss.sprint) {
+        header += `**Sprint:** #${ss.sprint.number} (${ss.sprint.status})\n`
+      }
+      if (ss.epic) {
+        header += `**Epic:** ${ss.epic.id} — ${ss.epic.title}\n`
+        header += `**Epic File:** \`${ss.epic.file}\`\n`
+        header += `**Epic Progress:** ${ss.epic.progress}\n`
+      }
+      if (ss.story) {
+        header += `\n**Story:** ${ss.story.id} — ${ss.story.title}\n`
+        header += `**Story File:** \`${ss.story.file}\` ← READ THIS FIRST\n`
+        header += `**Current Task:** ${ss.story.current_task || "all done"}\n`
+        header += `**Completed:** ${ss.story.completed_tasks.join(", ") || "none"}\n`
+        header += `**Pending:** ${ss.story.pending_tasks.join(", ") || "none"}\n`
+      }
+      
+      header += `\n### Next Action (DO THIS NOW)\n\`\`\`\n${ss.next_action || "Check TODO list"}\n\`\`\`\n`
+      
+      if (ss.key_decisions.length > 0) {
+        header += `\n### Key Technical Decisions\n`
+        header += ss.key_decisions.map(d => `- ${d}`).join("\n")
+      }
+      
+      sections.push(header)
+    }
+    // FALLBACK: parse epic state file
+    else {
+      const epicState = await getActiveEpicState()
+      if (epicState) {
+        const progress = epicState.totalStories > 0 
+          ? ((epicState.completedCount / epicState.totalStories) * 100).toFixed(0) 
+          : 0
 
-      sections.push(`## 🎯 Epic Workflow: ${epicState.epicTitle}
+        sections.push(`## 🎯 Epic Workflow: ${epicState.epicTitle}
 
 **Epic ID:** ${epicState.epicId}
 **Epic State:** \`${epicState.statePath}\` ← READ THIS FIRST
@@ -525,7 +656,10 @@ ${epicState.nextStoryPath ? `**Next Story:** \`${epicState.nextStoryPath}\` ←
 💡 **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) {
+      }
+    }
+    
+    if (!ss && ctx.story) {
       // Regular story mode
       const s = ctx.story
       const total = s.completedTasks.length + s.pendingTasks.length
@@ -777,6 +911,74 @@ This is /dev-epic autopilot mode. Execute stories sequentially until epic done.`
 4. Update todo/story when task complete`
   }
 
+  function buildBriefing(agent: string | null, ss: SessionState | null, ctx: SessionContext, readCommands: string): string {
+    const lines: string[] = []
+
+    // 1. WHO you are
+    if (agent) {
+      lines.push(`You are @${agent} (→ .opencode/agents/${agent}.md).`)
+    }
+
+    // 2. WHAT you are doing
+    if (ss) {
+      const cmd = ss.command || "unknown command"
+      if (ss.epic) {
+        lines.push(`You are executing ${cmd} ${ss.epic.id}: ${ss.epic.title}.`)
+      } else if (ss.story) {
+        lines.push(`You are executing ${cmd} ${ss.story.id}: ${ss.story.title}.`)
+      } else {
+        lines.push(`You are executing ${cmd}.`)
+      }
+    } else if (ctx.activeCommand) {
+      lines.push(`You are executing ${ctx.activeCommand}.`)
+    }
+
+    // 3. WHERE you stopped
+    if (ss?.story) {
+      const task = ss.story.current_task || "review"
+      lines.push(`You were on story ${ss.story.id}: ${ss.story.title}, task ${task}.`)
+      if (ss.story.completed_tasks.length > 0) {
+        lines.push(`Completed: ${ss.story.completed_tasks.join(", ")}.`)
+      }
+      if (ss.story.pending_tasks.length > 0) {
+        lines.push(`Remaining: ${ss.story.pending_tasks.join(", ")}.`)
+      }
+    } else if (ss?.epic) {
+      lines.push(`Epic progress: ${ss.epic.progress}.`)
+    } else if (ctx.story) {
+      lines.push(`You were on story: ${ctx.story.title}, task ${ctx.story.currentTask || "review"}.`)
+    }
+
+    // 4. WHAT to do next
+    if (ss?.next_action) {
+      lines.push(`\nNext action: ${ss.next_action}`)
+    }
+
+    // 5. READ these files
+    lines.push(`\n${readCommands}`)
+
+    // 6. KEY DECISIONS (if any)
+    if (ss?.key_decisions && ss.key_decisions.length > 0) {
+      lines.push(`\nKey decisions from your session:`)
+      for (const d of ss.key_decisions) {
+        lines.push(`- ${d}`)
+      }
+    }
+
+    // 7. TODO status (brief)
+    if (ctx.todos.length > 0) {
+      const inProgress = ctx.todos.filter(t => t.status === "in_progress")
+      const pending = ctx.todos.filter(t => t.status === "pending")
+      const completed = ctx.todos.filter(t => t.status === "completed")
+      lines.push(`\nTODO: ${completed.length} done, ${inProgress.length} in progress, ${pending.length} pending.`)
+    }
+
+    // 8. RULES
+    lines.push(`\nDO NOT ask user what to do. Read files above, then resume automatically.`)
+
+    return lines.join("\n")
+  }
+
   return {
     // Track active agent from chat messages
     "chat.message": async (input, output) => {
@@ -831,26 +1033,12 @@ This is /dev-epic autopilot mode. Execute stories sequentially until epic done.`
       
       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 
-        ? `You are @${agent} (.opencode/agents/${agent}.md). Load your persona and continue.`
-        : "You are an AI assistant helping with this project."
-
-      output.context.push(`# Session Continuation
-
-${agentIdentity}
-
-${readCommands}
-
----
-
-${context}
-
----
+      const readCommands = await generateReadCommands(agent, ctx.story, ctx.activeCommand, ctx.sessionState)
 
-${instructions}`)
+      // Build agentic briefing
+      const ss = ctx.sessionState
+      const briefing = buildBriefing(agent, ss, ctx, readCommands)
+      output.context.push(briefing)
       
       await log(directory, `  -> output.context pushed (${output.context.length} items)`)
       await log(directory, `=== COMPACTION DONE ===`)

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

@@ -9,64 +9,99 @@ metadata:
 
 # 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}</file>
+      <file>{current-story-file} — ONE only!</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>
+    <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="1">Parse epic file → "Story Tasks" section has all stories + tasks (no need to read story files yet)</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:
+    <step n="3">Create TODO list with IDs — stories, their tasks, and reviews:
       ```
-      [ ] Story 1: [Title]
-      [ ] Review Story 1
-      [ ] Story 2: [Title]
-      [ ] Review Story 2
+      [ ] E{N}-S01: {story title}
+        [ ] E{N}-S01-T01: {task title}
+        [ ] E{N}-S01-T02: {task title}
+        [ ] E{N}-S01-Review: run tests, verify AC
+      [ ] E{N}-S02: {story title}
+        [ ] E{N}-S02-T01: {task title}
+        [ ] E{N}-S02-T02: {task title}
+        [ ] E{N}-S02-Review: run tests, verify AC
       ...
-      [ ] Epic integration tests
-      [ ] Verify epic AC
+      [ ] E{N}-Integration: run epic integration tests
+      [ ] E{N}-AC: verify epic acceptance criteria
       ```
     </step>
+    <example>
+      ```
+      [ ] E04-S01: Merge Domain Logic
+        [ ] E04-S01-T01: MergeResult value object
+        [ ] E04-S01-T02: Merge service — primary selection
+        [ ] E04-S01-T03: Unit tests
+        [ ] E04-S01-Review: run tests, verify AC
+      [ ] E04-S02: Auto Merge on Link
+        [ ] E04-S02-T01: Event handler for link
+        [ ] E04-S02-T02: Best-effort merge logic
+        [ ] E04-S02-T03: Integration tests
+        [ ] E04-S02-Review: run tests, verify AC
+      [ ] E04-Integration: run epic integration tests
+      [ ] E04-AC: verify epic acceptance criteria
+      ```
+    </example>
     <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">
+    <critical>Status flow: in_progress → review → done. NEVER mark done before review!</critical>
     <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
+        - Read ONE story file
+        - Execute tasks ONE BY ONE (or parallel if independent)
+        - NEVER delegate entire story to @coder in one prompt
+        - After each task: verify, mark done, next task
       </action>
       
-      <action name="mark-done">
-        Mark story as completed in epic TODO
+      <action name="story-to-review">
+        All tasks done → set story status: review
+        Mark story TODO as "review" (NOT "done" yet!)
       </action>
       
-      <action name="review">
-        Mark "Review Story" as in_progress
-        Invoke @reviewer
+      <action name="review-story">
+        Invoke @reviewer on story code
         <if condition="CHANGES_REQUESTED">
           Add fix tasks → re-execute → re-review (max 3 attempts)
         </if>
         <if condition="APPROVED">
-          Mark "Review Story" as completed
+          Set story status: done
+          Mark story TODO as completed
         </if>
       </action>
       
@@ -79,32 +114,72 @@ metadata:
       
       <action name="compact">
         Mark next story as in_progress in TODO
-        Wait for auto-compaction
-        Plugin reads TODO + state → resume
+        Wait for auto-compaction → 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>
+    <critical>Epic also goes through review before done!</critical>
+    <step n="1">All stories done → set epic status: review</step>
+    <step n="2">Run epic integration tests (mark in TODO)</step>
+    <step n="3">Verify all AC from epic file (mark in TODO)</step>
+    <step n="4">If tests fail → fix → re-test</step>
+    <step n="5">All passed → set epic status: done</step>
+    <step n="6">Clear epic TODO list</step>
+    <step n="7">Update .opencode/session-state.yaml (next epic or done)</step>
+    <step n="8">Report completion with summary</step>
   </phase>
 
 </workflow>
 
+## Session State (MANDATORY)
+
+After each story/task completion, update `.opencode/session-state.yaml`:
+
+```yaml
+# .opencode/session-state.yaml — AI writes, compaction plugin reads
+command: /dev-epic
+agent: dev
+
+epic:
+  id: PROJ-E01
+  title: Epic Title
+  file: docs/sprint-artifacts/sprint-1/epic-01-desc.md
+  progress: "3/5 stories"
+
+story:
+  id: PROJ-S01-03
+  title: Current Story Title
+  file: docs/sprint-artifacts/sprint-1/stories/story-01-03-desc.md
+  current_task: T2
+  completed_tasks: [T1]
+  pending_tasks: [T2, T3]
+
+next_action: "Continue T2 of story S01-03"
+
+key_decisions:
+  - "Decision 1"
+```
+
+This file survives compaction and tells the agent where to resume.
+
 <outputs>
   - Implementation code for all stories
   - Updated epic-XX-state.yaml
+  - Updated .opencode/session-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>
+  <do>Execute stories IN ORDER as planned in epic file</do>
+  <do>Execute tasks within story ONE BY ONE (or parallel if independent)</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>
+  <dont>Reorder, skip, merge, or "optimize" story execution order</dont>
+  <dont>Combine tasks from different stories into one batch</dont>
+  <dont>Delegate entire story to @coder in one prompt — task by task only</dont>
 </rules>

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

@@ -9,46 +9,88 @@ metadata:
 
 # 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}</file>
-      <file>{current-story-file}</file>
+      <file>{current-epic-file} — ONE only!</file>
+      <file>{current-story-file} — ONE only!</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>
+    <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:
+    <step n="2">Create master TODO list with IDs — epics, stories, tasks, and reviews:
       ```
-      [ ] 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
+      [ ] E{N1}: {epic title}
+        [ ] E{N1}-S01: {story title}
+          [ ] E{N1}-S01-T01: {task title}
+          [ ] E{N1}-S01-T02: {task title}
+          [ ] E{N1}-S01-Review: run tests, verify AC
+        [ ] E{N1}-S02: {story title}
+          [ ] E{N1}-S02-T01: {task title}
+          [ ] E{N1}-S02-Review: run tests, verify AC
+        [ ] E{N1}-Integration: epic integration tests
+      [ ] E{N2}: {epic title}
+        [ ] E{N2}-S01: {story title}
+          [ ] E{N2}-S01-T01: {task title}
+          [ ] E{N2}-S01-Review: run tests, verify AC
+        [ ] E{N2}-Integration: epic integration tests
+      [ ] Sprint-Integration: run sprint integration tests
       ```
     </step>
+    <example>
+      ```
+      [ ] E04: Identity Merge
+        [ ] E04-S01: Merge Domain Logic
+          [ ] E04-S01-T01: MergeResult value object
+          [ ] E04-S01-T02: Merge service
+          [ ] E04-S01-T03: Unit tests
+          [ ] E04-S01-Review: run tests, verify AC
+        [ ] E04-S02: Auto Merge on Link
+          [ ] E04-S02-T01: Event handler
+          [ ] E04-S02-T02: Integration tests
+          [ ] E04-S02-Review: run tests, verify AC
+        [ ] E04-Integration: epic integration tests
+      [ ] E06: Team Management
+        [ ] E06-S01: Team CRUD
+          [ ] E06-S01-T01: Domain model
+          [ ] E06-S01-T02: Handler
+          [ ] E06-S01-Review: run tests, verify AC
+        [ ] E06-Integration: epic integration tests
+      [ ] Sprint-Integration: run sprint integration tests
+      ```
+    </example>
     <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">
+    <critical>Status flow: in_progress → review → done. NEVER mark done before review!</critical>
     <for-each item="epic" in="pending_epics">
       
       <action name="execute-epic">
@@ -58,14 +100,20 @@ metadata:
         - Clears epic TODO when done
       </action>
       
-      <action name="mark-done">
-        Mark epic as completed in sprint TODO
+      <action name="epic-to-review">
+        All stories done → set epic status: review
+        Mark epic TODO as "review" (NOT "done" yet!)
       </action>
       
       <action name="epic-review">
-        Mark "Review Epic" as in_progress
         Run epic integration tests
-        Mark "Review Epic" as completed
+        <if condition="TESTS_FAIL">
+          Fix → re-test (max 3 attempts)
+        </if>
+        <if condition="TESTS_PASS">
+          Set epic status: done
+          Mark epic TODO as completed
+        </if>
       </action>
       
       <action name="update-state">
@@ -76,31 +124,76 @@ metadata:
       
       <action name="compact">
         Mark next epic as in_progress in TODO
-        Wait for auto-compaction
-        Plugin reads sprint TODO → resume
+        Wait for auto-compaction → 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>
+    <critical>Sprint also goes through review before done!</critical>
+    <step n="1">All epics done → set sprint status: review</step>
+    <step n="2">Run sprint integration tests (mark in TODO)</step>
+    <step n="3">If tests fail → fix → re-test</step>
+    <step n="4">All passed → set sprint status: done in sprint-status.yaml</step>
+    <step n="5">Clear sprint TODO list</step>
+    <step n="6">Update .opencode/session-state.yaml (done)</step>
+    <step n="7">Report completion with summary + metrics</step>
   </phase>
 
 </workflow>
 
+## Session State (MANDATORY)
+
+After each epic/story/task completion, update `.opencode/session-state.yaml`:
+
+```yaml
+# .opencode/session-state.yaml — AI writes, compaction plugin reads
+command: /dev-sprint
+agent: dev
+
+sprint:
+  number: 2
+  status: in-progress
+
+epic:
+  id: PROJ-E04
+  title: Current Epic Title
+  file: docs/sprint-artifacts/sprint-2/epic-04-desc.md
+  progress: "3/5 stories"
+
+story:
+  id: PROJ-S04-03
+  title: Current Story Title
+  file: docs/sprint-artifacts/sprint-2/stories/story-04-03-desc.md
+  current_task: T2
+  completed_tasks: [T1]
+  pending_tasks: [T2, T3]
+
+next_action: "Continue T2 of story S04-03"
+
+key_decisions:
+  - "Decision 1"
+```
+
+This file survives compaction and tells the agent where to resume.
+
 <outputs>
   - Implementation code for all stories in sprint
   - Updated sprint-status.yaml
+  - Updated .opencode/session-state.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>
+  <do>Execute epics IN ORDER as planned in sprint-status.yaml</do>
+  <do>Within each epic, execute stories IN ORDER as planned</do>
+  <do>Within each story, execute tasks ONE BY ONE (or parallel if independent)</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>
+  <dont>Reorder, skip, merge, or "optimize" epic/story execution order</dont>
+  <dont>Work on multiple stories or epics in parallel</dont>
+  <dont>Delegate entire story to @coder in one prompt — task by task only</dont>
 </rules>

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

@@ -11,20 +11,31 @@ metadata:
 
 # Dev Story Skill
 
+## CRITICAL: Context Rules
+
+**READ ONLY (max ~70KB):**
+- `CLAUDE.md`
+- `docs/coding-standards/README.md`
+- `docs/coding-standards/patterns.md`
+- Story file
+
+**❌ DO NOT READ — WASTES CONTEXT:**
+- ❌ `docs/prd.md` — story already has context
+- ❌ `docs/architecture.md` — too large, coding-standards has patterns
+
+---
+
 <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>
-    <skip reason="too large, story has context">
-      <file>docs/prd.md</file>
-      <file>docs/architecture.md</file>
-    </skip>
-    <goal>~70KB context, not 200KB+</goal>
+    <goal>~70KB context, NOT 200KB+</goal>
   </phase>
 
   <phase name="2-transform" title="Transform Story Task → Executable Instruction">
@@ -57,21 +68,90 @@ metadata:
     </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 name="2b-todo" title="Create TODO with IDs">
+    <critical>TODO MUST use task IDs from story file!</critical>
+    <template>
+      ```
+      [ ] E{E}-S{N}-T01: {task title from story}
+      [ ] E{E}-S{N}-T02: {task title}
+      [ ] E{E}-S{N}-T03: {task title}
+      ...
+      [ ] E{E}-S{N}-Review: run all tests, verify AC
+      ```
+    </template>
+    <example>
+      ```
+      [ ] E04-S01-T01: Domain Model — MergeResult value object
+      [ ] E04-S01-T02: Merge Service — primary selection logic
+      [ ] E04-S01-T03: External ID reassignment
+      [ ] E04-S01-T04: Unit tests for merge logic
+      [ ] E04-S01-Review: run all tests, verify AC
+      ```
+    </example>
   </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 name="3-execute" title="Execute Tasks — One by One or Parallel">
+    <critical>DO NOT delegate entire story to @coder in one prompt!</critical>
+    <strategy>
+      For each task in TODO:
+      1. Check task dependencies (from story file)
+      2. If independent tasks exist → delegate in parallel (different files only)
+      3. If task depends on previous → delegate ONE task, wait for result
+      4. After @coder returns → verify, mark done, then next task
+    </strategy>
+    <loop>
+      <step n="1">Pick next task(s) from TODO</step>
+      <step n="2">Transform task → executable instruction (phase 2)</step>
+      <step n="3">Delegate to @coder using template below</step>
+      <step n="4">Verify result: tests pass, files compile</step>
+      <step n="5">Mark task ✅ in story file + TODO</step>
+      <step n="6">Update .opencode/session-state.yaml</step>
+      <step n="7">Next task or story complete</step>
+    </loop>
+    <parallel-rules>
+      OK to parallel: T01 (domain) + T02 (dto) — different files, no deps
+      NOT OK: T03 (service) depends on T01 (domain) — wait for T01 first
+    </parallel-rules>
+  </phase>
+
+  <phase name="4-review" title="Review BEFORE Done">
+    <critical>Status flow: in_progress → review → done. NEVER skip review!</critical>
+    <step n="1">All tasks done → set story status: review</step>
+    <step n="2">Run all tests, verify AC</step>
+    <step n="3">If called from /dev-epic: invoke @reviewer</step>
+    <step n="4">If fixes needed → fix → re-review (max 3 attempts)</step>
+    <step n="5">Review passed → set story status: done</step>
+    <step n="6">Update .opencode/session-state.yaml</step>
   </phase>
 
 </workflow>
 
+## Session State (MANDATORY)
+
+After each task completion, update `.opencode/session-state.yaml`:
+
+```yaml
+# .opencode/session-state.yaml — AI writes, compaction plugin reads
+command: /dev-story
+agent: dev
+
+story:
+  id: PROJ-S01-01
+  title: Story Title
+  file: docs/sprint-artifacts/sprint-1/stories/story-01-01-desc.md
+  current_task: T3
+  completed_tasks: [T1, T2]
+  pending_tasks: [T3, T4]
+
+next_action: "Continue T3: Implement handler"
+
+key_decisions:
+  - "Decision 1"
+  - "Decision 2"
+```
+
+This file survives compaction and tells the agent where to resume.
+
 ## Task Template for @coder
 
 <template name="coder-task">
@@ -108,9 +188,16 @@ metadata:
 </template>
 
 <rules name="delegation">
+  <rule name="task-by-task" critical="true">
+    Delegate ONE task at a time (or parallel group if independent).
+    NEVER delegate entire story as one big prompt.
+  </rule>
   <rule name="parallel">
     Each task gets full context. No shared state. Different files only.
   </rule>
+  <rule name="verify-between">
+    After each task: run tests, verify, mark done, THEN next task.
+  </rule>
   <rule name="no-code">
     Give direction, NOT solution. @coder writes implementation.
   </rule>

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

@@ -79,10 +79,10 @@ Epic is complete when:
 
 ## Stories
 
-| ID | Title | Size | Focus | Status |
-|----|-------|------|-------|--------|
-| S{{E}}-01 | {{title}} | S/M/L | → Unit: `{{unit}}` | ⬜ |
-| S{{E}}-02 | {{title}} | S/M/L | → Unit: `{{unit}}` | ⬜ |
+| ID | Title | Size | File | Status |
+|----|-------|------|------|--------|
+| E{{E}}-S01 | {{title}} | S/M/L | `story-{{E}}-01-{{slug}}.md` | ⬜ |
+| E{{E}}-S02 | {{title}} | S/M/L | `story-{{E}}-02-{{slug}}.md` | ⬜ |
 
 **Dependency Flow:**
 ```
@@ -91,8 +91,32 @@ S01 ──► S02 ──► S03
          └──► S04
 ```
 
-**Notes:**
-- {{implementation_note}}
+---
+
+## Story Tasks
+
+<!-- This section is populated by /stories command.
+     Used by /dev-epic to build TODO without reading all story files. -->
+
+### E{{E}}-S01: {{story title}}
+- E{{E}}-S01-T01: {{task title}}
+- E{{E}}-S01-T02: {{task title}}
+
+### E{{E}}-S02: {{story title}}
+- E{{E}}-S02-T01: {{task title}}
+- E{{E}}-S02-T02: {{task title}}
+
+<!-- Example:
+### E04-S01: Merge Domain Logic
+- E04-S01-T01: MergeResult value object
+- E04-S01-T02: Merge service — primary selection
+- E04-S01-T03: Unit tests
+
+### E04-S02: Auto Merge on Link
+- E04-S02-T01: Event handler for link
+- E04-S02-T02: Best-effort merge logic
+- E04-S02-T03: Integration tests
+-->
 
 ---
 

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

@@ -233,6 +233,26 @@ T1 ──► T2 ──► T3
 
 Save to: `docs/sprint-artifacts/sprint-[N]/stories/story-[EPIC]-[NN]-[description].md`
 
+## MANDATORY: Update Epic File
+
+After creating stories, update the parent epic's **Story Tasks** section.
+This lets `/dev-epic` build TODO from epic file alone — no need to read all stories.
+
+```markdown
+## Story Tasks
+
+### E04-S01: Merge Domain Logic
+- E04-S01-T01: MergeResult value object
+- E04-S01-T02: Merge service — primary selection
+- E04-S01-T03: Unit tests
+
+### E04-S02: Auto Merge on Link
+- E04-S02-T01: Event handler for link
+- E04-S02-T02: Best-effort merge logic
+```
+
+**Format:** `E{NN}-S{NN}-T{NN}: {task title}` — one line per task.
+
 ## Related Skills
 
 - `acceptance-criteria` - For detailed AC