@comfanion/workflow 4.36.12 → 4.36.14

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/bin/cli.js

@@ -323,13 +323,30 @@ program
         
         // Install dependencies only if vectorizer is enabled
         if (config.vectorizer_enabled) {
-          spinner.text = 'Installing vectorizer...';
+          spinner.text = 'Installing vectorizer dependencies...';
           try {
-            execSync('npm install --silent', { 
+            // Show progress during npm install
+            const steps = [
+              'Installing vectorizer dependencies...',
+              'Downloading @xenova/transformers (~50MB)...',
+              'Installing vectordb...',
+              'Installing glob...',
+              'Finalizing vectorizer setup...'
+            ];
+            let stepIndex = 0;
+            const progressInterval = setInterval(() => {
+              stepIndex = (stepIndex + 1) % steps.length;
+              spinner.text = steps[stepIndex];
+            }, 3000);
+            
+            execSync('npm install', { 
               cwd: newVectorizerDir,
               stdio: 'pipe',
-              timeout: 120000
+              timeout: 180000
             });
+            
+            clearInterval(progressInterval);
+            spinner.text = 'Vectorizer installed!';
           } catch (e) {
             // Non-fatal, will show warning below
           }
@@ -597,13 +614,30 @@ program
         
         // Install dependencies only if vectorizer is enabled
         if (vectorizerEnabled) {
-          spinner.text = 'Installing vectorizer...';
+          spinner.text = 'Installing vectorizer dependencies...';
           try {
-            execSync('npm install --silent', { 
+            // Show progress during npm install
+            const steps = [
+              'Installing vectorizer dependencies...',
+              'Downloading @xenova/transformers (~50MB)...',
+              'Installing vectordb...',
+              'Installing glob...',
+              'Finalizing vectorizer setup...'
+            ];
+            let stepIndex = 0;
+            const progressInterval = setInterval(() => {
+              stepIndex = (stepIndex + 1) % steps.length;
+              spinner.text = steps[stepIndex];
+            }, 3000);
+            
+            execSync('npm install', { 
               cwd: newVectorizerDir,
               stdio: 'pipe',
-              timeout: 120000
+              timeout: 180000
             });
+            
+            clearInterval(progressInterval);
+            spinner.text = 'Vectorizer installed!';
           } catch (e) {
             // Non-fatal, will show warning below
           }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comfanion/workflow",
-  "version": "4.36.12",
+  "version": "4.36.14",
   "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:27:25.856Z",
+  "buildDate": "2026-01-24T15:35:20.846Z",
   "files": [
     "config.yaml",
     "FLOW.yaml",