@abarcenas/ai-workflow-template 1.25.0 → 1.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.agents/instructions/agent-skill.instructions.md +18 -20
  2. package/.agents/instructions/agent.instructions.md +111 -570
  3. package/.agents/instructions/ai-prompt-engineering-safety.instructions.md +3 -3
  4. package/.agents/instructions/instructions.instructions.md +6 -7
  5. package/.agents/instructions/memory-bank.instructions.md +72 -18
  6. package/.agents/instructions/memory-schema.instructions.md +75 -0
  7. package/.agents/instructions/prompt.instructions.md +25 -30
  8. package/.agents/skills/conventional-commit/SKILL.md +2 -2
  9. package/.agents/skills/github-issues/SKILL.md +2 -2
  10. package/.agents/skills/memory-search/SKILL.md +69 -0
  11. package/.agents/skills/microsoft-docs/SKILL.md +1 -1
  12. package/.agents/skills/polygot-test-agent/SKILL.md +0 -1
  13. package/.agents/skills/prompt-builder/SKILL.md +15 -14
  14. package/.husky/post-merge +10 -0
  15. package/.husky/pre-commit +2 -0
  16. package/.opencode/agents/architect.agent.md +2 -1
  17. package/.opencode/agents/coder.agent.md +3 -1
  18. package/.opencode/agents/deployer.agent.md +1 -0
  19. package/.opencode/agents/designer.agent.md +2 -1
  20. package/.opencode/agents/e2e-tester.agent.md +1 -0
  21. package/.opencode/agents/implementer.agent.md +2 -1
  22. package/.opencode/agents/orchestrator/feature-pipeline.agent.md +4 -3
  23. package/.opencode/agents/orchestrator/orchestrator.agent.md +4 -3
  24. package/.opencode/agents/orchestrator/tdd-orchestrator.agent.md +8 -4
  25. package/.opencode/agents/researcher.agent.md +1 -0
  26. package/.opencode/agents/reviewer.agent.md +1 -0
  27. package/.opencode/agents/tracker.agent.md +2 -1
  28. package/.opencode/agents/unit-tester.agent.md +1 -0
  29. package/README.md +75 -4
  30. package/memory-bank/.vocabulary.json +52 -0
  31. package/opencode.mcp.example.json +7 -1
  32. package/package.json +18 -3
  33. package/scripts/mcp-memory-server.js +243 -0
  34. package/scripts/memory-cli.js +110 -0
  35. package/scripts/memory-index.js +512 -0
  36. package/scripts/normalize-memory.js +349 -0
  37. package/scripts/validate-memory-schema.js +190 -0
@@ -6,6 +6,7 @@ permission:
6
6
  search: "allow"
7
7
  edit: "allow"
8
8
  execute: "allow"
9
+ "memory-bank/*": allow
9
10
  model: deepseek/deepseek-v4-flash
10
11
  ---
11
12
 
@@ -28,13 +29,14 @@ You are a production code implementation specialist. You write clean, maintainab
28
29
  - Read the full phase section for context — understand what sibling tasks exist and how yours fits
29
30
  - Check the Parallel Execution Summary to see which batch you belong to and whether sibling tasks are running concurrently
30
31
  2. **Explore Context**: Read existing files to understand patterns, conventions, and integration points.
31
- 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md` and core `memory-bank/` files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`) for project context.
32
+ 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads.
32
33
  4. **Implement**: Write production code following established patterns.
33
34
  5. **Verify**: Check that the implementation compiles/runs correctly.
34
35
  6. **Document**: Record what was accomplished in all three locations:
35
36
  - **Plan file**: Open `/plan/{purpose}-{component}-{version}.md` and mark your task row's **Completed** column with the current date. If the task is the last incomplete in its phase, update the phase status as well.
36
37
  - **memory-bank/activeContext.md**: Append a summary of what was implemented, files changed, and current focus.
37
38
  - **memory-bank/progress.md**: Update the project status — document what now works and any known issues.
39
+ - Run `memory_bank_memory_update` to sync the index.
38
40
 
