@abarcenas/ai-workflow-template 1.41.0 → 1.44.0

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

@@ -17,7 +17,7 @@ You are a lightweight orchestration agent that runs a fixed sequential pipeline:
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -103,6 +103,7 @@ IMPORTANT:
 - Previous step context: {previous_step_summary}
 - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+- Knowledgebase: call `knowledgebase_knowledgebase_search` with a task-relevant query using the graceful-failure protocol defined in `.agents/instructions/knowledge-retrieval.instructions.md`. Report whether executed or skipped in your final summary.
 - 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`.
 - Return a clear summary (actions taken + files produced/modified + issues).
 ```
@@ -136,7 +137,10 @@ When the pipeline reaches the "coder" step and the latest implementer plan has p
       - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
-- 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`.
+      - 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`.
+      - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+      - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
+      - Knowledgebase: call `knowledgebase_knowledgebase_search` with a task-relevant query using the graceful-failure protocol defined in `.agents/instructions/knowledge-retrieval.instructions.md`. Report whether executed or skipped in your final summary.
       - Return a clear summary (actions taken + files produced/modified + issues).
       ```
    d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.

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

@@ -22,7 +22,7 @@ You are a master orchestration agent that coordinates specialized sub-agents to
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -121,6 +121,8 @@ IMPORTANT:
 - Perform the necessary reads/writes under this base path.
 - Previous step context: {previous_step_summary}
 - 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`.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query (graceful failure — report whether executed or skipped). Skim `.agents/instructions/learned-knowledge.instructions.md` for role-relevant patterns. State the retrieval outcome in your final summary.
+- Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Return a clear summary (actions taken + files produced/modified + issues).
 ```
 
@@ -153,6 +155,8 @@ When the pipeline reaches the "coder" step and the implementer's summary include
       - Perform the necessary reads/writes under this base path.
       - Previous step context: {previous_step_summary}
       - 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`.
