@abarcenas/ai-workflow-template 1.25.0 → 1.28.0

package/.agents/instructions/ai-prompt-engineering-safety.instructions.md

@@ -1,17 +1,17 @@
 ---
 applyTo: ["*"]
-description: "Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for Copilot and LLMs."
+description: "Comprehensive best practices for AI prompt engineering, safety frameworks, bias mitigation, and responsible AI usage for opencode and LLMs."
 ---
 
 # AI Prompt Engineering & Safety Best Practices
 
 ## Your Mission
 
-As GitHub Copilot, you must understand and apply the principles of effective prompt engineering, AI safety, and responsible AI usage. Your goal is to help developers create prompts that are clear, safe, unbiased, and effective while following industry best practices and ethical guidelines. When generating or reviewing prompts, always consider safety, bias, security, and responsible AI usage alongside functionality.
+As an AI assistant, you must understand and apply the principles of effective prompt engineering, AI safety, and responsible AI usage. Your goal is to help developers create prompts that are clear, safe, unbiased, and effective while following industry best practices and ethical guidelines. When generating or reviewing prompts, always consider safety, bias, security, and responsible AI usage alongside functionality.
 
 ## Introduction
 
-Prompt engineering is the art and science of designing effective prompts for large language models (LLMs) and AI assistants like GitHub Copilot. Well-crafted prompts yield more accurate, safe, and useful outputs. This guide covers foundational principles, safety, bias mitigation, security, responsible AI usage, and practical templates/checklists for prompt engineering.
+Prompt engineering is the art and science of designing effective prompts for large language models (LLMs) and AI assistants like opencode. Well-crafted prompts yield more accurate, safe, and useful outputs. This guide covers foundational principles, safety, bias mitigation, security, responsible AI usage, and practical templates/checklists for prompt engineering.
 
 ### What is Prompt Engineering?
 

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

@@ -1,18 +1,18 @@
 ---
-description: "Guidelines for creating high-quality custom instruction files for GitHub Copilot"
+description: "Guidelines for creating high-quality custom instruction files for opencode"
 applyTo: "**/*.instructions.md"
 ---
 
 # Custom Instructions File Guidelines
 
-Instructions for creating effective and maintainable custom instruction files that guide GitHub Copilot in generating domain-specific code and following project conventions.
+Instructions for creating effective and maintainable custom instruction files that guide opencode in generating domain-specific code and following project conventions.
 
 ## Project Context
 
-- Target audience: Developers and GitHub Copilot working with domain-specific code
+- Target audience: Developers and AI assistants working with domain-specific code
 - File format: Markdown with YAML frontmatter
 - File naming convention: lowercase with hyphens (e.g., `react-best-practices.instructions.md`)
-- Location: `.github/instructions/` directory
+- Location: `.agents/instructions/` directory
 - Purpose: Provide context-aware guidance for code generation, review, and documentation
 
 ## Required Frontmatter
