Agents Reference

The agent architecture is designed around delegation and file-based persistence. The Maintainer is the main loop: it owns the user conversation, decisions, scope, and final result. Subagents keep expensive context bounded, with durable artifacts and compact summaries carrying context between sessions.

Primary Agent

maintainer

The main-loop orchestrator. Handles user interaction, planning decisions, scope, the final result, and Git operations.

What it does:

• Loads skills automatically based on what you're asking for
• Delegates expensive exploration to subagents
• Keeps context lean by receiving digests instead of full outputs
• Persists curated documentation to docs/ and uses plans/ proportionally for multi-phase, multi-session, explicitly requested, or durably coordinated/tracked work
• Routes detailed planning and execution scope decisions through their owning skills, obtains material user-owned decisions before dependent work, owns plan updates/reductions through update-plan, and enforces any optional review gate once invoked
• Coordinates user-attended browser-walkthrough journeys in the main loop while optionally retaining a Delegate for bounded browser segments; routes automated acceptance to Implementer and agent-observed walkthroughs to Delegate
• Commits only when you ask

When it works itself vs. delegates:

• Works itself: planning decisions, user negotiation, and bounded low-risk changes in known files
• Delegates: focused evidence retrieval, codebase exploration, doc generation, implementation, reviews

Maintainers may directly read scoped source, docs//plans/, symbols, and compact targeted results. They keep uncurated bulk evidence out of the owning context: reliable focused filters are used when sufficient, while large logs, verbose command/test output, generated dumps, mass-search output, and evidence requiring broad assembly route to retriever.

Subagents

delegate

The one canonical, skill-driven persona and standard choice for normal delegation involving reasoning, synthesis, reviews, and skill-defined artifacts. Skills provide task expertise, scope authority, workflow, write boundaries, and output contracts; the persona does not duplicate those operational rules.

Typical tasks:

• Codebase exploration
• Running commands (tests, builds, verification)
• Analyzing data or logs
• Research and synthesis
• Agent-observed browser journeys through browser-walkthrough

Write boundary: delegate is read/analyze/verify by default. It may write skill-defined artifacts with explicit output paths/templates, such as reviews and implementation plans. Larger ad-hoc writes with undefined shape/targets should start with an informal Blueprint for primary approval. Code changes normally route to implementer; delegates do not perform Git operations.

Each phase implementation plan uses one fresh Delegate session. The Maintainer invokes phases sequentially, and each later phase delegate reads completed prior artifacts rather than inheriting an increasingly expensive authoring session.

review-fix applies explicitly accepted, evidence-backed defects using an eligible existing session that produced the review or diagnosis; a review artifact is supported but not required. Reuse that source session only when its retained context/output is correct and sufficient, so already-secured evidence is not collected again. Faulty, insufficient, or unavailable context routes to a fresh appropriate workflow with the finding source as a hint, never as claimed inherited context. The Primary's explicit instruction naming accepted defects and scope authorizes one bounded pass without a token, may assign bundled findings across multiple eligible source sessions, and decides whether materially new risk warrants an independent re-review. Plan-review findings remain primary-owned through update-plan.

For multiple implementation-plan reviews, the maintainer defaults to one reviewer session that is fresh from the authoring work, not one reviewer per phase. The reviewer works sequentially in dependency order, reuses consolidated evidence, writes each per-phase review artifact, records material cross-phase conflicts only in affected artifacts, and returns one compact aggregate digest. Parallel per-phase reviewers and nested phase-oriented retriever fan-out are not defaults; oversized review is divided only into contiguous dependency/domain groups with a central cross-partition interface check.

Delegates and reviewers send separable low-complexity evidence gathering and trivial task chains to retriever by default, even when raw input is large, and may call doc-explorer only for genuinely documentation- or module-oriented child tasks. They may directly read scoped source, authoritative docs/plans, symbols, and compact targeted evidence; after a Retriever summary they inspect only specific referenced gaps instead of repeating broad retrieval. The parent owns iterative analysis, source judgment, synthesis, verdicts, severity, scope interpretation, and final artifacts.

Model: Configured via config.yaml. Defaults to provider's choice if not set.

Why it exists: The built-in general uses the provider's default model. delegate uses your configured model — cheaper, faster, and predictable for routine tasks.

