@comfanion/workflow 4.21.0 → 4.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.21.0",
+  "version": "4.22.0",
   "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": "3.0.0",
-  "buildDate": "2026-01-24T11:19:45.550Z",
+  "buildDate": "2026-01-24T11:24:58.085Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",
@@ -12,6 +12,8 @@
     "checklists",
     "commands",
     "tools",
+    "plugins",
+    "package.json",
     "opencode.json"
   ]
 }

package/src/opencode/package.json

@@ -0,0 +1,5 @@
+{
+  "dependencies": {
+    "@opencode-ai/plugin": "1.1.34"
+  }
+}

package/src/opencode/plugins/README.md

@@ -0,0 +1,133 @@
+# Plugins
+
+Plugins that extend OpenCode with hooks, events, and custom tools.
+
+## Available Plugins
+
+### file-indexer.ts
+
+Automatically reindexes changed files for semantic search.
+
+**Features:**
+- Detects file type and updates appropriate index (code, docs, config)
+- Debounces rapid changes (2s) to avoid excessive indexing
+- Hooks into Edit/Write tool execution
+- Logs indexing activity for transparency
+
+**Events:** `file.edited`, `document.updated`, `tool.execute.after`
+
+**How it works:**
+
+| File Extension | Index Updated |
+|----------------|---------------|
+| `.js`, `.ts`, `.py`, etc. | `code` |
+| `.md`, `.txt`, `.rst` | `docs` |
+| `.yaml`, `.json`, `.toml` | `config` |
+
+**Prerequisites:**
+```bash
+npx opencode-workflow vectorizer install
+npx opencode-workflow index --index code
+```
+
+---
+
+### custom-compaction.ts
+
+Intelligent session compaction that preserves flow context.
+
+**Features:**
+- Tracks todo list and story task status
+- Identifies critical documentation files for context
+- Generates smart continuation prompts
+- Differentiates between completed and interrupted tasks
+
+**Hook:** `experimental.session.compacting`
+
+**What it does:**
+
+| Scenario | Compaction Output |
+|----------|-------------------|
+| **Task Completed** | Summary of completed work, next steps, validation reminders |
+| **Task Interrupted** | Current task, what was done, resume instructions, file list |
+
+**Critical Files Passed to Context:**
+- `CLAUDE.md` - Project coding standards
+- `AGENTS.md` - Agent definitions
+- `project-context.md` - Project overview
+- `.opencode/config.yaml` - Flow config
+- `docs/prd.md` - Product requirements
+- `docs/architecture.md` - System architecture
+- `docs/coding-standards/*.md` - Coding patterns
+- Active story file (if in progress)
+
+## Installation
+
+Plugins in `.opencode/plugins/` are automatically loaded by OpenCode.
+
+```bash
+# No installation needed - just place files in .opencode/plugins/
+```
+
+## Creating Custom Plugins
+
+### Hook Types
+
+```typescript
+// Compaction - customize context preservation
+"experimental.session.compacting": async (input, output) => {
+  output.context.push("Custom context...")
+  // or replace entirely:
+  output.prompt = "Custom prompt..."
+}
+
+// Events - react to flow changes
+event: async ({ event }) => {
+  if (event.type === "session.idle") { /* ... */ }
+  if (event.type === "todo.updated") { /* ... */ }
+}
+
+// Tool hooks - intercept tool execution
+"tool.execute.before": async (input, output) => { /* ... */ }
+"tool.execute.after": async (input, output) => { /* ... */ }
+```
+
+### Session Events
+
+| Event | When | Use Case |
+|-------|------|----------|
+| `session.idle` | Agent finished responding | Check task completion, send notifications |
+| `todo.updated` | Todo list changed | Track progress, update external systems |
+| `file.edited` | File was modified | Track active files for context |
+| `session.compacted` | Session was compacted | Log, analytics |
+
+### Example: Story Progress Tracker
+
+```typescript
+export const StoryTrackerPlugin: Plugin = async (ctx) => {
+  return {
+    event: async ({ event }) => {
+      if (event.type === "todo.updated") {
+        // Sync with Jira, send Slack notification, etc.
+      }
+    }
+  }
+}
+```
+
+### Example: Auto-Read Documentation
+
+```typescript
+export const AutoContextPlugin: Plugin = async (ctx) => {
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      // Always include coding standards in compaction
+      output.context.push(`
+## Coding Standards (MUST follow)
+- Read docs/coding-standards/README.md on resume
+- Follow patterns from CLAUDE.md
+      `)
+    }
+  }
+}
+```

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

