@abarcenas/ai-workflow-template 1.23.0 → 1.26.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/learned-knowledge.instructions.md

@@ -1,46 +1,22 @@
----
-applyTo: "**"
-description: "Persistent project knowledge accumulated across sessions. This file grows over time as agents discover patterns, conventions, gotchas, and preferences during work. It enables self-improvement — each session learns from the last."
----
+# Learned Knowledge
 
-# Learned Project Knowledge
+> Accumulated patterns, conventions, gotchas, and agent tuning notes from TDD and other pipeline sessions.
 
-This file is the project's cumulative memory. It is read at the start of every session and updated at the end of every orchestrated pipeline.
+## Session: 2026-06-13
 
-## How to Use
+**Pipeline:** TDD Infrastructure Bootstrap
+**Coverage:** N/A (infrastructure setup)
+**TDD Iterations:** 0
 
-- **Read this file** at the beginning of every task to apply previously discovered patterns and conventions.
-- **Append new entries** when you discover something that would help future sessions (patterns, gotchas, preferences).
-- **Never overwrite** — only append. This is a living log.
+**New knowledge:**
+- Project is a template distribution package (npm), not a deployable application
+- Source code is in `scripts/` (ES modules), not a traditional `src/` directory
+- E2E tests use Playwright with `tests/` directory, `.spec.ts` extension
+- Unit tests use Vitest with `scripts/` directory, `.test.{js,ts}` extension
+- Playwright config uses `chromium` as default, `fullyParallel: true`
+- Coverage threshold is 90% across all metrics (statements, branches, functions, lines)
 
----
-
-## Project Overview
-
-<!-- High-level project description filled in over time -->
-
-## Conventions & Patterns
-
-<!-- Coding conventions, architectural patterns, naming conventions discovered in this project -->
-
-## Gotchas & Deviations
-
-<!-- Unexpected behaviors, tricky configs, known pitfalls -->
-
-## Preferences
-
-<!-- User preferences about tooling, style, approach, etc. -->
-
-## Architecture Decisions
-
-<!-- Key technical decisions and their rationale -->
-
-## Agent Tuning Notes
-
-<!-- Per-agent prompt improvements discovered during sessions -->
-
----
-
-## Session Log
-
-<!-- New entries are appended here by the orchestrator after each pipeline -->
+**Agent tuning notes:**
+- unit-tester: Must be told to look in `scripts/` for source and test files, not `src/`
+- coder: Must be told the project uses ES module syntax (import/export, not require/module.exports)
+- implementer: Plans should target `scripts/` for production code and tests

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
 
@@ -70,6 +70,20 @@ flowchart TD
    - Includes task index file (`_index.md`) listing all tasks with their statuses
    - Preserves complete thought process and history for each task
 
+### Graph-Enhanced Context (graphify)
+
+When `graphify-out/graph.json` exists, it serves as a complementary machine-readable index of all file relationships, dependencies, and architectural patterns. The memory bank's markdown files capture human-written project context; graphify captures automatically extracted code-level connections.
+
+**Bootstrap:** If `graphify-out/graph.json` does not exist, run `graphify .` to generate the knowledge graph before reading any memory bank files. This ensures code-level relationship data is available alongside the markdown context.
+
+**When to query the graph instead of reading files:**
+- Architecture and dependency questions → `graphify query` (subgraph results, ~200-800 tokens)
+- Component interaction tracing → `graphify path "<A>" "<B>"`
+- Focused concept deep-dives → `graphify explain "<concept>"`
+- Community/pattern overview → `graphify-out/GRAPH_REPORT.md`
+
+**Keeping the graph current:** After any code modification, run `graphify update .` (AST-only, zero API cost) to sync the graph.
+
 ### Additional Context
 
 Create additional files/folders within memory-bank/ when they help organize:
@@ -80,14 +94,65 @@ 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
 
 ```mermaid
 flowchart TD
-    Start[Start] --> ReadFiles[Read Memory Bank]
-    ReadFiles --> CheckFiles{Files Complete?}
+    Start[Start] --> CheckGraph{graphify-out/graph.json exists?}
+    CheckGraph -->|No| Bootstrap[Run graphify .]
+    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]
     Plan --> Document[Document in Chat]
@@ -101,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
@@ -120,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
 ```
@@ -139,32 +209,70 @@ For every task:
 
 The Markdown record is the source of truth for auditing, traceability, and recovery after session resets.
 