retriever

A disposable, non-editing intelligent evidence worker for scoped information-gathering instructions from maintainers, delegates, or implementers. It may perform trivial chains such as multi-file reads with dedicated extraction, search followed by Markdown extraction, grouped commands, and requested web/browser retrieval. Raw input size does not change this routing. It returns the concise requested information summary with concrete paths, symbols, line references, and command or source evidence rather than concatenated contents.

retriever does not edit, create workflow artifacts, assign verdicts or severity, make caller-owned decisions, or delegate further. Concision is usefulness-driven; there is no universal hard numeric read or output cap. Numeric tool truncation remains a safety net, not the routing rule.

Bounded sessions requiring iterative analysis, source judgment, synthesis, or decisions beyond straightforward retrieval remain canonical Delegate work; a configured delegate-fast is the lighter choice.

Maintainers and workers directly read scoped source, docs/plans, symbols, and compact targeted results. A reliable focused filter may reduce raw evidence when it preserves the needed facts; otherwise broad searches, large or verbose output, generated dumps, and coherent multi-file evidence go to retriever with a focused question.

doc-explorer

Docs-focused subagent for project documentation and selected template-governed planning artifacts.

Doc Explorer is the documentation-specialized Delegate. It sends separable broad evidence and trivial task chains to retriever, retains documentation judgment and artifact ownership, and directly follows up only on specific referenced gaps.

Writes to:

• docs/ — project documentation
• plans/ — selected framework planning artifacts when explicitly routed by relevant skills

Does NOT write: Code files or ad-hoc analysis writeups; use delegate for those. Implementation plans default to the canonical delegate via author-and-verify-implementation-plan.

Used by: generate-docs and update-docs; it may provide bounded evidence or mechanical assistance to create-plan/update-plan/generate-handover, but the primary owns plan decisions, the handover narrative, and reduction remediation.

implementer

Executes exactly one phase/work package following the gated two-call protocol. Start a fresh Implementer for each package.

The implementer directly reads scoped source, docs/plans, symbols, and compact targeted results, and uses retriever for separable bulk or coherent multi-file evidence while retaining ownership of its Blueprint, edits, and verification. In BLUEPRINT it uses native parallel reads for compact independent results and retriever for broad, large, or exploratory evidence. BLUEPRINT remains command-free and may include a concise non-binding Package Sizing Note; only the Maintainer may approve the full package or issue a smaller fresh one. In EXECUTE, potentially verbose output is spooled under /tmp/opencode/, and checkpoints follow approved Blueprint steps or bounded parts of a large step.

execute-work-package owns the Implementer's detailed scope, completeness, underspecification, and configurable-value behavior. The persona only routes the role and protocol.

Protocol: BLUEPRINT → GATE → EXECUTE → DIGEST

BLUEPRINT and EXECUTE for that package always use the same compact task_id: the second turn depends on the inspection and approval context retained from the first. The session retires after the digest except for one narrow review-fix continuation: it may remediate explicitly accepted defects of that same completed package when retained context/output is correct and sufficient. It may not continue into another phase/package or remain active indefinitely.

Does:

• Proposes step lists (blueprint mode)
• Proposes advisory natural sizing cuts when useful, without choosing or executing a split
• Implements changes and stages verification: smallest targeted tests while changing/fixing, then the approved broad/full command as the final gate
• Runs approved automated browser acceptance through browser-walkthrough
• Returns compact digests

Does NOT:

• Git operations (commit, push, rebase)
• Write to docs/ or plans/

legacy-curator

Handles legacy repo cleanup before generating fresh docs.

Does:

• Moves scattered documentation to docs-legacy/
• Generates docs-legacy/summary.md

Does NOT: Commit changes (you review and commit).

Delegation Philosophy

Scope and review posture

No Gold-Plating. No Adversarial Reviewing. No Scope Creep. Maintainers and delegates should pursue evidence-backed problems, not invent improvements, hunt for gotchas, or broaden the objective. Related files, call sites, integration points, and tests remain discoverable when they are required for accepted work. Real defects must still be reported and fixed.

Why delegate instead of doing everything in the primary?

Context limits. The primary reads a lot during exploration — file contents, search results, tool outputs. Most of it isn't needed long-term. Delegating keeps the primary lean.

