alex
20b7ef0ea6
Add initial .memory/ knowledge base for the dotfiles repo: - knowledge.md: full desktop stack, tool configs, keybindings, conventions - decisions.md: architectural choices (Hyprland, Fish, Catppuccin Mocha, Neovim, OpenCode) - research/opencode-architecture.md: detailed OpenCode multi-agent system breakdown
107 lines
4.6 KiB
Markdown
107 lines
4.6 KiB
Markdown
# 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
|