The OpenCode Agent System Blueprint

Build Intelligent Workflow Systems with Context-Aware AI

The Golden Rule

Context flows in one direction: Commands load context immediately, Agents can look up additional context deterministically.

Like a well-organized library: the librarian (command) brings you the right books immediately, but you (agent) can look up specific references when needed.

How @ Symbol Context Loading Works (FUNDAMENTAL)

The Magic of Automatic Context Injection

When you create a slash command with @ references, OpenCode automatically loads that context into the agent's memory BEFORE the agent starts thinking:

# .opencode/command/create-component.md

---

name: create-component
agent: simple-coder

---

You are creating React components following our patterns.

**Request:** $ARGUMENTS

@.opencode/context/frontend/react-patterns.md
@.opencode/context/styling/design-system.md
@.opencode/context/core/validation-patterns.md

Create the component now.

What happens when user types /create-component "user profile card":

✅ OpenCode reads the command file
✅ Automatically loads react-patterns.md, design-system.md, validation-patterns.md
✅ Injects all context into the agent's working memory
✅ Agent receives: user request + all loaded context + instructions
✅ Agent can immediately use patterns without looking them up

Why This Mechanism Is Powerful

❌ Without @ loading:

Agent: "I need to create a component but don't know your patterns. Let me search..."
→ Agent uses generic patterns or has to look up files
→ Inconsistent results, slower execution

✅ With @ loading:

Agent: "I have your React patterns, design system, and validation rules loaded. Creating component..."
→ Agent immediately follows your exact patterns
→ Consistent, fast, high-quality results

Context Loading Strategy

Base Context (Always Load):

@.opencode/context/core/essential-patterns.md
@.opencode/context/architecture/project-structure.md

Domain-Specific Context (Load Based on Command Purpose):

# Frontend commands

@.opencode/context/frontend/react-patterns.md
@.opencode/context/styling/design-system.md

# Backend commands

@.opencode/context/backend/server-patterns.md
@.opencode/context/database/query-patterns.md

# Testing commands

@.opencode/context/testing/test-patterns.md

Dynamic Context Loading

# Advanced: Conditional context based on request analysis

@.opencode/context/core/essential-patterns.md
!`if echo "$ARGUMENTS" | grep -i "component\|ui" > /dev/null; then echo "@.opencode/context/frontend/react-patterns.md"; fi`
!`if echo "$ARGUMENTS" | grep -i "database\|query" > /dev/null; then echo "@.opencode/context/database/query-patterns.md"; fi`

Best Practices for @ Context Loading

Load 2-4 context files maximum (prevent cognitive overload)
Always include core patterns (essential-patterns.md)
Load domain-specific patterns based on command purpose
Keep context files focused (50-150 lines each)
Use conditional loading for dynamic context selection

Why This Architecture Matters

Understanding @ symbol auto-loading is crucial because:

It's the foundation of how agents get consistent context
It determines command design - you must anticipate what context agents need
It explains the architecture - why commands are "smart loaders" and agents are "focused executors"
It guides best practices - load the right context, not too much, not too little

This mechanism is what makes the system "intelligent" - agents always start with the right knowledge instead of having to discover it.

Core Principles

1. Single-Level Context Loading

OpenCode processes @ references only in command templates, NOT recursively in file contents.

# ✅ This works (in command template)

@.opencode/context/frontend/patterns.md
@.opencode/context/styling/design-system.md

# ❌ This doesn't work (inside patterns.md file)

# If patterns.md contains @other-file.md, it's treated as plain text

Critical Implication: Commands must load ALL necessary context upfront using @ references. Agents can look up additional files using tools (read, grep, glob), but cannot use @ loading themselves.

2. Deterministic vs Non-Deterministic Behavior

Commands: Non-deterministic - analyze requests and load appropriate context
Agents: Deterministic - predictable behavior, can look up additional context

3. Context Optimization

Maximum 4 context files per command (250-450 lines total)
50-150 lines per context file (optimal range)
Always load core patterns + request-specific context

The 5-Part Intelligent System

1. Commands (.opencode/command/)

What: Entry points that load immediate context based on request analysis Rule: Commands are non-deterministic - they adapt context to the request