Cost predictability. Subagents run on your configured model. The primary can use a frontier model for planning; subagents can use cheaper models for routine work.

Separation of concerns. Subagents write according to workflow ownership: docs-focused artifacts, skill-defined review/implementation-plan artifacts, or one gated code work package. The Maintainer orchestrates and owns the conversation, decisions, scope, and final result.

Raw command-output spooling

Potentially verbose commands spool their complete output to a predictable path under /tmp/opencode/. The owning maintainer, delegate/reviewer, or implementer retains the path, command, exit status, and compact metadata or decisive evidence. It can use a reliable focused filter or ask retriever to inspect the complete artifact. The spool aids continuation after an agent or process interruption on the same machine, but it is temporary and is not reboot-durable.

When to use retriever, delegate, or general

Stateful delegate reuse

Resume a delegate task_id for follow-up on the same thread, a narrower drill-down, small added context, or eligible review-fix remediation from that session's review or diagnosis. For remediation, correctness and sufficiency of retained context—not mere availability—control reuse; otherwise start the appropriate fresh workflow with a finding-source hint. Phase implementation-plan authoring remains one fresh Delegate per phase. Work-package execution remains one fresh Implementer per package, with post-digest reuse allowed only for accepted defects of that same completed package through review-fix. Changed objectives, model/variant changes, and independent opinions require fresh sessions. task_ids are session-local; durable continuity belongs in files when a persistent workflow exists.

Batch implementation-plan review is another deliberate reuse case: the reviewer starts independently from the author, then keeps its session across the ordered phases because shared evidence and cross-phase reasoning are review inputs. Separate reviewers are exceptions for explicit independent perspectives, unrelated domains, specialist requirements, or impractical combined context—not an automatic phase fan-out.

Aborted delegate recovery

Work likely to exhaust one session should be split before delegation by focused question, dependency group, or bounded work package. If a started subagent returns no usable digest, the maintainer neither resumes the bloated session nor absorbs the remainder. It resolves checkpoint_path(task_id), inspects the selected log and current working tree, maps last attempted/next announced work to the approved Blueprint when present or the original delegated objective otherwise, and issues a smaller fresh task that begins from current state. This uses existing evidence rather than a new handoff, digest state, recovery schema, or automatic split.

Checkpoint telemetry may lag the active turn. Capacity and cost decisions use only reported input usage and input K-tokens. Across providers, approximately 205k input tokens are a soft planning signal; at or above approximately 272k, agents stop expanding work and use the remaining budget for a coherent checkpointed digest or handoff. The 372k rejection boundary is emergency headroom, not a working target. Unknown telemetry stays unknown.

When to use delegate variants

Additional delegates (delegate-strong, delegate-fast, etc.) are generated model aliases of agents/delegate.md, not separate personas. They let you change capacity without duplicating task expertise:

> use delegate-strong for this review
> use delegate-fast for this routine analysis

See Installation → Additional Delegate Variants for setup.

Agent Routing

You ──prompt──▸ @maintainer ──delegates──▸ subagents
                    │                         │
                    │  skills loaded           │  writes to disk
                    │  automatically           │  returns digest
                    ▼                         ▼
               docs/ & proportional     code changes
               plans/ persistence       (maintainer commits
                                         when you ask)

Delegation targets:
  retriever ........ disposable straightforward evidence collection
  delegate ......... reasoning, synthesis, reviews, implementation plans
  doc-explorer ..... documentation-specialized Delegate
  implementer ...... one code work package (gated execution)
  legacy-curator ... docs-legacy/ archive
  general (built-in) second opinion, user-requested

Maintainers call retriever at delegation level 1. Delegates, reviewers, implementers, and Doc Explorer use it at level 2 for separable evidence; delegates may also call doc-explorer for documentation/module child tasks. OpenCode v1.18.2+ requires top-level subagent_depth: 2; older versions do not support that setting. See Installation → Nested Delegation.

The file structure IS the durable interface. Framework docs persist in docs/; work that needs multi-phase or multi-session coordination, explicit planning, or durable tracking persists in plans/. A bounded self-contained package may instead go directly to execute-work-package with an inline gated brief containing task, DoD, constraints, and final verification. No magic durable state—just explicit files or the approved compact execution session.