Brydon DeWitt
6b07e4ccb2
- AGENTS.md: design principles, enforcement hierarchy, deferred loading - agents/: brainstorm, build, orchestrator, research (auto-discovered by MCP server) - skills/: research methodology (auto-discovered by MCP server) - hooks/: pre-tool-use, post-tool-use (BFF block removed), session-start, stop, pre-compact, user-prompt-submit - frameworks/: opencode/plugin.ts (resolves hooks via import.meta.url — works as project-local or global plugin), github/hooks.json - mcp/index.ts: auto-discovers agents/*.md and skills/*.md from frontmatter (replaces hand-maintained registry); server renamed all-agents - docs/: agent-infrastructure.md (generalized), research docs (7 files), ai_architectures.md, llama-server-cuda-wsl2.md - install.sh: idempotent setup — Copilot global hooks, OpenCode global plugin + AGENTS.md + MCP entry, VS Code global MCP config
78 lines
2.7 KiB
Markdown
78 lines
2.7 KiB
Markdown
# 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.
|