/workflow                    → Intelligent routing with dynamic context
/plan-task                   → Task planning with architecture context
/execute-task               → Step execution with progress tracking
/create-frontend-component  → UI development with styling + frontend context
/create-backend-operation   → Server logic with backend + database context
/create-database-operation  → Database queries with focused database context
/review-completion          → Quality assurance with minimal context
/validate-with-tests        → Automated testing with testing context

Command Structure Pattern:

---
name: command-name
agent: target-agent
description: "What this command does"
---

You are [doing specific task]. [Direct instructions to agent].

**Request:** $ARGUMENTS

**Your Instructions:**

1. **ANALYZE** the request...
2. **IMPLEMENT** following patterns...
3. **VALIDATE** the results...

**Context Loaded:**
@.opencode/context/core/essential-patterns.md
@.opencode/context/[domain]/[specific-patterns].md
@.opencode/context/architecture/architecture-lite.md

**Success Criteria:**

- [Specific measurable outcomes]

Execute this [task type] now.

2. Agents (.opencode/agent/)

What: Deterministic AI workers with specific capabilities Rule: Agents can look up additional context but are predictable in behavior

Primary Agents:
├── workflow-orchestrator.md  → Routes requests and analyzes complexity
├── task-planner.md           → Creates detailed task plans with file tracking
├── task-executor.md          → Executes planned steps systematically
├── post-flight-reviewer.md   → Reviews completed work for compliance
└── simple-coder.md           → Implements focused development tasks

Subagents (Specialized):
├── subagents/code-reviewer.md    → Security and quality reviews (read-only)
├── subagents/test-writer.md      → Test creation and validation (reports issues)
├── subagents/pattern-finder.md   → Discovers existing implementations
└── subagents/doc-writer.md       → Documentation creation and updates

Agent Structure Pattern:

---
description: "What this agent does"
mode: primary|subagent
model: claude-4-sonnet
temperature: 0.1-0.3
tools:
  read: true|false
  edit: true|false
  write: true|false
  bash: true|false
  task: true|false
permissions:
  edit:
    "**/*.env*": "deny"
    "**/*.secret": "deny"
---

You are [specific role]. [Direct instructions for behavior].

**EXECUTE** this [process type] for every [task type]:

**1. [ACTION]** the [subject]:

- [Specific instruction 1]
- [Specific instruction 2]

**2. [ACTION]** the [subject]:

- [Specific instruction 1]
- [Specific instruction 2]

**RULES**:

- **ALWAYS** [critical requirement]
- **NEVER** [forbidden action]
- **ONLY** [scope limitation]

Execute [task type] now.

3. Context (.opencode/context/)

What: Layered knowledge system with focused domains Rule: Single-level loading - no recursive context references

context/
├── core/
│   └── essential-patterns.md    (76 lines - always loaded)
├── architecture/
│   └── architecture-lite.md     (74 lines - project structure)
├── frontend/
│   ├── frontend-patterns.md     (230 lines - React patterns)
│   └── styling/design-system.md (122 lines - UI standards)
├── backend/
│   ├── backend-patterns.md      (326 lines → split into focused files)
│   └── server-actions.md        (100 lines - focused server action patterns)
├── database/
│   └── database-queries.md      (207 lines - query patterns)
├── security/
│   └── security-patterns.md     (205 lines - auth patterns)
├── testing/
│   ├── testing-patterns.md      (322 lines → split)
│   └── unit-testing.md          (100 lines - focused test patterns)
└── debugging/
    └── common-errors.md          (304 lines → split by error type)

Context File Structure Pattern:

**[ACTION]** [subject] using these exact patterns:

**[PATTERN NAME]** - [When to use]:

```[language]
// Example code with clear comments
// Showing exactly what to do
```

[ANOTHER PATTERN] - [When to use]:

// Another example

RULES:

ALWAYS [critical requirement]
NEVER [forbidden action]
USE [specific tools/methods]


### 4. Task Management (tasks/)
**What:** File-based progress tracking with checkbox systems
**Rule:** Every complex task gets a plan file with step-by-step tracking

