chore: bootstrap .memory/ project knowledge files

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
2026-03-09 12:27:12 +00:00
parent 2b2dd11575
commit 20b7ef0ea6
5 changed files with 353 additions and 0 deletions
--- a/.memory/research/opencode-architecture.md
+++ b/.memory/research/opencode-architecture.md
@@ -0,0 +1,106 @@
+# 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