@abarcenas/ai-workflow-template 1.33.0 → 1.38.0

package/.agents/instructions/knowledgebase.instructions.md

@@ -0,0 +1,238 @@
+---
+applyTo: "**"
+---
+
+# Knowledgebase
+
+You have access to a centralized knowledgebase containing learned knowledge from past
+pipeline sessions across all projects that have been indexed. The knowledgebase is
+powered by PostgreSQL + pgvector with semantic (cosine similarity) search.
+
+**MANDATORY REQUIREMENT — NOT BEST EFFORT:** You MUST query the knowledgebase before
+planning any task, when encountering errors, and when starting work on a known area.
+This is not optional — it is a core part of your decision-making process. Skipping
+knowledgebase queries in these scenarios will result in missed context and degraded
+output quality.
+
+## MCP Tools
+
+The knowledgebase is accessed via the `knowledgebase` MCP server configured in
+`opencode.json`. The following tools are available:
+
+| Tool | Purpose | Parameters |
+|------|---------|------------|
+| `knowledgebase_search` | Semantic search across learned knowledge from all indexed projects | `query` (required), `topK` (default 5), `projectId` (optional) |
+| `knowledgebase_index` | Index or re-index a project's learned-knowledge.instructions.md | `projectId` (optional) |
+| `knowledgebase_stats` | Get knowledgebase statistics (total projects, chunks, DB size) | None |
+| `knowledgebase_list` | List all projects currently indexed in the knowledgebase | None |
+
+### Tool Details
+
+- **`knowledgebase_search`** — Use for finding relevant patterns, past decisions, and solutions.
+  Returns results ranked by cosine similarity with metadata (project, date, pipeline, content).
+  Results are OpenAI-compatible tool call responses with structured text content.
+
+- **`knowledgebase_index`** — Use to manually trigger re-indexing of a project's learned knowledge
+  file. Idempotent: unchanged sessions are skipped. Typically used when the post-commit hook
+  did not fire or you want to index changes before committing.
+
+- **`knowledgebase_stats`** — Use to check whether the knowledgebase has data and how much.
+  Useful for diagnosing empty results or confirming indexing worked.
+
+- **`knowledgebase_list`** — Use to discover which projects have contributed knowledge,
+  especially when searching for cross-project patterns.
+
+## When to Query
+
+**Always query BEFORE starting implementation work**, especially in these scenarios:
+
+### 1. Planning Tasks
+
+Search for past patterns, conventions, and architectural decisions relevant to the
+current task. Example queries:
+- "What verbose flag infrastructure exists?"
+- "How are parallel batch task dependencies structured?"
+- "What pattern is used for git hook templates?"
+
+### 2. Encountering Errors
+
+Before debugging from scratch, search for similar errors and their known resolutions.
+Example queries:
+- "spawnScript child process hanging silent output"
+- "process.exit kills parent import module"
+- "npm postinstall blocked in v12"
+
+### 3. Making Architectural Decisions
+
+Search for prior design decisions and their rationale before choosing an approach.
+Example queries:
+- "separate MCP server vs merged memory server"
+- "raw SQL vs ORM for vector database"
+- "post-commit vs pre-commit hook indexing"
+
+### 4. Working with Specific Technologies
+
+Search for tech-specific gotchas, configuration patterns, and integration notes.
+Example queries:
+- "child_process.spawn env var communication"
+- "husky v9 programmatic API"
+- "SHA-256 content hash idempotency"
+
+### 5. Agent Tuning
+
+If unsure about conventions or how to approach a task as a specific agent role.
+Example queries:
+- "what should the coder agent know about parallel batches"
+- "researcher ecosystem investigation patterns"
+- "tracker documentation format conventions"
+
+## How to Query
+
+Use natural language queries that describe the concept, problem, or pattern you are
+looking for. Be specific but concise — the embedding model works best with clear,
+focused queries.
+
+**Basic query:**
+```
+knowledgebase_search({
+    query: "how to handle verbose logging in child processes",
+    topK: 5
+})
+```
+
+**Filtered by project:**
+```
+knowledgebase_search({
+    query: "TDD pipeline patterns and conventions",
+    projectId: "my-app",
+    topK: 5
+})
+```
+
+**Finding specific error resolutions:**
+```
+knowledgebase_search({
+    query: "npm postinstall execution blocked in v12 dependency lifecycle",
+    topK: 3
+})
+```
+
+**Finding agent-specific guidance:**
+```
+knowledgebase_search({
+    query: "tracker documentation requirements and format for pipeline sessions",
+    topK: 5
+})
+```
+
+### Query Patterns by Use Case
+
+| Use Case | What to search for | Example |
+|----------|-------------------|---------|
+| **Error resolution** | Error message keywords, component names, symptom descriptions | "spawnScript hangs silent output capture" |
+| **Implementation approach** | Pattern names, technology names, architecture terms | "hash-based manifest sync namespace" |
+| **Conventions** | Project-specific terms, file naming, code structure | "hook marker comment idempotency" |
+| **Historical decisions** | Decision topic, alternative names, trade-off terms | "co-location constraint sync dependencies" |
+| **Agent behavior** | Agent role name, task type, pipeline stage | "parallel coder batch dependency ordering" |
+
+## How to Interpret Results
+
+Results are ranked by cosine similarity score (0.0–1.0, higher = more relevant):
+
+| Score Range | Interpretation | Action |
+|-------------|---------------|--------|
+| **≥ 0.85** | Highly relevant — directly applicable knowledge | Apply without reservation. This knowledge addresses your query. |
+| **0.70–0.84** | Relevant — related context that may inform your approach | Review carefully. May contain useful patterns with adaptation. |
+| **< 0.70** | Tangentially related — use with discretion | Consider as background context. Verify applicability before applying. |
+
+Each result includes these fields:
+
+- **`project`**: Which project the knowledge came from (package.json `name`). Cross-project
+  results are valuable — they may contain patterns not yet used in your current project.
+- **`date`**: When the session occurred. More recent knowledge (within 30 days) is generally
+  more applicable due to evolving project conventions.
+- **`pipeline`**: What pipeline type generated the knowledge (TDD, Feature, Research, etc.).
+  Helps assess whether the knowledge came from a similar workflow context.
+- **`content`**: The actual "New knowledge" bullets — the learned insights. May include
+  multiple lines per session.
+
+**More results ≠ better:** If the top result has similarity ≥ 0.85 and directly answers
+your question, you do not need to examine lower-ranked results. If all results are below
+0.70, refine your query with more specific terminology before proceeding.
+
+## Graceful Degradation
+
+The knowledgebase is **optional** — it requires a PostgreSQL database with pgvector
+extension. If the MCP server is unavailable or `DATABASE_URL` is not configured:
+
+1. **Do NOT block or fail** — Proceed with your task without the knowledgebase.
+2. **Make a note** — Record in your reasoning that the knowledgebase was unavailable.
+3. **Fall back to memory-bank** — Use `memory_search` and `memory_get` for local context.
+4. **Proceed normally** — The knowledgebase is an enhancement, not a dependency.
+
+The MCP tools return descriptive messages when the database is unavailable:
+- `knowledgebase_search` → "Knowledgebase not available: DATABASE_URL is not configured."
+- `knowledgebase_index` → "Knowledgebase not available: DATABASE_URL is not configured."
+- `knowledgebase_stats` → Returns zero counts (not an error).
+- `knowledgebase_list` → Returns empty list (not an error).
+
+## When NOT to Query
+
+Do NOT use the knowledgebase for:
+
+- **Project-specific file paths or configuration** — Use the memory bank (`memory_search`,
+  `memory_get`) or read the actual files.
+- **Current task status or active work tracking** — Use `memory-bank/activeContext.md`,
+  `memory-bank/progress.md`, or the tasks index.
+- **Code implementation details** — Read the actual source files or use the graphify
+  knowledge graph (`graphify query`, `graphify explain`).
+- **Runtime state or environment variables** — These are ephemeral and project-specific.
+- **Sensitive credentials or secrets** — Never query for passwords, API keys, tokens,
+  or connection strings.
+
+## Relationship to Memory Bank
+
+The knowledgebase and memory bank serve complementary but distinct roles:
+
+| Aspect | Knowledgebase (Layer 3) | Memory Bank (Layer 2) |
+|--------|------------------------|----------------------|
+| **Scope** | Cross-project — all indexed projects | Per-project — current project only |
+| **Content** | Learned patterns, conventions, gotchas | Current state, tasks, architecture |
+| **Persistence** | PostgreSQL + pgvector (external) | SQLite + sqlite-vec (embedded, filesystem) |
+| **Availability** | Optional — requires DATABASE_URL | Always available |
+| **Update trigger** | Post-commit hook + manual index | Memory update on session start + after changes |
+| **Query style** | Semantic (cosine similarity) | Semantic + full file reads |
+
+**Think of the knowledgebase as "what we've learned across all projects" and the memory
+bank as "what's happening right now in this project."**
+
+The full three-layer knowledge architecture is:
+
+```
+Layer 3: Knowledgebase → Cross-project learned patterns (PostgreSQL + pgvector)
+Layer 2: Memory Bank  → Per-project current state (SQLite + sqlite-vec)
+Layer 1: Markdown     → Git-committed source of truth (filesystem)
+```
+
+When you start a session, follow this order:
+1. Load memory bank context (`memory_search`)
+2. Query the knowledgebase for relevant past patterns (`knowledgebase_search`)
+3. Read specific project files as needed
+4. Proceed with the task
+
+## Closed-Loop Workflow
+
+The knowledgebase enables a continuous learning cycle:
+
+```
+1. Agent completes task
+2. Appends new insights to learned-knowledge.instructions.md
+3. Developer commits → post-commit hook triggers sync
+4. Knowledge is indexed in PostgreSQL + pgvector
+5. Future agents query knowledgebase before planning
+6. Learn from past sessions → produce better output
+7. Append new knowledge → cycle repeats
+```
+
+Each iteration improves all subsequent agent outputs by surfacing relevant past
+experience automatically.

