@abarcenas/ai-workflow-template 1.23.0 → 1.26.0

package/README.md

@@ -1,6 +1,6 @@
 # 🤖 AI Workflow Template
 
-**Publishable AI workflow starter pack for GitHub Copilot** - Auto-syncing, version-managed, npm-distributed agent configuration suite.
+**Publishable AI workflow starter pack for OpenCode** — Auto-syncing, version-managed, npm-distributed agent configuration suite with vector search memory.
 
 ---
 
@@ -12,12 +12,18 @@ This isn't a one-off template to clone—it's a **live npm package** that distri
 
 - ⚙️ **27+ Specialized AI Skills** - Reusable, task-based workflows (`.agents/skills/`)
 - 🧠 **Smart Agent Frameworks** - Plan Mode, Implementation Plans, Research Spikes (`.agents/agents/`)
+- 🔄 **Multi-Agent Orchestrator** — Dynamic pipeline builder with 10+ specialized sub-agents
+- 🧪 **TDD Orchestrator** — Strict RED→GREEN→REFACTOR/VERIFY test-driven pipeline (90% coverage gate)
 - 📝 **Framework Instructions** - Technology-specific guidance (`.agents/instructions/`)
 - 💬 **Prompt Templates** - Ready-to-use prompt blueprints (`.agents/prompts/`)
+- 🧠 **Memory Bank** — Persistent project context across AI sessions with semantic search
+- 🔍 **Vector Memory Search** — sqlite-vec powered semantic search (token-efficient, zero deps)
 - 🏃‍♂️ **Caveman Mode** - Ultra-compressed communication for token efficiency
-- 🧪 **Playwright Testing** - Automated testing with MCP integration
+- 🎭 **Playwright Testing** - Automated E2E testing with MCP integration
+- ⚡ **Vitest Unit Testing** — Fast unit tests with v8 coverage (≥90% threshold)
 - 📦 **Version Auto-Bumping** - Husky-managed semantic versioning
 - 🚀 **Auto-Publishing** - npm publish on merge to `main`
+- 🗺️ **graphify Knowledge Graph** — Queryable code-level relationship mapping
 
 ---
 
