@comfanion/workflow 4.10.0 → 4.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.10.0",
+  "version": "4.12.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-24T09:51:33.276Z",
+  "buildDate": "2026-01-24T10:10:09.577Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/agents/crawler.md

@@ -43,17 +43,25 @@ permission:
 
 <activation critical="MANDATORY">
   <step n="1">Receive exploration request from parent agent or user</step>
-  <step n="2">Scan codebase structure using glob/grep/bash</step>
-  <step n="3">Read relevant files to understand patterns</step>
-  <step n="4">Return structured findings with file:line references</step>
+  <step n="2">codeindex({ action: "list" }) → Check if semantic indexes exist</step>
+  <step n="3">IF indexes exist → codesearch({ query: "concept" }) → Get 5-10 relevant files</step>
+  <step n="4">Read top results from codesearch</step>
+  <step n="5">ONLY if needed: use grep for exact string matches</step>
+  <step n="6">Return structured findings with file:line references</step>
 
   <rules>
+    <r>CODESEARCH FIRST - Use semantic search before grep/glob!</r>
     <r>READ-ONLY - Cannot write or edit files</r>
     <r>No external calls - No network, no APIs</r>
     <r>Fast response - Return findings quickly, don't over-analyze</r>
     <r>Always cite file:line for findings</r>
     <r>Return structured output format</r>
   </rules>
+  
+  <anti-pattern>
+    ❌ WRONG: codeindex list → grep → glob → read 20 files
+    ✅ RIGHT: codeindex list → codesearch → read 3-5 files
+  </anti-pattern>
 </activation>
 
 <persona>
@@ -119,14 +127,24 @@ permission:
   </prefer-lsp-when>
 </lsp-exploration>
 
-<codesearch-exploration hint="ALWAYS TRY SEMANTIC SEARCH FIRST">
-  <critical>
-    BEFORE using grep/glob, ALWAYS check: codeindex({ action: "list" })
-    If indexes exist → USE codesearch instead of grep!
-    codesearch returns 5-10 relevant files vs 100+ grep matches
+<codesearch-exploration hint="MANDATORY - USE SEMANTIC SEARCH FIRST">
+  <critical priority="HIGHEST">
+    ⚠️ DO NOT USE grep/glob UNTIL you've tried codesearch!
+    
+    WRONG: codeindex({ action: "list" }) → see indexes → grep anyway
+    RIGHT: codeindex({ action: "list" }) → see indexes → codesearch({ query: "..." })
+    
+    codesearch returns 5-10 RELEVANT files
+    grep returns 100+ UNFILTERED matches - SLOW!
   </critical>
   
-  <first-step>codeindex({ action: "list" }) → Check if indexes exist</first-step>
+  <mandatory-workflow>
+    STEP 1: codeindex({ action: "list" }) → Check indexes
+    STEP 2: IF indexes exist → codesearch({ query: "your concept" }) → READ results
+    STEP 3: ONLY if codesearch fails → fall back to grep
+    
+    NEVER skip step 2!
+  </mandatory-workflow>
   
   <indexes hint="Different indexes for different content types">
     <index name="code">Source code (*.go, *.ts, *.py) - functions, classes, logic</index>
@@ -181,16 +199,27 @@ permission:
     - Regex pattern matching needed
   </use-grep-when>
   
-  <exploration-strategy priority="MANDATORY">
-    1. FIRST: codeindex({ action: "list" }) → Check what indexes exist
-    2. IF indexes exist:
-       - codesearch({ query: "concept", index: "code" }) → 5-10 relevant files (NOT 100+ grep matches!)
-       - Read top 3-5 results
-       - Done! Much faster than grep
-    3. IF no indexes:
-       - Suggest: "Index not found. Create with: codeindex({ action: 'reindex', index: 'code' })"
-       - Fall back to grep/glob
-    4. Use grep ONLY for exact string matches (function names, imports)
+  <exploration-strategy priority="MANDATORY - FOLLOW THIS ORDER">
+    1. codeindex({ action: "list" }) → See what indexes exist
+    
+    2. IMMEDIATELY after seeing indexes, USE THEM:
+       codesearch({ query: "category mapping logic", index: "code" })
+       → Returns 5-10 relevant files with code snippets!
+       
+    3. Read the codesearch results (top 3-5 files)
+       → You now have the answer. Done!
+       
+    4. ONLY use grep/glob for:
+       - Exact function name: grep "func CreateUser"
+       - Counting occurrences: grep -c "pattern"
+       - TODO/FIXME search
+       
+    5. IF no indexes exist:
+       - Suggest: codeindex({ action: "reindex", index: "code" })
+       - Fall back to grep as last resort
+       
+    ⚠️ ANTI-PATTERN: codeindex list → grep → glob → read 20 files = WRONG!
+    ✅ CORRECT:      codeindex list → codesearch → read 5 files = FAST!
   </exploration-strategy>
   
   <efficiency-comparison>