tasks/ ├── features/ # Feature development │ └── [feature-name]/ │ ├── task-plan.md # Main plan with checkboxes │ ├── execution-log.md # Detailed progress log │ └── review-report.md # Post-flight review ├── fixes/ # Bug fixes │ └── [issue-name]/ │ ├── task-plan.md │ └── fix-report.md ├── improvements/ # Code improvements │ └── [improvement-name]/ └── single/ # Simple tasks └── [task-name].md


**Task Plan File Structure:**
```markdown
# Task: [Task Name]

## Overview
**Request**: [Original user request]
**Complexity**: [Simple/Medium/Complex]
**Estimated Duration**: [Time estimate]
**Dependencies**: [List any blocking requirements]

## Task Breakdown

### Phase 1: [Phase Name]
- [ ] **Step 1.1**: [Specific action]
  - **Agent**: @[agent-name]
  - **Context**: [Required context files]
  - **Validation**: [How to verify completion]
  - **Duration**: [Time estimate]

- [ ] **Step 1.2**: [Specific action]
  - **Agent**: @[agent-name]
  - **Context**: [Required context files]
  - **Validation**: [How to verify completion]
  - **Duration**: [Time estimate]

## Quality Gates
- [ ] **Build Validation**: TypeScript compilation passes
- [ ] **Code Review**: Security and quality review completed
- [ ] **Testing**: All tests pass and coverage adequate
- [ ] **Integration**: Feature works end-to-end

## Acceptance Criteria
- [ ] [Specific requirement 1]
- [ ] [Specific requirement 2]

## Progress Tracking
**Started**: [Date/Time]
**Last Updated**: [Date/Time]
**Status**: [Planning/In Progress/Review/Complete]
**Completed Steps**: 0/[Total Steps]

5. Workflow Orchestration

What: Multi-agent coordination with quality gates Rule: Complex workflows use multiple agents with validation checkpoints

Workflow Types:
├── Simple (< 30 min)     → Direct execution with focused context
├── Medium (30min-2hrs)   → Task planning with step tracking
└── Complex (> 2hrs)      → Multi-phase with quality gates

Quality Gates:
├── Build Validation      → TypeScript, linting, build checks
├── Code Review          → Security and quality assessment
├── Testing              → Automated test execution
└── Post-Flight Review   → Instruction compliance verification

System Flow (Intelligent Workflow Management)

flowchart TD
    A[User Request] --> B[Workflow Orchestrator]
    B --> C{Analyze Request}
    C --> D{Complexity?}
    D -->|Simple| E[Direct Execution]
    D -->|Complex| F[Task Planning]

    E --> G[Load Focused Context]
    G --> H[Execute with Agent]
    H --> I[Validate Results]
    I --> J[Complete]

    F --> K[Create Task Plan File]
    K --> L[Step-by-Step Execution]
    L --> M[Update Progress Tracking]
    M --> N{More Steps?}
    N -->|Yes| O[Next Step]
    N -->|No| P[Quality Gates]
    O --> L
    P --> Q[Post-Flight Review]
    Q --> R[Mark Complete]

    style A fill:#E6F3FF
    style J fill:#E6FFE6
    style R fill:#E6FFE6

Context Loading Strategy

Dynamic Context Loading Pattern

# In workflow orchestrator

**ANALYZE** request: "$ARGUMENTS"

**BASE CONTEXT** (always loaded):
@.opencode/context/core/essential-patterns.md
@.opencode/context/architecture/architecture-lite.md

**CONDITIONAL CONTEXT** (based on request analysis):
!`if echo "$ARGUMENTS" | grep -i -E "(component|ui|frontend)" > /dev/null; then echo "@.opencode/context/styling/design-system.md"; fi`
!`if echo "$ARGUMENTS" | grep -i -E "(server|backend|action)" > /dev/null; then echo "@.opencode/context/backend/server-actions.md"; fi`
!`if echo "$ARGUMENTS" | grep -i -E "(database|query|data)" > /dev/null; then echo "@.opencode/context/database/database-queries.md"; fi`

Context Size Guidelines

✅ Optimal: 50-150 lines (focused, actionable patterns)
⚠️ Acceptable: 150-250 lines (comprehensive but manageable)
❌ Too Large: 250+ lines (should be split into focused files)

Context Loading Rules

Always load core patterns (essential-patterns.md + architecture-lite.md)
Maximum 4 context files per command (prevent overload)
Load based on request analysis (dynamic, not static)
Use bash commands for conditional loading

Implementation Guide

Step 1: Create Your Workflow Commands

# Essential Commands to Create:

/workflow # Main entry with intelligent routing
/plan-task # Complex task breakdown
/execute-task # Step-by-step execution
/create-frontend-component # UI development
/create-backend-operation # Server logic
/review-completion # Quality assurance

Step 2: Build Your Agent System

# Core Agents Needed:

workflow-orchestrator.md # Request analysis and routing
task-planner.md # Detailed planning with file tracking
task-executor.md # Step execution with progress updates
post-flight-reviewer.md # Compliance and quality review
simple-coder.md # Focused implementation work

# Specialized Subagents:

subagents/code-reviewer.md # Security and quality (read-only)
subagents/test-writer.md # Test creation (reports issues)

Step 3: Structure Your Context

# Context Organization:

core/essential-patterns.md # Always loaded (76 lines)
architecture/architecture-lite.md # Project structure (74 lines)
frontend/frontend-patterns.md # React patterns (230 lines)
styling/design-system.md # UI standards (122 lines)
backend/server-actions.md # Server patterns (100 lines)
database/database-queries.md # Query patterns (207 lines)

Step 4: Implement Task Management

# Task File Structure:

tasks/features/[name]/task-plan.md # Main planning file
tasks/features/[name]/review-report.md # Post-completion review
tasks/fixes/[name]/task-plan.md # Bug fix planning
tasks/single/[name].md # Simple tasks

Step 5: Add Quality Gates

# Automated Validation:

!`pnpm tsc --noEmit` # TypeScript check
!`pnpm lint` # Code quality
!`pnpm build` # Build validation
!`pnpm test` # Test execution

Best Practices

Context Management

Keep context files focused (50-150 lines)
Use single-level loading (no recursive @ references)
Load dynamically based on request analysis
Always include core patterns + architecture

Agent Design

Make agents deterministic (predictable behavior)
Give clear, direct instructions (not documentation)
Separate concerns (one agent, one responsibility)
Use structured response formats

Task Management

Break complex work into steps (15-30 minutes each)
Use checkbox tracking for progress visibility
Include validation criteria for each step
Implement quality gates at key milestones

Workflow Orchestration

Analyze before routing (complexity and domain)
Use appropriate workflows (simple vs complex)
Coordinate multiple agents for complex tasks
Validate at every step (build, test, review)

System Architecture

graph TB
    subgraph "User Interface"
        CMD["/workflow<br/>/plan-task<br/>/execute-task"]
    end

    subgraph ".opencode/command/"
        C1[workflow.md]
        C2[plan-task.md]
        C3[execute-task.md]
        C4[create-frontend-component.md]
        C5[create-backend-operation.md]
    end

    subgraph ".opencode/agent/"
        A1[workflow-orchestrator.md]
        A2[task-planner.md]
        A3[task-executor.md]
        A4[simple-coder.md]
        A5[post-flight-reviewer.md]
    end

    subgraph ".opencode/context/"
        CTX1[core/essential-patterns.md]
        CTX2[architecture/architecture-lite.md]
        CTX3[frontend/frontend-patterns.md]
        CTX4[backend/server-actions.md]
        CTX5[database/database-queries.md]
    end

    subgraph "tasks/"
        T1[features/[name]/task-plan.md]
        T2[fixes/[name]/task-plan.md]
        T3[single/[name].md]
    end

    CMD --> C1
    CMD --> C2
    CMD --> C3

    C1 --> A1
    C2 --> A2
    C3 --> A3
    C4 --> A4
    C5 --> A4

    A1 --> CTX1
    A1 --> CTX2
    A2 --> CTX2
    A3 --> CTX1
    A4 --> CTX3
    A4 --> CTX4

    A2 --> T1
    A3 --> T1
    A3 --> T2

Using the System (User Guide)

How Slash Commands Work

Slash commands automatically inject context into agents using @ references:

# User types this:
/create-component "user profile card with avatar upload"

# OpenCode automatically:
# 1. Loads the command file: .opencode/command/create-component.md
# 2. Reads all @ referenced context files
# 3. Injects context + user request into the agent
# 4. Agent starts with full knowledge of your patterns

Basic Commands

/workflow "your request" - Main entry point for any development task
/plan-task "complex feature" - For multi-step planning
/execute-task - Continue working on planned tasks

Command Examples

/workflow "Create a user profile component with form validation"
/create-frontend-component "Dashboard header with user menu"
/review-completion - Check completed work for quality

When to Use Which Command

Simple tasks (< 30 min) → /workflow
Complex features → /plan-task then /execute-task
Specialized work → /create-frontend-component, /create-backend-operation

Why This Works Better Than Chat

Consistent patterns: Agents always use YOUR coding standards
Faster execution: No time spent discovering or asking about patterns
Quality results: Context-aware from the first response
Scalable knowledge: Add new patterns once, use everywhere

Quick Start Implementation

1. Start with Core System

# Create essential structure
mkdir -p .opencode/{command,agent,context/{core,architecture}}
mkdir -p tasks/{features,fixes,single}

2. Create Main Entry Point

# .opencode/command/workflow.md

---

name: workflow
agent: workflow-orchestrator

---

You are analyzing requests and routing to optimal workflows.

**Request:** $ARGUMENTS

**Context Loaded:**
@.opencode/context/core/essential-patterns.md
@.opencode/context/architecture/architecture-lite.md

Route to appropriate specialized workflow now.

3. Build Workflow Orchestrator

# .opencode/agent/workflow-orchestrator.md

---

description: "Routes requests to specialized workflows"
mode: primary
tools: [read, grep, glob, task]

---

You are analyzing requests and routing to specialized workflows.

**ANALYZE** the request and **ROUTE** to appropriate command:

- Feature development → /plan-task or /create-frontend-component
- Bug fixes → /fix-issue
- Code review → /review-code

Execute routing now.

4. Add Essential Context

# .opencode/context/core/essential-patterns.md

**CORE PATTERNS** - Essential patterns for all development:

**AUTHENTICATION PATTERN**:

```typescript
const user = await getCurrentUser();
if (!user) return { error: "Unauthorized" };
```

VALIDATION PATTERN:

const validated = schema.safeParse(data);
if (!validated.success) return { error: "Validation failed" };


### 5. Test Your System
```bash
# Test the workflow
/workflow "Create a user profile component"
# Should route to appropriate workflow with right context

