oh-my-openkilo

# Agents

oh-my-openkilo ships **6 agents** in `agents/`. Each is a single markdown file: YAML frontmatter at the top (name, mode, model, variant, permissions) and a prompt body. Edit the file to change behavior, edit the `model:` line to swap models, edit `permissions:` to change the allowlist. No build step.

The pack divides the team into **2 primary agents** (you talk to them directly) and **4 subagents** (primaries fan out work to them in parallel). Two of OpenCode's built-in agents are disabled to avoid duplication: `build` (replaced by `builder`) and `plan` (replaced by `planner`).

## Quick reference

| # | Agent | Mode | Default model | When to use |
|---|-------|------|---------------|-------------|
| 01 | `builder` | primary | `opencode/muse-spark-1.3-contributor-free` | Default implementation. Triage, fan-out. |
| 02 | `planner` | primary | `opencode/muse-spark-1.3-contributor-free` | Pre-impl design, architecture, plan files. |
| 03 | `designer` | subagent | `opencode/muse-spark-1.3-contributor-free` | UI/UX, design system, a11y. Multimodal preferred for visual work. |
| 04 | `tester` | subagent | `opencode/muse-spark-1.3-contributor-free` | Test suites: write, run, isolate failures. |
| 05 | `reviewer` | subagent | `opencode/muse-spark-1.3-contributor-free` | Diff + security review. Read-only. |
| 06 | `documenter` | subagent | `opencode/muse-spark-1.3-contributor-free` | README, runbook, API docs in `docs/`. |

---

## Primary agents

### 01. `builder` — The Architect

**Role:** Default implementation agent. Triage incoming work: trivial fixes get done directly, anything that needs design gets routed to `planner`, anything that needs specialized hands gets fanned out to subagents.

**When to invoke:** any coding task, especially anything that touches more than one file or has multiple valid approaches.