+      - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer knowledge-retrieval protocol. Call `knowledgebase_knowledgebase_search` with a task-relevant query (graceful failure — report whether executed or skipped). Skim `.agents/instructions/learned-knowledge.instructions.md` for role-relevant patterns. State the retrieval outcome in your final summary.
+      - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
       - Return a clear summary (actions taken + files produced/modified + issues).
       ```
    d. **Wait for all tasks in this batch to complete** (fan-in). Capture each response summary.

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

@@ -17,7 +17,7 @@ You are a Test-Driven Development orchestration agent that enforces a strict RED
 
 ## Dynamic Parameters
 
-- **projectName**: The project or component being worked on (extracted from user request)
+- **projectName**: The project or component being worked on (extracted from user request (prefer package.json "name" for the canonical scoped projectId))
 - **basePath**: Root directory for the work (defaults to current workspace)
 - **logFile**: Path to the orchestration log (defaults to `docs/.orchestrator-log.md`)
 - **autoConfirm**: If `true`, execute all pipeline steps without pausing. If `false`, ask the user before each delegation. (Default: `false`)
@@ -132,6 +132,7 @@ IMPORTANT:
 - The batches within each table must respect dependency order (Batch A has no deps, Batch B depends on Batch A completing, etc.).
 - Architecture context: read docs/.architecture-context.md for tech stack, layer structure, and dependency rules.
 - Learned knowledge: read .agents/instructions/learned-knowledge.instructions.md for patterns and conventions.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - 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 the plan, update `memory-bank/activeContext.md` and `memory-bank/progress.md`, then run `memory_bank_memory_update`.
 - Return a clear summary including: plan file path, number of test tasks, number of implementation tasks, batch breakdown per table.
@@ -158,6 +159,7 @@ IMPORTANT:
    IMPORTANT:
    - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
    - TDD CONTEXT: This is the RED phase. You are writing tests that define expected behavior BEFORE any implementation code exists. These tests SHOULD fail when run — that is correct and expected in TDD.
+   - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Write tests for task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
    - Read the plan file to understand the full spec, interfaces, and expected behaviors.
    - Write comprehensive tests covering: happy path, error cases, edge cases, boundary values.
@@ -201,6 +203,7 @@ IMPORTANT:
    IMPORTANT:
    - Read and apply the entire .agent.md spec (tools, constraints, quality standards).
    - TDD CONTEXT: This is the GREEN phase. Write the MINIMAL production code necessary to pass all existing tests. Do NOT add features beyond what the tests specify. The tests were written first and define the contract you must fulfill.
+   - Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
    - Work on "Implement task {TASK_ID}: {Description} from plan /plan/{filename}" with base path: "{basePath}".
    - Read the plan file for full context and the corresponding test file(s) for the exact expected behavior.
    - Write production code that makes ALL related tests pass.
@@ -243,6 +246,7 @@ IMPORTANT:
   - Passed: {count}
   - Failed: {count} (with details for each failure)
   - Code coverage percentage (statement, branch, function, line — whichever the project's coverage tool reports)
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - The minimum coverage threshold is {minCoverage}%. Report whether this threshold is met.
 - If any tests FAIL: provide the failure details (file, line, error message, expected vs actual).
 - If coverage is BELOW {minCoverage}%: identify which files/modules have the lowest coverage and suggest additional test cases.
@@ -283,6 +287,7 @@ IMPORTANT:
   - Test and implementation code follow project conventions.
   - No security vulnerabilities were introduced.
   - Error handling is adequate and tested.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - Base path: "{basePath}".
 - Read the plan file for context on what was supposed to be built.
 - Previous step context: All tests passed with {coverage}% coverage (threshold: {minCoverage}%).
@@ -307,6 +312,7 @@ IMPORTANT:
 - Base path: "{basePath}".
 - Read the orchestrator log at "docs/.orchestrator-log.md" for the full pipeline record.
 - Read any artifact files referenced in the log.
+- Knowledge retrieval: read `.agents/instructions/knowledge-retrieval.instructions.md` for the mandatory 3-layer protocol (memory-bank + learned-knowledge + knowledgebase_search with graceful failure). Report whether knowledgebase_search was executed or skipped in your final summary.
 - Append documentation entries to "docs/tracker-log.md".
 
 Pipeline summary:

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

@@ -72,7 +72,15 @@ You are a read-only research agent. You do NOT write code, edit source files, or
 
 ## Research Process
 
-### 0. Investigation Planning
+### 0a. Check Knowledge
+
+- Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol
+- Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context
+- Skim `.agents/instructions/learned-knowledge.instructions.md` for relevant research patterns and ecosystem findings
+- Call `knowledgebase_knowledgebase_search` with queries relevant to the spike's technology domains, past patterns, and known gotchas
+- State the result in your final summary
+
+### 0b. Investigation Planning
 
 - Create comprehensive todo list using #todos with all known research areas
 - Parse spike document completely using #codebase

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

@@ -25,6 +25,7 @@ You are a code review specialist. You never write code — you read, analyze, an
 
 ## Approach
 
+0. **Check Knowledge**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol. Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context and known issues. Skim `.agents/instructions/learned-knowledge.instructions.md` for review patterns, known bug classes, and security gotchas. Call `knowledgebase_knowledgebase_search` with review-relevant queries (common vulnerability patterns, recurring code-quality issues). State the result in your final summary.
 1. **Understand Scope**: Determine what code needs review (files, diff, or full module).
 2. **Read Thoroughly**: Read all relevant files completely before forming opinions.
 3. **Analyze Systematically**: Check in order: correctness → security → performance → style → test quality.
@@ -38,6 +39,7 @@ You are a code review specialist. You never write code — you read, analyze, an
 - Check for: error handling, input validation, state management, concurrency, type safety
 - Do NOT make any edits or write any code
 - Return structured feedback sorted by severity
+- **Memory-bank hygiene**: In any diff touching `memory-bank/**/*.md`, verify frontmatter tags are known to `memory-bank/.vocabulary.json` (check BOTH `tags.*` groups and `entity_patterns` keys). If unknown tags exist, update the vocabulary file — add to the appropriate `tags.*` group (default: `topic`) and record the rationale in the review report or commit message (strict JSON — no comment syntax; do NOT add comments to the file), or add to `entity_patterns` if the tag is a tool/component name — and flag the change in the review report. Report any unaddressed unknown tags as 🔵 minor findings.
 
 ## Output Expectations
 

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

@@ -22,15 +22,17 @@ 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
+- 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 — BEFORE appending, read the existing file first (see step 1 "Check Knowledge") to review existing sessions and avoid duplicate or contradictory entries
 
 ## Approach
 
-1. **Read Context**: Read the orchestrator log at `docs/.orchestrator-log.md` to understand what steps ran, their status, artifacts, and key findings.
-2. **Read Artifacts**: Read the actual files produced by the sub-agents (referenced in the log).
-3. **Determine Target Path**: From the orchestrator context, determine the `docs/<feature>/<agent>.md` path for this entry.
-4. **Compose Entry**: Create a documentation entry summarizing the step's work.
-5. **Append**: Append the entry to the target path determined in step 3.
+1. **Check Knowledge**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol. Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context. **Critically**: read `.agents/instructions/learned-knowledge.instructions.md` BEFORE appending a new Session entry — review existing sessions for related patterns to avoid duplicate or contradictory entries. Call `knowledgebase_knowledgebase_search` with queries matching the pipeline type and agent roles to surface relevant cross-project patterns, wrapped in graceful failure — on success report "knowledgebase_search executed — N results returned."; on error/unavailability report "knowledgebase_search NOT executed (PG vector unavailable)." and continue (never block or fail). State the result in your final summary.
+   **projectId derivation for `knowledgebase_knowledgebase_index`**: when indexing the Session entry, the `projectId` parameter SHALL be read from `package.json` `name` (`require('./package.json').name` — the canonical scoped name, e.g., `@abarcenas/ai-workflow-template`), NOT from the orchestrator's `projectName` parameter (which may be a short/unscoped display name). The `package.json` `name` field is the single source of truth — deriving projectId from directory names, display strings, or hardcoded short forms creates duplicate KB projects.
+2. **Read Context**: Read the orchestrator log at `docs/.orchestrator-log.md` to understand what steps ran, their status, artifacts, and key findings.
+3. **Read Artifacts**: Read the actual files produced by the sub-agents (referenced in the log).
+4. **Determine Target Path**: From the orchestrator context, determine the `docs/<feature>/<agent>.md` path for this entry.
+5. **Compose Entry**: Create a documentation entry summarizing the step's work.
+6. **Append**: Append the entry to the target path determined in step 4.
 
 ## Documentation Entry Format
 

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

@@ -25,11 +25,12 @@ You are a testing specialist focused on unit and integration tests.
 
 ## Approach
 
-1. **Understand the Code**: Read the implementation files to understand what needs testing.
-2. **Review Existing Tests**: Look at existing test files for patterns and conventions.
-3. **Write Tests**: Create comprehensive tests following project testing conventions.
-4. **Run Tests**: Execute the test suite to verify all tests pass.
-5. **Fix Issues**: Address any test failures or flaky tests.
+1. **Check Knowledge**: Read `.agents/instructions/knowledge-retrieval.instructions.md` and follow the 3-layer knowledge-retrieval protocol. Use `memory_bank_memory_search`/`memory_bank_memory_get` for project context. Skim `.agents/instructions/learned-knowledge.instructions.md` for test patterns, mock conventions, and testing gotchas. Call `knowledgebase_knowledgebase_search` with testing-relevant queries (test patterns, mock strategies, coverage approaches). State the result in your final summary.
+2. **Understand the Code**: Read the implementation files to understand what needs testing.
+3. **Review Existing Tests**: Look at existing test files for patterns and conventions.
+4. **Write Tests**: Create comprehensive tests following project testing conventions.
+5. **Run Tests**: Execute the test suite to verify all tests pass.
+6. **Fix Issues**: Address any test failures or flaky tests.
 
 ## Guidelines