---
title: opencode-architecture
type: note
permalink: dotfiles/research/opencode-architecture
---

# OpenCode Architecture Research

## Overview

The OpenCode multi-agent configuration lives at `.config/opencode/` and is the most complex subsystem in this dotfiles repo.

## Directory Structure

```
.config/opencode/
├── opencode.jsonc                   # Main config
├── AGENTS.md                        # Global OpenCode config (NOT a symlink here)
├── CLAUDE.md -> .github/copilot-instructions.md  (symlink)
├── .cursorrules -> .github/copilot-instructions.md  (symlink)
├── .github/
│   └── copilot-instructions.md      # Canonical cross-tool instructions
├── agents/
│   ├── lead.md                      # Primary orchestrator (mode=primary, temp=0.3)
│   ├── coder.md                     # Implementation agent
│   ├── reviewer.md                  # Code review (read-only)
│   ├── tester.md                    # Testing/validation
│   ├── explorer.md                  # Codebase mapper
│   ├── researcher.md                # Technical investigator
│   ├── librarian.md                 # Documentation specialist
│   ├── critic.md                    # Plan gate
│   ├── sme.md                       # Domain expert consultant
│   └── designer.md                  # UI/UX specialist
├── .memory/
│   ├── knowledge.md                 # OpenCode-specific architecture knowledge
│   ├── decisions.md                 # Agent permission decisions, symlink strategy
│   ├── plans/                       # Active feature plans
│   └── research/                    # Research findings
└── skills/
    ├── doc-coverage/SKILL.md        # Documentation coverage checklist
    ├── git-workflow/SKILL.md        # Git commit/worktree/PR procedures
    └── work-decomposition/SKILL.md  # Multi-feature decomposition
```

## opencode.jsonc Key Settings

```jsonc
{
  "default_agent": "lead",
  "autoupdate": true,
  "plugin": "@tarquinen/opencode-dcp",
  "agents": {
    "general": { "disabled": true },
    "explore": { "disabled": true },
    "plan": { "permissions": { "write": "allow" } }
  },
  "permissions": {
    "websearch": "allow",
    "question": "allow",
    "external_directory": "deny"
  },
  "mcp": {
    "context7": { "url": "https://mcp.context7.com/mcp", "type": "remote" },
    "gh_grep": { "url": "https://mcp.grep.app", "type": "remote" },
    "playwright": { "command": "npx @playwright/mcp@latest --headless --browser chromium", "type": "local" }
  }
}
```

## Agent Model/Permission Matrix

| Agent | Model | Full Edit | Notes |
|---|---|---|---|
| lead | claude-opus-4 | ✅ | Orchestrator, all task types |
| coder | gpt-5.3-codex | ✅ | Implementation |
| librarian | claude-opus-4.6 | ✅ | Documentation |
| reviewer | claude-opus-4.6 | `.memory/*` only | Read-only code review |
| tester | claude-sonnet-4.6 | `.memory/*` only | Validation |
| explorer | claude-sonnet-4.6 | `.memory/*` only | Codebase mapping |
| researcher | claude-opus-4.6 | `.memory/*` only | Technical research |
| critic | claude-opus-4.6 | `.memory/*` only | Plan gate |
| sme | claude-opus-4.6 | `.memory/*` only | Domain expert |
| designer | claude-sonnet-4.6 | `.memory/*` only | UI/UX |

## Lead Agent Workflow

Phases: CLARIFY → DISCOVER → CONSULT → PLAN → CRITIC-GATE → EXECUTE → PHASE-WRAP

- **Tiered quality pipeline:** Tier 1 (full, new features), Tier 2 (standard), Tier 3 (fast, trivial)
- **Worktrees:** `.worktrees/<feature-name>` per feature branch
- **Retry circuit breaker:** 3 coder rejections → redesign; 5 failures → escalate
- **Commit format:** Conventional Commits (`feat:`, `fix:`, `chore:`, etc.)
- **Parallelization:** mandatory for independent work

## Memory Pattern

- `.memory/` tracked in git for cross-session persistence
- Agents with `.memory/*` write permission record directly (instruction-level enforcement)
- Structure: `knowledge.md` (architecture), `decisions.md` (design choices), `plans/<feature>.md`, `research/<topic>.md`

## Cross-Tool Instruction Files

- `.github/copilot-instructions.md` = single source of truth
- `CLAUDE.md` and `.cursorrules` = symlinks
- `AGENTS.md` = NOT a symlink in this repo (serves as global OpenCode config)
- **Note:** In OTHER projects, `AGENTS.md` should be a symlink. The OpenCode config dir is a special case.

## Skills

- **doc-coverage:** Validates canonical instruction file + symlinks; checks README + docs/* coverage
- **git-workflow:** Step-by-step git commit, worktree, and PR creation procedures  
- **work-decomposition:** Splits 3+ feature requests into independent workstreams with separate worktrees