@@ -0,0 +1,256 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import { readFile, access } from "fs/promises"
+import { join } from "path"
+
+interface TaskStatus {
+  id: string
+  content: string
+  status: "pending" | "in_progress" | "completed" | "cancelled"
+  priority: string
+}
+
+interface StoryContext {
+  path: string
+  title: string
+  status: string
+  currentTask: string | null
+  completedTasks: string[]
+  pendingTasks: string[]
+}
+
+interface SessionContext {
+  todos: TaskStatus[]
+  story: StoryContext | null
+  relevantFiles: string[]
+  activeAgent: string | null
+}
+
+/**
+ * Custom Compaction Plugin
+ * 
+ * Intelligent context preservation during session compaction:
+ * - Tracks task/story completion status
+ * - Preserves relevant documentation files
+ * - Generates continuation prompts for seamless resumption
+ */
+export const CustomCompactionPlugin: Plugin = async (ctx) => {
+  const { directory } = ctx
+
+  async function getTodoList(): Promise<TaskStatus[]> {
+    try {
+      const todoPath = join(directory, ".opencode", "state", "todos.json")
+      const content = await readFile(todoPath, "utf-8")
+      return JSON.parse(content)
+    } catch {
+      return []
+    }
+  }
+
+  async function getActiveStory(): Promise<StoryContext | null> {
+    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) return null
+
+      const storyPath = inProgressMatch[1]
+      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]+(.+)/g
+      let match
+      while ((match = taskRegex.exec(storyContent)) !== null) {
+        const [, checked, taskId, taskName] = match
+        if (checked === "x") {
+          completedTasks.push(`T${taskId}: ${taskName}`)
+        } else {
+          if (!currentTask) currentTask = `T${taskId}: ${taskName}`
+          pendingTasks.push(`T${taskId}: ${taskName}`)
+        }
+      }
+
+      return {
+        path: storyPath,
+        title: titleMatch?.[1] || "Unknown Story",
+        status: statusMatch?.[1] || "unknown",
+        currentTask,
+        completedTasks,
+        pendingTasks
+      }
+    } catch {
+      return null
+    }
+  }
+
+  async function getRelevantFiles(): Promise<string[]> {
+    const relevantPaths: string[] = []
+    
+    const criticalFiles = [
+      "CLAUDE.md",
+      "AGENTS.md", 
+      "project-context.md",
+      ".opencode/config.yaml",
+      "docs/prd.md",
+      "docs/architecture.md",
+      "docs/coding-standards/README.md",
+      "docs/coding-standards/patterns.md"
+    ]
+
+    for (const filePath of criticalFiles) {
+      try {
+        await access(join(directory, filePath))
+        relevantPaths.push(filePath)
+      } catch {
+        // File doesn't exist, skip
+      }
+    }
+
+    const story = await getActiveStory()
+    if (story) {
+      relevantPaths.push(story.path)
+    }
+
+    return relevantPaths
+  }
+
+  async function buildContext(): Promise<SessionContext> {
+    const [todos, story, relevantFiles] = await Promise.all([
+      getTodoList(),
+      getActiveStory(),
+      getRelevantFiles()
+    ])
+
+    return { todos, story, relevantFiles, activeAgent: null }
+  }
+
+  function formatContext(ctx: SessionContext): string {
+    const sections: string[] = []
+
+    if (ctx.todos.length > 0) {
+      const inProgress = ctx.todos.filter(t => t.status === "in_progress")
+      const completed = ctx.todos.filter(t => t.status === "completed")
+      const pending = ctx.todos.filter(t => t.status === "pending")
+
+      sections.push(`## Task Status
+
+**In Progress:** ${inProgress.length > 0 ? inProgress.map(t => t.content).join(", ") : "None"}
+**Completed:** ${completed.length > 0 ? completed.map(t => `✅ ${t.content}`).join("\n") : "None"}
+**Pending:** ${pending.length > 0 ? pending.map(t => `⬜ ${t.content}`).join("\n") : "None"}`)
+    }
+
+    if (ctx.story) {
+      const s = ctx.story
+      const total = s.completedTasks.length + s.pendingTasks.length
+      const progress = total > 0 ? (s.completedTasks.length / total * 100).toFixed(0) : 0
+
+      sections.push(`## Active Story
+
+**Story:** ${s.title}
+**Path:** ${s.path}
+**Status:** ${s.status}
+**Progress:** ${progress}% (${s.completedTasks.length}/${total} tasks)
+
+### Current Task
+${s.currentTask || "All tasks complete"}
+
+### Completed
+${s.completedTasks.length > 0 ? s.completedTasks.map(t => `✅ ${t}`).join("\n") : "None"}
+
+### Remaining
+${s.pendingTasks.length > 0 ? s.pendingTasks.map(t => `⬜ ${t}`).join("\n") : "All done!"}`)
+    }
+
+    if (ctx.relevantFiles.length > 0) {
+      sections.push(`## Critical Files (MUST re-read)
+
+${ctx.relevantFiles.map(f => `- \`${f}\``).join("\n")}`)
+    }
+
+    return sections.join("\n\n---\n\n")
+  }
+
+  function formatInstructions(ctx: SessionContext): string {
+    const hasInProgressTasks = ctx.todos.some(t => t.status === "in_progress")
+    const hasInProgressStory = ctx.story?.status === "in-progress"
+
+    if (!hasInProgressTasks && !hasInProgressStory) {
+      return `## Status: COMPLETED
+
+Previous task was completed successfully.
+
+**Next:**
+1. Review completed work
+2. Run validation/tests if applicable
+3. Ask user for next task`
+    }
+
+    const instructions = [`## Status: INTERRUPTED
+
+Session compacted while work in progress.
+
+**Resume:**`]
+
+    if (ctx.story?.currentTask) {
+      instructions.push(`
+1. Read story: \`${ctx.story.path}\`
+2. Current task: ${ctx.story.currentTask}
+3. Load skill: \`.opencode/skills/dev-story/SKILL.md\`
+4. Continue red-green-refactor
+5. Run tests first`)
+    }
+
+    if (hasInProgressTasks) {
+      const task = ctx.todos.find(t => t.status === "in_progress")
+      instructions.push(`
+1. Resume: ${task?.content}
+2. Check previous messages
+3. Continue from last action
+4. Update todo when complete`)
+    }
+
+    return instructions.join("\n")
+  }
+
+  return {
+    "experimental.session.compacting": async (input, output) => {
+      const ctx = await buildContext()
+      const context = formatContext(ctx)
+      const instructions = formatInstructions(ctx)
+
+      output.context.push(`# Session Continuation
+
+${context}
+
+---
+
+${instructions}
+
+---
+
+## On Resume
+
+1. **Read critical files** listed above
+2. **Check task/story status**
+3. **Continue from last point** - never start over
+4. **Run tests first** if implementing code`)
+    },
+
+    event: async ({ event }) => {
+      if (event.type === "session.idle") {
+        const story = await getActiveStory()
+        if (story && story.pendingTasks.length === 0) {
+          console.log(`[compaction] Story complete: ${story.title}`)
+        }
+      }
+    }
+  }
+}
+
+export default CustomCompactionPlugin

