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

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:

# 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

## 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

## Project Layout

!`find src -type f -name '*.ts' | head -20`

## Component Structure  

!`tree src/components -L 2`

Environment Information

## Environment

Node: !`node --version`
npm: !`npm --version`
OS: !`uname -a`

File Content Snippets

## 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:

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:

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:

# 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:

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:

// AI must explicitly call the task tool
task(
  subagent_type="CodeReviewer",
  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:

# 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):

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

# 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)

**Agent: `reviewer`** - Code review agent
- Purpose: Review code for quality and security
- When: After implementing features
- Invoke with: task(subagent_type="CodeReviewer", 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

# 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="TestEngineer",
    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:

  task(
    subagent_type="CodeReviewer",
    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:

  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="TestEngineer", description="Test feature", prompt="Write tests for X")

4. Automatically call:

   task(subagent_type="CodeReviewer", 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

# 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:

# 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"
)

@TestEngineer - Test generation and execution

task(
  subagent_type="TestEngineer", 
  description="Test auth system",
  prompt="Write comprehensive unit and integration tests for the authentication module. Ensure >80% coverage. Run tests and report results."
)

@CodeReviewer - Code quality and security review

task(
  subagent_type="CodeReviewer",
  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

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

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 @TestEngineer to validate implementation
2. Review - Invoke @CodeReviewer 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. Multistep tasks: Use sub-agents with task tool

---

⚠️ Common Pitfalls to Avoid

❌ DON'T DO THIS:

# 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:

# Good: Explicit tool call for agent invocation
**Agent: `tester`** - Invoke ONLY via task tool:
task(subagent_type="TestEngineer", 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="TestEngineer", description="Test X", prompt="Write and run tests for X")

---

🚀 Quick Start Template

Copy this template to create your own index:

# [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:

// 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
**@TestEngineer** - Use for testing

## Task
Implement the authentication flow following @docs/auth-spec.md

Dynamic File Loading

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# OS info
!`uname -a`

# Memory usage
!`free -h`

# Disk usage
!`df -h .`

# Process list (filtered)
!`ps aux | grep node`

---

🎯 Complete Real-World Example

# 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")`

**@TestEngineer** - Test creation
- Use when: After implementing auth features  
- Example: `task(subagent_type="TestEngineer", 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="TestEngineer", 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

   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="CodeReviewer", ...) @src/types.ts task(subagent_type="TestEngineer", ...) @.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:

task(
  subagent_type="TestEngineer",
  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:

task(
  subagent_type="CodeReviewer",
  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:

task(
  subagent_type="TestEngineer",
  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:

task(
  subagent_type="CodeReviewer",
  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)

# Implement Authentication

## Context Files
**Read these using read_file tool:**
- @docs/guidelines.md

## Agents
**Agent: `tester`** - Invoke with task tool:
task(subagent_type="TestEngineer", description="Test auth", prompt="...")

**Agent: `reviewer`** - Invoke with task tool:
task(subagent_type="CodeReviewer", 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

# 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

# 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="TestEngineer", description="...", prompt="...")

## Workflow
1. Read context files
2. Implement feature
3. Invoke tester agent
4. Report results

Template 3: Code Review Task

# 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="CodeReviewer",
  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

# 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: "TaskManager"
    orchestration-agent.md        # Agent name: "orchestration-agent"
    code/
      reviewer.md                 # Agent name: "code/reviewer"
      tester.md                   # Agent name: "code/tester"

Markdown Agent File Format:

---
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/TaskManager.md → Name: TaskManager
• File: .opencode/agent/code/reviewer.md → Name: code/reviewer

No opencode.json needed! Everything is in markdown.

❌ WRONG: Confusing Prompt

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: TaskManager
• Confusing agent files with agent invocation

✅ CORRECT: Clear Prompt

# 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/TaskManager.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: `TaskManager` (Subagent)

**IMPORTANT**: Agent is defined in a MARKDOWN file. The agent name comes from the file path!

**File location**: `.opencode/agent/TaskManager.md`
**Agent name**: `TaskManager` (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:

task(
  subagent_type="TaskManager",
  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

   task(
     subagent_type="TaskManager",
     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: TaskManager

**Invoke immediately for task breakdown:**

```javascript
task(
  subagent_type="TaskManager",
  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)

# 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: `TaskManager`** - For feature breakdown
Invoke: task(subagent_type="TaskManager", 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/TaskManager.md	N/A
Invoke task-manager	N/A	task(subagent_type="TaskManager", ...)
Reference in text	"the task-manager agent" or "TaskManager"	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)

---
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)

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)

Available subagents via task tool:
- TaskManager - For feature breakdown
- TestEngineer - 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