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

@ in agent markdown = Just informational text
@ in user prompt = OpenCode processes it (loads files/metadata)
To invoke agents = Always use task tool
Agent names = Full path from .opencode/agent/ directory
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:

✅ OpenCode checks if it's a file at that path
❌ File doesn't exist → Checks if it's a registered agent
✅ If agent exists: Attaches agent metadata as context (name, description, tools)
❌ Does NOT invoke/run the agent
⚠️ 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:

✅ Loads the file content as context
❌ Does NOT invoke the agent
✅ 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**:

javascript 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**:

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:

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

javascript 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

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

javascript 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

javascript 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

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 `@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:

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="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:

markdown

[Project Name] Context Index

🎯 Before Starting ANY Task

CRITICAL: Load these files first using read_file:

@[PATH_TO_GUIDELINES]
@[PATH_TO_STANDARDS]
@[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:

task(
subagent_type="[AGENT_NAME]",
description="[SHORT_DESC]",
prompt="[DETAILED_TASK_INSTRUCTIONS]"
)

🔄 Standard Workflows

After Code Changes

Invoke tester agent via task tool
Invoke reviewer agent via task tool
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


---

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

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:

Review the component list above
Read @docs/component-patterns.md using read_file

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

@docs/CODING_STANDARDS.md
@docs/AUTH_ARCHITECTURE.md
@src/auth/interfaces.ts
@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

Read all files marked [READ FIRST]
Review current implementation: !cat src/auth/auth.service.ts
Review existing tests: !cat tests/auth/auth.test.ts

Step 2: Implementation

Implement feature following @docs/CODING_STANDARDS.md
Follow patterns from @src/auth/interfaces.ts
Update types in @src/auth/types.ts

Step 3: Testing

Invoke tester agent via task tool for test creation

task(subagent_type="TestEngineer", description="Test auth", prompt="Write tests for auth module")

Run tests: Use run_terminal_cmd for npm test
Verify coverage meets requirements

Step 4: Review

Invoke security auditor agent via task tool

task(subagent_type="auditor", description="Security audit", prompt="Review auth for vulnerabilities")

Address any issues found
Re-run tests after fixes

Step 5: Documentation

Update @docs/AUTH_ARCHITECTURE.md with changes
Add inline code documentation
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:

@docs/coding-standards.md
@docs/architecture.md
@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:

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:

Invoke tester agent using task tool
Invoke reviewer agent using task tool
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:

@docs/CODING_STANDARDS.md - TypeScript coding patterns
@docs/AUTH_ARCHITECTURE.md - Authentication design patterns
@src/auth/types.ts - Existing auth type definitions
@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:

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:

Read Context: Load all files marked [CRITICAL] above
Implement: Create the authentication system
Test: Invoke tester agent via task tool
Review: Invoke reviewer agent via task tool
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="TestEngineer", description="Test auth", prompt="...")

Agent: reviewer - Invoke with task tool: task(subagent_type="CodeReviewer", description="Review auth", prompt="...")

Workflow

Read @docs/guidelines.md
Implement feature
Invoke tester agent via task tool

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)

@docs/standards.md
@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

Read context files
Implement feature
Invoke tester agent
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="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

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: "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:**

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/TaskManager.md` → Name: `TaskManager`
- 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: `TaskManager`
- 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/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:

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

Analyzes feature and creates subtask plan
Waits for your approval
Creates task files in tasks/subtasks/{feature}/
Returns task sequence and dependencies

🔄 Required Workflow

For complex features (4+ components):

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

Review the task plan (agent will request approval)
Approve and let agent create files
Implement tasks sequentially based on dependencies
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:

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

Invoke task-manager for breakdown
Review and approve task plan
Implement tasks in dependency order
Validate against acceptance criteria

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:

Break down feature using task-manager
Implement core components
Delegate complex subsystems if needed
Validate integration
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)

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:

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

cheatsheet-context-symbols.md 45 KB Permalink History Raw

OpenCode Context Reference Cheat Sheet

🎯 Quick Reference Table

🔑 Key Takeaways

🔧 Shell Commands

Inline Shell Commands (Automatic Execution)

Shell Command Patterns

Git Context

Project Structure

Environment Information

File Content Snippets

When to Use Shell Commands vs Tools

📁 File References

Initial Prompt (Automatic)

Nested References (Requires AI Action)

🤖 Sub-Agent References

⚠️ CRITICAL: Agent Context vs Agent Invocation

Understanding the Difference

Scenario 1: Using @agent-name (USUALLY NOT RECOMMENDED)

Scenario 2: Agent Invocation (RECOMMENDED)

Scenario 3: Loading Agent Documentation Files

Best Practice: Clear Agent Instructions

Listing Sub-Agents

Proactive Sub-Agent Invocation

🛠️ Tool References

Built-in OpenCode Tools

When to Reference Tools

💡 Complete Example: Index File

Bad: Using @ syntax for agent invocation

Bad: Treating agents like files

Bad: Vague agent reference

Bad: Assuming nested files are auto-loaded

Bad: Not specifying how to invoke

Bad: Mixing context and invocation

Good: Explicit tool call for agent invocation

Good: Clear separation of concerns

Good: Explicit read instruction for nested refs

Good: Clear tool invocation

Good: Proactive invocation instruction

[Project Name] Context Index

🎯 Before Starting ANY Task

🤖 Sub-Agents (MUST use task tool to invoke)

🔄 Standard Workflows

After Code Changes

📚 Reference Files (Load on-demand)

Complete Feature Context

Files to Read [READ FIRST]

Current Implementation

Git Context

Environment

Sub-Agents Available

Task

Load All Test Files

Database Migration Context

Current Migration Status

Latest Migration

Component Analysis

All React Components

Component Guidelines

Current branch

Recent commits

Modified files

Diff summary

Authors

Current commit hash

List TypeScript files

Count lines of code

Recent files

Directory tree

File size summary

Package version

Dependencies

Scripts

Node version

npm version

Find TODO comments

Find FIXME comments

Find specific function

Count test files

OS info

cheatsheet-context-symbols.md 45 KB

Permalink History Raw

Scenario 1: Using `@agent-name` (USUALLY NOT RECOMMENDED)

🤖 Sub-Agents (MUST use `task` tool to invoke)

Agent: `implementer`

Agent: `tester`

Agent: `reviewer`

Agent: `implementer`

Agent: `tester`

Agent: `reviewer`

Agent: `TaskManager` (Subagent)