package/src/opencode/plugins/file-indexer.ts

@@ -0,0 +1,169 @@
+import type { Plugin } from "@opencode-ai/plugin"
+import path from "path"
+import fs from "fs/promises"
+
+/**
+ * File Indexer Plugin
+ * 
+ * Automatically reindexes changed files for semantic search.
+ * 
+ * Listens to:
+ * - file.edited - when agent edits a file
+ * - file.watcher.updated - when file changes on disk
+ * - tool.execute.after - after Edit/Write tool executes
+ */
+
+// File extensions for each index type
+const INDEX_EXTENSIONS: Record<string, string[]> = {
+  code: ['.js', '.ts', '.jsx', '.tsx', '.mjs', '.cjs', '.py', '.go', '.rs', '.java', '.kt', '.swift', '.c', '.cpp', '.h', '.hpp', '.cs', '.rb', '.php', '.scala', '.clj'],
+  docs: ['.md', '.mdx', '.txt', '.rst', '.adoc'],
+  config: ['.yaml', '.yml', '.json', '.toml', '.ini', '.xml'],
+}
+
+// Debounce map to batch rapid changes
+const pendingFiles: Map<string, { indexName: string; timestamp: number }> = new Map()
+const DEBOUNCE_MS = 2000
+
+function getIndexForFile(filePath: string): string | null {
+  const ext = path.extname(filePath).toLowerCase()
+  for (const [indexName, extensions] of Object.entries(INDEX_EXTENSIONS)) {
+    if (extensions.includes(ext)) {
+      return indexName
+    }
+  }
+  return null
+}
+
+async function isVectorizerInstalled(projectRoot: string): Promise<boolean> {
+  try {
+    await fs.access(path.join(projectRoot, ".opencode", "vectorizer", "node_modules"))
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function processPendingFiles(projectRoot: string): Promise<void> {
+  if (pendingFiles.size === 0) return
+  
+  const now = Date.now()
+  const filesToProcess: Map<string, string[]> = new Map()
+  
+  for (const [filePath, info] of pendingFiles.entries()) {
+    if (now - info.timestamp >= DEBOUNCE_MS) {
+      const files = filesToProcess.get(info.indexName) || []
+      files.push(filePath)
+      filesToProcess.set(info.indexName, files)
+      pendingFiles.delete(filePath)
+    }
+  }
+  
+  if (filesToProcess.size === 0) return
+  
+  try {
+    const vectorizerModule = path.join(projectRoot, ".opencode", "vectorizer", "index.js")
+    const { CodebaseIndexer } = await import(`file://${vectorizerModule}`)
+    
+    for (const [indexName, files] of filesToProcess.entries()) {
+      const indexer = await new CodebaseIndexer(projectRoot, indexName).init()
+      
+      for (const filePath of files) {
+        try {
+          const wasIndexed = await indexer.indexSingleFile(filePath)
+          if (wasIndexed) {
+            console.log(`[file-indexer] ✅ Reindexed: ${path.relative(projectRoot, filePath)} -> ${indexName}`)
+          }
+        } catch (e) {
+          console.warn(`[file-indexer] ❌ Failed: ${filePath}: ${(e as Error).message}`)
+        }
+      }
+      
+      await indexer.unloadModel()
+    }
+  } catch (e) {
+    console.warn(`[file-indexer] ❌ Error: ${(e as Error).message}`)
+  }
+}
+
+export const FileIndexerPlugin: Plugin = async ({ directory }) => {
+  let processingTimeout: NodeJS.Timeout | null = null
+  
+  // Log plugin initialization
+  console.log(`[file-indexer] 🚀 Plugin loaded for: ${directory}`)
+  
+  function queueFileForIndexing(filePath: string): void {
+    const relativePath = path.relative(directory, filePath)
+    
+    // Skip ignored directories
+    if (
+      relativePath.startsWith('node_modules') ||
+      relativePath.startsWith('.git') ||
+      relativePath.startsWith('.opencode/vectors') ||
+      relativePath.startsWith('.opencode/vectorizer') ||
+      relativePath.startsWith('dist') ||
+      relativePath.startsWith('build')
+    ) {
+      return
+    }
+    
+    const indexName = getIndexForFile(filePath)
+    if (!indexName) return
+    
+    console.log(`[file-indexer] 📝 Queued: ${relativePath} -> ${indexName}`)
+    
+    pendingFiles.set(filePath, { indexName, timestamp: Date.now() })
+    
+    if (processingTimeout) {
+      clearTimeout(processingTimeout)
+    }
+    processingTimeout = setTimeout(async () => {
+      if (await isVectorizerInstalled(directory)) {
+        await processPendingFiles(directory)
+      }
+    }, DEBOUNCE_MS + 100)
+  }
+
+  return {
+    /**
+     * Event handler for file events
+     */
+    event: async ({ event }) => {
+      console.log(`[file-indexer] 📨 Event: ${event.type}`)
+      
+      // file.edited - when agent edits a file via Edit tool
+      if (event.type === "file.edited") {
+        const filePath = event.data?.path || event.data?.filePath
+        if (filePath) {
+          console.log(`[file-indexer] 📝 file.edited: ${filePath}`)
+          queueFileForIndexing(filePath)
+        }
+      }
+      
+      // file.watcher.updated - when file changes on disk (external or internal)
+      if (event.type === "file.watcher.updated") {
+        const filePath = event.data?.path || event.data?.filePath
+        if (filePath) {
+          console.log(`[file-indexer] 👁️ file.watcher.updated: ${filePath}`)
+          queueFileForIndexing(filePath)
+        }
+      }
+    },
+    
+    /**
+     * Hook: After any tool executes
+     */
+    "tool.execute.after": async (input, output) => {
+      const toolName = input.tool?.toLowerCase()
+      const filePath = input.args?.filePath
+      
+      console.log(`[file-indexer] 🔧 tool.execute.after: ${toolName}`)
+      
+      if ((toolName === "edit" || toolName === "write" || toolName === "patch") && filePath) {
+        console.log(`[file-indexer] 📝 Tool edited file: ${filePath}`)
+        queueFileForIndexing(filePath)
+      }
+    },
+  }
+}
+
+export default FileIndexerPlugin