@comfanion/workflow 4.38.1-dev.3 → 4.38.1-dev.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.1-dev.3",
+  "version": "4.38.1-dev.5",
   "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.3",
-  "buildDate": "2026-01-27T10:14:50.120Z",
+  "version": "4.38.1-dev.5",
+  "buildDate": "2026-01-27T10:42:36.948Z",
   "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,6 +321,78 @@ 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 {
       let storyPath: string | null = null
@@ -433,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
@@ -480,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
@@ -786,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

@@ -42,17 +42,37 @@ metadata:
   <phase name="2-init" title="Initialize Epic">
     <step n="1">Parse epic file → extract story list</step>
     <step n="2">Create epic state: docs/sprint-artifacts/sprint-N/.sprint-state/epic-XX-state.yaml</step>
-    <step n="3">Create TODO list:
+    <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}
+        [ ] S01 T1: {task title}
+        [ ] S01 T2: {task title}
+        [ ] S01 Review: run tests, verify AC
+      [ ] E{N}-S02: {story title}
+        [ ] S02 T1: {task title}
+        [ ] S02 T2: {task title}
+        [ ] S02 Review: run tests, verify AC
       ...
-      [ ] Epic integration tests
-      [ ] Verify epic AC
+      [ ] E{N} Integration tests
+      [ ] E{N} Verify epic AC
       ```
     </step>
+    <example>
+      ```
+      [ ] E04-S01: Merge Domain Logic
+        [ ] S01 T1: MergeResult value object
+        [ ] S01 T2: Merge service — primary selection
+        [ ] S01 T3: Unit tests
+        [ ] S01 Review: run tests, verify AC
+      [ ] E04-S02: Auto Merge on Link
+        [ ] S02 T1: Event handler for link
+        [ ] S02 T2: Best-effort merge logic
+        [ ] S02 T3: Integration tests
+        [ ] S02 Review: run tests, verify AC
+      [ ] E04 Integration tests
+      [ ] E04 Verify epic AC
+      ```
+    </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>
@@ -103,14 +123,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

@@ -44,20 +44,47 @@ metadata:
 
   <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]
-      ...
+      [ ] E{N1}: {epic title}
+        [ ] E{N1}-S01: {story title}
+          [ ] S01 T1: {task title}
+          [ ] S01 T2: {task title}
+          [ ] S01 Review: run tests, verify AC
+        [ ] E{N1}-S02: {story title}
+          [ ] S02 T1: {task title}
+          [ ] S02 Review: run tests, verify AC
+        [ ] E{N1} Review: integration tests
+      [ ] E{N2}: {epic title}
+        [ ] E{N2}-S01: {story title}
+          [ ] S01 T1: {task title}
+          [ ] S01 Review: run tests, verify AC
+        [ ] E{N2} Review: integration tests
       [ ] Sprint integration tests
       ```
     </step>
+    <example>
+      ```
+      [ ] E04: Identity Merge
+        [ ] E04-S01: Merge Domain Logic
+          [ ] S01 T1: MergeResult value object
+          [ ] S01 T2: Merge service
+          [ ] S01 T3: Unit tests
+          [ ] S01 Review: run tests, verify AC
+        [ ] E04-S02: Auto Merge on Link
+          [ ] S02 T1: Event handler
+          [ ] S02 T2: Integration tests
+          [ ] S02 Review: run tests, verify AC
+        [ ] E04 Review: integration tests
+      [ ] E06: Team Management
+        [ ] E06-S01: Team CRUD
+          [ ] S01 T1: Domain model
+          [ ] S01 T2: Handler
+          [ ] S01 Review: run tests, verify AC
+        [ ] E06 Review: integration tests
+      [ ] 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>
@@ -101,14 +128,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

@@ -68,6 +68,28 @@ metadata:
     </step>
   </phase>
 
+  <phase name="2b-todo" title="Create TODO with IDs">
+    <critical>TODO MUST use task IDs from story file!</critical>
+    <template>
+      ```
+      [ ] S{E}-{N} T1: {task title from story}
+      [ ] S{E}-{N} T2: {task title}
+      [ ] S{E}-{N} T3: {task title}
+      ...
+      [ ] S{E}-{N} Review: run all tests, verify AC
+      ```
+    </template>
+    <example>
+      ```
+      [ ] S04-01 T1: Domain Model — MergeResult value object
+      [ ] S04-01 T2: Merge Service — primary selection logic
+      [ ] S04-01 T3: External ID reassignment
+      [ ] S04-01 T4: Unit tests for merge logic
+      [ ] S04-01 Review: run all tests, verify AC
+      ```
+    </example>
+  </phase>
+
   <phase name="3-delegate" title="Delegate to @coder">
     <action>Formulate task using template below</action>
     <action>Call @coder with full context</action>
@@ -78,11 +100,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">