+## Graphify-Enhanced Context Retrieval
+
+When `graphify-out/graph.json` exists, prefer graphify over grep/glob for codebase questions:
+
+| Question Type | Graphify Command | Replaces |
+|---|---|---|
+| How does X work? | `graphify explain "X"` | Grep for definitions, reading multiple files |
+| What calls Y? | `graphify query "calls Y depends-on Y invokes Y"` | Recursive grep for callers across files |
+| How does A connect to B? | `graphify path "A" "B"` | Manual dependency tracing across files |
+| Architecture overview | `graphify query "architecture layers patterns dependencies"` | GRAPH_REPORT.md / file-by-file analysis |
+| Community structure | `graphify-out/GRAPH_REPORT.md` `## Communities` | Manual folder hierarchy analysis |
+| Key abstractions | `graphify query "interface abstract class base pattern"` | Grep for interface/abstract class definitions |
+
+**Token efficiency:** graphify queries return focused subgraphs (~200-800 tokens) vs. raw grep results (often 3000+ tokens for large codebases). Always query the graph first; fall back to grep only when graphify lacks sufficient data or `graphify-out/graph.json` is missing.
+
+**Expanding queries:** When a graphify query returns 0 hits, expand the question against the graph's vocabulary before falling back to grep. Run:
+```
+$(cat graphify-out/.graphify_python) -c "
+import json, re
+from pathlib import Path
+data = json.loads(Path('graphify-out/graph.json').read_text())
+vocab = set()
+for n in data['nodes']:
+    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
+        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
+        for p in parts:
+            t = p.lower()
+            if 3 <= len(t) <= 30:
+                vocab.add(t)
+Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)))
+print(f'vocab: {len(vocab)} tokens')
+"
+```
+Then select up to 12 tokens from the vocabulary list that semantically match the query intent, and re-run with the expanded query.
+
 ## Documentation Updates
 
 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
 
 ```mermaid
 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/instructions/task-implementation.instructions.md

@@ -22,12 +22,16 @@ All planning, implementation, and execution work must be recorded in Markdown fi
 
 **MUST complete before starting implementation:**
 
+0. **Verify graphify graph:** Check `graphify-out/graph.json` exists. If not, run `graphify .` to generate it. The graph provides code-level relationship data (dependencies, callers, patterns) that the memory bank's markdown docs alone cannot capture. Skip this step only if the task exclusively modifies markdown/docs files.
 1. Read `memory-bank/activeContext.md` to understand current focus and recent changes
 2. Read `memory-bank/progress.md` to understand project-wide status
 3. Read `memory-bank/tasks/_index.md` to find the task assigned to you
 4. Read the full task file in `memory-bank/tasks/` — understand the request, thought process, implementation plan, and all subtasks
-5. Identify referenced files mentioned in the task and examine them for context
-6. Understand current project structure and conventions
+5. **Graphify context for referenced files:** For each referenced file mentioned in the task:
+   - Run `graphify explain "<file-or-component>"` to get all connected nodes and their relationships
+   - Run `graphify path "<task-relevant-component>" "<referenced-file>"` to trace dependency chains
+   - Fall back to the Read tool only when graphify lacks detail or the file is not in the graph
+6. Understand current project structure and conventions via the graph's community structure (`graphify-out/GRAPH_REPORT.md` `## Communities`) and the memory bank's `systemPatterns.md`
 
 ## 2. Systematic Implementation Process
 
@@ -36,7 +40,7 @@ All planning, implementation, and execution work must be recorded in Markdown fi
 1. **Process subtasks in order** — Follow the task file's subtask sequence exactly, one step at a time
 2. **Before implementing any subtask:**
    - Fully understand all implementation requirements from the task file
-   - Gather any additional required context
+   - Gather any additional required context — prefer `graphify query "<subtask topic>"` over grep/glob for discovering related files, callers, and patterns
 3. **Implement the subtask completely with working code:**
    - Follow existing code patterns and conventions
    - Create working functionality that meets all requirements
@@ -74,6 +78,7 @@ All planning, implementation, and execution work must be recorded in Markdown fi
 2. Update `memory-bank/activeContext.md` — summarize what was implemented and set next steps
 3. Update `memory-bank/tasks/_index.md` — mark the task file as Completed
 4. Mark the task's overall status to Completed in its own file
+5. Run `graphify update .` to sync the knowledge graph with newly implemented code (AST-only, zero API cost)
 
 ## 5. Problem Resolution
 
@@ -88,16 +93,18 @@ All planning, implementation, and execution work must be recorded in Markdown fi
 ## Implementation Workflow
 
 ```
+0. Verify graphify-out/graph.json exists (run `graphify .` if not)
 1. Read activeContext.md, progress.md, tasks/_index.md, and the assigned task file
 2. For each unchecked subtask:
-   a. Fully understand requirements
+   a. Fully understand requirements — query graphify for context
    b. Implement with working code following workspace patterns
    c. Validate implementation meets requirements
    d. Mark subtask complete in task file
    e. Add progress log entry to task file with date and details
    f. Update activeContext.md and _index.md
 3. Repeat until all subtasks complete
-4. Update progress.md, activeContext.md, _index.md with final status
+4. Run `graphify update .` to sync graph
+5. Update progress.md, activeContext.md, _index.md with final status
 ```
 
 ## Success Criteria