@comfanion/workflow 4.38.1 → 4.38.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.38.1",
+  "version": "4.38.2",
   "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",
-  "buildDate": "2026-01-27T22:14:35.343Z",
+  "version": "4.38.2",
+  "buildDate": "2026-01-28T10:05:17.810Z",
   "files": [
     ".gitignore",
     "config.yaml",

package/src/opencode/FLOW.yaml

@@ -382,198 +382,6 @@ pipeline:
         output:
           - docs/sprint-artifacts/sprint-N/retrospective.md
 
-# =============================================================================
-# AGENTS (Personas - WHO does work)
-# =============================================================================
-# 
-# Model Strategy (based on Jan 2026 research):
-# - Architecture/Planning: Claude 4.5 Opus, Gemini 3 Pro (wisdom, context)
-# - Development: DeepSeek-V3.2 (cheapest, fast), GLM-4.7 (preserved thinking)
-# - Testing: GPT-5.2 Codex (best at finding bugs)
-# - UI/Frontend: MiniMax-M2.1 (fast, aesthetic)
-# - Research: Gemini 3 Pro (10M context, grounding)
-#
-agents:
-  analyst:
-    name: Sara
-    title: Business Analyst
-    icon: "📊"
-    description: Requirements Analyst - extracts FR/NFR through stakeholder interviews
-    mode: subagent
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.3
-    file: agents/analyst.md
-    expertise:
-      - Requirements engineering
-      - Business analysis
-      - Stakeholder interviews
-    personality: Methodical, thorough, asks clarifying questions
-    skills_used:
-      - requirements-gathering
-      - requirements-validation
-      - acceptance-criteria
-      - unit-writing
-      - methodologies
-      - doc-todo
-      - archiving
-
-  pm:
-    name: Dima
-    title: Product Manager
-    icon: "📋"
-    description: Product Manager - creates PRDs, epics, stories, sprint planning, Jira sync
-    mode: subagent
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.3
-    file: agents/pm.md
-    expertise:
-      - Product management
-      - B2B SaaS
-      - Agile/Sprint planning
-    personality: Business-focused, user-centric, data-driven
-    skills_used:
-      - prd-writing
-      - prd-validation
-      - acceptance-criteria
-      - epic-writing
-      - story-writing
-      - sprint-planning
-      - jira-integration
-      - unit-writing
-      - translation
-      - methodologies
-      - doc-todo
-      - archiving
-
-  architect:
-    name: Winston
-    title: Solution Architect
-    icon: "🏗️"
-    description: Solution Architect - designs system architecture, makes technical decisions
-    mode: subagent
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.2
-    file: agents/architect.md
-    expertise:
-      - Distributed systems
-      - Architecture patterns (chooses based on context)
-      - System design
-    personality: Technical, precise, patterns-focused
-    skills_used:
-      - architecture-design
-      - architecture-validation
-      - adr-writing
-      - coding-standards
-      - unit-writing
-      - methodologies
-      - api-design
-      - database-design
-      - diagram-creation
-      - module-documentation
-      - doc-todo
-      - archiving
-
-  dev:
-    name: Rick
-    title: Senior Developer
-    icon: "💻"
-    description: Developer - implements stories following red-green-refactor cycle
-    mode: subagent
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.2
-    file: agents/dev.md
-    expertise:
-      - Software development
-      - TDD/BDD
-      - Code review
-    personality: Precise, test-driven, follows story specifications exactly
-    skills_used:
-      - dev-story
-      - code-review
-      - test-design
-      - changelog
-      - doc-todo
-
-  coder:
-    name: Morty
-    title: Fast Coder
-    icon: "⚡"
-    description: Fast Coder - quick implementation, bug fixes, code following patterns
-    mode: subagent
-    hidden: true  # Internal subagent, invoked by @dev
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.1
-    file: agents/coder.md
-    expertise:
-      - Quick implementation
-      - Bug fixes
-      - Following existing patterns
-    personality: Fast, no questions, executes or fails
-    skills_used:
-      - test-design
-      - changelog
-      - doc-todo
-
-  reviewer:
-    name: Marcus
-    title: Code Reviewer
-    icon: "🔍"
-    description: Code Reviewer - security-focused review, bug finding, test coverage
-    mode: subagent
-    model: openai/gpt-5.2-codex  # Best at finding bugs and security issues
-    temperature: 0.1
-    file: agents/reviewer.md
-    expertise:
-      - Security review
-      - Bug finding
-      - Test coverage analysis
-      - Code quality
-    personality: Thorough, security-paranoid, always suggests fixes
-    skills_used:
-      - code-review
-    auto_invoke:
-      trigger: story_tasks_complete  # Called automatically when all story tasks done
-      before: story_marked_done
-
-  # Supporting Agents (not in main pipeline)
-  researcher:
-    name: Kristina
-    title: Researcher
-    icon: "🔍"
-    description: Researcher - conducts technical, market, and domain research
-    mode: subagent
-    model: google/gemini-2.5-pro  # Best for research - 1M context, grounding
-    # Alternatives: gemini-2.5-flash (faster), gemini-3-pro (preview)
-    temperature: 0.4
-    file: agents/researcher.md
-    expertise:
-      - Technical research
-      - Market analysis
-      - Domain expertise
-      - Deep research with web grounding
-    personality: Curious, thorough, evidence-based
-    skills_used:
-      - research-methodology
-      - methodologies
-
-  change-manager:
-    name: Bruce
-    title: Change Manager
-    icon: "🔄"
-    description: Change Manager - manages documentation change proposals
-    mode: subagent
-    model: anthropic/claude-sonnet-4-20250514
-    temperature: 0.2
-    file: agents/change-manager.md
-    expertise:
-      - Change management
-      - Impact analysis
-      - Version control
-    personality: Careful, systematic, risk-aware
-    skills_used:
-      - doc-todo
-      - archiving
-
 # =============================================================================
 # ARTIFACTS
 # =============================================================================
@@ -701,95 +509,3 @@ quickstart:
         - step: 18
           command: /retrospective
           description: Sprint retrospective
-
-# =============================================================================
-# HOOKS & EVENTS (Plugin Integration)
-# =============================================================================
-# 
-# Workflow emits events that plugins can subscribe to.
-# Plugins are in .opencode/plugins/ directory.
-#
-hooks:
-  # Compaction hook - preserve context during session compaction
-  compaction:
-    plugin: custom-compaction.ts
-    description: Preserves task/story status, critical files, continuation instructions
-    context_files:
-      always:
-        - CLAUDE.md
-        - AGENTS.md
-        - project-context.md
-        - .opencode/config.yaml
-      if_exists:
-        - docs/prd.md
-        - docs/architecture.md
-        - docs/coding-standards/README.md
-        - docs/coding-standards/patterns.md
-      dynamic:
-        - active_story_file    # From sprint-status.yaml
-        - modified_files       # Files edited in session
-
-events:
-  # Session lifecycle
-  session:
-    - session.started        # New session began
-    - session.idle           # Agent finished responding
-    - session.compacted      # Session was compacted
-    - session.error          # Error occurred
-
-  # Agent lifecycle  
-  agent:
-    - agent.activated        # Agent persona loaded
-    - agent.skill.loaded     # Skill file was read
-    - agent.task.started     # Agent started a task
-    - agent.task.completed   # Agent completed a task
-
-  # Workflow pipeline
-  workflow:
-    - workflow.stage.started     # Pipeline stage began
-    - workflow.stage.completed   # Pipeline stage finished
-    - workflow.stage.skipped     # Optional stage skipped
-    - workflow.validation.passed # Validation succeeded
-    - workflow.validation.failed # Validation failed
-
-  # Document lifecycle
-  document:
-    - document.created       # New doc created
-    - document.updated       # Doc modified
-    - document.validated     # Doc passed validation
-    - document.archived      # Doc moved to archive
-
-  # Sprint/Story lifecycle
-  sprint:
-    - epic.created           # Epic document created
-    - story.created          # Story document created
-    - story.started          # Story status → in-progress
-    - story.task.completed   # Task marked [x]
-    - story.completed        # All tasks done, status → review
-    - story.approved         # Code review passed, status → done
-    - sprint.planned         # Sprint planning completed
-    - sprint.completed       # All stories done
-
-  # Jira integration
-  jira:
-    - jira.sync.started      # Sync began
-    - jira.sync.completed    # Sync finished
-    - jira.issue.created     # New issue in Jira
-    - jira.issue.updated     # Issue updated
-    - jira.transition        # Status changed
-
-# Example plugin subscriptions
-# 
-# .opencode/plugins/notifications.ts:
-#   event: async ({ event }) => {
-#     if (event.type === "story.completed") {
-#       await sendSlackNotification(event.data)
-#     }
-#   }
-#
-# .opencode/plugins/jira-auto-sync.ts:
-#   event: async ({ event }) => {
-#     if (event.type === "story.task.completed") {
-#       await updateJiraProgress(event.data)
-#     }
-#   }

package/src/opencode/config.yaml

@@ -27,9 +27,6 @@ documentation:
     enforced: true  # Cannot be changed
     paths:
       - "docs/"
-      - "CLAUDE.md"
-      - "README.md"
-      - ".opencode/"
       
   # User-facing docs (translations, Confluence export)
   user_facing:
@@ -83,13 +80,6 @@ workflow:
   # Default validation level: strict | normal | minimal
   validation_level: normal
 
-# =============================================================================
-# AGENT DEFAULTS
-# =============================================================================
-agents:
-  default_model: "anthropic/claude-sonnet-4-20250514"
-  default_temperature: 0.3
-  
 # =============================================================================
 # JIRA INTEGRATION
 # =============================================================================

package/src/opencode/opencode.json

@@ -21,7 +21,8 @@
   "tools": {
     "lsp": true,
     "search": true,
-    "codeindex": true
+    "codeindex": true,
+    "usethis-todo": true
   },
   
   "permission": {

package/src/opencode/package.json

@@ -4,6 +4,6 @@
     "test:leak": "bun test --smol plugins/__tests__/ --test-name-pattern 'memory safety'"
   },
   "dependencies": {
-    "@opencode-ai/plugin": "1.1.36"
+    "@opencode-ai/plugin": "1.1.39"
   }
 }

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