@@ -158,6 +164,7 @@ Some agents require MCP servers configured in `opencode.mcp.json` (copy from `op
 - 📋 `create-implementation-plan` - Structured task planning
 - ✍️ `create-readme` - Automated README generation
 - 🎯 `context-map` - File relevance mapping
+- 🧠 `graphify` - Codebase knowledge graph generation
 
 ### Development Tools
 - 🎭 `playwright-explore-website` / `playwright-generate-test` - Browser automation
@@ -179,6 +186,140 @@ Some agents require MCP servers configured in `opencode.mcp.json` (copy from `op
 
 ---
 
+### 🧠 Knowledge Graph (graphify)
+
+Turns any folder of code, docs, papers, images, or videos into a **queryable knowledge graph** with community detection, interactive HTML visualization, and GraphRAG-ready JSON.
+
+```bash
+# Build a knowledge graph for the current directory
+/graphify
+
+# Build for a specific path
+/graphify <path>
+
+# Query an existing graph
+/graphify query "How does authentication work?"
+```
+
+#### Prerequisites
+
+- **Python 3.10+** — required runtime
+- **`graphifyy` Python package** — `pip install graphifyy` or `uv tool install graphifyy`
+- **Optional: Gemini API key** (`GEMINI_API_KEY` or `GOOGLE_API_KEY`) — enables faster semantic extraction; without it, graphify falls back to Claude subagents
+
+> 📖 [GitHub: safishamsi/graphify](https://github.com/safishamsi/graphify) — full docs, examples, and source
+
+---
+
+### 🧪 TDD Orchestrator — Test-Driven Development Pipeline
+
+The project enforces a strict **Test-Driven Development** methodology through a specialized orchestrator that runs the **RED → GREEN → REFACTOR/VERIFY** cycle:
+
+```
+implementer (PLAN) → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester (VERIFY) → reviewer → tracker
+```
+
+| Step | Agent | Phase | Description |
+|------|-------|-------|-------------|
+| 1 | Implementer | PLAN | Creates implementation plan with parallel test/code batch tables |
+| 2 | Unit Tester | RED | Writes FAILING tests first — defines expected behavior before any code exists |
+| 3 | Coder | GREEN | Writes MINIMAL production code to pass all tests — no extra features |
+| 4 | Unit Tester | VERIFY | Runs full suite, enforces ≥90% coverage threshold |
+| 5 | Reviewer | REFACTOR | Audits tests + implementation for quality, security, patterns |
+| 6 | Tracker | DOCUMENT | Records pipeline results to `docs/tracker-log.md` |
+
+**Key TDD rules enforced:**
+- Tests are ALWAYS written first (RED phase) — no implementation until tests exist
+- Coverage gate: if <90%, loop back to RED phase (up to 3 iterations)
+- Every test suite tracked in `memory-bank/tasks/`
+- Lessons learned persisted to `.agents/instructions/learned-knowledge.instructions.md`
+
+**How to invoke:**
+
+```bash
+@orchestrator Add user authentication with login/logout endpoints
+```
+
+The TDD orchestrator uses `subagent_type "tdd-orchestrator"` and auto-selects the strict TDD pipeline when testable code changes are requested.
+
+### 🧠 Memory Bank — Persistent Project Context with Vector Search
+
+The memory bank preserves project knowledge across AI sessions, preventing context loss after resets. **New: semantic vector search** lets agents query project memory without loading all files into context — saving thousands of tokens per session.
+
+#### Architecture
+
+```
+Markdown files (git-committed)          Vector Index (.gitignore'd)
+══════════════════════════════          ════════════════════════════
+memory-bank/                            memory-bank/.index/
+├── activeContext.md                    └── memory.db  ← sqlite-vec + better-sqlite3
+├── progress.md                              │
+├── systemPatterns.md                         │  rebuilt from .md files
+├── ...                                       ▼  on demand
+                                        memory_search("tdd orchestrator")
+                                        → top 5 relevant chunks (~500 tokens)
+```
+
+**Source of truth:** Markdown files (git-versioned, human-readable).  
+**Search index:** `sqlite-vec` vector database (disposable, rebuildable, never committed).
+
+#### MCP Tools (OpenCode)
+
+| Tool | Purpose |
+|---|---|
+| `memory_search` | Semantic search across memory-bank + docs (query + topK) |
+| `memory_update` | Incremental sync — only changed files (~2 seconds) |
+| `memory_rebuild` | Full rebuild from markdown files (rare — clone/corruption) |
+| `memory_get` | Read a specific memory file by name |
+| `memory_stats` | Index statistics (vector count, DB size) |
+
+#### File Structure
+
+```
+projectbrief.md → productContext.md / systemPatterns.md / techContext.md → activeContext.md → progress.md / tasks/
+```
+
+| File | Purpose |
+|------|---------|
+| `memory-bank/projectbrief.md` | Core requirements, goals, and scope |
+| `memory-bank/productContext.md` | Problem solved, UX goals |
+| `memory-bank/systemPatterns.md` | Architecture, design patterns, component relationships |
+| `memory-bank/techContext.md` | Technologies, dev setup, constraints |
+| `memory-bank/activeContext.md` | Current focus, recent changes, next steps |
+| `memory-bank/progress.md` | What works, what's left, known issues |
+| `memory-bank/tasks/` | Per-task tracking with `_index.md` |
+
+#### Document Schema
+
+All memory-bank files use YAML frontmatter for search indexing:
+
+```yaml
+---
+id: activeContext
+title: "Active Context"
+updated: 2026-07-23
+tags: [orchestrator, bootstrap, tdd]
+entities: [vitest, graphify, memory-bank]
+category: context
+---
+```
+
+See `memory-bank/.vocabulary.json` for the controlled vocabulary (user-extensible).
+
+**Auto-normalization:** `npm install` runs `normalize-memory.js` to add frontmatter to existing files.  
+**Pre-commit validation:** Husky hook rejects commits with invalid frontmatter.
+
+**Task commands:** `add task`, `update task [ID]`, `show tasks [filter]`
+
+#### Token Efficiency
+
+| Approach | Tokens per session |
+|---|---|
+| Read all memory files | ~5,000–15,000+ |
+| Semantic search | ~500–2,000 (top 3–5 chunks) |
+
+---
+
 ## 📦 Versioning
 
 Husky automatically bumps versions on every commit:
@@ -219,10 +360,43 @@ npm run sync -- --dry-run
 # Test package creation
 npm pack --json
 
-# Run Playwright tests
+# Run Playwright E2E tests
 npm test
+
+# Run unit tests (Vitest)
+npm run test:unit
+
+# Run unit tests with coverage (90% threshold)
+npm run test:unit:coverage
+
+# Watch mode for unit tests
+npm run test:unit:watch
+
+# ─── Memory Bank (Vector Search) ───
+
+# Build the vector search index (one-time, ~8 min for 5K files)
+npm run memory:rebuild
+
+# Incremental update (seconds — only changed files)
+npm run memory:update
+
+# Search project memory
+npm run memory:search "tdd orchestrator status"
+
+# Normalize document frontmatter (runs automatically on install)
+npm run memory:normalize
 ```
 
+### Testing
+
+| Type | Framework | Command | Coverage |
+|------|-----------|---------|----------|
+| E2E | Playwright | `npm test` | — |
+| Unit | Vitest | `npm run test:unit` | `npm run test:unit:coverage` (≥90%) |
+
+- **E2E tests** live in `tests/*.spec.ts` — browser automation via Playwright
+- **Unit tests** live in `scripts/*.test.{js,ts}` — component tests via Vitest with v8 coverage
+
 ---
 
 ## 🔄 Updating the Shared Template

package/memory-bank/.vocabulary.json

@@ -0,0 +1,52 @@
+{
+  "categories": {
+    "brief": "Project scope, goals (projectbrief.md)",
+    "product": "Product context, UX goals (productContext.md)",
+    "architecture": "System patterns, design decisions, component relationships",
+    "tech": "Technology stack, dev setup, constraints",
+    "context": "Current focus, recent changes, next steps (activeContext.md)",
+    "progress": "What works, what's left, known issues (progress.md)",
+    "task": "Individual task tracking (tasks/TASK*.md)",
+    "decision": "ADR-style architecture/technical decisions"
+  },
+
+  "tags": {
+    "agent_roles": [
+      "designer", "architect", "researcher", "coder", "implementer",
+      "tester", "reviewer", "tracker", "deployer", "orchestrator"
+    ],
+    "workflow": [
+      "bootstrap", "setup", "configuration", "migration", "refactor",
+      "tdd", "feature-pipeline", "onboarding", "normalization",
+      "research", "spike", "implementation"
+    ],
+    "memory_ops": [
+      "decision", "discovery", "status-update", "task-plan", "retrospective"
+    ]
+  },
+
+  "entity_patterns": {
+    "vitest":            ["vitest", "vitest\\.config", "@vitest\\/coverage"],
+    "playwright":        ["playwright", "@playwright", "browser.*test"],
+    "graphify":          ["graphify", "knowledge graph", "graph\\.json"],
+    "memory-bank":       ["memory-bank", "memory bank", "activeContext", "systemPatterns"],
+    "husky":             ["husky", "pre-commit", "git hook"],
+    "tdd-orchestrator":  ["tdd orchestrator", "RED.*GREEN.*REFACTOR"],
+    "mcp-server":        ["mcp", "modelcontextprotocol", "stdio", "mcp server"],
+    "sqlite-vec":        ["sqlite-vec", "sqlite.vec", "better-sqlite3"],
+    "transformers.js":   ["@xenova\\/transformers", "transformers\\.js", "all-MiniLM"],
+    "opencode":          ["opencode", "OpenCode", "open code"],
+    "npm":               ["npm", "npm package", "npm install"]
+  },
+
+  "file_category_map": {
+    "projectbrief":     "brief",
+    "productContext":   "product",
+    "systemPatterns":   "architecture",
+    "techContext":      "tech",
+    "activeContext":    "context",
+    "progress":         "progress"
+  },
+
+  "doc_types": ["spike", "architecture", "configuration", "orchestrator-log", "tracker-log", "decision"]
+}

package/opencode.mcp.example.json

@@ -53,12 +53,19 @@
       "type": "remote",
       "url": "https://your-mcp-server.com/mcp",
       "enabled": false
+    },
+    "memory-bank": {
+      "type": "local",
+      "command": ["node", "scripts/mcp-memory-server.js"],
+      "enabled": true
     }
   },
   "permission": {
     "ddg-search_*": "allow",
     "github_*": "allow",
     "mcp-everything_*": "allow",
-    "playwright_*": "allow"
+    "angular-cli_*": "allow",
+    "playwright_*": "allow",
+    "memory-bank_*": "allow"
   }
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.23.0",
-  "description": "A comprehensive template repository for AI-assisted development workflows using GitHub Copilot. This template provides a structured approach to leveraging AI assistance through pre-configured skills, prompts, agents, and coding standards.",
+  "version": "1.26.0",
+  "description": "A comprehensive template repository for AI-assisted development workflows using OpenCode. Provides structured agent pipelines, TDD orchestrator, memory bank with vector search, skills, prompts, and coding standards distributed as an npm package.",
   "main": "index.js",
   "scripts": {
     "test": "playwright test",
@@ -9,9 +9,16 @@
     "test:ui": "playwright test --ui",
     "test:debug": "playwright test --debug",
     "test:report": "playwright show-report",
+    "test:unit": "vitest run",
+    "test:unit:coverage": "vitest run --coverage",
+    "test:unit:watch": "vitest",
     "prepare": "husky",
     "sync": "node ./scripts/sync.js",
-    "postinstall": "node ./scripts/sync.js"
+    "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js",
+    "memory:search": "node ./scripts/memory-cli.js search",
+    "memory:rebuild": "node ./scripts/memory-cli.js rebuild",
+    "memory:update": "node ./scripts/memory-cli.js update",
+    "memory:normalize": "node ./scripts/normalize-memory.js"
   },
   "repository": {
     "type": "git",
@@ -31,13 +38,26 @@
     "scripts/",
     ".opencode/agents/",
     ".opencode/commands/",
+    ".husky/",
+    "memory-bank/.vocabulary.json",
     "AGENTS.md",
     "opencode.mcp.example.json",
-    "skills-lock.json"
+    "skills-lock.json",
+    ".husky/post-merge"
   ],
   "devDependencies": {
     "@playwright/test": "^1.59.1",
+    "@vitest/coverage-v8": "^4.1.8",
     "dotenv": "^17.4.2",
-    "husky": "^9.0.0"
+    "husky": "^9.0.0",
+    "vitest": "^4.1.8"
+  },
+  "dependencies": {
+    "better-sqlite3": "^12.11.0",
+    "sqlite-vec": "^0.1.9",
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "optionalDependencies": {
+    "@xenova/transformers": "^2.17.0"
   }
 }

package/scripts/mcp-memory-server.js

@@ -0,0 +1,243 @@
+#!/usr/bin/env node
+
+/**
+ * mcp-memory-server.js — MCP server exposing memory-bank tools to OpenCode.
+ *
+ * Provides: memory_search, memory_rebuild, memory_get
+ * Uses stdio transport — OpenCode spawns this as a child process.
+ *
+ * Configuration (opencode.json):
+ *   "memory-bank": {
+ *     "type": "local",
+ *     "command": ["node", "scripts/mcp-memory-server.js"],
+ *     "enabled": true
+ *   }
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { search, rebuildIndex, incrementalUpdate, getFile, getStats } from './memory-index.js';
+
+const VALID_FILES = [
+  'activeContext', 'systemPatterns', 'techContext',
+  'productContext', 'progress', 'projectbrief',
+  'tracker-log', 'architecture-context', 'orchestrator-log',
+  'spike-vector-db-memory', 'playwright-mcp-configuration',
+];
+
+const server = new Server(
+  {
+    name: 'memory-bank',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// ── List tools ───────────────────────────────────────────────────────
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: 'memory_search',
+      description:
+        'Semantic search across the project memory bank (activeContext, systemPatterns, progress, decisions, tasks). ' +
+        'Returns ranked chunks with source file and similarity score. ' +
+        'Use this instead of reading all memory files to save tokens.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Natural language query about project context, decisions, or status',
+          },
+          topK: {
+            type: 'number',
+            default: 5,
+            description: 'Number of results to return (1-20)',
+          },
+          sourceFile: {
+            type: 'string',
+            description: 'Optional: filter to a specific memory file (e.g., "activeContext", "systemPatterns")',
+          },
+        },
+        required: ['query'],
+      },
+    },
+    {
+      name: 'memory_rebuild',
+      description:
+        'Full rebuild of the memory vector index from memory-bank/*.md and docs/*.md files. ' +
+        'Re-indexes every file regardless of change. ' +
+        'Use memory_update instead for faster incremental sync (only changed files). ' +
+        'The index is disposable — rebuilding is safe.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+    {
+      name: 'memory_update',
+      description:
+        'Incremental update — only re-indexes files whose content changed (SHA-256 content hash). ' +
+        'Much faster than memory_rebuild for daily use (~2 seconds vs minutes). ' +
+        'Run this after completing tasks, writing to memory-bank, or after git pull.',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+    {
+      name: 'memory_get',
+      description:
+        'Read the full content of a specific memory file by name. ' +
+        'Use when you need the complete file, not just search snippets.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          file: {
+            type: 'string',
+            description: 'File ID without extension. One of: ' + VALID_FILES.join(', '),
+            enum: VALID_FILES,
+          },
+        },
+        required: ['file'],
+      },
+    },
+    {
+      name: 'memory_stats',
+      description: 'Get statistics about the memory index (vector count, file count, database size).',
+      inputSchema: {
+        type: 'object',
+        properties: {},
+      },
+    },
+  ],
+}));
+
+// ── Handle tool calls ────────────────────────────────────────────────
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'memory_search': {
+        const results = await search(args.query, {
+          topK: args.topK || 5,
+          sourceFile: args.sourceFile || undefined,
+        });
+
+        if (results.length === 0) {
+          return {
+            content: [{
+              type: 'text',
+              text: 'No results found. The index may be empty. Try running memory_rebuild first.',
+            }],
+          };
+        }
+
+        const formatted = results
+          .map((r, i) =>
+            `### Result ${i + 1} (score: ${r.score})\n` +
+            `**File:** \`${r.source_file}\`\n\n${r.content}`
+          )
+          .join('\n\n---\n\n');
+
+        return {
+          content: [{ type: 'text', text: formatted }],
+        };
+      }
+
+      case 'memory_rebuild': {
+        const result = await rebuildIndex();
+        return {
+          content: [{
+            type: 'text',
+            text: `Index rebuilt successfully.\n` +
+              `- Chunks indexed: ${result.indexed}\n` +
+              `- Chunks skipped (unchanged): ${result.skipped}\n` +
+              `- Total vectors: ${result.stats.totalVectors}\n` +
+              `- Total files: ${result.stats.totalFiles}\n` +
+              `- DB size: ${result.stats.dbSize}`,
+          }],
+        };
+      }
+
+      case 'memory_update': {
+        const result = await incrementalUpdate();
+        return {
+          content: [{
+            type: 'text',
+            text: `Index updated incrementally.\n` +
+              `- Chunks re-indexed: ${result.indexed}\n` +
+              `- Chunks cached (unchanged): ${result.skipped}\n` +
+              (result.changed.length > 0
+                ? `- Changed files: ${result.changed.join(', ')}\n`
+                : '- No files changed.\n') +
+              `- Total vectors: ${(await getStats()).totalVectors}`,
+          }],
+        };
+      }
+
+      case 'memory_get': {
+        const content = getFile(args.file);
+        if (!content) {
+          return {
+            content: [{
+              type: 'text',
+              text: `File not found: ${args.file}.md. Available files: ${VALID_FILES.join(', ')}`,
+            }],
+          };
+        }
+        return {
+          content: [{ type: 'text', text: content }],
+        };
+      }
+
+      case 'memory_stats': {
+        const stats = getStats();
+        return {
+          content: [{
+            type: 'text',
+            text: `**Memory Index Stats**\n` +
+              `- Total vectors: ${stats.totalVectors}\n` +
+              `- Total files indexed: ${stats.totalFiles}\n` +
+              `- Database size: ${stats.dbSize}`,
+          }],
+        };
+      }
+
+      default:
+        throw new Error(`Unknown tool: ${name}`);
+    }
+  } catch (err) {
+    return {
+      content: [{
+        type: 'text',
+        text: `Error: ${err.message}`,
+      }],
+      isError: true,
+    };
+  }
+});
+
+// ── Start server ─────────────────────────────────────────────────────
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('[memory-bank-mcp] Server started via stdio transport');
+}
+
+main().catch((err) => {
+  console.error('[memory-bank-mcp] Fatal error:', err);
+  process.exit(1);
+});