@@ -189,7 +189,7 @@ function getUser(id: any): any {
 
 Before finalizing instruction files:
 
-1. **Test with Copilot**: Try the instructions with actual prompts in VS Code
+1. **Test with opencode**: Try the instructions with actual tasks
 2. **Verify Examples**: Ensure code examples are correct and run without errors
 3. **Check Glob Patterns**: Confirm `applyTo` patterns match intended files
 
@@ -260,5 +260,4 @@ Description and example
 
 ## Additional Resources
 
-- [Custom Instructions Documentation](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)
-- [Awesome Copilot Instructions](https://github.com/github/awesome-copilot/tree/main/instructions)
+- [opencode Documentation](https://opencode.ai)

package/.agents/instructions/memory-bank.instructions.md

@@ -6,7 +6,7 @@ Coding standards, domain knowledge, and preferences that AI should follow.
 
 # Memory Bank
 
-You are an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I MUST read ALL memory bank files at the start of EVERY task - this is not optional.
+You are an expert software engineer with a unique characteristic: my memory resets completely between sessions. This isn't a limitation - it's what drives me to maintain perfect documentation. After each reset, I rely ENTIRELY on my Memory Bank to understand the project and continue work effectively. I use the vector search index (`memory_search`) to retrieve relevant context efficiently, and fall back to reading specific files (`memory_get`) when I need complete, un-summarized content.
 
 ## Memory Bank Structure
 
@@ -94,6 +94,42 @@ Create additional files/folders within memory-bank/ when they help organize:
 - Testing strategies
 - Deployment procedures
 
+### Vector Search Index (sqlite-vec)
+
+The memory bank includes a **semantic vector search index** powered by `sqlite-vec` + `better-sqlite3`. This allows token-efficient retrieval without loading all files into context.
+
+**Index location:** `memory-bank/.index/memory.db` (git-ignored, rebuildable)
+
+**MCP tools** (configured in `opencode.json`):
+- `memory_search` — Semantic search across all memory-bank and docs files
+- `memory_update` — **Daily use** — incremental sync (only changed files, ~2 seconds)
+- `memory_rebuild` — Full rebuild (corrupted index, model change, or fresh clone)
+- `memory_get` — Read a specific memory file by name
+- `memory_stats` — Check index status
+
+**When to use semantic search instead of reading all files:**
+- Session start → `memory_update` then `memory_search({ query: "current focus recent changes next steps" })` (~500 tokens vs ~5K+)
+- Before decisions → `memory_search({ query: "<topic>", topK: 5 })` for related context
+- Architecture questions → `memory_search({ query: "<pattern>", sourceFile: "systemPatterns" })"
+
+**When to still use full file reads:**
+- Need complete, un-summarized file content → `memory_get({ file: "<id>" })`
+- Index is empty or stale → `memory_rebuild()` then re-search
+
+**Sync triggers:**
+- After writing documentation → `memory_update` (incremental, fast)
+- Session start → `memory_update` first, then `memory_search`
+- After `git pull` → `memory_update` (or post-merge hook if configured)
+- Full `memory_rebuild` only for: fresh clone, corrupted index, embedding model change, or if incremental update missed changes
+
+### Document Schema (Frontmatter)
+
+All `memory-bank/**/*.md` files must have YAML frontmatter for search indexing. See `.agents/instructions/memory-schema.instructions.md` for the full schema and `memory-bank/.vocabulary.json` for the controlled vocabulary.
+
+**Required fields:** `id`, `title`, `updated`, `tags`, `entities`, `category`
+
+**Pre-commit validation:** The husky hook validates frontmatter before commits. Running `npm run memory:normalize` auto-fixes missing frontmatter.
+
 ## Core Workflows
 
 ### Plan Mode
@@ -102,9 +138,20 @@ Create additional files/folders within memory-bank/ when they help organize:
 flowchart TD
     Start[Start] --> CheckGraph{graphify-out/graph.json exists?}
     CheckGraph -->|No| Bootstrap[Run graphify .]
-    Bootstrap --> ReadFiles[Read Memory Bank]
-    CheckGraph -->|Yes| ReadFiles
-    ReadFiles --> QueryGraph[Query graphify for architecture context]
+    Bootstrap --> CheckIndex{memory index exists?}
+    CheckGraph -->|Yes| CheckIndex
+
+    CheckIndex -->|No| Rebuild[memory_rebuild]
+    CheckIndex -->|Yes| UpdateIndex[memory_update]
+    
+    Rebuild --> Search
+    UpdateIndex --> Search
+    Search --> GetContext{context sufficient?}
+    
+    GetContext -->|No| GetFile[memory_get: specific file]
+    GetFile --> GetContext
+    
+    GetContext -->|Yes| QueryGraph[Query graphify for architecture context]
     QueryGraph --> CheckFiles{Files Complete?}
 
     CheckFiles -->|No| Plan[Create Plan]
@@ -119,11 +166,15 @@ flowchart TD
 
 ```mermaid
 flowchart TD
-    Start[Start] --> Context[Check Memory Bank]
-    Context --> Update[Update Documentation]
-    Update --> Rules[Update instructions if needed]
-    Rules --> Execute[Execute Task]
-    Execute --> Document[Document Changes]
+    Start[Start] --> Context[memory_search: current task context]
+    Context --> Verify[Verify Understanding]
+    Verify --> ReadFiles{need full files?}
+    ReadFiles -->|Yes| GetFull[memory_get: specific files]
+    ReadFiles -->|No| Execute[Execute Task]
+    GetFull --> Execute
+    Execute --> Update[Update Documentation]
+    Update --> UpdateIndex[memory_update]
+    UpdateIndex --> Done[Done]
 ```
 
 ### Task Management
@@ -138,7 +189,8 @@ flowchart TD
     Execute[Execute Task] --> Update[Add Progress Log Entry]
     Update --> StatusChange[Update Task Status]
     StatusChange --> IndexUpdate[Update _index.md]
-    IndexUpdate --> Complete{Completed?}
+    IndexUpdate --> UpdateIndex[memory_update]
+    UpdateIndex --> Complete{Completed?}
     Complete -->|Yes| Archive[Mark as Completed]
     Complete -->|No| Execute
 ```
@@ -198,7 +250,7 @@ Memory Bank updates occur when:
 
 1. Discovering new project patterns
 2. After implementing significant changes
-3. When user requests with **update memory bank** (MUST review ALL files)
+3. When user requests with **update memory bank** (validate via `memory_get` for specific files)
 4. When context needs clarification
 5. After code changes that introduce new relationships — run `graphify update .` to sync the graph
 
@@ -207,18 +259,20 @@ flowchart TD
     Start[Update Process]
 
     subgraph Process
-        P1[Review ALL Files]
-        P2[Document Current State]
-        P3[Clarify Next Steps]
-        P4[Update instructions]
-
-        P1 --> P2 --> P3 --> P4
+        P1[memory_search: all sections]
+        P2[memory_get: files needing updates]
+        P3[Document Current State]
+        P4[Clarify Next Steps]
+        P5[Update instructions]
+        P6[memory_update]
+
+        P1 --> P2 --> P3 --> P4 --> P5 --> P6
     end
 
     Start --> Process
 ```
 
-Note: When triggered by **update memory bank**, I MUST review every memory bank file, even if some don't require updates. Focus particularly on activeContext.md, progress.md, and the tasks/ folder (including \_index.md) as they track current state.
+Note: When triggered by **update memory bank**, first search for changes since last update via `memory_search`, then read specific files via `memory_get`. Focus particularly on activeContext.md, progress.md, and the tasks/ folder (including \_index.md) as they track current state. After making changes, run `memory_rebuild` to sync the index.
 
 ## Project Intelligence (instructions)
 

package/.agents/instructions/memory-schema.instructions.md

@@ -0,0 +1,75 @@
+---
+description: "Valid frontmatter schema and controlled vocabulary for memory-bank and docs files"
+name: "memory-schema"
+---
+
+# Memory Schema
+
+When writing or updating files in `memory-bank/` or `docs/`, apply the following frontmatter schema. The controlled vocabulary lives in `memory-bank/.vocabulary.json` — extend it there as new concepts enter the project.
+
+## Required Frontmatter (memory-bank/)
+
+Every `memory-bank/**/*.md` file must have:
+
+```yaml
+---
+id: <filename-slug>       # e.g., "activeContext" from "activeContext.md"
+title: "<H1 heading>"     # e.g., "Active Context"
+updated: YYYY-MM-DD       # ISO date of last content change
+tags: [<1-5 tags>]        # From controlled vocabulary in .vocabulary.json
+entities: [<0-n entries>] # Components/tools referenced; free-form but use entity_patterns as guide
+category: <from list>     # One of: brief, product, architecture, tech, context, progress, task, decision
+---
+```
+
+### Field Rules
+
+- **id**: Stable slug matching the filename (lowercase, no extension). Never change after creation.
+- **title**: Must match the `# H1` heading in the file body.
+- **updated**: Update on every content change. Use `YYYY-MM-DD` format.
+- **tags**: Pick 1–5 from `memory-bank/.vocabulary.json` → `tags.*`. New tags added by editing that file.
+- **entities**: Free-form list of components, tools, or systems referenced in the file. Use the `entity_patterns` from `.vocabulary.json` as a suggestion guide.
+- **category**: Exactly one from the `categories` map in `.vocabulary.json`.
+
+### Heading Structure
+
+Every memory-bank file must have:
+- Exactly one `# Title` (H1) — matches frontmatter `title`
+- Content organized under `## Sections` (H2)
+- No flat text outside sections
+- Each `## Section` is a searchable chunk
+
+## Lighter Schema (docs/)
+
+`docs/*.md` files use a lighter schema:
+
+```yaml
+---
+id: <filename-slug>
+title: "<H1 heading>"
+updated: YYYY-MM-DD
+tags: [<1-5 tags>]
+doc_type: <from list>     # spike, architecture, configuration, orchestrator-log, tracker-log, decision
+---
+```
+
+Docs files do not require `category`, `entities`, or strict heading structure. Hidden files (`.architecture-context.md`, `.orchestrator-log.md`) keep their leading dot.
+
+## Auto-Suggest on Normalization
+
+When `scripts/normalize-memory.js` runs (postinstall or manual), it:
+- Adds missing frontmatter using filename, H1 title, and git modification date
+- Auto-suggests `tags` by scanning content for vocabulary keywords
+- Auto-suggests `entities` using regex patterns from `.vocabulary.json`
+- Does NOT overwrite existing frontmatter fields
+- Logs all auto-applied suggestions
+
+## Pre-Commit Validation
+
+The husky pre-commit hook (`scripts/validate-memory-schema.js`) rejects commits where:
+- Staged memory-bank files have missing or invalid frontmatter
+- `updated` field is missing or not ISO date format
+- `category` is not in the allowed list
+- `id` does not match the filename
+
+The hook reads `.vocabulary.json` at validation time, so new tags/categories are picked up automatically.

package/.agents/instructions/prompt.instructions.md

@@ -1,17 +1,17 @@
 ---
-description: "Guidelines for creating high-quality prompt files for GitHub Copilot"
+description: "Guidelines for creating high-quality prompt files for opencode"
 applyTo: "**/*.prompt.md"
 ---
 
-# Copilot Prompt Files Guidelines
+# opencode Prompt Files Guidelines
 
-Instructions for creating effective and maintainable prompt files that guide GitHub Copilot in delivering consistent, high-quality outcomes across any repository.
+Instructions for creating effective and maintainable prompt files that guide the AI assistant in delivering consistent, high-quality outcomes across any repository.
 
 ## Scope and Principles
 
-- Target audience: maintainers and contributors authoring reusable prompts for Copilot Chat.
+- Target audience: maintainers and contributors authoring reusable prompts for opencode.
 - Goals: predictable behaviour, clear expectations, minimal permissions, and portability across repositories.
-- Primary references: VS Code documentation on prompt files and organization-specific conventions.
+- Primary references: opencode documentation on prompt files and organization-specific conventions.
 
 ## Frontmatter Requirements
 
@@ -19,55 +19,52 @@ Every prompt file should include YAML frontmatter with the following fields:
 
 ### Required/Recommended Fields
 
-| Field           | Required    | Description                                                                                 |
-| --------------- | ----------- | ------------------------------------------------------------------------------------------- |
-| `description`   | Recommended | A short description of the prompt (single sentence, actionable outcome)                     |
-| `name`          | Optional    | The name shown after typing `/` in chat. Defaults to filename if not specified              |
-| `agent`         | Recommended | The agent to use: `ask`, `edit`, `agent`, or a custom agent name. Defaults to current agent |
-| `model`         | Optional    | The language model to use. Defaults to the currently selected model                         |
-| `tools`         | Optional    | List of tool/tool set names available for this prompt                                       |
-| `argument-hint` | Optional    | Hint text shown in chat input to guide user interaction                                     |
+| Field         | Required    | Description                                                                             |
+| ------------- | ----------- | --------------------------------------------------------------------------------------- |
+| `description` | Recommended | A short description of the prompt (single sentence, actionable outcome)                 |
+| `name`        | Optional    | The name shown when invoking the prompt. Defaults to filename if not specified          |
 
 ### Guidelines
 
 - Use consistent quoting (single quotes recommended) and keep one field per line for readability and version control clarity
-- If `tools` are specified and the current agent is `ask` or `edit`, the default agent becomes `agent`
 - Preserve any additional metadata (`language`, `tags`, `visibility`, etc.) required by your organization
+- opencode prompts have a simpler frontmatter model than other platforms; avoid adding tool, model, or agent fields that are not supported
 
 ## File Naming and Placement
 
-- Use kebab-case filenames ending with `.prompt.md` and store them under `.github/prompts/` unless your workspace standard specifies another directory.
+- Use kebab-case filenames ending with `.prompt.md` and store them under `.agents/prompts/` unless your workspace standard specifies another directory.
 - Provide a short filename that communicates the action (for example, `generate-readme.prompt.md` rather than `prompt1.prompt.md`).
 
 ## Body Structure
 
-- Start with an `#` level heading that matches the prompt intent so it surfaces well in Quick Pick search.
+- Start with an `#` level heading that matches the prompt intent so it surfaces well in search.
 - Organize content with predictable sections. Recommended baseline: `Mission` or `Primary Directive`, `Scope & Preconditions`, `Inputs`, `Workflow` (step-by-step), `Output Expectations`, and `Quality Assurance`.
 - Adjust section names to fit the domain, but retain the logical flow: why → context → inputs → actions → outputs → validation.
 - Reference related prompts or instruction files using relative links to aid discoverability.
 
 ## Input and Context Handling
 
-- Use `${input:variableName[:placeholder]}` for required values and explain when the user must supply them. Provide defaults or alternatives where possible.
-- Call out contextual variables such as `${selection}`, `${file}`, `${workspaceFolder}` only when they are essential, and describe how Copilot should interpret them.
-- Document how to proceed when mandatory context is missing (for example, “Request the file path and stop if it remains undefined”).
+- Describe required inputs clearly in prose (for example, "The user must supply a file path to the target component"). When optional, specify defaults or how the prompt should infer the value.
+- Reference file paths and workspace context explicitly rather than relying on implicit contextual variables. If the prompt needs a specific file, state the expected path or pattern (for example, "Look for `src/config/*.ts` and use the first match").
+- Document how to proceed when mandatory context is missing (for example, "Request the file path and stop if it remains undefined").
 
 ## Tool and Permission Guidance
 
-- Limit `tools` to the smallest set that enables the task. List them in the preferred execution order when the sequence matters.
-- If the prompt inherits tools from a chat mode, mention that relationship and state any critical tool behaviours or side effects.
+- opencode provides the following tools: `Bash`, `Read`, `Write`, `Edit`, `Grep`, `Glob`, `Task`, `TodoWrite`, `Skill`, `WebFetch`, `WebSearch`, among others. Limit tool usage to the smallest set that enables the task.
+- If the prompt expects the assistant to run shell commands, explicitly name `Bash` as a required tool. For file inspection, prefer `Read` and `Grep` over shell-based alternatives.
 - Warn about destructive operations (file creation, edits, terminal commands) and include guard rails or confirmation steps in the workflow.
+- When the prompt depends on a specific skill, reference it by name so the assistant can load it via the `Skill` tool.
 
 ## Instruction Tone and Style
 
-- Write in direct, imperative sentences targeted at Copilot (for example, “Analyze”, “Generate”, “Summarize”).
+- Write in direct, imperative sentences targeted at the AI assistant (for example, "Analyze", "Generate", "Summarize").
 - Keep sentences short and unambiguous, following Google Developer Documentation translation best practices to support localization.
 - Avoid idioms, humor, or culturally specific references; favor neutral, inclusive language.
 
 ## Output Definition
 
-- Specify the format, structure, and location of expected results (for example, “Create `docs/adr/adr-XXXX.md` using the template below”).
-- Include success criteria and failure triggers so Copilot knows when to halt or retry.
+- Specify the format, structure, and location of expected results (for example, "Create `docs/adr/adr-XXXX.md` using the template below").
+- Include success criteria and failure triggers so the assistant knows when to halt or retry.
 - Provide validation steps—manual checks, automated commands, or acceptance criteria lists—that reviewers can execute after running the prompt.
 
 ## Examples and Reusable Assets
@@ -79,21 +76,19 @@ Every prompt file should include YAML frontmatter with the following fields:
 ## Quality Assurance Checklist
 
 - [ ] Frontmatter fields are complete, accurate, and least-privilege.
-- [ ] Inputs include placeholders, default behaviours, and fallbacks.
+- [ ] Inputs include default behaviours and fallbacks for missing context.
 - [ ] Workflow covers preparation, execution, and post-processing without gaps.
 - [ ] Output expectations include formatting and storage details.
 - [ ] Validation steps are actionable (commands, diff checks, review prompts).
 - [ ] Security, compliance, and privacy policies referenced by the prompt are current.
-- [ ] Prompt executes successfully in VS Code (`Chat: Run Prompt`) using representative scenarios.
+- [ ] Prompt executes successfully in opencode using representative scenarios.
 
 ## Maintenance Guidance
 
 - Version-control prompts alongside the code they affect; update them when dependencies, tooling, or review processes change.
-- Review prompts periodically to ensure tool lists, model requirements, and linked documents remain valid.
+- Review prompts periodically to ensure tool references, linked documents, and workspace conventions remain valid.
 - Coordinate with other repositories: when a prompt proves broadly useful, extract common guidance into instruction files or shared prompt packs.
 
 ## Additional Resources
 
-- [Prompt Files Documentation](https://code.visualstudio.com/docs/copilot/customization/prompt-files#_prompt-file-format)
-- [Awesome Copilot Prompt Files](https://github.com/github/awesome-copilot/tree/main/prompts)
-- [Tool Configuration](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode#_agent-mode-tools)
+- [opencode Documentation](https://opencode.ai)

package/.agents/skills/conventional-commit/SKILL.md

@@ -17,13 +17,13 @@ description: "Prompt and workflow for generating conventional commit messages us
 2. Run `git diff` or `git diff --cached` to inspect changes.
 3. Stage your changes with `git add <file>`.
 4. Construct your commit message using the following XML structure.
-5. After generating your commit message, Copilot will automatically run the following command in your integrated terminal (no confirmation needed):
+5. Run the following command in your terminal:
 
 ```bash
 git commit -m "type(scope): description"
 ```
 
-6. Just execute this prompt and Copilot will handle the commit for you in the terminal.
+6. Run the commit command in your terminal.
 
 ### Commit Message Structure
 

package/.agents/skills/github-issues/SKILL.md

@@ -87,7 +87,7 @@ State values: `open`, `closed`
 ```json
 {
   "owner": "github",
-  "repo": "awesome-copilot",
+  "repo": "example-project",
   "title": "[Bug] Login page crashes when using SSO",
   "body": "## Description\nThe login page crashes when users attempt to authenticate using SSO.\n\n## Steps to Reproduce\n1. Navigate to login page\n2. Click 'Sign in with SSO'\n3. Page crashes\n\n## Expected Behavior\nSSO authentication should complete and redirect to dashboard.\n\n## Actual Behavior\nPage becomes unresponsive and displays error.\n\n## Environment\n- Browser: [To be filled]\n- OS: [To be filled]\n\n## Additional Context\nReported by user.",
   "labels": ["bug"]
@@ -103,7 +103,7 @@ State values: `open`, `closed`
 ```json
 {
   "owner": "github",
-  "repo": "awesome-copilot",
+  "repo": "example-project",
   "title": "[Feature] Add dark mode support",
   "body": "## Summary\nAdd dark mode theme option for improved user experience and accessibility.\n\n## Motivation\n- Reduces eye strain in low-light environments\n- Increasingly expected by users\n- Improves accessibility\n\n## Proposed Solution\nImplement theme toggle with system preference detection.\n\n## Acceptance Criteria\n- [ ] Toggle switch in settings\n- [ ] Persists user preference\n- [ ] Respects system preference by default\n- [ ] All UI components support both themes\n\n## Alternatives Considered\nNone specified.\n\n## Additional Context\nHigh priority request.",
   "labels": ["enhancement", "high-priority"]

package/.agents/skills/memory-search/SKILL.md

@@ -0,0 +1,69 @@
+---
+description: "Search project memory bank using semantic vector search"
+name: "memory-search"
+---
+
+# Memory Search Skill
+
+Use this skill to retrieve project context from the memory bank without loading all files into context.
+
+## When to Use
+
+- At the start of a session: search for current project focus and recent changes
+- Before making a decision: search for related past decisions
+- When stuck: search for architectural patterns or known issues
+- After writing to memory-bank: run `memory_rebuild` to update the index
+
+## Available MCP Tools
+
+This skill uses the `memory-bank` MCP server, configured in `opencode.json`:
+
+| Tool | Purpose |
+|---|---|
+| `memory_search` | Semantic search across all memory-bank and docs files |
+| `memory_update` | Incremental sync — only changed files (~2 seconds). Use daily. |
+| `memory_rebuild` | Full rebuild (rare — fresh clone, corrupted index) |
+| `memory_get` | Read a specific memory file by name |
+| `memory_stats` | Get index statistics (vector count, file count, DB size) |
+
+## Workflow
+
+### Session Start
+
+1. Run `memory_stats` to check if the index is populated
+2. If empty, run `memory_rebuild`; otherwise, run `memory_update`
+3. Search for current context: `memory_search({ query: "current focus recent changes next steps" })`
+
+### During Tasks
+
+- Before implementing: `memory_search({ query: "<topic>", topK: 5 })` for related decisions
+- When writing to memory-bank: update files, then run `memory_update`
+- For full file content: `memory_get({ file: "activeContext" })`
+
+### After Git Pull
+
+The `post-merge` hook runs `memory:update` automatically if memory-bank files changed.
+
+### Search Tips
+
+- **Be specific**: "TDD orchestrator bootstrap prerequisites" gets better results than "project"
+- **Use contextual terms**: Include entity names (vitest, playwright, graphify) from the vocabulary
+- **Filter by file**: `memory_search({ query: "...", sourceFile: "systemPatterns" })` to narrow scope
+- **Top-K tuning**: Use `topK: 3` for focused queries, `topK: 10` for broad exploration
+
+## Vocabulary Reference
+
+See `memory-bank/.vocabulary.json` for the full controlled vocabulary. Key tags:
+
+- **Agent roles**: orchestrator, coder, reviewer, tracker, architect, researcher
+- **Workflow**: tdd, feature-pipeline, bootstrap, configuration, refactor, migration
+- **Memory ops**: decision, discovery, status-update, task-plan, retrospective
+- **Technologies**: typescript, vitest, playwright, graphify, mcp, sqlite-vec
+
+## Manual CLI (for debugging)
+
+```bash
+node scripts/memory-cli.js search "tdd orchestrator"
+node scripts/memory-cli.js rebuild
+node scripts/memory-cli.js stats
+```

package/.agents/skills/microsoft-docs/SKILL.md

@@ -64,7 +64,7 @@ GitHub docs live on **docs.github.com** and **cli.github.com**.
 
 | Library ID             | Use for                                       |
 | ---------------------- | --------------------------------------------- |
-| `/websites/github_en`  | Actions, API, repos, security, admin, Copilot |
+| `/websites/github_en`  | Actions, API, repos, security, admin |
 | `/websites/cli_github` | GitHub CLI (`gh`) commands and flags          |
 
 ### Agent Framework — Use Learn MCP + Context7

package/.agents/skills/polygot-test-agent/SKILL.md

@@ -154,7 +154,6 @@ Add tests for the authentication module with focus on edge cases
 
 - Project must have a build/test system configured
 - Testing framework should be installed (or installable)
-- VS Code with GitHub Copilot extension
 
 ## Troubleshooting
 

package/.agents/skills/prompt-builder/SKILL.md

@@ -1,14 +1,14 @@
 ---
 name: prompt-builder
-description: "Guide users through creating high-quality GitHub Copilot prompts with proper structure, tools, and best practices."
+description: "Guide users through creating high-quality opencode prompts with proper structure, tools, and best practices."
 ---
 
 # Professional Prompt Builder
 
-You are an expert prompt engineer specializing in GitHub Copilot prompt development with deep knowledge of:
+You are an expert prompt engineer specializing in opencode prompt development with deep knowledge of:
 
 - Prompt engineering best practices and patterns
-- VS Code Copilot customization capabilities
+- opencode customization capabilities
 - Effective persona design and task specification
 - Tool integration and front matter configuration
 - Output format optimization for AI consumption
@@ -27,7 +27,7 @@ I will ask you targeted questions to gather all necessary information. After col
 
 ### 2. **Persona Definition**
 
-- What role/expertise should Copilot embody? Be specific about:
+- What role/expertise should the AI assistant embody? Be specific about:
   - Technical expertise level (junior, senior, expert, specialist)
   - Domain knowledge (languages, frameworks, tools)
   - Years of experience or specific qualifications
@@ -42,15 +42,15 @@ I will ask you targeted questions to gather all necessary information. After col
 
 ### 4. **Context & Variable Requirements**
 
-- Will it use `${selection}` (user's selected code)?
-- Will it use `${file}` (current file) or other file references?
-- Does it need input variables like `${input:variableName}` or `${input:variableName:placeholder}`?
-- Will it reference workspace variables (`${workspaceFolder}`, etc.)?
+- Will it use selected text from the editor?
+- Will it use the current file path or other file references?
+- Does it need custom input parameters or variable references?
+- Will it reference the workspace root path or other project-level variables?
 - Does it need to access other files or prompt files as dependencies?
 
 ### 5. **Detailed Instructions & Standards**
 
-- What step-by-step process should Copilot follow?
+- What step-by-step process should the AI follow?
 - Are there specific coding standards, frameworks, or libraries to use?
 - What patterns or best practices should be enforced?
 - Are there things to avoid or constraints to respect?
@@ -68,11 +68,10 @@ I will ask you targeted questions to gather all necessary information. After col
 
 Which tools does this prompt need? Common options include:
 
-- **File Operations**: `codebase`, `editFiles`, `search`, `problems`
-- **Execution**: `runCommands`, `runTasks`, `runTests`, `terminalLastCommand`
-- **External**: `fetch`, `githubRepo`, `openSimpleBrowser`
-- **Specialized**: `playwright`, `usages`, `vscodeAPI`, `extensions`
-- **Analysis**: `changes`, `findTestFiles`, `testFailure`, `searchResults`
+- **File Operations**: `Read`, `Write`, `Edit`, `Grep`, `Glob`
+- **Execution**: `Bash`
+- **External**: `WebFetch`, `WebSearch`
+- **Specialized**: `playwright` (Playwright MCP)
 
 ### 8. **Technical Configuration**
 
@@ -111,9 +110,11 @@ After gathering all requirements, I will generate a complete `.prompt.md` file f
 ```markdown
 ---
 description: "[Clear, concise description from requirements]"
+name: "[prompt-name]"
 agent: "[agent|ask|edit based on task type]"
 tools: ["[appropriate tools based on functionality]"]
 model: "[only if specific model required]"
+argument-hint: "[hint text shown in chat input]"
 ---
 
 # [Prompt Title]

package/.husky/post-merge

@@ -0,0 +1,10 @@
+#!/bin/sh
+. "$(dirname "$0")/_/husky.sh"
+
+# After git pull/merge, check if memory-bank files changed
+# and update the vector index incrementally
+
+if git diff HEAD@{1} --name-only 2>/dev/null | grep -q "^memory-bank\|^docs/"; then
+  echo "[memory-bank] Memory bank files changed. Updating vector index..."
+  node scripts/memory-cli.js update 2>/dev/null || echo "[memory-bank] Index update skipped (service not installed)"
+fi

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+node scripts/bump-version.js
+node scripts/validate-memory-schema.js

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

@@ -5,6 +5,7 @@ permission:
   read: allow
   search: allow
   edit: allow
+  "memory-bank/*": allow
 model: deepseek/deepseek-v4-pro
 ---
 
@@ -24,7 +25,7 @@ You are a system architecture specialist focused on designing robust, maintainab
 
 1. **Understand Requirements**: Parse the feature or system requirements from context.
 2. **Explore Existing Architecture**: Read relevant parts of the codebase to understand current patterns.
-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` with architectural decisions made.
+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` with architectural decisions made, then run `memory_bank_memory_update`.
 4. **Design the Solution**: Define components, their responsibilities, and how they interact.
 5. **Document**: Produce architecture documentation covering decisions, rationale, and alternatives.