39
41
  ## Guidelines
40
42
 
@@ -7,6 +7,7 @@ permission:
7
7
  edit: allow
8
8
  execute: allow
9
9
  "github/*": allow
10
+ "memory-bank/*": allow
10
11
  model: deepseek/deepseek-v4-flash
11
12
  ---
12
13
 
@@ -5,6 +5,7 @@ permission:
5
5
  read: "allow"
6
6
  search: "allow"
7
7
  edit: "allow"
8
+ "memory-bank/*": allow
8
9
  model: deepseek/deepseek-v4-flash
9
10
  ---
10
11
 
@@ -30,7 +31,7 @@ You are a UI/UX design specialist focused on creating intuitive, accessible, and
30
31
 
31
32
  1. **Understand Requirements**: Parse the design needs from the prompt or orchestrator context.
32
33
  2. **Explore Existing Patterns**: Review existing components, styles, and design tokens in the codebase.
33
- 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md` and core `memory-bank/` files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`) for project context. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect design changes.
34
+ 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect design changes, then run `memory_bank_memory_update`.
34
35
  4. **Check Latest API**: Use Context7 MCP to fetch current TailwindCSS v4+ and daisyUI v5+ APIs before writing markup — avoids deprecated patterns and leverages newest features.
35
36
  5. **Design/Implement**: Create or modify UI components following established patterns.
36
37
  6. **Validate**: Check for accessibility, responsiveness, and consistency.
@@ -7,6 +7,7 @@ permission:
7
7
  edit: allow
8
8
  execute: allow
9
9
  "playwright/*": allow
10
+ "memory-bank/*": allow
10
11
  model: deepseek/deepseek-v4-flash
11
12
  ---
12
13
 
@@ -6,6 +6,7 @@ permission:
6
6
  search: allow
7
7
  edit: allow
8
8
  execute: allow
9
+ "memory-bank/*": allow
9
10
  model: deepseek/deepseek-v4-pro
10
11
  ---
11
12
 
@@ -25,7 +26,7 @@ You are an implementation planning specialist. You translate architecture and de
25
26
 
26
27
  1. **Analyze Input**: Read the architecture doc, design spec, or requirements.
27
28
  2. **Explore Codebase**: Understand existing code patterns, conventions, and integration points.
28
- 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md` and core `memory-bank/` files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`) for project context. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect what was planned.
29
+ 3. **Check Memory Bank**: Read `.agents/instructions/memory-bank.instructions.md`. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md` and `memory-bank/progress.md` to reflect what was planned, then run `memory_bank_memory_update`.
29
30
  4. **Define Tasks**: Break the work into atomic, ordered tasks with:
30
31
  - Exact file paths and line numbers
31
32
  - Specific changes or additions needed
@@ -8,6 +8,7 @@ permission:
8
8
  execute: allow
9
9
  agent: allow
10
10
  todo: allow
11
+ "memory-bank/*": allow
11
12
  model: deepseek/deepseek-v4-pro
12
13
  ---
13
14
 
@@ -69,7 +70,7 @@ Parse the user's request to determine:
69
70
  - Whether autoConfirm mode is requested (check user's message for phrases like "full pipeline", "auto", "go ahead")
70
71
  - **Read `.agents/instructions/learned-knowledge.instructions.md`** to apply previously discovered patterns and avoid known pitfalls
71
72
  - **Read `docs/.architecture-context.md`** if it exists — it contains the project's auto-detected architecture context (tech stack, layer structure, abstractions, dependency rules) so sub-agents don't rediscover it
72
- - **Read memory-bank core files**: `memory-bank/projectbrief.md`, `memory-bank/activeContext.md`, `memory-bank/systemPatterns.md`, `memory-bank/techContext.md`, `memory-bank/progress.md` if they exist
73
+ - **Search memory-bank**: use `memory_bank_memory_search` for semantic context and `memory_bank_memory_get` to read core files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`)
73
74
 
74
75
  ### Step 2: Initialize Log
75
76
 
@@ -107,7 +108,7 @@ IMPORTANT:
107
108
  - Previous step context: {previous_step_summary}
