Brydon DeWitt 6b07e4ccb2 feat: add shared agent infrastructure (.agents/)

- 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

2026-05-22 13:13:43 -04:00

2.7 KiB

Raw Blame History

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/:

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:

# 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.

2.7 KiB Raw Blame History