@comfanion/workflow 4.38.1-dev.2 → 4.38.1-dev.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.1-dev.2",
+  "version": "4.38.1-dev.4",
   "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.2",
-  "buildDate": "2026-01-27T01:09:08.937Z",
+  "version": "4.38.1-dev.4",
+  "buildDate": "2026-01-27T10:26:28.340Z",
   "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
 
-      sections.push(`## 🎯 Epic Workflow: ${epicState.epicTitle}
+    // 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}
 
 **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
@@ -831,7 +965,7 @@ 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)
+      const readCommands = await generateReadCommands(agent, ctx.story, ctx.activeCommand, ctx.sessionState)
 
       // Agent identity reminder
       const agentIdentity = agent 

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

@@ -103,14 +103,47 @@ metadata:
     <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>
+    <step n="5">Update .opencode/session-state.yaml (next epic or done)</step>
+    <step n="6">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>
 

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

@@ -101,14 +101,51 @@ metadata:
     <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>
+    <step n="4">Update .opencode/session-state.yaml (done)</step>
+    <step n="5">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>
 

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

@@ -78,11 +78,38 @@ metadata:
     <action>Run tests</action>
     <action>Check "Done when" criteria</action>
     <action>Mark task ✅ in story file</action>
+    <action>Update .opencode/session-state.yaml (see format below)</action>
     <next>Next task or story complete</next>
   </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">