108
109
  - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
109
110
  - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
110
- - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant.
111
+ - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
111
112
  - Return a clear summary (actions taken + files produced/modified + issues).
112
113
  ```
113
114
 
@@ -140,7 +141,7 @@ When the pipeline reaches the "coder" step and the latest implementer plan has p
140
141
  - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
141
142
  - Perform the necessary reads/writes under this base path.
142
143
  - Previous step context: {previous_step_summary}
143
- - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant.
144
+ - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
144
145
  - Return a clear summary (actions taken + files produced/modified + issues).
145
146
  ```
146
147
  d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.
@@ -13,6 +13,7 @@ permission:
13
13
  "context7/*": allow
14
14
  "github/*": allow
15
15
  "playwright/*": allow
16
+ "memory-bank/*": allow
16
17
  model: deepseek/deepseek-v4-pro
17
18
  ---
18
19
 
@@ -81,7 +82,7 @@ Parse the user's request to determine:
81
82
  - Whether autoConfirm mode is requested (check user's message for phrases like "full pipeline", "auto", "go ahead")
82
83
  - **Read `.agents/instructions/learned-knowledge.instructions.md`** to apply previously discovered patterns and avoid known pitfalls
83
84
  - **Read `docs/.architecture-context.md`** if it exists — it contains the project's auto-detected architecture context (tech stack, layer structure, abstractions, dependency rules) so sub-agents don't rediscover it
84
- - **Read memory-bank core files**: `memory-bank/projectbrief.md`, `memory-bank/activeContext.md`, `memory-bank/systemPatterns.md`, `memory-bank/techContext.md`, `memory-bank/progress.md` if they exist
85
+ - **Search memory-bank**: use `memory_bank_memory_search` for semantic context and `memory_bank_memory_get` to read core files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`)
85
86
 
86
87
  ### Step 2: Build Pipeline
87
88
 
@@ -124,7 +125,7 @@ IMPORTANT:
124
125
  - Work on "{work_unit}" with base path: "{basePath}".
125
126
  - Perform the necessary reads/writes under this base path.
126
127
  - Previous step context: {previous_step_summary}
127
- - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant.
128
+ - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
128
129
  - Return a clear summary (actions taken + files produced/modified + issues).
129
130
  ```
130
131
 
@@ -157,7 +158,7 @@ When the pipeline reaches the "coder" step and the latest implementer plan has p
157
158
  - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
158
159
  - Perform the necessary reads/writes under this base path.
159
160
  - Previous step context: {previous_step_summary}
160
- - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant.
161
+ - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads. After completing work, update `memory-bank/activeContext.md`, `memory-bank/progress.md`, and `memory-bank/tasks/_index.md` if relevant, then run `memory_bank_memory_update`.
161
162
  - Return a clear summary (actions taken + files produced/modified + issues).
162
163
  ```
163
164
  d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.
@@ -8,6 +8,7 @@ permission:
8
8
  execute: allow
9
9
  agent: allow
10
10
  todo: allow
11
+ "memory-bank/*": allow
11
12
  model: deepseek/deepseek-v4-pro
12
13
  ---
13
14
 
@@ -93,7 +94,7 @@ Parse the user's request to determine:
93
94
  - Whether the user specified `minCoverage` or `maxTDDIterations` overrides (e.g. "minCoverage=85", "maxIterations=5")
94
95
  - **Read `.agents/instructions/learned-knowledge.instructions.md`** to apply previously discovered patterns and avoid known pitfalls
95
96
  - **Read `docs/.architecture-context.md`** if it exists — it contains the project's auto-detected architecture context (tech stack, layer structure, abstractions, dependency rules) so sub-agents don't rediscover it
96
- - **Read memory-bank core files**: `memory-bank/projectbrief.md`, `memory-bank/activeContext.md`, `memory-bank/systemPatterns.md`, `memory-bank/techContext.md`, `memory-bank/progress.md` if they exist
97
+ - **Search memory-bank**: use `memory_bank_memory_search` for semantic context and `memory_bank_memory_get` to read core files (`projectbrief.md`, `activeContext.md`, `systemPatterns.md`, `techContext.md`, `progress.md`)
97
98
 
98
99
  ### Step 2: Build Pipeline
99
100
 
@@ -136,8 +137,8 @@ IMPORTANT:
136
137
  - The batches within each table must respect dependency order (Batch A has no deps, Batch B depends on Batch A completing, etc.).
137
138
  - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
138
139
  - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
139
- - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Read `memory-bank/activeContext.md` and `memory-bank/progress.md` for current state.
140
- - After completing the plan, update `memory-bank/activeContext.md` and `memory-bank/progress.md`.
140
+ - Memory bank: read `.agents/instructions/memory-bank.instructions.md` for task/file conventions. Use `memory_bank_memory_search` for semantic context retrieval and `memory_bank_memory_get` for full file reads.
141
+ - After completing the plan, update `memory-bank/activeContext.md` and `memory-bank/progress.md`, then run `memory_bank_memory_update`.
141
142
  - Return a clear summary including: plan file path, number of test tasks, number of implementation tasks, batch breakdown per table.
142
143
  ```
143
144
 
@@ -173,6 +174,7 @@ IMPORTANT:
173
174
  2. Update `memory-bank/tasks/_index.md` — add the new test task entry.
174
175
  3. Update `memory-bank/activeContext.md` — append test coverage baseline for this component.
175
176
  4. Update `memory-bank/progress.md` — document which test suites were created and their status.
177
+ 5. Run `memory_bank_memory_update` to sync the index.
176
178
  - Return a clear summary: test files created, number of test cases per file, coverage areas covered, memory-bank files updated.
177
179
  ```
178
180
  d. **Wait for all test tasks in this batch to complete** (fan-in). Capture each response summary.
@@ -214,7 +216,8 @@ IMPORTANT:
214
216
  - Update memory-bank files:
215
217
  1. Update `memory-bank/activeContext.md` — append what was implemented and which tests it satisfies.
216
218
  2. Update `memory-bank/progress.md` — document implementation status and test alignment.
217
- 3. Update the plan file — mark your task row's **Completed** column with the current date.
219
+ 3. Run `memory_bank_memory_update` to sync the index.
220
+ 4. Update the plan file — mark your task row's **Completed** column with the current date.
218
221
  - Return a clear summary: files created/modified, which test files were satisfied, build verification results, memory-bank files updated.
219
222
  ```
220
223
  d. **Wait for all implementation tasks in this batch to complete** (fan-in). Capture each response summary.
@@ -253,6 +256,7 @@ IMPORTANT:
253
256
  1. Update `memory-bank/activeContext.md` — append test run results and coverage report.
254
257
  2. Update `memory-bank/progress.md` — document verification status.
255
258
  3. Update `memory-bank/tasks/_index.md` — update test task statuses based on pass/fail results.
259
+ 4. Run `memory_bank_memory_update` to sync the index.
256
260
  - Return a clear summary including: pass/fail counts, coverage percentage, threshold met (yes/no), failing test details if any, coverage gaps if any.
257
261
  ```
258
262
 
@@ -8,6 +8,7 @@ permission:
8
8
  edit: allow
9
9
  "ddg-search/*": allow
10
10
  "context7/*": allow
11
+ "memory-bank/*": allow
11
12
  model: deepseek/deepseek-v4-pro
12
13
  ---
13
14
 
@@ -6,6 +6,7 @@ permission:
6
6
  search: allow
7
7
  edit: allow
8
8
  "github/*": allow
9
+ "memory-bank/*": allow
9
10
  model: deepseek/deepseek-v4-flash
10
11
  ---
11
12
 
@@ -7,6 +7,7 @@ permission:
7
7
  glob: allow
8
8
  edit: allow
9
9
  write: allow
10
+ "memory-bank/*": allow
10
11
  model: deepseek/deepseek-v4-flash
11
12
  ---
12
13
 
@@ -19,7 +20,7 @@ You are a documentation specialist. You never write code — you read agent outp
19
20
  - Read the orchestrator's log and artifact files from a completed pipeline step
20
21
  - Extract what was accomplished, what files were produced, and key decisions
21
22
  - Append a structured entry to `docs/tracker-log.md`
22
- - Append a summary entry to `memory-bank/progress.md` with the same structured information
23
+ - Append a summary entry to `memory-bank/progress.md` with the same structured information, then run `memory_bank_memory_update`
23
24
 
24
25
  ## Approach
25
26
 
@@ -6,6 +6,7 @@ permission:
6
6
  search: allow
7
7
  edit: allow
8
8
  execute: allow
9
+ "memory-bank/*": allow
9
10
  model: deepseek/deepseek-v4-flash
10
11
  ---
11
12
 
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # 🤖 AI Workflow Template
2
2
 
3
- **Publishable AI workflow starter pack for GitHub Copilot** - Auto-syncing, version-managed, npm-distributed agent configuration suite.
3
+ **Publishable AI workflow starter pack for OpenCode** — Auto-syncing, version-managed, npm-distributed agent configuration suite with vector search memory.
4
4
 
5
5
  ---
6
6
 
@@ -16,7 +16,8 @@ This isn't a one-off template to clone—it's a **live npm package** that distri
16
16
  - 🧪 **TDD Orchestrator** — Strict RED→GREEN→REFACTOR/VERIFY test-driven pipeline (90% coverage gate)
17
17
  - 📝 **Framework Instructions** - Technology-specific guidance (`.agents/instructions/`)
18
18
  - 💬 **Prompt Templates** - Ready-to-use prompt blueprints (`.agents/prompts/`)
19
- - 🧠 **Memory Bank** — Persistent project context across AI sessions
19
+ - 🧠 **Memory Bank** — Persistent project context across AI sessions with semantic search
20
+ - 🔍 **Vector Memory Search** — sqlite-vec powered semantic search (token-efficient, zero deps)
20
21
  - 🏃‍♂️ **Caveman Mode** - Ultra-compressed communication for token efficiency
21
22
  - 🎭 **Playwright Testing** - Automated E2E testing with MCP integration
22
23
  - ⚡ **Vitest Unit Testing** — Fast unit tests with v8 coverage (≥90% threshold)
@@ -241,9 +242,38 @@ implementer (PLAN) → unit-tester∥ (RED) → coder∥ (GREEN) → unit-tester
241
242
 
242
243
  The TDD orchestrator uses `subagent_type "tdd-orchestrator"` and auto-selects the strict TDD pipeline when testable code changes are requested.
243
244
 
244
- ### 🧠 Memory Bank — Persistent Project Context
245
+ ### 🧠 Memory Bank — Persistent Project Context with Vector Search
245
246
 
246
- The memory bank preserves project knowledge across AI sessions, preventing context loss after resets:
247
+ 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.
248
+
249
+ #### Architecture
250
+
251
+ ```
252
+ Markdown files (git-committed) Vector Index (.gitignore'd)
253
+ ══════════════════════════════ ════════════════════════════
254
+ memory-bank/ memory-bank/.index/
255
+ ├── activeContext.md └── memory.db ← sqlite-vec + better-sqlite3
256
+ ├── progress.md │
257
+ ├── systemPatterns.md │ rebuilt from .md files
258
+ ├── ... ▼ on demand
259
+ memory_search("tdd orchestrator")
260
+ → top 5 relevant chunks (~500 tokens)
261
+ ```
262
+
263
+ **Source of truth:** Markdown files (git-versioned, human-readable).
264
+ **Search index:** `sqlite-vec` vector database (disposable, rebuildable, never committed).
265
+
266
+ #### MCP Tools (OpenCode)
267
+
268
+ | Tool | Purpose |
269
+ |---|---|
270
+ | `memory_search` | Semantic search across memory-bank + docs (query + topK) |
271
+ | `memory_update` | Incremental sync — only changed files (~2 seconds) |
272
+ | `memory_rebuild` | Full rebuild from markdown files (rare — clone/corruption) |
273
+ | `memory_get` | Read a specific memory file by name |
274
+ | `memory_stats` | Index statistics (vector count, DB size) |
275
+
276
+ #### File Structure
247
277
 
248
278
  ```
249
279
  projectbrief.md → productContext.md / systemPatterns.md / techContext.md → activeContext.md → progress.md / tasks/
@@ -259,8 +289,35 @@ projectbrief.md → productContext.md / systemPatterns.md / techContext.md → a
259
289
  | `memory-bank/progress.md` | What works, what's left, known issues |
260
290
  | `memory-bank/tasks/` | Per-task tracking with `_index.md` |
261
291
 
292
+ #### Document Schema
293
+
294
+ All memory-bank files use YAML frontmatter for search indexing:
295
+
296
+ ```yaml
297
+ ---
298
+ id: activeContext
299
+ title: "Active Context"
300
+ updated: 2026-07-23
301
+ tags: [orchestrator, bootstrap, tdd]
302
+ entities: [vitest, graphify, memory-bank]
303
+ category: context
304
+ ---
305
+ ```
306
+
307
+ See `memory-bank/.vocabulary.json` for the controlled vocabulary (user-extensible).
308
+
309
+ **Auto-normalization:** `npm install` runs `normalize-memory.js` to add frontmatter to existing files.
310
+ **Pre-commit validation:** Husky hook rejects commits with invalid frontmatter.
311
+
262
312
  **Task commands:** `add task`, `update task [ID]`, `show tasks [filter]`
263
313
 
314
+ #### Token Efficiency
315
+
316
+ | Approach | Tokens per session |
317
+ |---|---|
318
+ | Read all memory files | ~5,000–15,000+ |
319
+ | Semantic search | ~500–2,000 (top 3–5 chunks) |
320
+
264
321
  ---
265
322
 
266
323
  ## 📦 Versioning
@@ -314,6 +371,20 @@ npm run test:unit:coverage
314
371
 
315
372
  # Watch mode for unit tests
316
373
  npm run test:unit:watch
374
+
375
+ # ─── Memory Bank (Vector Search) ───
376
+
377
+ # Build the vector search index (one-time, ~8 min for 5K files)
378
+ npm run memory:rebuild
379
+
380
+ # Incremental update (seconds — only changed files)
381
+ npm run memory:update
382
+
383
+ # Search project memory
384
+ npm run memory:search "tdd orchestrator status"
385
+
386
+ # Normalize document frontmatter (runs automatically on install)
387
+ npm run memory:normalize
317
388
  ```
318
389
 
319
390
  ### Testing
@@ -0,0 +1,52 @@
1
+ {
2
+ "categories": {
3
+ "brief": "Project scope, goals (projectbrief.md)",
4
+ "product": "Product context, UX goals (productContext.md)",
5
+ "architecture": "System patterns, design decisions, component relationships",
6
+ "tech": "Technology stack, dev setup, constraints",
7
+ "context": "Current focus, recent changes, next steps (activeContext.md)",
8
+ "progress": "What works, what's left, known issues (progress.md)",
9
+ "task": "Individual task tracking (tasks/TASK*.md)",
10
+ "decision": "ADR-style architecture/technical decisions"
11
+ },
12
+
13
+ "tags": {
14
+ "agent_roles": [
15
+ "designer", "architect", "researcher", "coder", "implementer",
16
+ "tester", "reviewer", "tracker", "deployer", "orchestrator"
17
+ ],
18
+ "workflow": [
19
+ "bootstrap", "setup", "configuration", "migration", "refactor",
20
+ "tdd", "feature-pipeline", "onboarding", "normalization",
21
+ "research", "spike", "implementation"
22
+ ],
23
+ "memory_ops": [
24
+ "decision", "discovery", "status-update", "task-plan", "retrospective"
25
+ ]
26
+ },
27
+
28
+ "entity_patterns": {
29
+ "vitest": ["vitest", "vitest\\.config", "@vitest\\/coverage"],
30
+ "playwright": ["playwright", "@playwright", "browser.*test"],
31
+ "graphify": ["graphify", "knowledge graph", "graph\\.json"],
32
+ "memory-bank": ["memory-bank", "memory bank", "activeContext", "systemPatterns"],
33
+ "husky": ["husky", "pre-commit", "git hook"],
34
+ "tdd-orchestrator": ["tdd orchestrator", "RED.*GREEN.*REFACTOR"],
35
+ "mcp-server": ["mcp", "modelcontextprotocol", "stdio", "mcp server"],
36
+ "sqlite-vec": ["sqlite-vec", "sqlite.vec", "better-sqlite3"],
37
+ "transformers.js": ["@xenova\\/transformers", "transformers\\.js", "all-MiniLM"],
38
+ "opencode": ["opencode", "OpenCode", "open code"],
39
+ "npm": ["npm", "npm package", "npm install"]
40
+ },
41
+
42
+ "file_category_map": {
43
+ "projectbrief": "brief",
44
+ "productContext": "product",
45
+ "systemPatterns": "architecture",
46
+ "techContext": "tech",
47
+ "activeContext": "context",
48
+ "progress": "progress"
49
+ },
50
+
51
+ "doc_types": ["spike", "architecture", "configuration", "orchestrator-log", "tracker-log", "decision"]
52
+ }
@@ -53,6 +53,11 @@
53
53
  "type": "remote",
54
54
  "url": "https://your-mcp-server.com/mcp",
55
55
  "enabled": false
56
+ },
57
+ "memory-bank": {
58
+ "type": "local",
59
+ "command": ["node", "scripts/mcp-memory-server.js"],
60
+ "enabled": true
56
61
  }
57
62
  },
58
63
  "permission": {
@@ -60,6 +65,7 @@
60
65
  "github_*": "allow",
61
66
  "mcp-everything_*": "allow",
62
67
  "angular-cli_*": "allow",
63
- "playwright_*": "allow"
68
+ "playwright_*": "allow",
69
+ "memory-bank_*": "allow"
64
70
  }
65
71
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@abarcenas/ai-workflow-template",
3
- "version": "1.25.0",
3
+ "version": "1.28.0",
4
4
  "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.",
5
5
  "main": "index.js",
6
6
  "scripts": {
@@ -14,7 +14,11 @@
14
14
  "test:unit:watch": "vitest",
15
15
  "prepare": "husky",
16
16
  "sync": "node ./scripts/sync.js",
17
- "postinstall": "node ./scripts/sync.js"
17
+ "postinstall": "node ./scripts/sync.js && node ./scripts/normalize-memory.js",
18
+ "memory:search": "node ./scripts/memory-cli.js search",
19
+ "memory:rebuild": "node ./scripts/memory-cli.js rebuild",
20
+ "memory:update": "node ./scripts/memory-cli.js update",
21
+ "memory:normalize": "node ./scripts/normalize-memory.js"
18
22
  },
19
23
  "repository": {
20
24
  "type": "git",
@@ -34,9 +38,12 @@
34
38
  "scripts/",
35
39
  ".opencode/agents/",
36
40
  ".opencode/commands/",
41
+ ".husky/",
42
+ "memory-bank/.vocabulary.json",
37
43
  "AGENTS.md",
38
44
  "opencode.mcp.example.json",
39
- "skills-lock.json"
45
+ "skills-lock.json",
46
+ ".husky/post-merge"
40
47
  ],
41
48
  "devDependencies": {
42
49
  "@playwright/test": "^1.59.1",
@@ -44,5 +51,13 @@
44
51
  "dotenv": "^17.4.2",
45
52
  "husky": "^9.0.0",
46
53
  "vitest": "^4.1.8"
54
+ },
55
+ "dependencies": {
56
+ "better-sqlite3": "^12.11.0",
57
+ "sqlite-vec": "^0.1.9",
58
+ "@modelcontextprotocol/sdk": "^1.0.0"
59
+ },
60
+ "optionalDependencies": {
61
+ "@xenova/transformers": "^2.17.0"
47
62
  }
48
63
  }