@comfanion/workflow 4.38.2 → 4.38.3-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.2",
+  "version": "4.38.3-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.38.2",
-  "buildDate": "2026-01-28T10:05:17.810Z",
+  "version": "4.38.3-dev.1",
+  "buildDate": "2026-01-28T11:01:04.180Z",
   "files": [
     ".gitignore",
     "config.yaml",

package/src/opencode/agents/architect.md

@@ -123,7 +123,7 @@ permission:
   </size-awareness>
 
   <phase name="2. Planning">
-    <action>Create tasklist with todowrite()</action>
+    <action>Create tasklist with todowrite() (TODOv2)</action>
     <action>Present plan to user with specific files/changes</action>
     <action>Ask for confirmation with question() tool</action>
     <action>WAIT for user approval before proceeding</action>

package/src/opencode/agents/dev.md

@@ -4,7 +4,7 @@ mode: all            # Can be primary agent or invoked via @dev
 temperature: 0.2
 
 model: anthropic/claude-opus-4-5  # Strong
-#model: z.ai/glm-4.7  # Can break
+#model: zai-coding-plan/glm-4.7  # Can break
 #model: openai/gpt-5.2-codex 
 
 # Tools - FULL ACCESS for implementation
@@ -40,6 +40,7 @@ permission:
   <step n="2">IMMEDIATE: store {user_name}, {communication_language} from .opencode/config.yaml</step>
   <step n="3">Greet user by {user_name}, communicate in {communication_language}</step>
   <step n="4">Understand user request and select appropriate skill</step>
+  <step n="5">Create tasklist with todowrite() (TODOv2)</step>
 
   <search-first critical="MANDATORY - DO THIS BEFORE GLOB/GREP">
     BEFORE using glob or grep, you MUST call search() first:
@@ -68,23 +69,6 @@ permission:
     <r critical="MANDATORY">🔍 SEARCH FIRST: Call search() BEFORE glob when exploring codebase.
        search({ query: "feature pattern", index: "code" }) → THEN glob if needed</r>
   </rules>
-
-  <todo-usage hint="How to use TODO for tracking">
-    <create>
-      todowrite([
-        { id: "story-task-1", content: "Task 1: Create entity", status: "pending", priority: "high" },
-        { id: "story-task-2", content: "Task 2: Add repository", status: "pending", priority: "medium" },
-        ...
-      ])
-    </create>
-    <update-progress>
-      todoread() → get current list
-      todowrite([...list with task.status = "in_progress"])
-    </update-progress>
-    <mark-complete>
-      todowrite([...list with task.status = "completed"])
-    </mark-complete>
-  </todo-usage>
 </activation>
 
 <persona>

package/src/opencode/agents/pm.md

@@ -105,7 +105,7 @@ permission:
   </phase>
 
   <phase name="2. Planning">
-    <action>Create tasklist with todowrite()</action>
+    <action>Create tasklist with todowrite() (TODOv2)</action>
     <action>Present plan to user with specific deliverables</action>
     <action>Ask for confirmation with question() tool</action>
     <action>WAIT for user approval before proceeding</action>

package/src/opencode/config.yaml

@@ -211,7 +211,7 @@ epic_workflow:
   # 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
+  test_after_each_story: true
   
   # Run integration tests after epic complete
   # When true: all stories done → run epic integration tests

package/src/opencode/plugins/__tests__/usethis-todo.test.ts

@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "bun:test"
 import { readFile } from "fs/promises"
 import { join } from "path"
 import { createTempDir, cleanupTempDir } from "./helpers/mock-ctx"
-import { write, update, read } from "../../tools/usethis_todo"
+import { write, update, read, read_by_id, read_five } from "../../tools/usethis_todo"
 
 describe("usethis_todo tool", () => {
   let tempDir: string
@@ -28,7 +28,7 @@ describe("usethis_todo tool", () => {
     const output = await write.execute(
       {
         todos: [
-          { id: "A1", content: "First task", status: "ready", priority: "HIGH" },
+          { id: "A1", content: "First task", description: "Longer details", status: "ready", priority: "HIGH" },
           { id: "A2", content: "Second task", status: "pending", priority: "LOW" },
         ],
       },
@@ -41,6 +41,7 @@ describe("usethis_todo tool", () => {
     const enhanced = JSON.parse(await readFile(enhancedPath, "utf-8"))
     expect(enhanced.length).toBe(2)
     expect(enhanced[0].content).toBe("First task")
+    expect(enhanced[0].description).toBe("Longer details")
 
     const nativePath = join(
       process.env.XDG_DATA_HOME!,
@@ -52,6 +53,7 @@ describe("usethis_todo tool", () => {
     const native = JSON.parse(await readFile(nativePath, "utf-8"))
     expect(native.length).toBe(2)
     expect(native[0].content).toContain("First task")
+    expect(native[0].content).toContain("Longer details")
   })
 
   it("update merges by id and can add new tasks", async () => {
@@ -60,7 +62,7 @@ describe("usethis_todo tool", () => {
     await write.execute(
       {
         todos: [
-          { id: "A1", content: "First task", status: "pending", priority: "MED" },
+          { id: "A1", content: "First task", description: "v1", status: "pending", priority: "MED" },
         ],
       },
       ctx
@@ -69,7 +71,7 @@ describe("usethis_todo tool", () => {
     const result = await update.execute(
       {
         todos: [
-          { id: "A1", content: "First task", status: "done", priority: "MED" },
+          { id: "A1", content: "First task", description: "v2", status: "done", priority: "MED" },
           { id: "A2", content: "Second task", status: "ready", priority: "LOW" },
         ],
       },
@@ -82,6 +84,7 @@ describe("usethis_todo tool", () => {
     const enhanced = JSON.parse(await readFile(enhancedPath, "utf-8"))
     expect(enhanced.length).toBe(2)
     expect(enhanced.find((t: any) => t.id === "A1")?.status).toBe("done")
+    expect(enhanced.find((t: any) => t.id === "A1")?.description).toBe("v2")
   })
 
   it("read returns graph with content", async () => {
@@ -99,4 +102,78 @@ describe("usethis_todo tool", () => {
     expect(output).toContain("Task content")
     expect(output).toContain("Available Now")
   })
+
+  it("read_five returns up to 5 available tasks with description", async () => {
+    const ctx = { sessionID: "sess-five", directory: tempDir } as any
+    await write.execute(
+      {
+        todos: [
+          { id: "A1", content: "T1", description: "D1", status: "ready", priority: "HIGH" },
+          { id: "A2", content: "T2", status: "ready", priority: "MED" },
+          { id: "A3", content: "T3", status: "ready", priority: "LOW" },
+          { id: "A4", content: "T4", status: "ready", priority: "LOW" },
+          { id: "A5", content: "T5", status: "ready", priority: "LOW" },
+          { id: "A6", content: "T6", status: "ready", priority: "LOW" },
+        ],
+      },
+      ctx
+    )
+
+    const out = await read_five.execute({}, ctx)
+    expect(out).toContain("Next 5")
+    expect(out).toContain("A1")
+    expect(out).toContain("T1")
+    expect(out).toContain("D1")
+    expect(out).toContain("+1 more")
+  })
+
+  it("read_by_id returns task with resolved blockers", async () => {
+    const ctx = { sessionID: "sess-get", directory: tempDir } as any
+    await write.execute(
+      {
+        todos: [
+          {
+            id: "A1",
+            content: "Task content",
+            description: "More details",
+            status: "ready",
+            priority: "HIGH",
+            blockedBy: ["B1"],
+          },
+          {
+            id: "B1",
+            content: "Blocker task",
+            status: "done",
+            priority: "LOW",
+            blockedBy: ["C1"],
+          },
+          {
+            id: "C1",
+            content: "Root blocker",
+            status: "pending",
+            priority: "MED",
+          },
+        ],
+      },
+      ctx
+    )
+
+    const out = await read_by_id.execute({ id: "A1" }, ctx)
+    expect(out).toContain("id: A1")
+    expect(out).toContain("content:")
+    expect(out).toContain("Task content")
+    expect(out).toContain("blockedBy: B1")
+    expect(out).toContain("description:")
+    expect(out).toContain("More details")
+
+    expect(out).toContain("blockedBy (resolved):")
+    expect(out).toContain("- B1")
+    expect(out).toContain("- C1")
+  })
+
+  it("read_by_id returns not found", async () => {
+    const ctx = { sessionID: "sess-miss", directory: tempDir } as any
+    const out = await read_by_id.execute({ id: "NOPE" }, ctx)
+    expect(out).toContain("not found")
+  })
 })

package/src/opencode/plugins/usethis-todo-publish.ts

@@ -9,10 +9,16 @@ import type { Plugin } from "@opencode-ai/plugin"
 export const UsethisTodoPublish: Plugin = async ({ client }) => {
   return {
     "tool.execute.after": async (input, output) => {
-      if (input.tool !== "usethis_todo_write" && input.tool !== "usethis_todo_update") return
+      if (
+          input.tool !== "usethis_todo_write"
+          && input.tool !== "usethis_todo_update"
+          && input.tool !== "usethis_todo_read_five"
+          && input.tool !== "usethis_todo_read"
+          && input.tool !== "usethis_todo_read_by_id"
+      ) return
 
       const text = [
-          `## TODO`,
+        `## TODO`,
         // `session: ${input.sessionID}`,
         "",
         output.output

package/src/opencode/tools/usethis_todo.ts

@@ -1,16 +1,17 @@
 /**
  * TODO Tool with Dependencies & Priority — v3 (dual storage)
- * 
+ *
  * 4 commands:
  *   usethis_todo_write({ todos: [...] })    - create/update TODO list
  *   usethis_todo_read()                     - read TODO with graph analysis
- *   usethis_todo_read_next_five()           - get next 5 available tasks
+ *   usethis_todo_read_five()           - get next 5 available tasks
+ *   usethis_todo_read_by_id()           - get next 5 available tasks
  *   usethis_todo_update(id, field, value)   - update any task field
- * 
+ *
  * Storage:
  *   Enhanced: .opencode/session-todos/{sid}.json  (title, blockedBy, graph)
  *   Native:  ~/.local/share/opencode/storage/todo/{sid}.json  (TUI display)
- * 
+ *
  * Features:
  * - Hierarchical IDs: E01-S01-T01
  * - Dependencies: blockedBy field
@@ -30,7 +31,8 @@ import fs from "fs/promises"
 
 interface Todo {
   id: string              // E01-S01-T01
-  content: string         // Full task description
+  content: string         // Short task summary
+  description?: string    // Full task description (optional)
   status: string          // pending | ready | in_progress | waiting_review | done | cancelled
   priority: string        // CRIT | HIGH | MED | LOW
   blockedBy?: string[]    // IDs of blocking tasks
@@ -115,12 +117,13 @@ function toNative(todo: Todo): NativeTodo {
     MED: "medium",
     LOW: "low",
   }
-  
+
   const deps = todo.blockedBy?.length ? ` [← ${todo.blockedBy.join(", ")}]` : ""
+  const desc = todo.description?.trim() ? ` — ${todo.description.trim()}` : ""
 
   return {
     id: todo.id,
-    content: `${todo.content}${deps}`,
+    content: `${todo.content}${desc}${deps}`,
     status: statusMap[todo.status] || "pending",
     priority: prioMap[todo.priority] || "medium",
   }
@@ -139,16 +142,16 @@ async function writeTodos(todos: Todo[], sid: string, directory?: string): Promi
   const enhancedPath = getEnhancedPath(sid, directory)
   await fs.mkdir(path.dirname(enhancedPath), { recursive: true })
   await fs.writeFile(enhancedPath, JSON.stringify(todos, null, 2), "utf-8")
-  
+
   // 2. Native storage (for TUI display)
   const nativeTodos = todos.map(toNative)
   try {
     const nativePaths = await getNativePaths(sid)
     await Promise.allSettled(
-      nativePaths.map(async (nativePath) => {
-        await fs.mkdir(path.dirname(nativePath), { recursive: true })
-        await fs.writeFile(nativePath, JSON.stringify(nativeTodos, null, 2), "utf-8")
-      }),
+        nativePaths.map(async (nativePath) => {
+          await fs.mkdir(path.dirname(nativePath), { recursive: true })
+          await fs.writeFile(nativePath, JSON.stringify(nativeTodos, null, 2), "utf-8")
+        }),
     )
   } catch {
     // Native write failure is non-fatal
@@ -162,7 +165,7 @@ async function writeTodos(todos: Todo[], sid: string, directory?: string): Promi
 function analyzeGraph(todos: Todo[]): TodoGraph {
   const blocked: Record<string, string[]> = {}
   const availableTodos: Todo[] = []
-  
+
   for (const todo of todos) {
     if (todo.status !== "ready") continue
     const activeBlockers = (todo.blockedBy || []).filter(id => {
@@ -175,11 +178,11 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
       blocked[todo.id] = activeBlockers
     }
   }
-  
+
   const P: Record<string, number> = { CRIT: 0, HIGH: 1, MED: 2, LOW: 3 }
   availableTodos.sort((a, b) => (P[a.priority] ?? 2) - (P[b.priority] ?? 2))
   const available = availableTodos.map(t => t.id)
-  
+
   // Parallel groups
   const parallel: string[][] = []
   const seen = new Set<string>()
@@ -198,7 +201,7 @@ function analyzeGraph(todos: Todo[]): TodoGraph {
     }
     if (group.length > 0) parallel.push(group)
   }
-  
+
   return { todos, available, parallel, blocked }
 }
 
@@ -214,42 +217,45 @@ function formatGraph(graph: TodoGraph): string {
   const total = todos.length
   const done = todos.filter(t => t.status === "done").length
   const wip = todos.filter(t => t.status === "in_progress").length
-  
+
   const lines: string[] = [`═══ TODO Graph [${done}/${total} done, ${wip} in progress] ═══`, ""]
-  
+
   lines.push("All Tasks:")
   for (const t of todos) {
     const deps = t.blockedBy?.length ? ` ← ${t.blockedBy.join(", ")}` : ""
-    lines.push(`  ${SI(t.status)} ${PE(t.priority)} ${t.id}: ${t.content}${deps}`)
+    const desc = t.description?.trim() ? ` — ${t.description.trim()}` : ""
+    lines.push(`  ${SI(t.status)} ${PE(t.priority)} ${t.id}: ${t.content}${desc}${deps}`)
   }
   lines.push("")
-  
+
   if (graph.available.length > 0) {
     lines.push("Available Now:")
     for (const id of graph.available) {
       const t = todos.find(x => x.id === id)
-      lines.push(`  → ${PE(t?.priority)} ${id}: ${t?.content}`)
+      const desc = t?.description?.trim() ? ` — ${t.description.trim()}` : ""
+      lines.push(`  → ${PE(t?.priority)} ${id}: ${t?.content}${desc}`)
     }
   } else {
     lines.push("Available Now: none")
   }
   lines.push("")
-  
+
   const multi = graph.parallel.filter(g => g.length > 1)
   if (multi.length > 0) {
     lines.push("Parallel Groups:")
     multi.forEach((g, i) => lines.push(`  Group ${i + 1}: ${g.join(", ")}`))
     lines.push("")
   }
-  
+
   if (Object.keys(graph.blocked).length > 0) {
     lines.push("Blocked:")
     for (const [id, blockers] of Object.entries(graph.blocked)) {
       const t = todos.find(x => x.id === id)
-      lines.push(`  ⊗ ${id}: ${t?.content} ← waiting: ${blockers.join(", ")}`)
+      const desc = t?.description?.trim() ? ` — ${t.description.trim()}` : ""
+      lines.push(`  ⊗ ${id}: ${t?.content}${desc} ← waiting: ${blockers.join(", ")}`)
     }
   }
-  
+
   return lines.join("\n")
 }
 
@@ -258,27 +264,28 @@ function formatGraph(graph: TodoGraph): string {
 // ============================================================================
 
 export const write = tool({
-  description: "Create or update TODO list. TODOv2",
+  description: "Create or update TODO list. TODOv2 (Prefer this instead of TODO)",
   args: {
     todos: tool.schema.array(
-      tool.schema.object({
-        id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
-        content: tool.schema.string().describe("Full task description"),
-        status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
-        priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
-        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
-      })
+        tool.schema.object({
+          id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
+          content: tool.schema.string().describe("Short task summary"),
+          description: tool.schema.string().optional().describe("Full task description"),
+          status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
+          priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
+          blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
+        })
     ).describe("Array of todos"),
   },
   async execute(args, context) {
     const now = Date.now()
-    const todos = args.todos.map(t => ({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
+    const todos = args.todos.map((t: any) => ({ ...t, createdAt: t.createdAt || now, updatedAt: now }))
     await writeTodos(todos, context.sessionID, context.directory)
     return formatGraph(analyzeGraph(todos))
   },
 })
 
-export const read_next_five = tool({
+export const read_five = tool({
   description: "Read current TODO list. Shows Next 5 tasks.",
   args: {},
   async execute(_args, context) {
@@ -290,7 +297,8 @@ export const read_next_five = tool({
     for (const id of next5) {
       const t = graph.todos.find(x => x.id === id)
       if (t) {
-        lines.push(`${PE(t.priority)} ${id}: ${t.content}`)
+        const desc = t.description?.trim() ? `\n   ${t.description.trim()}` : ""
+        lines.push(`${PE(t.priority)} ${id}: ${t.content}${desc}`)
         lines.push("")
       }
     }
@@ -309,17 +317,88 @@ export const read = tool({
   },
 })
 
+export const read_by_id = tool({
+  description: "Read task by id.",
+  args: {
+    id: tool.schema.string().describe("Task ID"),
+  },
+  async execute(args, context) {
+    const todos = await readTodos(context.sessionID, context.directory)
+    const todo = todos.find(t => t.id === args.id)
+    if (!todo) return `❌ Task ${args.id} not found`
+
+    const byId = new Map(todos.map(t => [t.id, t]))
+
+    // Resolve blockers transitively (task -> blockedBy -> blockedBy ...)
+    const blockers: Todo[] = []
+    const missing: string[] = []
+    const seen = new Set<string>()
+    const stack = [...(todo.blockedBy || [])]
+
+    while (stack.length > 0) {
+      const id = stack.shift()!
+      if (seen.has(id)) continue
+      seen.add(id)
+
+      const t = byId.get(id)
+      if (!t) {
+        missing.push(id)
+        continue
+      }
+
+      blockers.push(t)
+      if (t.blockedBy?.length) stack.push(...t.blockedBy)
+    }
+
+    const lines: string[] = []
+    lines.push(`id: ${todo.id}`)
+    lines.push(`priority: ${todo.priority}`)
+    lines.push(`status: ${todo.status}`)
+
+    if (todo.blockedBy?.length) {
+      lines.push(`blockedBy: ${todo.blockedBy.join(", ")}`)
+    }
+
+    lines.push("")
+    lines.push("content:")
+    lines.push(todo.content)
+
+    if (todo.description?.trim()) {
+      lines.push("")
+      lines.push("description:")
+      lines.push(todo.description.trim())
+    }
+
+    if (blockers.length) {
+      lines.push("")
+      lines.push("blockedBy (resolved):")
+      for (const b of blockers) {
+        const d = b.description?.trim() ? ` — ${b.description.trim()}` : ""
+        lines.push(`- ${b.id} [${b.status}] ${b.priority}: ${b.content}${d}`)
+      }
+    }
+
+    if (missing.length) {
+      lines.push("")
+      lines.push(`blockedBy missing: ${missing.join(", ")}`)
+    }
+
+    return lines.join("\n")
+  },
+})
+
 export const update = tool({
-  description: "Update tasks. Same interface as write, but merges by id.",
+  description: "Update task(s). Send 1 or many for update",
   args: {
     todos: tool.schema.array(
-      tool.schema.object({
-        id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
-        content: tool.schema.string().describe("Full task description"),
-        status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
-        priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
-        blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
-      })
+        tool.schema.object({
+          id: tool.schema.string().describe("Task ID in concat format: E01-S01-T01"),
+          content: tool.schema.string().describe("Short task summary"),
+          description: tool.schema.string().optional().describe("Full task description"),
+          status: tool.schema.string().describe("pending | ready | in_progress | waiting_review | done | cancelled"),
+          priority: tool.schema.string().describe("CRIT | HIGH | MED | LOW"),
+          blockedBy: tool.schema.array(tool.schema.string()).optional().describe("IDs of blocking tasks"),
+        })
     ).describe("Array of todos to update"),
   },
   async execute(args, context) {