# The OpenCode Agent System Blueprint _Build Intelligent Workflow Systems with Context-Aware AI_ --- ## 📘 What Is This Blueprint? **This is a teaching document** that explains how the OpenCode agent system works and how to extend it for your needs. **You don't need to read this to use the system** - the agents work out of the box. Read this document only if you want to: - Understand the architecture behind the system - Create your own custom agents and commands - Extend the system with domain-specific patterns - Learn how context loading and agent coordination works **If you just want to start building**, skip this document and use `openagent` instead. See the [README.md](../../README.md) for quick start instructions. --- ## ⚡ TL;DR - Quick Reference **For New Users:** - Start with `opencode --agent openagent` for all questions and tasks - The agent handles planning, implementation, testing, and review automatically - Add your coding patterns to `.opencode/context/project/project-context.md` - Let the agent delegate to specialized subagents when needed **For Advanced Users Building Custom Agents:** - Use `/prompt-enchancer` to create complex agents with workflows - Read this document to understand architecture patterns - Learn how context loading works (the `@` symbol) - Extend the system with domain-specific context files **Core Concept:** ``` Commands load context → Agents execute with that context → Subagents handle specialized tasks ``` **When to read this document:** - ✅ You want to create custom agents or commands - ✅ You need to understand how context loading works - ✅ You want to extend the system for your specific needs - ❌ You just want to start building (use `openagent` instead) --- ## 🎯 What This Document Teaches This blueprint explains the architecture patterns behind the OpenCode agent system. You'll learn: - How context loading works (the `@` symbol) - How agents, commands, and context files work together - How to create custom agents and commands - How to extend the system for your needs > **📖 Installation & Usage:** See [README.md](../../README.md) in the repository root. --- ## Understanding Examples in This Document **When you see commands like `/workflow`, `/plan-task`, `/create-frontend-component`:** - These are pattern examples showing how you COULD structure commands - Most aren't implemented in the repository - The existing `openagent` and `opencoder` already handle these workflows - Create them only if you have specific repeated patterns **When you see extensive context hierarchies:** - The repository includes `core/` and `project/` context files - Add domain-specific files (`frontend/`, `backend/`, `database/`) as needed - Start simple, expand based on your needs **When you see task management structures:** - The `task-manager` agent creates `tasks/` directories automatically - `openagent` creates session files in `.tmp/sessions/` for context preservation - No need to pre-create structures --- ## The Golden Rule **Context flows in one direction: Commands load context immediately, Agents can look up additional context deterministically.** Think of it 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 ### 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. **Example command structure:** - Command file references context files using `@.opencode/context/...` - OpenCode reads those files automatically - Context is injected 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 Is Powerful **Without @ loading:** - Agent doesn't know your patterns - Has to search or use generic patterns - Inconsistent results, slower execution **With @ loading:** - Agent has your patterns loaded immediately - Follows your exact standards - Consistent, fast, high-quality results ### Best Practices for Context Loading 1. **Load 2-4 context files maximum** - Prevent cognitive overload 2. **Always include core patterns** - Essential patterns every agent needs 3. **Load domain-specific patterns** - Based on what the command does 4. **Keep context files focused** - 50-150 lines each 5. **Use conditional loading** - Load different context based on request analysis ### Why This Architecture Matters - **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** - Commands are "smart loaders", agents are "focused executors" - **It guides best practices** - Load the right context, not too much, not too little --- ## Core Principles ### 1. Single-Level Context Loading OpenCode processes `@` references only in command templates, NOT recursively in file contents. - ✅ Works: `@` references in command files - ❌ Doesn't work: `@` references inside context files (treated as plain text) **Implication:** Commands must load ALL necessary context upfront. 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** - Plus request-specific context --- ## The System Components ### 1. Commands (.opencode/command/) **What they do:** Entry points that load context based on request analysis **Examples:** - `/commit` - Smart git commits - `/optimize` - Code optimization - `/test` - Testing workflows - `/prompt-enchancer` - Improve prompts and create complex agents **How they work:** - User types a command - Command analyzes the request - Loads appropriate context files using `@` - Passes everything to an agent - Agent executes with full context ### 2. Agents (.opencode/agent/) **What they do:** AI workers with specific capabilities and predictable behavior **Main agents in this repo:** - `openagent` - Universal coordinator for general tasks, questions, and workflows (recommended default) - `opencoder` - Specialized development agent for complex coding and architecture - `system-builder` - Meta-level generator for creating custom AI architectures **Subagents (specialized helpers):** Core Coordination: - `task-manager` - Task breakdown and planning - `documentation` - Documentation authoring Code Specialists: - `coder-agent` - Quick implementations - `reviewer` - Code review and security - `tester` - Test creation and validation - `build-agent` - Type checking and validation - `codebase-pattern-analyst` - Pattern discovery Utilities: - `image-specialist` - Image generation (Gemini AI) System Builder (Meta-Level): - `domain-analyzer` - Domain analysis - `agent-generator` - Agent generation - `context-organizer` - Context organization - `workflow-designer` - Workflow design - `command-creator` - Command creation **Agent structure:** - Frontmatter with metadata (description, mode, tools, permissions) - Clear instructions for behavior - Specific rules and constraints - Structured response formats ### 3. Context (.opencode/context/) **What it is:** Layered knowledge system with your coding patterns **Structure:** - `core/` - Essential patterns (always loaded) - `project/` - Your project-specific patterns - Add more as needed: `frontend/`, `backend/`, `database/`, etc. **How it works:** - Context files contain your coding standards - Commands load relevant context using `@` - Agents follow those patterns automatically - Single-level loading (no recursive references) **Best practices:** - Keep files focused (50-150 lines) - Use clear pattern names - Include when to use each pattern - Add rules and constraints ### 4. Task Management (tasks/) **What it is:** File-based progress tracking with checkboxes **Structure:** - `features/` - Feature development - `fixes/` - Bug fixes - `improvements/` - Code improvements - `single/` - Simple tasks **How it works:** - `task-manager` creates task files automatically - Each task has a plan with checkboxes - Agents update progress as they work - Quality gates ensure standards are met ### 5. Workflow Orchestration **How agents coordinate:** - Simple tasks (< 30 min) - Direct execution - Medium tasks (30min-2hrs) - Task planning with tracking - Complex tasks (> 2hrs) - Multi-phase with quality gates **Quality gates:** - Build validation (TypeScript, linting) - Code review (security, quality) - Testing (automated tests) - Post-flight review (compliance check) --- ## System Flow **Simple workflow:** 1. User makes request 2. Agent analyzes and plans 3. User approves 4. Agent implements step-by-step 5. Validation runs automatically 6. Complete **Complex workflow:** 1. User makes request 2. Agent delegates to `@task-manager` 3. Task manager creates detailed plan 4. Agent implements one step at a time 5. Progress tracked in task files 6. Quality gates at milestones 7. Subagents handle specialized work 8. Post-flight review 9. Complete --- ## Context Loading Strategy ### Dynamic Context Loading Commands can load different context based on request analysis: - Analyze the user's request - Determine domain (frontend, backend, database, etc.) - Load base context (core patterns) - Load domain-specific context conditionally - Pass everything to agent ### Context Size Guidelines - ✅ **Optimal**: 50-150 lines (focused, actionable) - ⚠️ **Acceptable**: 150-250 lines (comprehensive but manageable) - ❌ **Too Large**: 250+ lines (split into focused files) ### Context Loading Rules 1. Always load core patterns 2. Maximum 4 context files per command 3. Load based on request analysis (dynamic, not static) 4. Use bash commands for conditional loading --- ## Building Your Own Agents ### Use /prompt-enchancer **If you're building custom agents with complex workflows, use the `/prompt-enchancer` command:** - Helps you create well-structured agent prompts - Guides you through best practices - Ensures proper formatting and instructions - Creates agents that work well with the system **How to use it:** ``` /prompt-enchancer "I want to create an agent that does X" ``` The command will help you: - Structure your agent properly - Add appropriate context loading - Define clear instructions - Set up permissions and tools - Create workflow patterns ### Agent Design Best Practices 1. **Make agents deterministic** - Predictable behavior 2. **Give clear, direct instructions** - Not documentation 3. **Separate concerns** - One agent, one responsibility 4. **Use structured response formats** - Consistent output 5. **Define permissions** - Control what agents can do 6. **Specify tools** - Only give access to what's needed ### When to Create Custom Agents Create custom agents when: - You have repeated workflows - You need specialized behavior - You want domain-specific expertise - You have unique quality requirements Don't create custom agents when: - `openagent` or `opencoder` already handles it - It's a one-time task - You're just starting out --- ## Extending the System ### Adding Domain-Specific Context 1. Create context directory for your domain 2. Add pattern files (50-150 lines each) 3. Reference in commands using `@` 4. Agents automatically use your patterns **Example domains:** - Frontend (React, Vue, etc.) - Backend (APIs, servers) - Database (queries, schemas) - Testing (unit, integration) - Security (auth, validation) ### Creating Custom Commands 1. Identify repeated workflows 2. Determine what context is needed 3. Create command file with `@` references 4. Specify target agent 5. Add clear instructions 6. Test and refine **Use `/prompt-enchancer` to help create complex commands.** ### Building Specialized Subagents 1. Identify specialized capability needed 2. Define clear scope and responsibility 3. Set appropriate permissions 4. Create focused instructions 5. Test with main agents --- ## 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 ### Agent Design - Make agents deterministic (predictable behavior) - Give clear, direct instructions (not documentation) - Separate concerns (one agent, one responsibility) - Use structured response formats - **Use `/prompt-enchancer` for complex agents** ### 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) --- ## The Simple Path (Recommended) **Don't create specialized commands/agents right away. Instead:** 1. **Start with `openagent`** for everything (questions and tasks) 2. **Add context files** for your tech stack as needed 3. **Use `@task-manager`** when features get complex (openagent delegates automatically) 4. **Let subagents** handle specialized work (@tester, @reviewer, @coder-agent) 5. **Create specialized commands** only when you have repeated workflows 6. **Use `/prompt-enchancer`** when building custom agents ### Example Progression **Week 1:** Use `openagent` for everything (questions and tasks) **Week 2:** Add project-specific context to `project/project-context.md` **Week 3:** Agent automatically picks up your patterns **Week 4:** Create a command if you have repeated workflows (use `/prompt-enchancer`) ### How the System Improves The system improves naturally as you: 1. Add context files - Capture your coding patterns 2. Refine agent prompts - Improve instructions based on results 3. Create project-specific commands - Automate repeated workflows 4. Build subagents - Extract specialized capabilities 5. Document in context/ - Every pattern you discover **The key principle:** Start simple, extend only when you have a clear need. --- ## Project Structure ``` .opencode/ ├── agent/ # AI agents │ ├── openagent.md │ ├── opencoder.md │ ├── system-builder.md │ └── subagents/ # Specialized helpers │ ├── reviewer.md │ ├── tester.md │ ├── coder-agent.md │ ├── documentation.md │ ├── build-agent.md │ └── codebase-pattern-analyst.md ├── command/ # Slash commands │ ├── commit.md │ ├── optimize.md │ ├── test.md │ ├── clean.md │ ├── context.md │ ├── prompt-enchancer.md # Use this to build agents! │ └── worktrees.md ├── context/ # Coding patterns │ ├── core/ # Essential patterns (always loaded) │ │ └── essential-patterns.md │ └── project/ # Your patterns (add here!) │ └── project-context.md ├── plugin/ # Optional: Telegram notifications └── tool/ # Optional: Gemini AI image tools ``` --- ## Key Takeaways 1. **Context flows one direction** - Commands load immediately, Agents look up deterministically 2. **Keep context focused** - 50-150 lines per file, maximum 4 files per command 3. **Make agents predictable** - Deterministic behavior with clear instructions 4. **Track everything** - File-based task management with checkbox progress 5. **Validate continuously** - Quality gates and post-flight reviews 6. **Start simple** - Build core system first, add complexity gradually 7. **Use `/prompt-enchancer`** - When building custom agents with workflows --- ## Remember _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._ _The `openagent` is your universal coordinator and `opencoder` is your senior developer. Add specialists only when needed._ _When you need to build custom agents, use `/prompt-enchancer` to create well-structured, complex agents with proper workflows._