package/.agents/instructions/learned-knowledge.instructions.md

@@ -66,3 +66,101 @@
 - **coder**: When fixing child process output capture, consider both stdout and stderr channels independently — they serve different purposes (results vs diagnostics). `stdio: 'inherit'` is clean for real-time streaming but means stdout is no longer capturable programmatically
 - **unit-tester**: When testing child process spawn behavior, mock `child_process` spawn module rather than using real subprocesses — this avoids side effects and keeps tests fast. Use `vi.mock` with factory functions to control `stdio` arg and `env` values
 - **tracker**: Record dead-code discoveries alongside implementation details — the "existing but unused infrastructure" finding is a recurring pattern worth tracking across sessions
+
+## Session: 2026-07-24 — Fix Hook Script References for Consumer Projects
+
+**Pipeline:** researcher → implementer → coder (5 parallel tasks T1–T5) → tracker
+**Coverage:** 7/7 unit tests passing (2 existing + 5 new), 52/52 integration assertions, 13/13 MCP references verified
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Hash-based manifest namespace pattern** — `__scripts__/<relPath>` extends the proven `.agents/` (bare path) and `__opencode__/` namespace pattern. The 3-case sync logic (new → copy, untouched → overwrite, locally modified → skip with warning) applies identically across all sync sections. No manifest version schema change needed for adding new namespace keys.
+- **Co-location constraint for imported dependencies** — `memory-cli.js` imports `'./memory-index.js'` and `mcp-memory-server.js` also imports `'./memory-index.js'`. Both the consumer-facing script AND its co-located dependency must be in the same sync array. This is an architectural constraint: if you sync one, you must sync all of its relative-import dependencies.
+- **`ensureParentDirectory()` handles nested paths automatically** — `mcp/playwright-mcp-launcher.js` lives in a subdirectory, and the existing `ensureParentDirectory()` helper (which calls `mkdirSync(dirname(filePath), { recursive: true })`) creates it without any special handling.
+- **`spawnSync` for testing modules with `process.exit()`** — `sync.js` calls `process.exit()` and cannot be imported as a module. The proven pattern: use `child_process.spawnSync` to invoke it as a child process, with `INIT_CWD` pointing to an isolated temp directory (created via `mkdtempSync`), and clean up in `afterAll`. This is the same pattern used by `sync-phase.js` in production.
+- **Two Playwright MCP patterns coexist by design** — The template's own root `opencode.json` uses `npx @playwright/mcp@latest` (modern, no file dependency), while `opencode.mcp.example.json` uses the launcher script wrapper with env var configuration (`HEADLESS`, `SLOW_MO`, `VIEWPORT`). Both serve different audiences: the template itself vs. consumer projects that may need launcher configuration.
+- **Marker comment for managed-file detection** — The `HOOK_MARKER` (`# Managed by @abarcenas/ai-workflow-template setup`) is the first line of hook files. This enables `discover.js` `isManaged` detection by reading the first line. The marker must be on line 1 for detection to work — the shebang (`#!/bin/sh`) moves to line 2, which is safe because husky sources hook files rather than executing them directly.
+- **Relative paths in hooks become valid after script sync — no hook content changes needed** — The key architectural insight: `constants.js` `TEMPLATE_HOOKS` content uses `node scripts/memory-cli.js update` which resolves correctly from the consumer root once `scripts/` exists there. Zero modifications to `constants.js`, `hooks.js`, `.husky/post-merge`, or `.husky/pre-commit` are needed.
+- **Content integrity via SHA-256 manifest tracking** — Every synced file is hashed with SHA-256. The manifest tracks `__scripts__/<relPath>` → hash. This enables idempotent re-runs (hash match → no warning), local modification detection (on-disk hash ≠ manifest hash → skip with warning), and force overwrite (`--force` ignores local modifications).
+- **Cross-file MCP reference auditing is essential** — 13 reference points across 7 files needed verification (`opencode.mcp.example.json`, `opencode.mcp.json`, `opencode.json` root, `scripts/mcp-memory-server.js`, `scripts/sync.js`, `scripts/sync.test.js`, `.agents-sync-manifest.json`, `docs/playwright-mcp-configuration.md`). Every reference from MCP configs, sync arrays, test assertions, manifest entries, and documentation must be cross-checked to ensure path resolution after sync changes — this is easy to miss.
+- **`--force` flag consistency across all sync sections** — The `--force` flag semantics are identical for `.agents/`, `.opencode/`, `__scripts__/`, and root files: it bypasses local modification protection and overwrites. This consistency should be preserved for any future sync sections.
+
+**Agent tuning notes:**
+- **researcher**: Must conduct a 6-tier script inventory with dependency chain analysis when determining sync scope. The co-location constraint (`memory-cli.js` imports `'./memory-index.js'`) was discovered by tracing `import` chains — always follow relative imports to find all files that must be co-located. Also check MCP config files (`opencode.mcp.json`, `opencode.json`) for script path references that create additional sync requirements.
+- **implementer (planning)**: When parallel batches share a dependency (Phase 2 and 3 both depend on Phase 1), verify that batch-independent tasks truly have no shared-file dependencies. T2 (test code), T3 (integration verification), T4 (audit), and T5 (documentation) all depended on T1 but were fully independent of each other — this enabled parallel execution without conflicts. The plan's explicit dependency table with "Can run in parallel?" and "Depends on" columns is essential for coder batch scheduling.
+- **coder (T1 — sync.js core logic)**: When adding a new sync section that mirrors an existing one (`.opencode/` block), copy-paste with careful variable renaming is correct and efficient. The 3-case hash logic is proven and consistent. Only 3 things need to change: (1) the tracked key namespace (`__scripts__/` instead of `__opencode__/`), (2) source/target directory paths, (3) the log prefix in verbose messages. The accumulator pattern (`scriptsCopied`/`scriptsSkipped` feeding into global `copied`/`skipped`) should also be mirrored.
+- **coder (T2 — unit tests)**: Test infrastructure for `process.exit()` modules is reusable across all sync test files — create a `createTempDir()` helper with `mkdtempSync`, a `runSync(tempDir, args)` helper using `spawnSync`, and cleanup in `afterAll`. Assertion patterns to reuse: file existence (`expect(existsSync(path)).toBe(true)`), content match (`readFileSync(path) === sourceContent`), mtime invariance for skip tests, manifest key presence, and SHA-256 hash format validation (`/^[a-f0-9]{64}$/`).
+- **coder (T3 — integration verification)**: Integration verification in a simulated consumer project requires a comprehensive test harness. The pattern: create temp consumer dir with minimal `package.json`, run sync with `INIT_CWD`, then assert on filesystem state and script execution. Content integrity via SHA-256 comparison is more reliable than byte-by-byte comparison. Test groups should cover: first-run sync, idempotent re-run, locally modified preservation, `--force` overwrite, `--dry-run`, hook path resolution, post-merge hook path, syntax validation for all synced scripts, and script execution from consumer root.
+- **coder (T4 — MCP audit)**: MCP reference auditing requires structured cross-referencing. Create a table with columns: File, Lines, Reference text, and Status. Track every reference point across ALL files, not just obvious ones (documentation references are the ones most often missed). Note architectural nuances like the two Playwright patterns (npx vs launcher script) — these are design decisions worth documenting, not bugs.
+- **tracker**: The feature-specific documentation (`docs/hook-script-references/tracker.md`) should include a "Total Results" summary section at the end with unit tests, integration assertions, MCP references, and files modified. This gives readers an executive-summary view without reading the full multi-step pipeline.
+
+## Session: 2026-07-29 — Centralized Knowledgebase (pgvector MCP)
+
+**Pipeline:** researcher → architect → implementer → coder (5 parallel batches, 17 tasks) → unit-tester → reviewer → tracker
+**Coverage:** 158 tests passing across 9 test files (103 existing + 28 new + 27 setup index.mock), 0 failures
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **5-batch parallel execution with 17 tasks (6 concurrent coders in Batch A) works cleanly** — Foundation-first ordering: Batch A (6 foundation files with zero code dependencies) → Batch B (CLI + MCP server, depend on T6 core engine) → Batch C (setup integration, depend on T5/T6/T7) → Batch D (config + agent permissions, independent) → Batch E (tests, depend on T6/T7/T9). Zero collisions across all 17 tasks. The explicit "Can run in parallel?" + "Depends on" columns in the plan prevented race conditions.
+- **Graceful degradation must be built into EVERY exported function** — When `DATABASE_URL` is not set, `getPool()` returns null and every subsequent function (search, upsert, stats, list) checks pool === null before doing anything. NEVER throw — return empty/zero results with informative messages. This pattern applies to any optional service integration.
+- **Separate MCP server for different DB lifecycle** — The knowledgebase uses PostgreSQL (network service, needs external server, optional), while memory-bank uses SQLite (local file, always available). Different database lifecycle, different failure modes, different setup requirements = separate MCP server. The existing 9-server pattern in opencode.json comfortably extends to 10 servers.
+- **Lazy imports via dynamic `import()` for ALL optional dependencies** — `pg`, `pgvector`, `@xenova/transformers` all loaded inside try/catch blocks. This is the proven pattern from `memory-index.js`. A helper function pattern: `async function getDep(name) { try { return await import(name); } catch { return null; } }`.
+- **`knowledgebase_*: allow` permission glob** — MCP tool names use the prefix `knowledgebase_` (search, index, stats, list) and the permission glob `knowledgebase_*: allow` matches them. This follows the existing `memory-bank_*` pattern exactly. All 13 agent files updated with one line each.
+- **Mock list maintenance is a recurring testing burden (RISK-07 proven)** — When adding a new import (`registerKnowledgebase` from `./knowledgebase.js`) to `setup/index.js`, the existing `vi.mock()` list in `setup/index.test.js` must be updated with a mock factory. This is a proven risk that materialized. Mitigation: check the test file's mock list whenever adding imports.
+- **post-commit hook auto-discovers via TEMPLATE_HOOKS** — Adding a `post-commit` entry to `TEMPLATE_HOOKS` in `constants.js` automatically includes it in `installHooks()` which iterates `Object.keys(TEMPLATE_HOOKS)`. Zero changes to `hooks.js`. The 6 merge cases (A–F) apply identically to the new hook.
+- **`process.execPath` for spawning Node.js child processes** — Always use `process.execPath` (not hardcoded `node`) when spawning Node.js scripts via `child_process.spawn`. This ensures the correct Node.js binary is used regardless of PATH or version manager.
+- **`all-MiniLM-L6-v2` (384d) sufficient for sub-10k chunk corpus** — Default embedding model is already an optional dependency, runs locally, costs $0, and achieves ~78% recall@5. OpenAI `text-embedding-3-small` (1536d) upgrade path documented in SQL file comments and `setEmbeddingProvider()` stub.
+- **Content hash SHA-256 for idempotent chunk indexing** — Hash = `createHash('sha256').update(content + session_date + pipeline).digest('hex')`. The `ON CONFLICT (project_id, session_date, content_hash)` in PostgreSQL prevents duplicate indexing. Hash is computed server-side in Node.js, not in the database.
+- **Connection pool sizing for single-user MCP** — Pool max: 5 (sufficient for single-user stdio MCP processes), idleTimeoutMillis: 30000 (frees idle connections), connectionTimeoutMillis: 5000 (fast failure on unavailable server). Each MCP server process gets its own pool (stdlib spawn = one process per connection).
+- **HNSW index parameters for small to medium corpus** — `m = 16, ef_construction = 64` for the HNSW index on VECTOR(384). These are conservative defaults suitable for <100k chunks. For larger corpora (>1M chunks), consider m=32, ef_construction=200.
+- **`--topK` and `--threshold` validation matters** — The reviewer flagged that CLI args `--topK` lacks lower bound validation (should be ≥ 1) and `--threshold` lacks upper bound (should be ≤ 1.0). These are subtle validation gaps that tests should specifically cover.
+- **Environment variable passthrough in child process spawns is often missed** — The reviewer noted that `AI_WORKFLOW_VERBOSE` is not passed to the knowledgebase CLI when spawned from `knowledgebase.js`. This is the same pattern that caused silent hangs in the verbose logging feature. Any child process spawn should check for env var passthrough.
+
+**Agent tuning notes:**
+- **researcher**: Must explicitly investigate existing infrastructure for reuse opportunities before proposing new mechanisms — discovered that `installHooks()` auto-discovers via `Object.keys(TEMPLATE_HOOKS)`, meaning adding a new hook to constants.js requires zero hooks.js changes. This kind of existing-infrastructure finding is the most valuable research output.
+- **architect**: Module boundaries should follow the "one concern per file" rule with clear interface types. The core engine (`knowledgebase-index.js`) has 11 exports making it the single source of truth for all DB operations. The CLI and MCP server only import from core — they never import from each other. This clean separation enabled independent parallel development.
+- **implementer (planning)**: The 5-batch structure with 17 tasks proved effective. Key planning insights: (1) Batch A must contain ONLY files with zero internal code dependencies — every file stands alone. (2) Batch D (config + agent perms) is always independent and should always be parallel. (3) Batch E (tests) must depend on all implementation batches to avoid missing-test-coverage issues. (4) RISK-07 (mock list maintenance) should be included in every plan that modifies index.js imports.
+- **coder (parallel batches)**: 17 tasks across 5 batches with 6 concurrent coders in Batch A worked with zero collisions. Key enablers: (1) Foundation-first ordering ensures dependent batches never block. (2) Clear file ownership — no two tasks wrote to the same file. (3) Pattern-matching from existing implementations (`memory-index.js` → `knowledgebase-index.js`, `memory-cli.js` → `knowledgebase-cli.js`) reduced design decisions and sped implementation. (4) The `knowledgebase.js` Phase 6 module inlines the spawn helper instead of importing from `sync-phase.js` — this avoids cross-phase coupling but creates a minor code duplication that's acceptable for template distribution.
+- **unit-tester**: When testing modules with optional external service dependencies (PostgreSQL, pgvector), mock the connection layer (`pg.Pool`) rather than the business logic. Use `vi.mock('pg', ...)` with factory functions that return mock pool objects. Never create real database connections in unit tests. Key patterns: test with DATABASE_URL unset (graceful path), DATABASE_URL set but pool connection fails (error path), and DATABASE_URL set with successful connection (happy path).
+- **reviewer**: Found 4 major issues despite all tests passing. Key proactive checks for future pipelines: (1) Verify ALL environment variables are passed through child process spawns (env passthrough is the most commonly missed item). (2) Check CLI argument validation ranges — numeric args like --topK and --threshold need both lower and upper bounds. (3) Look for dead code left behind during refactoring — `setEmbeddingProvider()` was left as a no-op stub when it should have received initial implementation or been removed with a comment. (4) Verify test assertions actually test the intended behavior — not just that code runs without error.
+- **tracker**: The reviewer's findings should be incorporated into learned knowledge when they uncover patterns applicable beyond the current pipeline. The env var passthrough gap is a recurring issue (same class as the verbose logging root cause) and is worth tracking as a universal checklist item for any child process spawn.
+
+## Session: 2026-07-30
+
+**Pipeline:** Ad-hoc bug fixes (post-knowledgebase-implementation)
+**Coverage:** 4 bugs fixed across 3 files; all 158 tests passing after fixes
+**TDD Iterations:** 0 (ad-hoc, not pipelined)
+
+**New knowledge:**
+- `chunkLearnedKnowledge()` parser bug: regex `[\s\S]*?(?=\*\*|$)` stopped at inline bold markers within bullet content (e.g., `**npm v12 blocks...**`), causing empty content for 4/5 chunks. Fix: use position-based parsing with `indexOf()` + targeted regex `/(?:\n|^)\s*\*\*[^:\n]*:\*\*/m` to find next section header (distinguished by `:**` ending). The key distinction: section headers have `:**` after the bold marker (e.g., `**New knowledge:**`), while inline bold content does not.
+- `embed()` returned `Float32Array` which fails `Array.isArray()` in pgvector's `toSql()`, causing all chunks to have null embeddings. Fix: return `Array.from(result.data)` — a plain JS Array that pgvector accepts. `Float32Array` is a typed array, not a standard Array; pgvector's SQL formatter checks `Array.isArray()` and silently inserts null for non-Array values.
+- `hooks.test.js` `expectedContent()` was not updated when `buildHookContent()` was fixed (double `HOOK_MARKER` bug). Tests need to stay in sync with code changes — whenever a content-generating function changes, audit all test assertions that reference the generated content.
+- Husky v9 deprecation: `. "$(dirname "$0")/_/husky.sh"` is dead in v9+ — the `h` script handles setup natively. MUST remove this line from ALL `TEMPLATE_HOOKS` templates. Failing to remove it causes "File not found" errors in consumer hook execution.
+- `knowledgebase-cli.js` never called `dotenv.config()` — `DATABASE_URL` appeared unset even when `.env` had it. All CLI scripts that read `process.env` MUST import `dotenv/config`. This is a universal pattern: any Node.js script that depends on `.env` variables must explicitly load them; `process.env` does not auto-load `.env` files.
+- Knowledgebase gap identified: ad-hoc bug fixes not recorded to `learned-knowledge.instructions.md` unless a full feature pipeline runs. The closed-loop workflow has a blind spot for non-pipeline work. Without pipeline orchestration, there is no agent or step responsible for recording learned knowledge.
+
+**Agent tuning notes:**
+- When fixing bugs, the coder should ALSO record the root cause + fix to learned-knowledge. Consider adding a `--record` flag or post-fix prompt to the coder agent spec.
+- The orchestrator's Step 7 (Persist Lessons Learned) only fires at pipeline end — ad-hoc fixes bypass it entirely. A standalone "record-session" command or hook could fill this gap without requiring the full pipeline machinery.
+
+## Session: 2026-07-30 — MCP Config Rename
+
+**Pipeline:** implementer (bootstrap) → researcher → implementer (planning) → coder → reviewer → tracker
+**Coverage:** 109 tests passing across 2 test files (7 sync + 102 setup), 0 regressions, 8 files modified, 1 file deleted
+**TDD Iterations:** 0 (feature pipeline, not TDD)
+
+**New knowledge:**
+- **Three naming contexts pattern for config renames** — Every config rename involves three distinct naming concerns that must be planned independently: (1) repository/template name (what lives in git, e.g., `opencode.mcp.example.json`), (2) consumer provisioning name (what gets placed on consumer projects, e.g., `opencode.json`), and (3) documentation name (how it's referred to in docs, e.g., `opencode.mcp`). Each may differ and must be tracked separately. In this pipeline, the template name stayed unchanged while the consumer target and documentation references changed independently.
+- **`git mv` is not always the right approach for rename + retain** — When a file must remain in the repo under its original name (template source) but the consumer provisioning target changes, do NOT rename the tracked file. Keep the original, update the sync logic to copy to a different target path. The `git mv` approach would change the tracked template when only the consumer output target needs to change.
+- **Auto-copy redundancy with single-file patterns** — When a single file serves both template and live roles (eliminating the example/live distinction), the auto-copy step in `sync.js` becomes redundant because the root file sync already copies the template to consumers. Removing the auto-copy simplifies the sync pipeline and eliminates a potential source of drift between the two copies.
+- **Corrected-plan note placement is critical** — When user feedback rejects the initial plan approach, place a "Corrected Plan Note" BEFORE the original plan content. It must contain: what was originally proposed, why it was rejected, and the accepted alternative. This ensures coder agents read the correction first and don't follow the rejected approach. In this pipeline, the original `git mv` plan was corrected to "keep template, update sync target only" — and the note at the top of the plan file prevented the coder from executing the wrong approach.
+- **`.gitignore` should future-proof against related file spillover** — When removing a specific file entry from `.gitignore`, consider broadening it to cover related naming variants. In this pipeline: `opencode.mcp.json` → `opencode.mcp` (no extension) covers any stray `opencode.mcp*` files in the future.
+- **Historical documentation freeze during renames** — Spike docs, archived plans, and historical tracker entries document past state and should NOT be updated during rename operations. Only live documentation (README, activeContext, progress, docs guides) should be updated. Historical files represent snapshots and changing them would erase the audit trail.
+- **User correction acceptance loop** — In this pipeline, the user reviewed the researcher output and corrected the approach before the implementer created the plan. The researcher's recommendation was to `git mv opencode.mcp.example.json → opencode.mcp`, but the user identified that the `.example` file should stay (it's the template) and the consumer target should be `opencode.json` (opencode's default config filename). The implementer incorporated this correction into the plan. This is the correct pattern: researcher explores options and recommends, user validates direction before plan creation.
+
+**Agent tuning notes:**
+- **researcher**: When auditing references for a rename, categorize ALL hits by change priority: "Must change" (source code, config, sync logic), "Should change" (live documentation, memory bank), "Optional" (historical/spike docs). Include the rationale for each category. Also explicitly list files that do NOT reference the renamed item — this negative confirmation is as valuable as positive hits. And consider including an alternative recommendation section — the user may choose a different approach than the researcher recommends.
+- **implementer (planning)**: Always include a prominent "Corrected Plan Note" when user feedback changes the approach. The note should contain: what was originally proposed, why it was rejected, and the accepted alternative. Place it BEFORE the original plan content to ensure coder agents read it first. Also, if the plan diverges significantly from the accepted approach in its detailed tasks, note each divergence explicitly.
+- **coder**: When executing a config rename, use the 3-name-context mental model (template name, consumer target name, documentation name) to ensure all changes are internally consistent. Verify each context independently — a change that's correct in one context may be wrong in another. The `.gitignore` entry should future-proof against related file spillover (e.g., `opencode.mcp` covers `opencode.mcp.json`, `opencode.mcp.bak`, etc.).
+- **reviewer**: Pre-existing test coverage gaps should be noted separately from issues introduced by the change. A change that is correct but reveals an existing gap is still APPROVED — the gap is a pre-existing concern, not a regression. Use the "pre-existing" label to distinguish.
+- **tracker**: The "Three naming contexts" pattern (repo template, consumer provisioning, documentation) is a reusable architectural insight for ANY config rename pipeline. It should be recorded in learned knowledge as a universal pattern, not a one-time fix. Also note the user correction acceptance loop as a pattern — researcher recommends, user validates, implementer incorporates — this validates the confirmation gate architecture.

package/.husky/post-commit

@@ -0,0 +1,10 @@
+# Managed by @abarcenas/ai-workflow-template setup
+#!/bin/sh
+
+# After commit, check if learned knowledge file changed
+# and sync to the centralized knowledgebase
+
+if git diff HEAD~1 --name-only 2>/dev/null | grep -q ".agents/instructions/learned-knowledge.instructions.md"; then
+  echo "[knowledgebase] Learned knowledge file changed. Syncing to knowledgebase..."
+  node scripts/knowledgebase-cli.js sync 2>/dev/null || echo "[knowledgebase] Sync skipped (DATABASE_URL not configured or service unavailable)"
+fi

package/.husky/post-merge

@@ -1,6 +1,5 @@
 # Managed by @abarcenas/ai-workflow-template setup
 #!/bin/sh
-. "$(dirname "$0")/_/husky.sh"
 
 # After git pull/merge, check if memory-bank files changed
 # and update the vector index incrementally

package/.opencode/agents/architect.agent.md

@@ -5,6 +5,7 @@ permission:
   read: allow
   search: allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/coder.agent.md

@@ -7,6 +7,7 @@ permission:
   edit: "allow"
   execute: "allow"
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/.opencode/agents/deployer.agent.md

@@ -8,6 +8,7 @@ permission:
   execute: allow
   "github/*": allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/.opencode/agents/designer.agent.md

@@ -5,6 +5,7 @@ permission:
   read: "allow"
   search: "allow"
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/.opencode/agents/e2e-tester.agent.md

@@ -6,6 +6,7 @@ permission:
   search: allow
   "chrome-devtools/*": allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/.opencode/agents/implementer.agent.md

@@ -7,6 +7,7 @@ permission:
    edit: allow
    execute: allow
    "memory-bank/*": allow
+   "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/orchestrator/feature-pipeline.agent.md

@@ -7,6 +7,7 @@ permission:
   agent: allow
   todo: allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/orchestrator/orchestrator.agent.md

@@ -12,6 +12,7 @@ permission:
   "github/*": allow
   "chrome-devtools/*": allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md

@@ -7,6 +7,7 @@ permission:
   agent: allow
   todo: allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/researcher.agent.md

@@ -8,6 +8,7 @@ permission:
   "ddg-search/*": allow
   "context7/*": allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 

package/.opencode/agents/reviewer.agent.md

@@ -7,6 +7,7 @@ permission:
   edit: allow
   "github/*": allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/.opencode/agents/tracker.agent.md

@@ -8,6 +8,7 @@ permission:
   edit: allow
   write: allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 
@@ -21,6 +22,7 @@ You are a documentation specialist. You never write code — you read agent outp
 - Extract what was accomplished, what files were produced, and key decisions
 - Append a structured entry to `docs/tracker-log.md`
 - Append a summary entry to `memory-bank/progress.md` with the same structured information, then run `memory_bank_memory_update`
+- Append a new `## Session:` entry to `.agents/instructions/learned-knowledge.instructions.md` after every pipeline, recording discoveries, patterns, gotchas, and agent tuning notes for future cross-project reference
 
 ## Approach
 

package/.opencode/agents/unit-tester.agent.md

@@ -7,6 +7,7 @@ permission:
   edit: allow
   execute: allow
   "memory-bank/*": allow
+  "knowledgebase/*": allow
 model: deepseek/deepseek-v4-flash
 ---
 

package/README.md

@@ -189,7 +189,7 @@ All subsequent runs skip this — agents get architecture context pre-filled.
 
 #### MCP Tooling
 
-Some agents require MCP servers configured in `opencode.mcp.json` (copy from `opencode.mcp.example.json`):
+Some agents require MCP servers configured in `opencode.mcp`:
 
 | Agent | Required MCP | Purpose |
 |---|---|---|

package/memory-bank/.vocabulary.json

@@ -18,10 +18,16 @@
     "workflow": [
       "bootstrap", "setup", "configuration", "migration", "refactor",
       "tdd", "feature-pipeline", "onboarding", "normalization",
-      "research", "spike", "implementation"
+      "research", "spike", "implementation", "implementation-planning",
+      "documentation"
     ],
     "memory_ops": [
-      "decision", "discovery", "status-update", "task-plan", "retrospective"
+      "decision", "discovery", "status-update", "task-plan", "retrospective",
+      "bug-fix", "verification"
+    ],
+    "topic": [
+      "knowledgebase", "pgvector", "mcp", "embeddings", "dotenv",
+      "chunk-parser", "agent-exercise"
     ]
   },
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abarcenas/ai-workflow-template",
-  "version": "1.33.0",
+  "version": "1.38.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.",
   "main": "index.js",
   "bin": {
@@ -21,7 +21,10 @@
     "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"
+    "memory:normalize": "node ./scripts/normalize-memory.js",
+    "kb:sync": "node ./scripts/knowledgebase-cli.js sync",
+    "kb:search": "node ./scripts/knowledgebase-cli.js search",
+    "kb:stats": "node ./scripts/knowledgebase-cli.js stats"
   },
   "repository": {
     "type": "git",
@@ -48,7 +51,8 @@
     "AGENTS.md",
     "opencode.mcp.example.json",
     "skills-lock.json",
-    ".husky/post-merge"
+    ".husky/post-merge",
+    ".husky/post-commit"
   ],
   "devDependencies": {
     "@playwright/test": "^1.59.1",
@@ -58,11 +62,13 @@
     "vitest": "^4.1.8"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
     "better-sqlite3": "^12.11.0",
-    "sqlite-vec": "^0.1.9",
-    "@modelcontextprotocol/sdk": "^1.0.0"
+    "sqlite-vec": "^0.1.9"
   },
   "optionalDependencies": {
-    "@xenova/transformers": "^2.17.0"
+    "@xenova/transformers": "^2.17.0",
+    "pg": "^8.22.0",
+    "pgvector": "^0.3.0"
   }
 }