# Agent Definition Files

Each `.md` file here defines a custom OpenCode agent (prompt, model,
permissions).

## ⚠️ Symlink required

OpenCode only loads agents from `.opencode/agents/` (or
`~/.config/opencode/agents/`). Files here are **not loaded automatically**. Each
file must be symlinked using a **two-level relative path** from
`.opencode/agents/`:

```bash
cd .opencode/agents
ln -s ../../.agents/agents/<name>.md <name>.md
```

> **Do NOT use three `../` levels.** `.opencode/agents/` is two levels below the
> repo root, not three. A wrong-depth path creates a broken symlink that
> silently fails — OpenCode will not error, the agent simply won't load.

Current symlinks (verify with `ls -la .opencode/agents/`):

| Agent file        | Symlinked?                            |
| ----------------- | ------------------------------------- |
| `build.md`        | ✅ `.opencode/agents/build.md`        |
| `orchestrator.md` | ✅ `.opencode/agents/orchestrator.md` |
| `brainstorm.md`   | ✅ `.opencode/agents/brainstorm.md`   |
| `research.md`     | ✅ `.opencode/agents/research.md`     |

When you add a new agent here, add its symlink and update this table.

## Verification

After adding or changing an agent, run the following to confirm OpenCode can
read it:

```bash
# 1. Confirm symlink resolves (should print file contents, not an error)
cat .opencode/agents/<name>.md | head -5

# 2. Confirm OpenCode registers the agent with correct permissions
opencode agent list

# Check that your agent appears with the right mode (all/primary/subagent)
# and that deny rules are present at the bottom of its permission list.
# If it's missing: broken symlink, YAML frontmatter parse error, or OpenCode
# was not restarted after the change.
```

Expected output for `orchestrator` after a correct setup:

```
orchestrator (all)
  [
    ...
    { "permission": "edit", "action": "deny", "pattern": "*" },
    { "permission": "bash", "action": "deny", "pattern": "*" }
  ]
```

## Invoking custom agents

- **Tab**: cycles through `primary` and `all`-mode agents as the active session
  agent
- **`@mention`**: invokes an agent — but only at the **start of a fresh
  session**. Sending `@orchestrator ...` after already exchanging messages in a
  Build session causes the current model to process the text as freeform input.
  Open a new session first, then `@mention` as the first message.
- **CLI**: `opencode run --agent orchestrator "your prompt"` — reliable,
  session-agnostic invocation for scripting or testing.

## Permission config

`opencode.json` `agent.<name>.permission` only applies if a matching markdown
file is loaded. Without the symlink, permission config for that agent is
silently ignored.