@comfanion/workflow 4.36.13 → 4.36.15

package/README.md

@@ -1,15 +1,61 @@
 # @comfanion/workflow
 
-Initialize OpenCode Workflow system for AI-assisted development.
+AI-assisted development workflow with **semantic code search**, agents, and structured documentation.
 
 [![npm version](https://img.shields.io/npm/v/@comfanion/workflow.svg)](https://www.npmjs.com/package/@comfanion/workflow)
 
+## Features
+
+- 🔍 **Semantic Code Search** - Find code by meaning, not just text (`"authentication logic"` → finds auth handlers)
+- 🤖 **AI Agents** - Specialized personas (Analyst, PM, Architect, Developer) with skills
+- 📝 **Structured Workflow** - PRD → Architecture → Epics → Stories → Implementation
+- 🔄 **Auto-indexing** - Background indexing on startup with fun toast notifications
+- 🎯 **Jira Integration** - Bidirectional sync with your project
+
 ## Quick Start
 
 ```bash
 npx @comfanion/workflow init
 ```
 
+## Semantic Code Search
+
+Search your codebase by **meaning**, not just text matching:
+
+```bash
+# In Claude Code / AI assistant:
+/search "user authentication middleware"    # Finds auth-related code
+/search "database connection handling"      # Finds DB setup
+/search "error handling patterns"           # Finds error handlers
+```
+
+### How It Works
+
+1. **Vectorizer** converts code into embeddings using local AI model
+2. **Indexes** are stored in `.opencode/vectors/` (code, docs, config)
+3. **Search** finds semantically similar code chunks
+4. **Auto-indexer** keeps indexes fresh on startup
+
+### Available Indexes
+
+| Index | Files | Use Case |
+|-------|-------|----------|
+| `code` | `*.js, *.ts, *.py, *.go...` | Find functions, classes, logic |
+| `docs` | `*.md, *.txt` | Find documentation, guides |
+| `config` | `*.yaml, *.json` | Find configuration, settings |
+
+### Commands
+
+```bash
+# Manual indexing
+npx @comfanion/workflow index              # Index all
+npx @comfanion/workflow index --code       # Index code only
+npx @comfanion/workflow index --docs       # Index docs only
+
+# Check index status
+npx @comfanion/workflow index --status
+```
+
 ## Installation
 
 ### NPX (recommended)
@@ -22,11 +68,15 @@ npx @comfanion/workflow init
 
 ```bash
 npm install -g @comfanion/workflow
-comfanion-workflow init
-# or
 opencode-workflow init
 ```
 
+### Alternative Package Name
+
+```bash
+npx create-opencode-workflow init
+```
+
 ## Commands
 
 ### `init`
@@ -40,21 +90,13 @@ npx @comfanion/workflow init
 **Interactive prompts:**
 
 1. **Your name** - For personalized agent communication
-2. **Communication language** - Ukrainian or English
+2. **Communication language** - Ukrainian, English, Russian
 3. **Development methodology** - TDD or STUB
-4. **Jira integration** - Enable/disable
-5. **Repository structure** - Create README, CONTRIBUTING, etc.
+4. **Vectorizer** - Enable semantic search
+5. **Jira integration** - Enable/disable
 
 **Flags:**
 
-```bash
-# Skip prompts, use defaults
-npx @comfanion/workflow init -y
-
-# With specific options
-npx @comfanion/workflow init --tdd --jira --full
-```
-
 | Flag | Description |
 |------|-------------|
 | `-y, --yes` | Skip prompts, use defaults |
@@ -65,12 +107,17 @@ npx @comfanion/workflow init --tdd --jira --full
 
 ### `update`
 
-Update `.opencode/` to latest version while preserving `config.yaml`.
+Update `.opencode/` to latest version.
 
 ```bash
 npx @comfanion/workflow update
 ```
 
+**Preserves:**
+- ✅ Your `config.yaml` (with comments!)
+- ✅ Vector indexes (`.opencode/vectors/`)
+- ✅ Custom settings
+
 ### `doctor`
 
 Check installation health.
@@ -79,49 +126,102 @@ Check installation health.
 npx @comfanion/workflow doctor
 ```
 
-### `config`
+### `vectorizer`
 
-Show current configuration.
+Manage semantic search vectorizer.
 
 ```bash
-npx @comfanion/workflow config
+npx @comfanion/workflow vectorizer install   # Install dependencies
+npx @comfanion/workflow vectorizer status    # Check status
+```
+
+## Configuration
+
+### `config.yaml`
+
+```yaml
+# User settings
+user_name: "Developer"
+communication_language: "en"  # en, uk, ru
+
+# Development
+development:
+  methodology: tdd  # tdd or stub
+
+# Semantic Search
+vectorizer:
+  enabled: true
+  auto_index: true      # Auto-index on startup
+  debounce_ms: 5000
+  indexes:
+    code: { enabled: true }
+    docs: { enabled: true }
+    config: { enabled: false }
+  exclude:
+    - "node_modules/**"
+    - "dist/**"
+    - "*.min.js"
+
+# Jira Integration
+jira:
+  enabled: false
+  url: "https://your-domain.atlassian.net"
+  project_key: "PROJ"
 ```
 
 ## What Gets Created
 
-### `.opencode/` (always)
+### `.opencode/`
 
 ```
 .opencode/
 ├── config.yaml          # Your configuration
-├── FLOW.yaml            # Workflow definition (v3.0)
-├── agents/              # Agent personas
-├── skills/              # Knowledge modules with templates (25+)
-├── workflows/           # Workflow instructions
-├── checklists/          # Validation checklists
+├── FLOW.yaml            # Workflow definition
+├── agents/              # AI agent personas
+│   ├── analyst.md       # Business Analyst
+│   ├── pm.md            # Product Manager
+│   ├── architect.md     # Solution Architect
+│   └── dev.md           # Senior Developer
+├── skills/              # Knowledge modules (25+)
+├── plugins/             # Auto-indexer plugin
+├── vectorizer/          # Semantic search engine
+│   ├── index.js
+│   └── package.json
+├── vectors/             # Vector indexes (auto-created)
+│   ├── code/
+│   ├── docs/
+│   └── config/
+├── tools/               # MCP tools
+│   ├── search.ts        # Semantic search tool
+│   └── codeindex.ts     # Index management tool
 └── commands/            # Slash commands
 ```
 
-### `docs/` (always)
+### `docs/`
 
 ```
 docs/
 ├── sprint-artifacts/    # Epics, stories, sprints
 ├── requirements/        # Requirements documents
 ├── architecture/        # Architecture + ADRs
-├── api/                 # API documentation
-├── coding-standards/    # Coding standards
-└── confluence/          # Translations (Ukrainian)
+└── coding-standards/    # Coding patterns
 ```
 
-### Repository files (with `--full`)
+## Auto-Indexer Plugin
 
-```
-README.md                # Project readme
-CONTRIBUTING.md          # Git workflow, commit conventions
-CHANGELOG.md             # Change history
-.gitignore               # Git ignore patterns
-.gitattributes           # Git attributes
+The auto-indexer runs on Claude Code / AI assistant startup:
+
+- 🔍 Checks if indexes need updating
+- 📊 Shows toast notification with file count
+- ☕ Shows fun message while indexing ("Grab a coffee!")
+- 📝 Logs to `.opencode/indexer.log`
+
+**Disable auto-indexing:**
+
+```yaml
+# config.yaml
+vectorizer:
+  auto_index: false
 ```
 
 ## Methodologies
@@ -129,9 +229,9 @@ CHANGELOG.md             # Change history
 ### TDD (Test-Driven Development)
 
 ```
-1. Write failing test
-2. Write minimal code to pass
-3. Refactor
+1. Write failing test (RED)
+2. Write minimal code to pass (GREEN)
+3. Refactor (BLUE)
 4. Repeat
 ```
 
@@ -146,13 +246,18 @@ CHANGELOG.md             # Change history
 
 ## Jira Integration
 
-If enabled, set credentials:
+Set credentials:
 
 ```bash
 export JIRA_EMAIL="your-email@company.com"
 export JIRA_API_TOKEN="your-api-token"
 ```
 
+## Requirements
+
+- **Node.js** >= 18
+- **~100MB disk** for vectorizer dependencies
+
 ## Links
 
 - **npm:** https://www.npmjs.com/package/@comfanion/workflow

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.36.13",
+  "version": "4.36.15",
   "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-24T15:30:55.138Z",
+  "buildDate": "2026-01-24T15:52:25.533Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",

package/src/opencode/config.yaml

@@ -235,28 +235,50 @@ vectorizer:
   # Debounce time in ms (wait before indexing after file change)
   debounce_ms: 1000
   
-  # Indexes to maintain
+  # Indexes to maintain - each has pattern (what to include) and ignore (what to skip)
   indexes:
+    # Code index - source code files
     code:
       enabled: true
-      extensions: ['.js', '.ts', '.jsx', '.tsx', '.py', '.go', '.rs', '.java']
+      # Glob pattern for files to index
+      pattern: "**/*.{js,ts,jsx,tsx,mjs,cjs,py,go,rs,java,kt,swift,c,cpp,h,hpp,cs,rb,php,scala,clj}"
+      # Glob patterns to ignore
+      ignore:
+        - "**/node_modules/**"
+        - "**/.git/**"
+        - "**/dist/**"
+        - "**/build/**"
+        - "**/.opencode/**"
+        - "**/docs/**"
+        - "**/vendor/**"
+        - "**/__pycache__/**"
+        - "**/*.min.js"
+        - "**/*.bundle.js"
+    
+    # Documentation index - markdown, text files
     docs:
       enabled: true
-      extensions: ['.md', '.mdx', '.txt', '.rst']
+      # Only docs folder by default (change to "**/*.md" for all markdown)
+      pattern: "docs/**/*.{md,mdx,txt,rst,adoc}"
+      ignore: []
+    
+    # Configuration index - yaml, json, toml
     config:
-      enabled: false  # Usually not needed
-      extensions: ['.yaml', '.yml', '.json', '.toml']
+      enabled: false               # Disabled by default
+      pattern: "**/*.{yaml,yml,json,toml,ini}"
+      ignore:
+        - "**/node_modules/**"
+        - "**/.git/**"
+        - "**/.opencode/**"
+        - "**/package-lock.json"
+        - "**/yarn.lock"
   
-  # Directories to exclude from indexing
+  # Global exclude patterns (applied to ALL indexes, in addition to per-index ignore)
   exclude:
     - node_modules
     - .git
-    - dist
-    - build
     - .opencode/vectors
     - .opencode/vectorizer
-    - vendor
-    - __pycache__
 
 # =============================================================================
 # LSP (Language Server Protocol) - Code Intelligence

package/src/vectorizer/index.js

@@ -17,9 +17,9 @@ if (!DEBUG) {
 }
 
 /**
- * Index presets for different content types
+ * Default index presets (can be overridden by config.yaml)
  */
-const INDEX_PRESETS = {
+const DEFAULT_PRESETS = {
   code: {
     pattern: '**/*.{js,ts,jsx,tsx,mjs,cjs,py,go,rs,java,kt,swift,c,cpp,h,hpp,cs,rb,php,scala,clj}',
     ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/.opencode/**', '**/docs/**', '**/vendor/**', '**/__pycache__/**'],
@@ -42,6 +42,82 @@ const INDEX_PRESETS = {
   }
 };
 
+// Will be populated from config.yaml if available
+let INDEX_PRESETS = { ...DEFAULT_PRESETS };
+let GLOBAL_IGNORE = [];
+
+/**
+ * Load index configuration from config.yaml
+ * @param {string} projectRoot - Project root directory
+ */
+async function loadConfig(projectRoot) {
+  try {
+    const configPath = path.join(projectRoot, '.opencode', 'config.yaml');
+    const content = await fs.readFile(configPath, 'utf8');
+    
+    // Parse vectorizer section from YAML
+    const vectorizerMatch = content.match(/^vectorizer:([\s\S]*?)(?=^[a-z]|\Z)/m);
+    if (!vectorizerMatch) return;
+    
+    const section = vectorizerMatch[1];
+    
+    // Parse global exclude
+    const excludeMatch = section.match(/^\s{2}exclude:\s*\n((?:\s{4}-\s+.+\n?)*)/m);
+    if (excludeMatch) {
+      GLOBAL_IGNORE = excludeMatch[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*-\s*/, '').trim())
+        .filter(Boolean)
+        .map(p => p.includes('*') ? p : `**/${p}/**`);
+    }
+    
+    // Parse indexes section
+    const indexesMatch = section.match(/^\s{2}indexes:\s*\n([\s\S]*?)(?=^\s{2}[a-z]|\s{2}exclude:|\Z)/m);
+    if (!indexesMatch) return;
+    
+    const indexesSection = indexesMatch[1];
+    
+    // Parse each index (code, docs, config)
+    for (const indexName of ['code', 'docs', 'config']) {
+      const indexRegex = new RegExp(`^\\s{4}${indexName}:\\s*\\n([\\s\\S]*?)(?=^\\s{4}[a-z]|\\Z)`, 'm');
+      const indexMatch = indexesSection.match(indexRegex);
+      if (!indexMatch) continue;
+      
+      const indexSection = indexMatch[1];
+      
+      // Parse enabled
+      const enabledMatch = indexSection.match(/^\s+enabled:\s*(true|false)/m);
+      const enabled = enabledMatch ? enabledMatch[1] === 'true' : true;
+      
+      // Parse pattern
+      const patternMatch = indexSection.match(/^\s+pattern:\s*["']?([^"'\n]+)["']?/m);
+      const pattern = patternMatch ? patternMatch[1].trim() : DEFAULT_PRESETS[indexName]?.pattern;
+      
+      // Parse ignore array
+      const ignoreMatch = indexSection.match(/^\s+ignore:\s*\n((?:\s+-\s+.+\n?)*)/m);
+      let ignore = [];
+      if (ignoreMatch) {
+        ignore = ignoreMatch[1]
+          .split('\n')
+          .map(line => line.replace(/^\s*-\s*/, '').replace(/["']/g, '').trim())
+          .filter(Boolean);
+      }
+      
+      if (enabled && pattern) {
+        INDEX_PRESETS[indexName] = {
+          pattern,
+          ignore,
+          description: `${indexName} files from config.yaml`
+        };
+      }
+    }
+    
+    if (DEBUG) console.log('[vectorizer] Loaded config:', { INDEX_PRESETS, GLOBAL_IGNORE });
+  } catch (e) {
+    if (DEBUG) console.log('[vectorizer] Using default presets (no config.yaml)');
+  }
+}
+
 class CodebaseIndexer {
   /**
    * @param {string} projectRoot - Project root directory
@@ -55,9 +131,15 @@ class CodebaseIndexer {
     this.model = null;
     this.db = null;
     this.hashes = {};
+    this.configLoaded = false;
   }
 
   async init() {
+    // Load config on first init
+    if (!this.configLoaded) {
+      await loadConfig(this.root);
+      this.configLoaded = true;
+    }
     await fs.mkdir(this.cacheDir, { recursive: true });
     this.db = await lancedb.connect(path.join(this.cacheDir, 'lancedb'));
     await this.loadHashes();
@@ -219,10 +301,14 @@ class CodebaseIndexer {
    */
   async checkHealth(extraIgnore = []) {
     const { glob } = await import('glob');
-    const preset = INDEX_PRESETS[this.indexName] || INDEX_PRESETS.code;
+    const preset = INDEX_PRESETS[this.indexName] || DEFAULT_PRESETS.code;
     
-    // Combine preset ignore with extra ignore patterns
-    const ignore = [...(preset.ignore || []), ...extraIgnore.map(p => `**/${p}/**`)];
+    // Combine: preset ignore + global ignore + extra ignore
+    const ignore = [
+      ...(preset.ignore || []), 
+      ...GLOBAL_IGNORE,
+      ...extraIgnore.map(p => p.includes('*') ? p : `**/${p}/**`)
+    ];
     
     const expectedFiles = await glob(preset.pattern, { 
       cwd: this.root, 
@@ -295,10 +381,14 @@ class CodebaseIndexer {
    */
   async indexAll(onProgress = null, extraIgnore = []) {
     const { glob } = await import('glob');
-    const preset = INDEX_PRESETS[this.indexName] || INDEX_PRESETS.code;
+    const preset = INDEX_PRESETS[this.indexName] || DEFAULT_PRESETS.code;
     
-    // Combine preset ignore with extra ignore patterns
-    const ignore = [...(preset.ignore || []), ...extraIgnore.map(p => `**/${p}/**`)];
+    // Combine: preset ignore + global ignore + extra ignore
+    const ignore = [
+      ...(preset.ignore || []), 
+      ...GLOBAL_IGNORE,
+      ...extraIgnore.map(p => p.includes('*') ? p : `**/${p}/**`)
+    ];
     
     const files = await glob(preset.pattern, { 
       cwd: this.root,