Merge main into dev: sync subagent invocation improvements and context guide

- Merge improved subagent invocation syntax from main
- Add comprehensive OpenCode context reference cheatsheet
- Resolve conflicts in .gitignore (keep both eval results and tasks)
- Update opencoder.md with correct task() invocation patterns

.gitignore

@@ -202,5 +202,5 @@ temp/
 evals/results/*
 !evals/results/.gitkeep
 
-# Task tracking (temporary)
-tasks/
+# User-generated task files
+tasks/

.opencode/agent/opencoder.md

@@ -1,5 +1,5 @@
 ---
-description: "Specialized development agent for complex coding, architecture, and multi-file refactoring"
+description: "Multi-language implementation agent for modular and functional development"
 mode: primary
 temperature: 0.1
 tools:
@@ -29,16 +29,24 @@ permissions:
     ".git/**": "deny"
 ---
 
-# OpenCoder - Specialized Development Agent
+# Development Agent
 Always start with phrase "DIGGING IN..."
 
-**Your expert development partner for complex coding tasks**
+## Available Subagents (invoke via task tool)
 
-You have access to the following subagents: 
-- `@task-manager`
-- `@subagents/tester` @tester
-- `@subagents/documentation` @documentation
-- `@subagents/coder-agent` @coder-agent
+- `subagents/core/task-manager` - Feature breakdown (4+ files, >60 min)
+- `subagents/code/coder-agent` - Simple implementations
+- `subagents/code/tester` - Testing after implementation
+- `subagents/core/documentation` - Documentation generation
+
+**Invocation syntax**:
+```javascript
+task(
+  subagent_type="subagents/core/task-manager",
+  description="Brief description",
+  prompt="Detailed instructions for the subagent"
+)
+```
 
 Focus:
 You are a coding specialist focused on writing clean, maintainable, and scalable code. Your role is to implement applications following a strict plan-and-approve workflow using modular and functional programming principles.
@@ -67,14 +75,14 @@ Code Standards
 
 Subtask Strategy
 
-- When a feature spans multiple modules or is estimated > 60 minutes, delegate planning to `@task-manager` to generate atomic subtasks under `tasks/subtasks/{feature}/` using the `{sequence}-{task-description}.md` pattern and a feature `README.md` index.
+- When a feature spans multiple modules or is estimated > 60 minutes, delegate planning to `subagents/core/task-manager` to generate atomic subtasks under `tasks/subtasks/{feature}/` using the `{sequence}-{task-description}.md` pattern and a feature `README.md` index.
 - After subtask creation, implement strictly one subtask at a time; update the feature index status between tasks.
 
 Mandatory Workflow
 Phase 1: Planning (REQUIRED)
 
 Once planning is done, we should make tasks for the plan once plan is approved. 
-So pass it to the `@task-manager` to make tasks for the plan.
+So pass it to the `subagents/core/task-manager` to make tasks for the plan.
 
 ALWAYS propose a concise step-by-step implementation plan FIRST
 Ask for user approval before any implementation
@@ -90,7 +98,7 @@ After each increment:
 - Run build checks
 - Execute relevant tests
 
-For simple tasks, use the `@subagents/coder-agent` to implement the code to save time.
+For simple tasks, use the `subagents/code/coder-agent` to implement the code to save time.
 
 Use Test-Driven Development when tests/ directory is available
 Request approval before executing any risky bash commands
@@ -98,7 +106,7 @@ Request approval before executing any risky bash commands
 Phase 3: Completion
 When implementation is complete and user approves final result:
 
-Emit handoff recommendations for write-test and documentation agents
+Emit handoff recommendations for `subagents/code/tester` and `subagents/core/documentation` agents
 
 Response Format
 For planning phase:
@@ -115,7 +123,7 @@ Copy## Implementing Step [X]: [Description]
 Remember: Plan first, get approval, then implement one step at a time. Never implement everything at once.
 Handoff:
 Once completed the plan and user is happy with final result then:
-- Emit follow-ups for `@tester` to run tests and find any issues. 
+- Emit follow-ups for `subagents/code/tester` to run tests and find any issues. 
 - Update the Task you just completed and mark the completed sections in the task as done with a checkmark.
 
 

dev/ai-tools/opencode/cheatsheet-context-symbols.md

@@ -0,0 +1,1801 @@
+# OpenCode Context Reference Cheat Sheet
+
+> **Purpose**: Master reference for defining files, agents, and tools in prompts that work seamlessly with OpenCode's automatic tool resolution.
+
+---
+
+## 🎯 Quick Reference Table
+
+| Type | Syntax | Auto-Loaded? | AI Action Required | When to Use |
+|------|--------|--------------|-------------------|-------------|
+| **File (Initial)** | `@file.md` | ✅ Yes | ❌ No | User's initial prompt |
+| **File (Nested)** | `@file.md` | ❌ No | ✅ Yes (read_file) | Inside loaded files |
+| **Directory** | `@src/components/` | ✅ Yes | ❌ No | Folder context |
+| **Sub-Agent (Context)** | `@agent-name` | ✅ Yes* | ❌ No | Reference agent info |
+| **Sub-Agent (Invoke)** | `task(subagent_type="name")` | ❌ No | ✅ Yes (task tool) | Delegate tasks |
+| **Shell Command** | `` !`command` `` | ✅ Yes | ❌ No | Inline command output |
+| **Config File** | `instructions: []` in `opencode.json` | ✅ Yes | ❌ No | Always-needed context |
+| **Agent (Markdown)** | `.opencode/agent/**/*.md` | ✅ Auto-registered | ❌ No | Define agents |
+
+---
+
+
+## 🔑 Key Takeaways
+
+1. **@ in agent markdown** = Just informational text
+2. **@ in user prompt** = OpenCode processes it (loads files/metadata)
+3. **To invoke agents** = Always use `task` tool
+4. **Agent names** = Full path from `.opencode/agent/` directory
+5. **Don't use @ to list agents** in your prompt - it's confusing!
+
+The `@` symbol only has special meaning in **USER PROMPTS**, not in **AGENT SYSTEM PROMPTS**.
+
+------
+
+## 🔧 Shell Commands
+
+### Inline Shell Commands (Automatic Execution)
+
+Use the `` !`command` `` syntax to execute commands and inline their output into prompts:
+
+```markdown
+# Example: Include git information
+Current branch: !`git branch --show-current`
+Recent commits: !`git log --oneline -5`
+
+# Example: Include system information  
+Node version: !`node --version`
+Available memory: !`free -h | grep Mem`
+
+# Example: Include file contents
+Database schema: !`cat schema.sql`
+
+# Example: Include directory structure
+Project structure:
+!`tree -L 2 -I 'node_modules|dist'`
+```
+
+**How it works:**
+- ✅ Commands execute when prompt is processed
+- ✅ Output is inserted into the prompt text
+- ✅ Great for dynamic context (git status, file lists, system info)
+- ⚠️ Commands run in shell with current working directory
+
+### Shell Command Patterns
+
+#### Git Context
+
+```markdown
+## Current Work Context
+
+Branch: !`git branch --show-current`
+Modified files: !`git status --short`
+Last commit: !`git log -1 --pretty=format:'%h - %s'`
+Uncommitted changes:
+!`git diff --stat`
+```
+
+#### Project Structure
+
+```markdown
+## Project Layout
+
+!`find src -type f -name '*.ts' | head -20`
+
+## Component Structure  
+
+!`tree src/components -L 2`
+```
+
+#### Environment Information
+
+```markdown
+## Environment
+
+Node: !`node --version`
+npm: !`npm --version`
+OS: !`uname -a`
+```
+
+#### File Content Snippets
+
+```markdown
+## Configuration
+
+Current eslint rules:
+!`cat .eslintrc.json`
+
+Package scripts:
+!`cat package.json | jq .scripts`
+```
+
+### When to Use Shell Commands vs Tools
+
+| Scenario | Use Shell `!` Syntax | Use `run_terminal_cmd` Tool |
+|----------|---------------------|---------------------------|
+| **Static context in prompt** | ✅ | ❌ |
+| **Git information** | ✅ | ❌ |
+| **File contents** | ✅ | ❌ |
+| **Interactive AI execution** | ❌ | ✅ |
+| **Based on AI decisions** | ❌ | ✅ |
+| **Build/test commands** | ❌ | ✅ |
+| **Requires error handling** | ❌ | ✅ |
+
+---
+
+## 📁 File References
+
+### Initial Prompt (Automatic)
+When **you** type this in your prompt:
+
+```markdown
+Follow guidelines in @GUIDELINES.md
+Use patterns from @src/patterns/
+```
+
+**OpenCode automatically:**
+- ✅ Reads `GUIDELINES.md`
+- ✅ Lists `src/patterns/` directory
+- ✅ Attaches content to AI context
+- ❌ Does NOT read nested @ references inside these files
+
+### Nested References (Requires AI Action)
+
+When `GUIDELINES.md` contains:
+
+```markdown
+Also see @CODE_STYLE.md and @TESTING.md
+```
+
+**OpenCode does:**
+- ❌ Does NOT automatically read these
+- ✅ AI sees them as plain text
+
+**To make AI read them, use explicit instructions:**
+
+```markdown
+# GUIDELINES.md
+
+⚠️ **CRITICAL**: Before proceeding, read these files using read_file:
+
+1. @CODE_STYLE.md - Coding standards (READ FIRST)
+2. @TESTING.md - Testing patterns (READ FIRST)  
+3. @ARCHITECTURE.md - System design (READ FIRST)
+
+[rest of your guidelines...]
+```
+
+**Key phrases that work:**
+- ✅ `READ FIRST`
+- ✅ `use read_file tool`
+- ✅ `CRITICAL: Read these files`
+- ✅ `Load immediately before proceeding`
+
+---
+
+## 🤖 Sub-Agent References
+
+### ⚠️ CRITICAL: Agent Context vs Agent Invocation
+
+**IMPORTANT DISTINCTION: Agent Files vs Agent Names**
+
+#### Understanding the Difference
+
+**Agent File** (Documentation):
+- Path: `.opencode/agents/subagents/core/taskmanager.md`
+- This is a MARKDOWN FILE describing the agent
+- Use `@.opencode/agents/subagents/core/taskmanager.md` to load file content
+- Result: Loads documentation/instructions as text
+
+**Agent Name** (System Registration):
+- Name: `taskmanager` (registered in OpenCode)
+- This is the actual AGENT that can execute tasks
+- Use `task(subagent_type="taskmanager", ...)` to invoke
+- Result: Agent runs and performs work
+
+#### Scenario 1: Using `@agent-name` (USUALLY NOT RECOMMENDED)
+When you use `@agent-name` in **your initial prompt**:
+
+```markdown
+Use @reviewer agent for code review
+```
+
+**What happens:**
+1. ✅ OpenCode checks if it's a file at that path
+2. ❌ File doesn't exist → Checks if it's a registered agent
+3. ✅ If agent exists: Attaches agent **metadata** as context (name, description, tools)
+4. ❌ Does **NOT invoke/run** the agent
+5. ⚠️ This loads agent info but doesn't execute anything
+
+**Result:** AI knows the agent exists but doesn't execute it.
+
+**When to use:** Rarely needed. Only if you want to reference agent capabilities in context.
+
+#### Scenario 2: Agent Invocation (RECOMMENDED)
+To actually **run** an agent and execute tasks:
+
+```javascript
+// AI must explicitly call the task tool
+task(
+  subagent_type="reviewer",
+  description="Review code",
+  prompt="Review the auth implementation for security issues"
+)
+```
+
+**Result:** Agent **executes** and returns results.
+
+**When to use:** Always - this is how you actually invoke agents.
+
+#### Scenario 3: Loading Agent Documentation Files
+If you have agent documentation files:
+
+```markdown
+# Initial prompt
+Follow guidelines in @.opencode/agents/subagents/core/taskmanager.md
+```
+
+**What happens:**
+1. ✅ Loads the **file** content as context
+2. ❌ Does NOT invoke the agent
+3. ✅ Good for loading agent usage instructions
+
+**When to use:** When you want to load documentation about how to use agents.
+
+---
+
+### Best Practice: Clear Agent Instructions
+
+**❌ DON'T write this (confusing - uses @ for agents):**
+```markdown
+Use @reviewer to review code
+Review with @taskmanager agent
+```
+**Problems:**
+- Loads agent metadata, doesn't invoke
+- AI might be confused about how to use it
+- Mixing file syntax with agent invocation
+
+**✅ DO write this (clear and explicit):**
+
+**Option 1: If you have agent documentation files**
+```markdown
+# Load agent documentation (file)
+@.opencode/agents/subagents/core/taskmanager.md
+
+# Then instruct AI how to invoke (not using @)
+**Agent: `taskmanager`**
+- Purpose: Task planning and breakdown
+- Invoke with: task(subagent_type="taskmanager", description="Plan X", prompt="Break down feature Y")
+```
+
+**Option 2: Direct invocation instructions (no @ at all)**
+```markdown
+**Agent: `reviewer`** - Code review agent
+- Purpose: Review code for quality and security
+- When: After implementing features
+- Invoke with: task(subagent_type="reviewer", description="Review X", prompt="Review Y for Z issues")
+
+**DO NOT use @reviewer** - This loads metadata, not invocation
+**ALWAYS use task tool** - This actually runs the agent
+```
+
+---
+
+### Listing Sub-Agents
+
+```markdown
+# Available Sub-Agents
+
+⚠️ **IMPORTANT**: These agents are NOT loaded as context. You MUST invoke them using the `task` tool:
+
+## Code Agents
+
+**Agent: `tester`** (DO NOT use @tester as context reference)
+- **Purpose**: Test generation and execution
+- **When to invoke**: After implementing features, before commits
+- **Tool call**: 
+  ```javascript
+  task(
+    subagent_type="tester",
+    description="Test auth",
+    prompt="Write comprehensive tests for auth module with >80% coverage"
+  )
+  ```
+
+**Agent: `reviewer`** (DO NOT use @reviewer as context reference)
+- **Purpose**: Code review and quality checks  
+- **When to invoke**: After completing code changes
+- **Tool call**: 
+  ```javascript
+  task(
+    subagent_type="reviewer",
+    description="Review changes",
+    prompt="Review the authentication implementation for security vulnerabilities, code quality, and best practices"
+  )
+  ```
+
+## Core Agents
+
+**Agent: `planner`** (DO NOT use @planner as context reference)
+- **Purpose**: Project planning and task breakdown
+- **When to invoke**: Starting large features or projects
+- **Tool call**: 
+  ```javascript
+  task(
+    subagent_type="planner",
+    description="Plan feature",
+    prompt="Break down the payment system feature into implementable tasks with dependencies"
+  )
+  ```
+```
+
+### Proactive Sub-Agent Invocation
+
+To make the AI **automatically** invoke sub-agents at appropriate times:
+
+```markdown
+## Agent Automation Rules
+
+**CRITICAL**: Agents are invoked via `task` tool, NOT by referencing them with @.
+
+**After completing code changes, ALWAYS:**
+1. Invoke the `tester` agent using `task` tool to write and run tests
+2. Invoke the `reviewer` agent using `task` tool to review code quality
+3. Report results back to the user
+
+**Example workflow:**
+1. User requests feature
+2. You implement the code
+3. Automatically call: 
+   ```javascript
+   task(subagent_type="tester", description="Test feature", prompt="Write tests for X")
+   ```
+4. Automatically call: 
+   ```javascript
+   task(subagent_type="reviewer", description="Review feature", prompt="Review X for quality")
+   ```
+5. Summarize results for user
+
+**Important**: 
+- Sub-agents return results ONLY to you. You must summarize for the user.
+- DO NOT use `@agent-name` syntax to invoke agents
+- ALWAYS use the `task` tool for agent invocation
+```
+
+---
+
+## 🛠️ Tool References
+
+### Built-in OpenCode Tools
+
+```markdown
+## Available Tools
+
+**File Operations**
+- `read_file` - Read file contents (supports line ranges)
+- `write_file` - Create or overwrite files  
+- `search_replace` - Edit files with precision
+- `list_dir` - List directory contents
+- `glob_file_search` - Find files by pattern
+
+**Code Operations**
+- `grep` - Search code with ripgrep
+- `codebase_search` - Semantic code search
+
+**Execution**
+- `run_terminal_cmd` - Execute shell commands
+- `task` - Invoke sub-agents
+
+**Planning**
+- `todo_write` - Create and manage task lists
+```
+
+### When to Reference Tools
+
+```markdown
+# Task Instructions
+
+When you need to find configuration files, use `glob_file_search` to locate them.
+
+When analyzing code patterns, use `codebase_search` for semantic understanding.
+
+When editing code, use `search_replace` for precision rather than rewriting entire files.
+```
+
+---
+
+## 💡 Complete Example: Index File
+
+Here's a **production-ready index file** that works perfectly with OpenCode:
+
+```markdown
+# Project Context Index
+
+## 📋 Quick Start
+
+**CRITICAL INSTRUCTION**: Before proceeding with ANY task:
+1. Read the files marked `[READ FIRST]` using the `read_file` tool
+2. Review the available sub-agents below
+3. Follow the coding standards and patterns defined in these files
+
+---
+
+## 📚 Core Documentation [READ FIRST]
+
+Load these files immediately using `read_file`:
+
+- @docs/CODING_STANDARDS.md - TypeScript/React coding patterns
+- @docs/TESTING_STRATEGY.md - Test requirements and patterns
+- @docs/ARCHITECTURE.md - System design and component structure
+- @.opencode/WORKFLOWS.md - Development workflows and CI/CD
+
+---
+
+## 🤖 Available Sub-Agents
+
+Use the `task` tool to invoke these specialized agents:
+
+### Development Agents
+
+**@subagents/code/implementer** - Complex feature implementation
+```javascript
+task(
+  subagent_type="implementer",
+  description="Implement user auth",
+  prompt="Create complete authentication system with JWT tokens, including login, logout, and session management. Follow patterns in @docs/ARCHITECTURE.md"
+)
+```
+
+**@subagents/code/tester** - Test generation and execution
+```javascript
+task(
+  subagent_type="tester", 
+  description="Test auth system",
+  prompt="Write comprehensive unit and integration tests for the authentication module. Ensure >80% coverage. Run tests and report results."
+)
+```
+
+**@subagents/code/reviewer** - Code quality and security review
+```javascript
+task(
+  subagent_type="reviewer",
+  description="Review auth code",
+  prompt="Review the authentication implementation for security vulnerabilities, code quality, and adherence to @docs/CODING_STANDARDS.md. Provide specific improvement suggestions."
+)
+```
+
+### Documentation Agents
+
+**@subagents/docs/technical-writer** - API and code documentation
+```javascript
+task(
+  subagent_type="technical-writer",
+  description="Document auth API", 
+  prompt="Generate comprehensive API documentation for the authentication endpoints, including request/response examples and error codes."
+)
+```
+
+### Planning Agents
+
+**@subagents/core/architect** - System design and planning
+```javascript
+task(
+  subagent_type="architect",
+  description="Design payment system",
+  prompt="Design a payment processing system architecture that integrates with Stripe. Break down into implementable tasks. Consider scalability and error handling."
+)
+```
+
+---
+
+## 🔄 Automated Workflows
+
+### After Implementing Code
+
+**ALWAYS execute this workflow:**
+
+1. **Test** - Invoke `@subagents/code/tester` to validate implementation
+2. **Review** - Invoke `@subagents/code/reviewer` for quality check
+3. **Document** - Update relevant documentation
+4. **Report** - Summarize results to user with:
+   - What was implemented
+   - Test results and coverage
+   - Any issues found in review
+   - Next recommended steps
+
+### Before Starting Large Features
+
+**ALWAYS execute this workflow:**
+
+1. **Plan** - Invoke `@subagents/core/architect` for design
+2. **Load Context** - Read relevant documentation from @docs/
+3. **Break Down** - Create detailed TODO list with `todo_write`
+4. **Confirm** - Ask user to confirm approach
+
+---
+
+## 📖 Additional Context Files
+
+### Code Patterns & Examples
+
+For specific implementation patterns, read these on-demand:
+
+- @examples/api-patterns.ts - REST API implementation patterns
+- @examples/component-patterns.tsx - React component patterns
+- @examples/test-patterns.test.ts - Testing patterns and fixtures
+- @examples/error-handling.ts - Error handling strategies
+
+### Configuration Files
+
+Reference these when setting up tools or CI/CD:
+
+- @.github/workflows/ - GitHub Actions workflows
+- @tsconfig.json - TypeScript configuration
+- @package.json - Project dependencies and scripts
+
+---
+
+## 🎯 Tool Usage Guidelines
+
+### File Search Strategy
+
+1. **Known filename**: Use `read_file` directly
+2. **Pattern match**: Use `glob_file_search` (e.g., "*.test.ts")
+3. **Semantic search**: Use `codebase_search` (e.g., "authentication logic")
+4. **Text search**: Use `grep` for exact text matches
+
+### Editing Strategy
+
+1. **Small changes**: Use `search_replace` for precision
+2. **New files**: Use `write_file`
+3. **Large refactors**: Consider sub-agent with `task` tool
+
+### Execution Strategy
+
+1. **Simple commands**: Use `run_terminal_cmd`
+2. **Complex workflows**: Create shell scripts first
+3. **Multi-step tasks**: Use sub-agents with `task` tool
+
+---
+
+## ⚠️ Common Pitfalls to Avoid
+
+### ❌ DON'T DO THIS:
+
+```markdown
+# Bad: Using @ syntax for agent invocation
+Use @tester when needed
+Review with @reviewer after coding
+
+# Bad: Treating agents like files
+Read @tester for testing guidelines
+See @reviewer documentation
+
+# Bad: Vague agent reference
+Use the tester agent when needed
+
+# Bad: Assuming nested files are auto-loaded
+See @guidelines.md (which references @other.md)
+
+# Bad: Not specifying how to invoke
+Available agents: tester, reviewer, planner
+
+# Bad: Mixing context and invocation
+Use @agent-name to run the agent
+```
+
+### ✅ DO THIS:
+
+```markdown
+# Good: Explicit tool call for agent invocation
+**Agent: `tester`** - Invoke ONLY via task tool:
+task(subagent_type="tester", description="Test feature", prompt="Write comprehensive tests for X")
+
+# Good: Clear separation of concerns
+**File**: @docs/testing-guide.md - Load with read_file
+**Agent**: `tester` - Invoke with task tool
+
+# Good: Explicit read instruction for nested refs
+**CRITICAL**: Read @guidelines.md, then read all files it references using read_file
+
+# Good: Clear tool invocation
+Use the `codebase_search` tool to find authentication logic
+
+# Good: Proactive invocation instruction
+After implementing code, ALWAYS invoke the tester agent:
+task(subagent_type="tester", description="Test X", prompt="Write and run tests for X")
+```
+
+---
+
+## 🚀 Quick Start Template
+
+Copy this template to create your own index:
+
+```markdown
+# [Project Name] Context Index
+
+## 🎯 Before Starting ANY Task
+
+**CRITICAL**: Load these files first using `read_file`:
+1. @[PATH_TO_GUIDELINES]
+2. @[PATH_TO_STANDARDS]
+3. @[PATH_TO_ARCHITECTURE]
+
+---
+
+## 🤖 Sub-Agents (MUST use `task` tool to invoke)
+
+**Agent: `[AGENT_NAME]`** (DO NOT use @[AGENT_NAME] as context)
+- Purpose: [Description]
+- When to invoke: [When to invoke]
+- Tool call: 
+  ```javascript
+  task(
+    subagent_type="[AGENT_NAME]",
+    description="[SHORT_DESC]",
+    prompt="[DETAILED_TASK_INSTRUCTIONS]"
+  )
+  ```
+
+---
+
+## 🔄 Standard Workflows
+
+### After Code Changes
+1. Invoke tester agent via `task` tool
+2. Invoke reviewer agent via `task` tool  
+3. Report results to user
+
+Example:
+```javascript
+// Step 1: Test
+task(subagent_type="[TESTER_AGENT]", description="Test feature", prompt="Write tests for X")
+
+// Step 2: Review
+task(subagent_type="[REVIEWER_AGENT]", description="Review feature", prompt="Review X for quality")
+
+// Step 3: Summarize results for user
+```
+
+---
+
+## 📚 Reference Files (Load on-demand)
+
+- @[FILE_PATH] - [Description] (Read when: [TRIGGER])
+
+---
+```
+
+---
+
+## 🔍 Verification Checklist
+
+Before sharing your index file, verify:
+
+- [ ] All **file** references use `@` prefix
+- [ ] Agent references use `task` tool, NOT `@` syntax
+- [ ] Agent names are plain text (e.g., `tester`), not `@tester`
+- [ ] Nested file references have explicit "READ FIRST" instructions
+- [ ] Sub-agents have complete `task()` tool call examples
+- [ ] Sub-agents show when/why to invoke them
+- [ ] Clear distinction between files (@file.md) and agents (task tool)
+- [ ] Automated workflows use `task` tool for agents
+- [ ] Tool usage instructions are specific
+- [ ] No ambiguous or vague instructions
+- [ ] No mixing of @ syntax for agents
+
+---
+
+## 📝 Quick Reference Notes
+
+- **Files**: Use `@path/to/file.md` in prompts (auto-loaded initially, nested require read_file)
+- **Agent Files**: Use `@.opencode/agents/subagents/core/agent.md` to load documentation
+- **Agent Invocation**: Use `task` tool, NOT `@agent-name` syntax
+- **Agent Names**: Plain text only (e.g., `taskmanager`), never `@taskmanager`
+- **Shell**: Use `` !`command` `` for automatic execution in prompts
+- **Key Rule**: `@` is for FILES only, `task` tool is for AGENTS
+- **Rare Exception**: `@agent-name` loads agent metadata (usually not needed)
+
+---
+
+## 🎨 Advanced Patterns
+
+### Combining Multiple Context Types
+
+```markdown
+# Complete Feature Context
+
+## Files to Read [READ FIRST]
+@docs/auth-spec.md
+@src/auth/types.ts
+
+## Current Implementation
+!`find src/auth -type f -name '*.ts'`
+
+## Git Context
+Branch: !`git branch --show-current`
+Changes: !`git diff --name-only`
+
+## Environment
+Node: !`node --version`
+Dependencies: !`npm list --depth=0 | grep auth`
+
+## Sub-Agents Available
+
+**@subagents/code/implementer** - Use for implementation
+**@subagents/code/tester** - Use for testing
+
+## Task
+Implement the authentication flow following @docs/auth-spec.md
+```
+
+### Dynamic File Loading
+
+```markdown
+# Load All Test Files
+
+Test files in project:
+!`find . -name "*.test.ts" -o -name "*.spec.ts"`
+
+**INSTRUCTION**: Read all test files above using `read_file` to understand testing patterns.
+```
+
+### Conditional Context
+
+```markdown
+# Database Migration Context
+
+## Current Migration Status
+!`npm run db:status 2>&1`
+
+## Latest Migration
+!`ls -t migrations/ | head -1 | xargs cat`
+
+**If migrations are pending**: Read @docs/migration-guide.md
+**If migrations are up-to-date**: Proceed with schema changes
+```
+
+### Nested Shell Commands with File References
+
+```markdown
+# Component Analysis
+
+## All React Components
+!`find src -name "*.tsx" | grep -v test`
+
+## Component Guidelines
+@docs/component-patterns.md
+
+**CRITICAL**: 
+1. Review the component list above
+2. Read @docs/component-patterns.md using `read_file`
+3. Ensure new components follow established patterns
+```
+
+---
+
+## 🔗 Shell Command Cheat Sheet
+
+### Git Commands
+
+```bash
+# Current branch
+!`git branch --show-current`
+
+# Recent commits
+!`git log --oneline -n 10`
+
+# Modified files
+!`git status --short`
+
+# Diff summary
+!`git diff --stat`
+
+# Authors
+!`git shortlog -sn --all`
+
+# Current commit hash
+!`git rev-parse HEAD`
+```
+
+### File System Commands
+
+```bash
+# List TypeScript files
+!`find src -name "*.ts" -type f`
+
+# Count lines of code
+!`find src -name "*.ts" | xargs wc -l | tail -1`
+
+# Recent files
+!`ls -lt src | head -10`
+
+# Directory tree
+!`tree -L 3 -I 'node_modules|dist|.git'`
+
+# File size summary
+!`du -sh src/*`
+```
+
+### Project Info Commands
+
+```bash
+# Package version
+!`cat package.json | jq -r .version`
+
+# Dependencies
+!`npm list --depth=0`
+
+# Scripts
+!`cat package.json | jq .scripts`
+
+# Node version
+!`node --version`
+
+# npm version
+!`npm --version`
+```
+
+### Search Commands
+
+```bash
+# Find TODO comments
+!`grep -r "TODO" src --include="*.ts"`
+
+# Find FIXME comments
+!`grep -r "FIXME" src --include="*.ts"`
+
+# Find specific function
+!`grep -rn "function authenticate" src`
+
+# Count test files
+!`find . -name "*.test.ts" | wc -l`
+```
+
+### System Commands
+
+```bash
+# OS info
+!`uname -a`
+
+# Memory usage
+!`free -h`
+
+# Disk usage
+!`df -h .`
+
+# Process list (filtered)
+!`ps aux | grep node`
+```
+
+---
+
+## 🎯 Complete Real-World Example
+
+```markdown
+# Feature Implementation: User Authentication
+
+## Pre-Flight Context Loading
+
+### CRITICAL: Read These Files First
+1. @docs/CODING_STANDARDS.md
+2. @docs/AUTH_ARCHITECTURE.md  
+3. @src/auth/interfaces.ts
+4. @tests/auth/auth.test.ts
+
+### Current State
+
+**Branch**: !`git branch --show-current`
+
+**Modified Files**:
+!`git status --short`
+
+**Existing Auth Files**:
+!`find src/auth -name "*.ts" -type f`
+
+**Test Coverage**:
+!`npm run test:coverage -- src/auth 2>&1 | tail -5`
+
+### Dependencies
+
+**Current Auth Libraries**:
+!`npm list | grep -E "(passport|jwt|bcrypt)"`
+
+**Node Version**: !`node --version`
+
+## Sub-Agents Available
+
+**@subagents/code/implementer** - Feature implementation
+- Use when: Implementing new auth flows
+- Example: `task(subagent_type="implementer", description="OAuth flow", prompt="Implement OAuth2 flow with Google, following patterns in @docs/AUTH_ARCHITECTURE.md")`
+
+**@subagents/code/tester** - Test creation
+- Use when: After implementing auth features  
+- Example: `task(subagent_type="tester", description="Test OAuth", prompt="Write integration tests for OAuth2 flow with >90% coverage")`
+
+**@subagents/security/auditor** - Security review
+- Use when: Before deploying auth changes
+- Example: `task(subagent_type="auditor", description="Audit auth", prompt="Review auth implementation for security vulnerabilities, SQL injection, XSS, and CSRF")`
+
+## Implementation Workflow
+
+### Step 1: Context Loading
+1. Read all files marked [READ FIRST]
+2. Review current implementation: !`cat src/auth/auth.service.ts`
+3. Review existing tests: !`cat tests/auth/auth.test.ts`
+
+### Step 2: Implementation
+1. Implement feature following @docs/CODING_STANDARDS.md
+2. Follow patterns from @src/auth/interfaces.ts
+3. Update types in @src/auth/types.ts
+
+### Step 3: Testing
+1. Invoke tester agent via `task` tool for test creation
+   ```javascript
+   task(subagent_type="tester", description="Test auth", prompt="Write tests for auth module")
+   ```
+2. Run tests: Use `run_terminal_cmd` for `npm test`
+3. Verify coverage meets requirements
+
+### Step 4: Review
+1. Invoke security auditor agent via `task` tool
+   ```javascript
+   task(subagent_type="auditor", description="Security audit", prompt="Review auth for vulnerabilities")
+   ```
+2. Address any issues found
+3. Re-run tests after fixes
+
+### Step 5: Documentation
+1. Update @docs/AUTH_ARCHITECTURE.md with changes
+2. Add inline code documentation
+3. Update API documentation
+
+## Reference Files (Load on-demand)
+
+- @docs/api/auth-endpoints.md - API documentation
+- @examples/auth-examples.ts - Usage examples
+- @config/auth.config.ts - Configuration options
+
+## Additional Context
+
+**Database Schema**:
+!`cat migrations/latest_auth_schema.sql`
+
+**Environment Variables**:
+!`cat .env.example | grep AUTH`
+
+---
+
+**REMEMBER**: 
+- Files: Use `@filename` (nested require read_file)
+- Agents: Use `task` tool, NOT `@agent-name`
+- Shell: `` !`cmd` `` executes automatically in prompt
+- Agent names are plain text (e.g., `tester`), never `@tester`
+```
+
+---
+
+## 📝 Notes
+
+- **Auto-loaded**: Initial `@` references in YOUR prompt (files only)
+- **Requires tool call**: Nested `@` references in loaded files
+- **Agent as context**: `@agent-name` in initial prompt attaches agent info (not invocation)
+- **Agent invocation**: Always requires `task` tool call - NEVER use `@` syntax
+- **Shell commands**: `` !`command` `` syntax executes automatically in prompt processing
+- **Tool commands**: `run_terminal_cmd` for AI-driven execution during conversation
+- **Key distinction**: Files use `@`, Agents use `task` tool
+
+---
+
+## 🎯 Quick Decision Tree
+
+**Need to load a file?**
+- Initial prompt → Use `@path/to/file.md`
+- Nested reference → Add "READ FIRST" instruction for AI to use `read_file`
+- Agent docs → Use `@.opencode/agents/subagents/core/agent.md` (file path)
+
+**Need to invoke an agent?**
+- ❌ **NEVER** use `@agent-name` syntax for invocation
+- ✅ AI must call `task(subagent_type="name", ...)`
+- ✅ Use plain agent names (e.g., `taskmanager`, not `@taskmanager`)
+- ✅ Add clear invocation instructions in your context
+- ⚠️ Using `@agent-name` only loads metadata (rarely useful)
+
+**Need to run a command?**
+- Static context → Use `` !`command` `` in prompt
+- AI-driven execution → AI uses `run_terminal_cmd` tool
+
+**Structure Example:**
+```
+Files (use @):          Agents (use task):
+@docs/guide.md          task(subagent_type="reviewer", ...)
+@src/types.ts           task(subagent_type="tester", ...)
+@.opencode/agents/      [agent name without @]
+  taskmanager.md        
+```
+
+---
+
+---
+
+## 🎯 THE PERFECT PROMPT TEMPLATE
+
+Use this template to avoid ALL confusion and work seamlessly with OpenCode:
+
+### Template Structure
+
+```markdown
+# [Task Name]
+
+## 📋 Context Files (Load with read_file tool)
+
+**CRITICAL**: Read these files FIRST using the `read_file` tool:
+1. @docs/coding-standards.md
+2. @docs/architecture.md
+3. @src/types/core.ts
+
+---
+
+## 📚 Additional Documentation (Auto-loaded)
+
+Current git status:
+Branch: !`git branch --show-current`
+Recent changes: !`git status --short`
+
+Project structure:
+!`find src -type d -maxdepth 2`
+
+---
+
+## 🤖 Available Agents (Invoke via task tool ONLY)
+
+**IMPORTANT**: DO NOT use @ syntax for agents. Use the `task` tool to invoke.
+
+### Agent: `implementer`
+**Purpose**: Complex feature implementation
+**When to invoke**: When implementing new features or major refactors
+**How to invoke**:
+```javascript
+task(
+  subagent_type="implementer",
+  description="Implement feature X",
+  prompt="Create complete implementation of X following @docs/architecture.md patterns. Include error handling and validation."
+)
+```
+
+### Agent: `tester`
+**Purpose**: Test creation and execution
+**When to invoke**: After implementing features, before committing
+**How to invoke**:
+```javascript
+task(
+  subagent_type="tester",
+  description="Test feature X",
+  prompt="Write comprehensive tests for X with >80% coverage. Run tests and report results."
+)
+```
+
+### Agent: `reviewer`
+**Purpose**: Code review and quality checks
+**When to invoke**: After code changes, before finalizing
+**How to invoke**:
+```javascript
+task(
+  subagent_type="reviewer",
+  description="Review feature X",
+  prompt="Review the implementation of X for code quality, security vulnerabilities, and adherence to @docs/coding-standards.md"
+)
+```
+
+---
+
+## 🔄 Required Workflow
+
+**After implementing ANY code:**
+1. Invoke `tester` agent using task tool
+2. Invoke `reviewer` agent using task tool
+3. Summarize results to user
+
+---
+
+## 🎯 Your Task
+
+[Describe the specific task here]
+
+---
+
+## ⚠️ Important Reminders
+
+- Files: Use `@path/to/file.md` syntax
+- Agent invocation: Use `task(subagent_type="name", ...)` 
+- NEVER use `@agent-name` to invoke agents
+- Agent names are plain text: `tester`, `reviewer`, NOT `@tester`
+```
+
+---
+
+### Real-World Example: Perfect Prompt
+
+```markdown
+# Implement User Authentication System
+
+## 📋 Context Files (Load FIRST)
+
+**CRITICAL**: Use `read_file` tool to load these before starting:
+1. @docs/CODING_STANDARDS.md - TypeScript coding patterns
+2. @docs/AUTH_ARCHITECTURE.md - Authentication design patterns
+3. @src/auth/types.ts - Existing auth type definitions
+4. @tests/auth/auth.test.ts - Existing test patterns
+
+---
+
+## 📚 Current State (Auto-loaded)
+
+**Git Context**:
+Branch: !`git branch --show-current`
+Modified: !`git status --short`
+
+**Existing Auth Files**:
+!`find src/auth -name "*.ts" -type f`
+
+**Dependencies**:
+!`npm list | grep -E "(jwt|bcrypt|passport)"`
+
+---
+
+## 🤖 Available Agents
+
+### Agent: `implementer`
+Purpose: Feature implementation
+Invoke with:
+```javascript
+task(
+  subagent_type="implementer",
+  description="Implement auth flow",
+  prompt="Create authentication system with JWT tokens, including login, logout, and session management. Follow patterns in @docs/AUTH_ARCHITECTURE.md. Include middleware, controllers, and services."
+)
+```
+
+### Agent: `tester`
+Purpose: Test creation
+Invoke with:
+```javascript
+task(
+  subagent_type="tester",
+  description="Test auth system",
+  prompt="Write unit and integration tests for authentication module. Cover login, logout, token refresh, and session management. Ensure >85% coverage. Run tests and report results."
+)
+```
+
+### Agent: `reviewer`
+Purpose: Security and quality review
+Invoke with:
+```javascript
+task(
+  subagent_type="reviewer",
+  description="Review auth implementation",
+  prompt="Review authentication implementation for security vulnerabilities (SQL injection, XSS, CSRF), proper token handling, password security, and adherence to @docs/CODING_STANDARDS.md"
+)
+```
+
+---
+
+## 🔄 Required Workflow
+
+**You MUST follow this workflow:**
+
+1. **Read Context**: Load all files marked [CRITICAL] above
+2. **Implement**: Create the authentication system
+3. **Test**: Invoke `tester` agent via task tool
+4. **Review**: Invoke `reviewer` agent via task tool
+5. **Report**: Summarize implementation, test results, and review findings
+
+---
+
+## 🎯 Task Details
+
+Implement a complete authentication system with:
+- JWT-based authentication
+- Login/logout endpoints
+- Token refresh mechanism
+- Session management
+- Password hashing with bcrypt
+- Middleware for protected routes
+
+Requirements:
+- Follow patterns in @docs/AUTH_ARCHITECTURE.md
+- Adhere to @docs/CODING_STANDARDS.md
+- Integrate with existing user model in @src/models/user.ts
+- Add proper error handling
+- Include request validation
+
+---
+
+## ⚠️ Important Rules
+
+- Load files with @ syntax: `@docs/file.md`
+- Invoke agents with task tool: `task(subagent_type="name", ...)`
+- NEVER use `@agent-name` to invoke agents
+- Agent names are plain text: `tester`, NOT `@tester`
+- Shell commands auto-execute: !`git status`
+```
+
+---
+
+## 📝 Anti-Pattern Examples (What NOT To Do)
+
+### ❌ BAD PROMPT (Confusing)
+```markdown
+Use @tester and @reviewer agents to test the code.
+Follow @guidelines and implement authentication.
+```
+
+**Problems:**
+- Uses `@` for agents (only loads metadata, doesn't invoke)
+- No clear invocation instructions
+- Mixing file and agent syntax
+- No explicit workflow
+
+### ✅ GOOD PROMPT (Clear)
+```markdown
+# Implement Authentication
+
+## Context Files
+**Read these using read_file tool:**
+- @docs/guidelines.md
+
+## Agents
+**Agent: `tester`** - Invoke with task tool:
+task(subagent_type="tester", description="Test auth", prompt="...")
+
+**Agent: `reviewer`** - Invoke with task tool:
+task(subagent_type="reviewer", description="Review auth", prompt="...")
+
+## Workflow
+1. Read @docs/guidelines.md
+2. Implement feature
+3. Invoke tester agent via task tool
+4. Invoke reviewer agent via task tool
+```
+
+---
+
+## 🎨 Prompt Templates by Use Case
+
+### Template 1: Simple Feature Implementation
+```markdown
+# Implement [Feature Name]
+
+## Context
+Read: @docs/standards.md
+
+Git status: !`git status --short`
+
+## Task
+[Detailed description]
+
+## No Agents Needed
+(Simple task, no agents required)
+```
+
+### Template 2: Complex Feature with Agents
+```markdown
+# Implement [Complex Feature]
+
+## Context Files (Read FIRST)
+1. @docs/standards.md
+2. @docs/architecture.md
+
+## Current State
+!`git status --short`
+!`find src/[module] -name "*.ts"`
+
+## Available Agents
+
+**Agent: `implementer`**
+Invoke: task(subagent_type="implementer", description="...", prompt="...")
+
+**Agent: `tester`**
+Invoke: task(subagent_type="tester", description="...", prompt="...")
+
+## Workflow
+1. Read context files
+2. Implement feature
+3. Invoke tester agent
+4. Report results
+```
+
+### Template 3: Code Review Task
+```markdown
+# Review [Feature/Module]
+
+## Context
+Files to review:
+!`git diff --name-only main...HEAD`
+
+Recent changes:
+!`git log --oneline -5`
+
+## Agent
+
+**Agent: `reviewer`**
+Invoke immediately:
+task(
+  subagent_type="reviewer",
+  description="Review recent changes",
+  prompt="Review all changes in current branch for code quality, security, and adherence to standards"
+)
+
+## Task
+Run code review and report findings.
+```
+
+### Template 4: Documentation Task
+```markdown
+# Document [Feature]
+
+## Context
+Implementation files:
+!`find src/[module] -name "*.ts"`
+
+## Agent
+
+**Agent: `documenter`**
+Invoke: task(subagent_type="documenter", description="Document X", prompt="...")
+
+## Task
+Generate comprehensive documentation for [feature].
+```
+
+---
+
+## 🔑 Golden Rules for Perfect Prompts
+
+1. **Files**: Always use `@path/to/file.md`
+2. **Agents**: Always use `task(subagent_type="name", ...)`
+3. **Shell**: Always use `` !`command` `` for dynamic context
+4. **Clarity**: Separate files, agents, and tasks into clear sections
+5. **Workflow**: Always specify the execution order
+6. **Agent Names**: Plain text only - `tester`, never `@tester`
+7. **Context First**: Load all context before describing the task
+8. **Explicit Instructions**: Tell AI exactly when and how to invoke agents
+
+---
+
+## 🎯 REAL-WORLD EXAMPLE: Your Agent Setup
+
+Based on your actual agent configurations (task-manager subagent + orchestration agent):
+
+### Your Agent Files Structure & Naming
+
+**CRITICAL**: Agents are defined in MARKDOWN files. The agent NAME comes from the FILE PATH!
+
+```
+.opencode/
+  agent/                          # All agents as markdown files
+    subagents/
+      core/
+        task-manager.md           # Agent name: "subagents/core/task-manager"
+    orchestration-agent.md        # Agent name: "orchestration-agent"
+    code/
+      reviewer.md                 # Agent name: "code/reviewer"
+      tester.md                   # Agent name: "code/tester"
+```
+
+**Markdown Agent File Format:**
+```markdown
+---
+description: "Brief description of agent"
+mode: subagent                    # or "primary" or "all"
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: true
+  task: true
+permissions:
+  edit:
+    "**/*.secret": "deny"
+  bash:
+    "rm -rf *": "deny"
+---
+
+# Agent Prompt Content Here
+
+Your agent instructions, personality, rules, etc.
+All the markdown content becomes the agent's system prompt.
+```
+
+**How OpenCode determines agent names (from source code):**
+1. Scans `.opencode/agent/**/*.md` files recursively
+2. Parses YAML frontmatter (between `---` markers) for config
+3. Uses markdown content as the agent's system prompt
+4. Agent name = file path from `agent/` directory (minus `.md`)
+
+**Examples:**
+- File: `.opencode/agent/task-manager.md` → Name: `task-manager`
+- File: `.opencode/agent/subagents/core/task-manager.md` → Name: `subagents/core/task-manager`
+- File: `.opencode/agent/code/reviewer.md` → Name: `code/reviewer`
+
+**No opencode.json needed!** Everything is in markdown.
+
+### ❌ WRONG: Confusing Prompt
+
+```markdown
+Use @task-manager to break down the feature
+Have @orchestration-agent coordinate the work
+```
+
+**Problems:**
+- Using `@` for agent invocation (only loads metadata)
+- AI won't actually invoke the agents
+- Wrong agent name - should include full path: `subagents/core/task-manager`
+- Confusing agent files with agent invocation
+
+### ✅ CORRECT: Clear Prompt
+
+```markdown
+# Implement User Dashboard Feature
+
+## 📋 Context Files (Load FIRST)
+
+**Agent Documentation** (optional - only if you need to understand agent capabilities):
+- @.opencode/agent/orchestration-agent.md - Main agent guidelines
+- @.opencode/agent/subagents/core/task-manager.md - Task breakdown process
+
+**Project Documentation**:
+- @docs/coding-standards.md
+- @docs/architecture.md
+
+**Current State**:
+Branch: !`git branch --show-current`
+Files: !`find src/dashboard -name "*.ts"`
+
+---
+
+## 🤖 Available Agents
+
+### Agent: `subagents/core/task-manager` (Subagent)
+
+**IMPORTANT**: Agent is defined in a MARKDOWN file. The agent name comes from the file path!
+
+**File location**: `.opencode/agent/subagents/core/task-manager.md`
+**Agent name**: `subagents/core/task-manager` (path from `agent/` directory)
+**Format**: Markdown with YAML frontmatter
+
+**File structure:**
+```markdown
+---
+description: "Breaks down complex features into subtasks"
+mode: subagent
+temperature: 0.1
+tools: { read: true, write: true, ... }
+---
+
+# Task Manager Agent Prompt
+[Your agent instructions here...]
+```
+
+**Purpose**: Break down complex features into atomic subtasks
+
+**When to invoke**: 
+- Feature has 4+ components
+- Need structured task breakdown
+- Complex dependencies exist
+
+**How to invoke**:
+```javascript
+task(
+  subagent_type="subagents/core/task-manager",
+  description="Break down dashboard feature",
+  prompt="Break down the user dashboard feature into atomic subtasks. Feature includes: profile widget, activity feed, notification center, and settings panel. Create structured task files in /tasks/ directory following your two-phase workflow."
+)
+```
+
+**What it does**:
+1. Analyzes feature and creates subtask plan
+2. Waits for your approval
+3. Creates task files in `tasks/subtasks/{feature}/`
+4. Returns task sequence and dependencies
+
+---
+
+## 🔄 Required Workflow
+
+**For complex features (4+ components):**
+
+1. **Invoke task-manager** to break down the feature
+   ```javascript
+   task(
+     subagent_type="subagents/core/task-manager",
+     description="Break down dashboard",
+     prompt="Analyze and break down user dashboard feature with profile, activity, notifications, and settings components. Create task files with dependencies and acceptance criteria."
+   )
+   ```
+
+2. **Review the task plan** (agent will request approval)
+
+3. **Approve and let agent create files**
+
+4. **Implement tasks** sequentially based on dependencies
+
+5. **Validate each task** against acceptance criteria
+
+---
+
+## 🎯 Your Task
+
+Implement a user dashboard feature with:
+- Profile widget (avatar, name, stats)
+- Activity feed (recent actions, timestamps)
+- Notification center (alerts, read/unread states)
+- Settings panel (preferences, theme toggle)
+
+Requirements:
+- Follow @docs/architecture.md patterns
+- Responsive design
+- Real-time updates for notifications
+- Accessibility compliant
+
+**Since this is complex (4+ components), invoke the task-manager agent first.**
+
+---
+
+## ⚠️ Important Notes
+
+- **Agent files** (`.md` in `.opencode/agents/`): Use `@` to load as documentation
+- **Agent invocation**: Use `task(subagent_type="name", ...)` to actually run the agent
+- **Agent names**: Plain text - `task-manager`, NOT `@task-manager`
+- The orchestration agent is your primary agent (already active)
+- Invoke `task-manager` when you need feature breakdown
+```
+
+---
+
+## 🎨 Prompt Templates for Your Specific Agents
+
+### Template 1: Complex Feature (Needs Task Breakdown)
+
+```markdown
+# Implement [Complex Feature Name]
+
+## 📋 Context
+
+**Read these files:**
+- @docs/coding-standards.md
+- @docs/architecture.md
+- @.opencode/context/core/workflows/delegation.md
+
+**Current state:**
+!`git status --short`
+!`find src/[module] -type f`
+
+---
+
+## 🤖 Agent: subagents/core/task-manager
+
+**Invoke immediately for task breakdown:**
+
+```javascript
+task(
+  subagent_type="subagents/core/task-manager",
+  description="Break down [feature]",
+  prompt="Break down [feature description] into atomic subtasks. Include:
+  - Component 1: [details]
+  - Component 2: [details]
+  - Component 3: [details]
+  
+  Create task files in /tasks/ with dependencies, acceptance criteria, and test requirements. Follow your two-phase workflow (plan → approve → create files)."
+)
+```
+
+---
+
+## 🎯 Task Details
+
+[Detailed feature requirements]
+
+---
+
+## 🔄 Workflow
+
+1. Invoke task-manager for breakdown
+2. Review and approve task plan
+3. Implement tasks in dependency order
+4. Validate against acceptance criteria
+5. Report completion
+```
+
+### Template 2: Simple Task (Direct Execution)
+
+```markdown
+# [Simple Task Name]
+
+## 📋 Context
+
+**Read:**
+- @docs/coding-standards.md
+
+**Current state:**
+!`git status --short`
+
+---
+
+## 🎯 Task
+
+[Task description - simple, 1-3 files]
+
+---
+
+## ⚠️ Notes
+
+- Simple task, no task-manager needed
+- Execute directly
+- Follow coding standards from @docs/coding-standards.md
+```
+
+### Template 3: Coordination Task (Uses Orchestration Features)
+
+```markdown
+# Coordinate [Multi-Step Feature]
+
+## 📋 Context
+
+**Read orchestration guidelines:**
+- @.opencode/agents/orchestration-agent.md
+- @.opencode/context/core/workflows/delegation.md
+
+**Current state:**
+!`git status --short`
+
+---
+
+## 🔄 Coordination Workflow
+
+This task requires coordination across multiple steps:
+
+1. **Break down** feature using task-manager
+2. **Implement** core components
+3. **Delegate** complex subsystems if needed
+4. **Validate** integration
+5. **Report** completion
+
+---
+
+## 🤖 Agents Available
+
+**Agent: `subagents/core/task-manager`** - For feature breakdown
+Invoke: task(subagent_type="subagents/core/task-manager", description="...", prompt="...")
+
+**Agent: `general`** - For delegated complex work (if needed)
+Invoke: task(subagent_type="general", description="...", prompt="...")
+
+---
+
+## 🎯 Task
+
+[Complex coordinated task description]
+
+---
+
+## 📝 Orchestration Rules
+
+From @.opencode/agents/orchestration-agent.md:
+- Request approval before execution
+- Stop on failures (don't auto-fix)
+- Report → Propose → Approve → Fix
+- Confirm before cleanup
+```
+
+---
+
+## 🎯 Key Insights for Your Setup
+
+### Your Orchestration Agent (Primary)
+- **Already active** - it's processing your prompts
+- **Has task delegation** capability
+- **Follows approval workflow**
+- **Can invoke task-manager** when needed
+
+### Your Task-Manager Subagent
+- **Invoked via task tool** when you need breakdown
+- **Two-phase workflow**: Plan → Approve → Create
+- **Creates files** in `tasks/subtasks/{feature}/`
+- **Returns structured** task plans
+
+### Critical Distinctions
+
+| What | File Syntax | Agent Invocation |
+|------|-------------|------------------|
+| Load agent docs | `@.opencode/agent/subagents/core/task-manager.md` | N/A |
+| Invoke task-manager | N/A | `task(subagent_type="subagents/core/task-manager", ...)` |
+| Reference in text | "the task-manager agent" or "subagents/core/task-manager" | N/A |
+| Load project docs | `@docs/standards.md` | N/A |
+
+**KEY INSIGHT**: The agent name comes from the file path structure, NOT just the filename!
+
+### Decision Flow
+
+```
+Is it complex (4+ components)?
+  ↓ YES
+  Invoke task-manager → Get breakdown → Implement tasks
+  
+  ↓ NO
+  Execute directly (orchestration agent handles it)
+
+Need to understand agents?
+  ↓ YES
+  Load agent docs: @.opencode/agents/[agent].md
+  
+  ↓ NO
+  Skip - just invoke when needed
+```
+
+---
+
+---
+
+## 🤔 Design Philosophy: Why List Subagents?
+
+**You might ask**: "Why do I need to tell the AI about subagents in my prompt when the `task` tool already lists them?"
+
+**You're right - it's redundant!** Here's the reality:
+
+### The Ideal World (How It Should Work)
+```markdown
+---
+tools:
+  task: true  # AI should figure out the rest
+---
+
+# Your Agent
+Delegate complex work to specialized subagents.
+```
+
+The AI should:
+1. ✅ See the `task` tool
+2. ✅ Read the tool's description (which lists agents)
+3. ✅ Use it when appropriate
+
+### The Real World (Current AI Limitations)
+
+Current AI models don't always:
+- ❌ Read tool descriptions carefully
+- ❌ Remember to check available tools
+- ❌ Connect "complex task" → "delegate" → "use task tool"
+
+So we **compensate** by:
+- Explicitly mentioning agents in prompts
+- Providing invocation examples
+- Repeating instructions
+
+### Two Approaches
+
+**Option 1: Minimal (Trust the Tool)**
+```markdown
+For complex work, use the `task` tool to delegate to specialized subagents.
+Available agents are documented in the task tool description.
+```
+- ✅ Clean, minimal
+- ⚠️ AI might not delegate when it should
+
+**Option 2: Explicit (Be Redundant)**
+```markdown
+Available subagents via task tool:
+- subagents/core/task-manager - For feature breakdown
+- subagents/code/tester - For testing
+
+Invoke with: task(subagent_type="...", description="...", prompt="...")
+```
+- ⚠️ Redundant with tool description
+- ✅ AI consistently delegates appropriately
+
+**Recommendation**:
+
+**Last Updated**: 2024-11-21
+**OpenCode Version**: Latest
+

registry.json

@@ -824,7 +824,7 @@
     }
   },
   "metadata": {
-    "lastUpdated": "2025-11-19",
+    "lastUpdated": "2025-11-21",
     "schemaVersion": "1.0.0"
   }
 }