**Prompt:** [`agents/builder.md`](../agents/builder.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** any strong instruction-following coding model. Swap to `anthropic/claude-sonnet-4-5`, `openai/gpt-5` if you have provider credentials and want higher quality on complex tasks.

**Model guidance:** `builder` is a generalist that delegates. It does not need your strongest reasoning model; it needs a model that's good at following delegation rules and not jumping to code before the design is settled. Free models are fine for everyday work.

**Permissions:** allowlist in frontmatter — `read`, `edit`, `shell`, `glob`, `grep`, `todowrite`, `subagent` (designer/tester/reviewer/documenter), `agentmemory_*`, `webfetch`, `websearch`, `lsp`, `skill`, `question`; everything else denied.

**Dispatched by:** you, directly. `builder` is the default agent when you start a session.

**Dispatches to:** `planner` (complex design), `designer` (UI), `tester` (tests), `reviewer` (security/quality), `documenter` (docs). Integration/merge/conflicts: handled inline (git).

---

### 02. `planner` — The Oracle

**Role:** Pre-implementation design partner. Reads the brief, gathers codebase evidence via `graphify query`/`graphify path` and native `webfetch`/`websearch`, then writes a plan you confirm before any code is touched. The "think before you ship" agent.

**When to invoke:** new feature, big refactor, architecture decision, anything where you'd otherwise waste an hour coding the wrong thing.

**Prompt:** [`agents/planner.md`](../agents/planner.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** strong reasoning and planning models. Worth paying for: `anthropic/claude-sonnet-4-5`, `openai/gpt-5` (or any long-context model for big repos).

**Model guidance:** `planner` does the high-leverage work — it decides what to build and how. A weak model here means a weak plan, which means wasted implementation time downstream. If you mix free + paid, this is the agent to upgrade first.

**Permissions:** allowlist in frontmatter — `read`, `edit`, `glob`, `grep`, `todowrite`, `subagent` (reviewer only), `chrome-devtools_*`, `agentmemory_*`, `perplexity_*`, `webfetch`, `websearch`, `lsp`, `skill`, `question`; `shell` limited to graphify/git/rm commands, everything else denied (no direct `shell`; planning happens in markdown files)

**Dispatched by:** you, directly, or by `builder` when it judges a task is too complex to implement without design.

**Dispatches to:** `reviewer` (during analysis), with `designer`, `tester`, `documenter` recommended in the plan for the parent to run.

---

## Subagents

### 03. `designer` — The Frontend Specialist

**Role:** UI/UX, React/Next.js, design systems, accessibility, frontend performance. Visual reviews and frontend polish via screenshots when available; falls back to text-only feedback otherwise.

**When to invoke:** new screen, design exploration, brand consistency check, frontend perf audit, accessibility review.

**Prompt:** [`agents/designer.md`](../agents/designer.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** strong UI/UX judgment + frontend implementation. Good fits: `anthropic/claude-sonnet-4-5`, `google/gemini-2.5-pro`.

**Model guidance:** Choose a model that is strong at UI/UX judgment, frontend implementation, and visual polish. Multimodal is a plus because the agent reviews screenshots and mockups.

**Permissions:** allowlist in frontmatter — `read`, `edit`, `shell`, `glob`, `grep`, `todowrite`, `chrome-devtools_*`, `agentmemory_*`, `shadcn_*`, `reactbits_*`, `magicuidesign*`, `webfetch`, `websearch`, `lsp`, `skill`; no subagents, everything else denied.

**Required MCP:** none. Multimodal model recommended for visual work; text-only is fine for design review and a11y.

**Dispatched by:** `builder` or `planner` when the task involves UI/UX work.

---

### 04. `tester` — The Quality Gate

**Role:** Writes test suites, runs them, iterates failures in isolation. Reports compact results: which tests pass, which fail, which are flaky, what's the next action. Never mixes "write the feature" with "test the feature".

**When to invoke:** you just wrote code that needs coverage, or a CI test is failing locally and you want a systematic isolation loop instead of guessing.

**Prompt:** [`agents/tester.md`](../agents/tester.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** reliable test-running model. Good fits: any `opencode/*` or `anthropic/*` model with solid bash execution. No need for a frontier model.

**Model guidance:** `tester` runs shell commands a lot (test runners, fixtures, isolation). Pick a model that handles `bash` reliably and is comfortable reading test output, not one that's good at "creative" reasoning.

**Permissions:** allowlist in frontmatter — `read`, `edit`, `shell`, `glob`, `grep`, `todowrite`, `agentmemory_*`, `skill`; no subagents, no web, everything else denied.

**Dispatched by:** `builder` after implementation, or by you when a test fails.

---

### 05. `reviewer` — The Diff Detective

**Role:** Read-only code + security review. Compares a diff against the repo's standards and the originating spec. Catches things you missed: race conditions, missing error handling, security smells, off-by-one, wrong abstractions. Never edits.

**When to invoke:** you finished a chunk of work and want a sanity check before merging, or you're about to touch auth/data and want a second pair of eyes.

**Prompt:** [`agents/reviewer.md`](../agents/reviewer.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** strong reasoning + security awareness. Worth paying for on auth/data paths: `anthropic/claude-sonnet-4-5`, `openai/gpt-5`.

**Model guidance:** `reviewer` reads code and produces a verdict, not a fix. It benefits from a model that's good at finding edge cases and security smells, not from raw code generation speed. For security-sensitive work (auth, crypto, payments), upgrade to your strongest model.

**Permissions:** allowlist in frontmatter — `read`, `glob`, `grep`, `shell`, `webfetch`, `websearch`, `lsp`, `skill`; read-only by design (no `edit`, no subagents, no MCP tools)

**Dispatched by:** `builder` and `planner` for sanity checks, or by you via "Ask `reviewer` to look at this diff".

---

### 06. `documenter` — The Technical Writer

**Role:** Creates and improves documentation in `docs/`, verified against the actual code (not vibes). Useful for READMEs, runbooks, onboarding guides, API docs. Will not write docs that lie about what the code does.

**When to invoke:** you shipped a new module and the README is lying, you need a how-to for a tricky setup, or you want API docs that match the current behavior.

**Prompt:** [`agents/documenter.md`](../agents/documenter.md)

**Default model:** `opencode/muse-spark-1.3-contributor-free`

**Recommended models:** long-context writing model. Good fits: `anthropic/claude-sonnet-4-5` (or any long-context model for big codebases).

**Model guidance:** Documentation work rewards context. The agent reads code, summarizes it, and produces prose. A 1M-context model means it can hold a whole repo in mind while writing; a small-context model means it makes things up.

**Permissions:** allowlist in frontmatter — `read`, `edit`, `glob`, `grep`, `agentmemory_*`, `webfetch`, `websearch`, `skill`; no `shell`, no subagents, everything else denied

**Dispatched by:** `builder` when implementation touches user-facing surfaces, or by you directly.

---

## Built-in OpenCode agents (disabled)

The pack disables two of OpenCode's built-in agents to avoid duplication:

- `build` is replaced by `builder`
- `plan` is replaced by `planner`

To re-enable them, edit your `opencode.json` and remove the corresponding `disabled: true` entries under `agents`.

## How to invoke

In a normal OpenCode session, you can either:

- Let `builder` pick the right subagent automatically (most common).
- Be explicit: "Ask `tester` to write tests for the auth module", "Have `reviewer` sanity-check this diff", "Have `designer` review the UI for a11y".

Subagents are also dispatched by `builder` and `planner` via the `subagent` tool, in parallel when the subtasks are independent.

## How to change a model

1. Open the agent's `.md` file under `~/.config/opencode/agents/` (the file the installer copied; same as the source in `agents/`).
2. Edit the `model:` line. Use the format `<provider>/<model>` (e.g. `anthropic/claude-sonnet-4-5`, `openai/gpt-5`).
3. Save and run `/reload` (or restart OpenCode).

`variant:` (reasoning effort) sits in the same frontmatter block as `model:`. The pack ships it tuned per role; defaults and how to adjust are in [Reasoning effort](#reasoning-effort). (`temperature:` was dropped: OpenCode V2 ignores the legacy key.)

Free models are good for everyday work but slower and less capable than paid ones. If you have provider credentials configured in `opencode.json`, a useful split is:

- **Cheap/free for:** `tester`, `documenter`
- **Pay for:** `builder`, `planner`, `designer`, `reviewer` (especially on auth/data paths)

## Reasoning effort

Agent frontmatter sets `variant` (how much the model reasons before answering) per agent. The pack ships it tuned per role:

| Agent | `variant` | Why |
|-------|-----------|-----|
| `builder` | `xhigh` | Max reasoning depth for build quality. |
| `planner` | `xhigh` | Deep reasoning for architecture. |
| `reviewer` | `high` | One notch down for speed; stable, repeatable findings. |
| `tester` | `medium` | Iteration speed matters in test-fix loops. |
| `documenter` | `low` | Docs need fluency, not deep reasoning; cheapest and fastest. |
| `designer` | `medium` | Medium reasoning for a11y and system calls. |

Reasoning effort is a direct latency and cost multiplier: every notch down means fewer reasoning tokens per turn. Raise `variant` back to `xhigh` on any agent where the output quality drops. Restart OpenCode after editing, since frontmatter is read at session start.

## Adding a new agent

See [CONTRIBUTING.md](../CONTRIBUTING.md#adding-a-new-agent--skill--rule). New agents are typically subagents specialized for one job that the existing 6 don't cover well.

More agent context in PanPanFR/oh-my-openkilo

54 other files this repository gives its agents.