Joao Melo

Posted on May 18

Deep Dive into OpenCode Agent Orchestration

#ai #opensource #productivity #agents

The evolution of AI coding assistants has rapidly shifted from single-prompt chat interactions to autonomous, multi-agent systems. At the forefront of this movement is OpenCode, a terminal-native AI engine built to read, write, test, and debug code directly within your local environment.

While standard AI tools handle simple, isolated edits, solving complex software tickets—such as a multi-layered codebase refactor, writing matching integration tests, or updating complex deployment pipelines—requires orchestration. By dividing responsibilities into Agents, Sub-agents, Tools, and Skills, the OpenCode ecosystem provides an enterprise-ready blueprint for true software autonomy.

The Four Pillars of Agentic Autonomy

To build an automated workflow, you must understand how its core layers pass context and execute logic.

1. Primary Agents (The Project Leads)

Primary agents are the high-level controllers that you interface with during a terminal session. They maintain the overarching goal of the task and map out the step-by-step strategy.

Build Mode: The default primary agent. It operates with full tool write privileges (file operations, system terminal access) and is optimized for heavy implementation.
Plan Mode: A restricted, read-only primary agent. It is designed purely for architectural analysis, brainstorming, and code review. It defaults to "ask before writing," ensuring it won't alter your filesystem while plotting a migration strategy.

2. Sub-agents (The Specialized Contractors)

A primary agent's main bottleneck is its context window; loading massive dependency files or heavy documentation can cause the model to lose track of the core objective. Sub-agents are temporary, highly isolated assistants spun up to execute highly focused micro-tasks.

@explore: A lightning-fast, read-only sub-agent built solely to navigate large codebases and locate files or specific structural patterns.
@scout: A dedicated research sub-agent that safely clones external repositories or pulls down upstream documentation into a managed cache, cross-referencing logic without cluttering your local environment.

3. Custom Tools (The Hands)

Tools are the deterministic functions and shell hooks that bridge an agent's reasoning loop with your physical system. When an AI generates a structured command, the underlying harness converts it into a concrete action, such as executing localized scripts or custom database query checkers stored inside your project's .opencode/tools/ folder.

4. Custom Skills (The Blueprints)

While tools are functional mechanisms, Skills represent specialized domain knowledge. Defined via the cross-platform Agent Skills Open Standard, these are structured SKILL.md markdown files containing YAML frontmatter that teach agents how to execute a workflow according to specific rules.

Real-World Architecture: The Automated Garage Platform

To see how these four pillars interact outside of theoretical abstractions, consider a real-world project: an Automated Garage & Maintenance Platform. This custom local stack is designed to track vehicle telemetry, manage analytics dashboards on Google Cloud, and orchestrate heavy vehicle detailing logs.

Instead of relying on a generic LLM that might mix up infrastructure code with chemical equations, the environment is orchestrated using custom OpenCode components.

       [User Prompt]
             │
             ▼
     @garage-lead (Agent)
             │
      ┌──────┴────────────────────────┐
      ▼                               ▼
@gcp-provisioner (Sub-agent)    @detailing-planner (Sub-agent)
      │                               │
      ├─► [cloud-native-standards]    ├─► [surface-prep-guidelines]
      │   (Skill)                     │   (Skill)
      │                               │
      └─► terraform_apply()           └─► query_inventory()
          (Tool)                          (Tool)

The Custom Setup

The Custom Agent (@garage-lead): The master coordinator. It is injected with a high-level system prompt via AGENTS.md to understand vehicle diagnostics and infrastructure boundaries, routing incoming tasks to specialized sub-agents.
The Custom Sub-agents: * @gcp-provisioner: A sub-agent restricted entirely to the /infrastructure directory, tasked with handling cloud deployments.
- @detailing-planner: A domain-specific sub-agent engineered to sequence vehicle restoration, paint protection steps, and chemical ratios.
The Custom Tools: Bespoke local scripts exposed to the AI, including read_obd2_telemetry() (extracting temperature and exhaust errors from a local diagnostic database), query_inventory() (checking active stocks of parts and detailing products), and a restricted terraform_apply() hook.
The Custom Skills: Bound via localized markdown files to inject strict operational guardrails:
- cloud-native-standards: Forces the infrastructure sub-agent to ensure any new cloud services are isolated to internal traffic and use proper service accounts.
- surface-prep-guidelines: Hardcodes strict domain-specific physical rules. It instructs the agent that V-Floc is a neutral pH shampoo (never to be used as an all-purpose cleaner/APC) and explicitly dictates that V-04 and Sinergy are entirely different products, preventing chemical layering hallucinations.

The Execution Loop

When a user inputs: "Check the vehicle telemetry, provision a dashboard for the data, and build a detailing checklist for the weekend," the orchestrator executes a multi-threaded autonomous loop:

@garage-lead triggers read_obd2_telemetry() to assess the vehicle's cooling and exhaust metrics.
The agent dispatches @gcp-provisioner, which reads the cloud-native-standards skill and uses terraform_apply() to safely stand up an internal analytics dashboard on Google Cloud.
Simultaneously, @detailing-planner wakes up, calls query_inventory() to check available products, pulls the surface-prep-guidelines skill, and generates a precise step-by-step cleaning log—ensuring the interior APC teardown and the neutral pH exterior wash happen in the exact sequence required to avoid material damage.

OpenCode vs. Claude Code: Quick Comparison

For engineering teams evaluating terminal-native automation, OpenCode and Anthropic's Claude Code share similar design principles, but their execution philosophies differ:

Architectural Component	OpenCode Framework	Claude Code CLI
Model Integration	Fully model-agnostic; supports 75+ cloud and local engines (Ollama, OpenRouter).	Proprietary ecosystem; heavily optimized for Anthropic's native Claude models.
The Skills Standard	Natively implements the cross-platform Agent Skills Open Standard (`SKILL.md`).	Developed the initial Agent Skills Open Standard for progressive token context reduction.
Tool Execution	Executes localized scripts, binary hooks, and raw shell commands out of the box.	Integrates heavily with the Model Context Protocol (MCP) to talk to local or remote servers.
Task Isolation	Relies on community plugins or wrapper workspaces (e.g., Superset) for multi-branch tasks.	Natively splits complex tasks into parallel executions using automated Git worktrees.

Summary

Modern software automation is shifting away from simple text completion toward structured agent networks. As demonstrated by the automated garage platform, separating high-level strategy (Primary Agents) from isolated research (Sub-agents), and pairing execution mechanics (Tools) with architectural rules (Skills) allows developers to step back from manual code writing and step into the role of a systems manager over a highly efficient AI factory.

DEV Community