dotfiles/.memory/research/opencode-architecture.md

title, type, permalink

title	type	permalink
opencode-architecture	note	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

{
  "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