2025-12-31 15:41:10 +00:00

45 KiB

Raw Blame History

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

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

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

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:

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

Automatically call:

task(subagent_type="reviewer", description="Review feature", prompt="Review X for quality")

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

@subagents/code/tester - Test generation and execution

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

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

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:

Test - Invoke @subagents/code/tester to validate implementation
Review - Invoke @subagents/code/reviewer for quality check
Document - Update relevant documentation
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:

Plan - Invoke @subagents/core/architect for design
Load Context - Read relevant documentation from @docs/
Break Down - Create detailed TODO list with todo_write
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

Known filename: Use read_file directly
Pattern match: Use glob_file_search (e.g., "*.test.ts")
Semantic search: Use codebase_search (e.g., "authentication logic")
Text search: Use grep for exact text matches

Editing Strategy

Small changes: Use search_replace for precision
New files: Use write_file
Large refactors: Consider sub-agent with task tool

Execution Strategy

Simple commands: Use run_terminal_cmd
Complex workflows: Create shell scripts first
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="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:

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

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] (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

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

**@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")

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

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:

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:

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

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:

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)

# 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

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

# 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

Files: Always use @path/to/file.md
Agents: Always use task(subagent_type="name", ...)
Shell: Always use !`command` for dynamic context
Clarity: Separate files, agents, and tasks into clear sections
Workflow: Always specify the execution order
Agent Names: Plain text only - tester, never @tester
Context First: Load all context before describing the task
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:

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

Scans .opencode/agent/**/*.md files recursively
Parses YAML frontmatter (between --- markers) for config
Uses markdown content as the agent's system prompt
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

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

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

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:

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

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

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)

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

---
tools:
  task: true  # AI should figure out the rest
---

# Your Agent
Delegate complex work to specialized subagents.

The AI should:

✅ See the task tool
✅ Read the tool's description (which lists agents)
✅ 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:
- 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

45 KiB Raw Blame History

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

Core Agents

When to Reference Tools

💡 Complete Example: Index File

Documentation Agents

Planning Agents

🔄 Automated Workflows

After Implementing Code

Before Starting Large Features

📖 Additional Context Files

Code Patterns & Examples

Configuration Files

🎯 Tool Usage Guidelines

File Search Strategy

Editing Strategy

Execution Strategy

⚠️ Common Pitfalls to Avoid

❌ DON'T DO THIS:

✅ DO THIS:

🚀 Quick Start Template

🔄 Standard Workflows

After Code Changes

📚 Reference Files (Load on-demand)

Dynamic File Loading

Conditional Context

Nested Shell Commands with File References

🔗 Shell Command Cheat Sheet

Git Commands

File System Commands

Project Info Commands

Search Commands

System Commands

🎯 Complete Real-World Example

Step 4: Review

Step 5: Documentation

Reference Files (Load on-demand)

Additional Context

Agent: tester

Agent: reviewer

🔄 Required Workflow

🎯 Your Task

⚠️ Important Reminders

Agent: tester

Agent: reviewer

🔄 Required Workflow

🎯 Task Details

⚠️ Important Rules

✅ GOOD PROMPT (Clear)

🎨 Prompt Templates by Use Case

Template 1: Simple Feature Implementation

Template 2: Complex Feature with Agents

Template 3: Code Review Task

Template 4: Documentation Task

🔑 Golden Rules for Perfect Prompts

🎯 REAL-WORLD EXAMPLE: Your Agent Setup

Your Agent Files Structure & Naming

❌ WRONG: Confusing Prompt

✅ CORRECT: Clear Prompt

45 KiB

Raw Blame History

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

Agent: `tester`

Agent: `reviewer`

Agent: `tester`

Agent: `reviewer`