Skip to content

agents-playbook.md

Latest commit

 

History

History
290 lines (202 loc) · 8.71 KB

agents-playbook.md

File metadata and controls

290 lines (202 loc) · 8.71 KB

Agents Playbook 🧠

This guide explains how the custom agents in this repo work, when to use each one, and how they fit into real OpenCode workflows.

Goal: keep execution fast, safe, and low-friction while preserving the current default (build). ⚡

Quick summary table 📋

Agent Type Main job Can edit code? Best moment to use
build primary (default) Direct implementation Yes Small/clear tasks, quick fixes
orchestrator primary Lead complex multi-step delivery + delegate specialists Yes Medium/large tasks, end-to-end execution
explore subagent Internal codebase discovery and pattern finding No "Where is X?" / multi-module discovery
librarian subagent External docs and OSS evidence lookup No Framework/library behavior, upstream examples
oracle subagent High-signal architecture/debug review No Hard tradeoffs, repeated failed attempts
verifier subagent Run/interpret tests, lint, build No After meaningful code changes
reviewer subagent Risk/correctness/maintainability review No Before declaring done
release-scribe subagent PR/changelog/release notes drafting No Final communication and release prep

Agent model for this repo 🧭

  • build remains the default for speed and familiarity.
  • orchestrator is the execution lead for bigger flows.
  • Specialist subagents are intentionally read-only to reduce accidental drift.
  • Completion should only happen after implementation + validation + review gates pass.
  • Model allocation defaults and fallbacks are documented in docs/model-allocation-policy.md.

Architecture and safety contracts:

  • docs/agent-architecture.md
  • docs/agent-tool-restrictions.md

Think of it as:

orchestrator -> delegates research/review tasks -> executes changes -> validates -> reports

How to select agents (Tab menu) ⌨️

In OpenCode prompt:

  1. Press Tab
  2. Pick agent (build, plan, or orchestrator)
  3. Run your prompt normally

Our custom specialist subagents are intentionally marked hidden, so they stay out of the Tab switcher and are used through delegation or explicit @agent mention instead.

You can verify available agents with:

opencode agent list

Validate agent contract + runtime wiring with:

This now also verifies orchestration policy markers in the nearest AGENTS.md (quickplay + WT checklist + pressure defaults).

/agent-doctor
/agent-doctor --json

Runtime discoverability commands:

/agent-catalog list
/agent-catalog explain orchestrator
/agent-catalog doctor --json

When these hints appear automatically in execution flow:

  • delegation router injects /agent-catalog explain <subagent> when it infers or applies routing metadata
  • fallback orchestrator injects /agent-catalog list + explain hint when it rewrites a failed delegation path

Real usage examples 🛠️

1) Small bug fix (stay on build)

Use when issue is isolated and file location is clear.

Example prompt:

Fix the null-check bug in auth token parsing and run relevant tests.

Why: minimal overhead, direct implementation is fastest.

2) Multi-file feature (switch to orchestrator)

Use when request spans multiple modules and requires verification/review.

Example prompt:

Implement end-to-end support for workspace profile presets, including docs and tests.
Keep iterating until done or a concrete blocker.

Expected flow:

  • orchestrator may ask explore to map impacted files
  • implements changes
  • uses verifier for checks
  • uses reviewer before final done claim

3) External library behavior confusion (use librarian)

Example prompt:

Find official docs and upstream examples for OpenCode agent file format and summarize best practice for read-only subagents.

Expected output:

  • sources with links
  • concise recommendation
  • tradeoffs/notes

4) Architecture decision under uncertainty (use oracle)

Example prompt:

Review this plan: replace default build flow with orchestrator globally.
Assess risks, migration strategy, and rollback plan.

Expected output:

  • one recommended path
  • key risks
  • concrete next steps + effort sizing

5) Pre-merge validation gate (use verifier + reviewer)

Example prompt:

Validate this branch and give me a ship/no-ship recommendation.
Run the fastest high-signal checks first, then broaden if needed.

Expected output:

  • exact commands + results
  • issue list by severity
  • single best next action

6) PR and release communication (use release-scribe)

Example prompt:

Draft PR summary + changelog bullets from this branch diff.
Include testing notes and user-facing impact.

Expected output:

  • concise PR summary
  • Adds/Changes/Fixes/Removals bullets
  • release-note style blurb

When to use build vs orchestrator ⚖️

Use build when:

  • scope is clear
  • <= 2 files touched
  • no external research needed

Use orchestrator when:

  • cross-module task
  • unknown code ownership/locations
  • non-trivial validation/review needed
  • you want "continue iterating until done"

Suggested handoff rules for consistent results 🔁

For non-trivial work:

  1. orchestrator starts
  2. explore if 2+ modules or unclear ownership
  3. strategic-planner when sequencing or milestone order is unclear
  4. ambiguity-analyst when assumptions, acceptance criteria, or scope boundaries are still fuzzy
  5. librarian if external behavior matters
  6. implementation by orchestrator with a single writer by default
  7. verifier for checks
  8. reviewer final risk pass
  9. release-scribe if PR/release text needed

Escalate to oracle when:

  • 2+ failed fix attempts
  • architecture/security/performance tradeoff is ambiguous

Planner bundle examples:

  • explore + strategic-planner: when you know work is large but need file/sequence mapping first
  • explore + ambiguity-analyst: when requirements are incomplete and the main need is unknown surfacing
  • strategic-planner + plan-critic: when the plan exists but sequencing, feasibility, or testability still need stress-testing
  • after planner fan-out, return to one writer unless explicit reservations make parallel writers safe

Planner + reservation example:

git worktree add ../my_opencode-wt-planning -b feat/planning-slice HEAD
/reservation set --own-paths "docs/**" --active-paths "docs/**,agent/**" --writer-count 1
Select `orchestrator`
Delegate `explore` + `strategic-planner` to map docs and sequencing
If scope is still fuzzy, add `ambiguity-analyst`
Implement with one writer in the linked worktree
/reservation clear

Use this when planning work needs a real reserved path boundary before implementation starts.

When not to use each agent 🚫

Agent Avoid when
orchestrator task is trivial and single-file with no delegation need
explore external documentation research is primary
librarian only internal code discovery is needed
oracle straightforward implementation is already clear
verifier design/architecture decisions are needed instead of command execution
reviewer no meaningful diff exists to review
release-scribe implementation/debugging is needed rather than communication output
strategic-planner immediate coding is required and plan is already concrete
ambiguity-analyst scope is already unambiguous and execution can proceed directly
plan-critic task is too early for critique (no concrete plan exists yet)

Guardrails and expectations 🛡️

  • Read-only subagents must not edit files.
  • Runtime hook guard blocks delegated commit/PR/edit intents for read-only subagents; keep mutating operations on the primary agent.
  • Do not declare done without validation evidence.
  • If blocked, return exact blocker + evidence + next best action.
  • Prefer practical outcomes over over-engineering.

Installation and sync notes 🔧

  • Agent files are stored in this repo under agent/*.md.
  • Source-of-truth specs live in agent/specs/*.json and generate agent/*.md via scripts/build_agents.py.
  • Installer copies them to ~/.config/opencode/agent/.
  • build remains default via opencode.json (default_agent: build).

Generation commands:

python3 scripts/build_agents.py --profile balanced
python3 scripts/build_agents.py --profile balanced --check

If agents are not visible, run:

REPO_URL="/path/to/my_opencode" REPO_REF="main" ./install.sh
opencode agent list

TL;DR 🎉

  • Keep build for quick tasks.
  • Use orchestrator for complex "keep going" execution.
  • Use specialist subagents for focused read-only discovery, validation, review, and release communication.