package/src/opencode/tools/codesearch.ts

@@ -43,6 +43,7 @@ Prerequisites: Run 'npx @comfanion/workflow index --index <name>' first.`,
     index: tool.schema.string().optional().default("code").describe("Index to search: code, docs, config, or custom name"),
     limit: tool.schema.number().optional().default(5).describe("Number of results to return (default: 5)"),
     searchAll: tool.schema.boolean().optional().default(false).describe("Search all indexes instead of just one"),
+    freshen: tool.schema.boolean().optional().default(true).describe("Auto-update stale files before searching (default: true)"),
   },
 
   async execute(args, context) {
@@ -65,6 +66,14 @@ Prerequisites: Run 'npx @comfanion/workflow index --index <name>' first.`,
       const limit = args.limit || 5
       const indexName = args.index || "code"
 
+      // Auto-freshen stale files before searching
+      let freshenStats = { updated: 0 }
+      if (args.freshen !== false) {
+        const tempIndexer = await new CodebaseIndexer(projectRoot, args.index || "code").init()
+        freshenStats = await tempIndexer.freshen()
+        await tempIndexer.unloadModel() // Free memory after freshen
+      }
+
       if (args.searchAll) {
         // Search all indexes
         const tempIndexer = await new CodebaseIndexer(projectRoot, "code").init()
@@ -76,8 +85,12 @@ Prerequisites: Run 'npx @comfanion/workflow index --index <name>' first.`,
 
         for (const idx of indexes) {
           const indexer = await new CodebaseIndexer(projectRoot, idx).init()
+          if (args.freshen !== false) {
+            await indexer.freshen()
+          }
           const results = await indexer.search(args.query, limit)
           allResults.push(...results.map((r: any) => ({ ...r, _index: idx })))
+          await indexer.unloadModel() // Free memory after each index search
         }
 
         // Sort by distance and take top N
@@ -96,6 +109,7 @@ Prerequisites: Run 'npx @comfanion/workflow index --index <name>' first.`,
         const indexer = await new CodebaseIndexer(projectRoot, indexName).init()
         const results = await indexer.search(args.query, limit)
         allResults = results.map((r: any) => ({ ...r, _index: indexName }))
+        await indexer.unloadModel() // Free memory after search
       }
 
       if (allResults.length === 0) {

package/src/vectorizer/index.js

@@ -196,6 +196,54 @@ class CodebaseIndexer {
     return results;
   }
 
+  /**
+   * Freshen index - check for stale files and reindex only changed ones
+   * Returns { checked, updated, deleted } counts
+   */
+  async freshen() {
+    let checked = 0;
+    let updated = 0;
+    let deleted = 0;
+
+    const indexedFiles = Object.keys(this.hashes);
+    
+    for (const relPath of indexedFiles) {
+      checked++;
+      const filePath = path.join(this.root, relPath);
+      
+      try {
+        const content = await fs.readFile(filePath, 'utf8');
+        const currentHash = this.fileHash(content);
+        
+        if (this.hashes[relPath] !== currentHash) {
+          // File changed - reindex it
+          await this.indexFile(filePath);
+          updated++;
+        }
+      } catch (e) {
+        // File deleted or unreadable - remove from index
+        delete this.hashes[relPath];
+        deleted++;
+      }
+    }
+    
+    if (deleted > 0) {
+      await this.saveHashes();
+    }
+    
+    return { checked, updated, deleted };
+  }
+
+  /**
+   * Index a single file by path (convenience method)
+   */
+  async indexSingleFile(filePath) {
+    const absPath = path.isAbsolute(filePath) 
+      ? filePath 
+      : path.join(this.root, filePath);
+    return await this.indexFile(absPath);
+  }
+
   /**
    * Get indexing statistics for this index
    */