Remember

Context flows one direction - Commands load immediately, Agents look up deterministically
Keep context focused - 50-150 lines per file, maximum 4 files per command
Make agents predictable - Deterministic behavior with clear instructions
Track everything - File-based task management with checkbox progress
Validate continuously - Quality gates and post-flight reviews
Start simple - Build core system first, add complexity gradually

Think of this system like a professional development team: each member has a specific role, they communicate clearly, they track their work systematically, and they validate quality at every step.

AGENT-SYSTEM-BLUEPRINT.md 21 KB History Raw

The OpenCode Agent System Blueprint

The Golden Rule

How @ Symbol Context Loading Works (FUNDAMENTAL)

The Magic of Automatic Context Injection

Why This Mechanism Is Powerful

Context Loading Strategy

Dynamic Context Loading

Best Practices for @ Context Loading

Why This Architecture Matters

Core Principles

1. Single-Level Context Loading

2. Deterministic vs Non-Deterministic Behavior

3. Context Optimization

The 5-Part Intelligent System

1. Commands (.opencode/command/)

2. Agents (.opencode/agent/)

3. Context (.opencode/context/)

5. Workflow Orchestration

System Flow (Intelligent Workflow Management)

Context Loading Strategy

Dynamic Context Loading Pattern

Context Size Guidelines

Context Loading Rules

Implementation Guide

Step 1: Create Your Workflow Commands

Step 2: Build Your Agent System

Step 3: Structure Your Context

Step 4: Implement Task Management

Step 5: Add Quality Gates

Best Practices

Context Management

Agent Design

Task Management

Workflow Orchestration

System Architecture

Using the System (User Guide)

How Slash Commands Work

Basic Commands

Command Examples

When to Use Which Command

Why This Works Better Than Chat

Quick Start Implementation

1. Start with Core System

2. Create Main Entry Point

3. Build Workflow Orchestrator

4. Add Essential Context

Remember

AGENT-SYSTEM-BLUEPRINT.md 21 KB

History Raw