@@ -0,0 +1,102 @@
+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"
+
+describe("usethis_todo tool", () => {
+  let tempDir: string
+  let originalXdg: string | undefined
+
+  beforeEach(async () => {
+    tempDir = await createTempDir()
+    originalXdg = process.env.XDG_DATA_HOME
+    process.env.XDG_DATA_HOME = join(tempDir, "xdg-data")
+  })
+
+  afterEach(async () => {
+    if (originalXdg === undefined) {
+      delete process.env.XDG_DATA_HOME
+    } else {
+      process.env.XDG_DATA_HOME = originalXdg
+    }
+    await cleanupTempDir(tempDir)
+  })
+
+  it("writes enhanced and native todo files", async () => {
+    const ctx = { sessionID: "sess-test", directory: tempDir } as any
+    const output = await write.execute(
+      {
+        todos: [
+          { id: "A1", content: "First task", status: "ready", priority: "HIGH" },
+          { id: "A2", content: "Second task", status: "pending", priority: "LOW" },
+        ],
+      },
+      ctx
+    )
+
+    expect(output).toContain("TODO Graph")
+
+    const enhancedPath = join(tempDir, ".opencode", "session-todos", "sess-test.json")
+    const enhanced = JSON.parse(await readFile(enhancedPath, "utf-8"))
+    expect(enhanced.length).toBe(2)
+    expect(enhanced[0].content).toBe("First task")
+
+    const nativePath = join(
+      process.env.XDG_DATA_HOME!,
+      "opencode",
+      "storage",
+      "todo",
+      "sess-test.json"
+    )
+    const native = JSON.parse(await readFile(nativePath, "utf-8"))
+    expect(native.length).toBe(2)
+    expect(native[0].content).toContain("First task")
+  })
+
+  it("update merges by id and can add new tasks", async () => {
+    const ctx = { sessionID: "sess-merge", directory: tempDir } as any
+
+    await write.execute(
+      {
+        todos: [
+          { id: "A1", content: "First task", status: "pending", priority: "MED" },
+        ],
+      },
+      ctx
+    )
+
+    const result = await update.execute(
+      {
+        todos: [
+          { id: "A1", content: "First task", status: "done", priority: "MED" },
+          { id: "A2", content: "Second task", status: "ready", priority: "LOW" },
+        ],
+      },
+      ctx
+    )
+
+    expect(result).toContain("Updated 2 task(s)")
+
+    const enhancedPath = join(tempDir, ".opencode", "session-todos", "sess-merge.json")
+    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")
+  })
+
+  it("read returns graph with content", async () => {
+    const ctx = { sessionID: "sess-read", directory: tempDir } as any
+    await write.execute(
+      {
+        todos: [
+          { id: "A1", content: "Task content", status: "ready", priority: "HIGH" },
+        ],
+      },
+      ctx
+    )
+
+    const output = await read.execute({}, ctx)
+    expect(output).toContain("Task content")
+    expect(output).toContain("Available Now")
+  })
+})

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

@@ -0,0 +1,36 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+/**
+ * Publishes a TODO snapshot into the session chat.
+ *
+ * Why: the TODO sidebar may not live-refresh when we write native todo files
+ * (no todo.updated Bus event). This makes changes visible in the main dialog.
+ */
+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
+
+      const text = [
+          `## TODO`,
+        // `session: ${input.sessionID}`,
+        "",
+        output.output
+      ].join("\n")
+
+      try {
+        await client.session.prompt({
+          path: { id: input.sessionID },
+          body: {
+            noReply: true,
+            parts: [{ type: "text", text }],
+          },
+        })
+      } catch {}
+
+      // Debug toasts removed
+    },
+  }
+}
+
+export default UsethisTodoPublish

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

@@ -0,0 +1,37 @@
+import type { Plugin } from "@opencode-ai/plugin"
+
+/**
+ * UseThis TODO UI Plugin — zero-state
+ * 
+ * ONLY sets output.title for usethis_todo_* tools in TUI.
+ * No caching, no env vars, no before hook, no HTTP calls.
+ * Parses tool output string directly in after hook.
+ */
+
+export const UsethisTodoUIPlugin: Plugin = async () => {
+  return {
+    "tool.execute.after": async (input, output) => {
+      if (!input.tool.startsWith("usethis_todo_")) return
+
+      const out = output.output || ""
+
+      if (input.tool === "usethis_todo_write") {
+        const match = out.match(/\[(\d+)\/(\d+) done/)
+        output.title = match ? `📋 TODO: ${match[2]} tasks` : "📋 TODO updated"
+
+      } else if (input.tool === "usethis_todo_update") {
+        const match = out.match(/^✅ (.+)$/m)
+        output.title = match ? `📝 ${match[1]}` : "📝 Task updated"
+
+      } else if (input.tool === "usethis_todo_read") {
+        const match = out.match(/\[(\d+)\/(\d+) done, (\d+) in progress\]/)
+        output.title = match ? `📋 TODO [${match[1]}/${match[2]} done]` : "📋 TODO list"
+
+      } else if (input.tool === "usethis_todo_read_next_five") {
+        output.title = "📋 Next 5 tasks"
+      }
+    }
+  }
+}
+
+export default UsethisTodoUIPlugin

package/src/opencode/tools/usethis_todo.ts

@@ -0,0 +1,344 @@
+/**
+ * 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_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
+ * - Priority: CRIT | HIGH | MED | LOW (auto-sorted)
+ * - Graph: shows available, blocked, parallel tasks
+ * - Dual write: native OpenCode storage for TUI integration
+ */
+
+import { tool } from "@opencode-ai/plugin"
+import path from "path"
+import os from "os"
+import fs from "fs/promises"
+
+// ============================================================================
+// Types
+// ============================================================================
+
+interface Todo {
+  id: string              // E01-S01-T01
+  content: string         // Full task description
+  status: string          // pending | ready | in_progress | waiting_review | done | cancelled
+  priority: string        // CRIT | HIGH | MED | LOW
+  blockedBy?: string[]    // IDs of blocking tasks
+  createdAt?: number
+  updatedAt?: number
+}
+
+interface NativeTodo {
+  id: string
+  content: string         // "title: content" combined
+  status: string          // pending | in_progress | completed | cancelled
+  priority: string        // high | medium | low
+}
+
+interface TodoGraph {
+  todos: Todo[]
+  available: string[]
+  parallel: string[][]
+  blocked: Record<string, string[]>
+}
+
+// ============================================================================
+// Storage — dual write
+// ============================================================================
+
+// Resolve project directory (context.directory may be undefined via MCP)
+function dir(directory?: string): string {
+  return directory || process.env.OPENCODE_PROJECT_DIR || process.cwd()
+}
+
+// Enhanced storage path (project-local)
+function getEnhancedPath(sid: string, directory?: string): string {
+  return path.join(dir(directory), ".opencode", "session-todos", `${sid || "current"}.json`)
+}
+
+async function getNativeDataDirs(): Promise<string[]> {
+  const dirs = new Set<string>()
+
+  // 1) xdg-basedir (what OpenCode itself uses)
+  try {
+    const mod: any = await import("xdg-basedir")
+    if (mod?.xdgData && typeof mod.xdgData === "string") {
+      dirs.add(mod.xdgData)
+    }
+  } catch {
+    // ignore
+  }
+
+  // 2) explicit XDG override
+  if (process.env.XDG_DATA_HOME) {
+    dirs.add(process.env.XDG_DATA_HOME)
+  }
+
+  // 3) common fallbacks
+  dirs.add(path.join(os.homedir(), ".local", "share"))
+  dirs.add(path.join(os.homedir(), "Library", "Application Support"))
+
+  return [...dirs]
+}
+
+async function getNativePaths(sid: string): Promise<string[]> {
+  const baseDirs = await getNativeDataDirs()
+  const file = `${sid || "current"}.json`
+  return baseDirs.map((base) => path.join(base, "opencode", "storage", "todo", file))
+}
+
+// Map our format → native format
+function toNative(todo: Todo): NativeTodo {
+  // Status mapping: our → native
+  const statusMap: Record<string, string> = {
+    pending: "pending",
+    ready: "pending",           // native has no "ready"
+    in_progress: "in_progress",
+    waiting_review: "in_progress",  // native has no "waiting_review"
+    done: "completed",          // native uses "completed" not "done"
+    cancelled: "cancelled",
+  }
+  // Priority mapping: CRIT/HIGH/MED/LOW → high/medium/low
+  const prioMap: Record<string, string> = {
+    CRIT: "high",
+    HIGH: "high",
+    MED: "medium",
+    LOW: "low",
+  }
+  
+  const deps = todo.blockedBy?.length ? ` [← ${todo.blockedBy.join(", ")}]` : ""
+
+  return {
+    id: todo.id,
+    content: `${todo.content}${deps}`,
+    status: statusMap[todo.status] || "pending",
+    priority: prioMap[todo.priority] || "medium",
+  }
+}
+
+async function readTodos(sid: string, directory?: string): Promise<Todo[]> {
+  try {
+    return JSON.parse(await fs.readFile(getEnhancedPath(sid, directory), "utf-8"))
+  } catch {
+    return []
+  }
+}
+
+async function writeTodos(todos: Todo[], sid: string, directory?: string): Promise<void> {
+  // 1. Enhanced storage (our full format)
+  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")
+      }),
+    )
+  } catch {
+    // Native write failure is non-fatal
+  }
+}
+
+// ============================================================================
+// Graph analysis
+// ============================================================================
+
+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 => {
+      const b = todos.find(t => t.id === id)
+      return b && b.status !== "done"
+    })
+    if (activeBlockers.length === 0) {
+      availableTodos.push(todo)
+    } else {
+      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>()
+  for (const id of available) {
+    if (seen.has(id)) continue
+    const group = [id]
+    seen.add(id)
+    for (const other of available) {
+      if (seen.has(other)) continue
+      const a = todos.find(t => t.id === id)
+      const b = todos.find(t => t.id === other)
+      if (!b?.blockedBy?.includes(id) && !a?.blockedBy?.includes(other)) {
+        group.push(other)
+        seen.add(other)
+      }
+    }
+    if (group.length > 0) parallel.push(group)
+  }
+  
+  return { todos, available, parallel, blocked }
+}
+
+// ============================================================================
+// Formatting
+// ============================================================================
+
+const PE = (p?: string) => p === "CRIT" ? "🔴" : p === "HIGH" ? "🟠" : p === "LOW" ? "🟢" : "🟡"
+const SI = (s: string) => s === "done" ? "✓" : s === "in_progress" ? "⚙" : s === "ready" ? "○" : s === "cancelled" ? "✗" : s === "waiting_review" ? "⏳" : "·"
+
+function formatGraph(graph: TodoGraph): string {
+  const { todos } = graph
+  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}`)
+  }
+  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}`)
+    }
+  } 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(", ")}`)
+    }
+  }
+  
+  return lines.join("\n")
+}
+
+// ============================================================================
+// Tools
+// ============================================================================
+
+export const write = tool({
+  description: "Create or update TODO list. TODOv2",
+  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"),
+      })
+    ).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 }))
+    await writeTodos(todos, context.sessionID, context.directory)
+    return formatGraph(analyzeGraph(todos))
+  },
+})
+
+export const read_next_five = tool({
+  description: "Read current TODO list. Shows Next 5 tasks.",
+  args: {},
+  async execute(_args, context) {
+    const todos = await readTodos(context.sessionID, context.directory)
+    const graph = analyzeGraph(todos)
+    if (graph.available.length === 0) return "No tasks available. All blocked or not ready."
+    const next5 = graph.available.slice(0, 5)
+    const lines: string[] = ["Next 5 available tasks:", ""]
+    for (const id of next5) {
+      const t = graph.todos.find(x => x.id === id)
+      if (t) {
+        lines.push(`${PE(t.priority)} ${id}: ${t.content}`)
+        lines.push("")
+      }
+    }
+    if (graph.available.length > 5) lines.push(`... +${graph.available.length - 5} more`)
+    return lines.join("\n")
+  },
+})
+
+export const read = tool({
+  description: "Read current TODO list. Shows all tasks.",
+  args: {},
+  async execute(_args, context) {
+    const todos = await readTodos(context.sessionID, context.directory)
+    if (todos.length === 0) return "No todos. Use usethis_todo_write to create."
+    return formatGraph(analyzeGraph(todos))
+  },
+})
+
+export const update = tool({
+  description: "Update tasks. Same interface as write, but merges by id.",
+  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"),
+      })
+    ).describe("Array of todos to update"),
+  },
+  async execute(args, context) {
+    const todos = await readTodos(context.sessionID, context.directory)
+    const now = Date.now()
+    const byId = new Map(todos.map(t => [t.id, t]))
+
+    for (const incoming of args.todos) {
+      const existing = byId.get(incoming.id)
+      if (existing) {
+        Object.assign(existing, incoming)
+        existing.updatedAt = now
+      } else {
+        byId.set(incoming.id, { ...incoming, createdAt: now, updatedAt: now })
+      }
+    }
+
+    const merged = [...byId.values()]
+    await writeTodos(merged, context.sessionID, context.directory)
+    return `✅ Updated ${args.todos.length} task(s)\n\n${formatGraph(analyzeGraph(merged))}`
+  },
+})