dotfiles/.config/opencode/.memory/knowledge/overview.md

Project Overview

This is the OpenCode agentic configuration for a multi-agent coding workflow. It defines agent roles, permissions, quality pipelines, and project memory conventions used across all projects that load this config.

• Config root: ~/.config/opencode/
• Config file: opencode.jsonc — defines default agent, plugins, global permissions, and MCP servers.
• Agent definitions: agents/*.md — one file per agent with YAML frontmatter (model, permissions, temperature) and markdown instructions.
• Memory system: .memory/ — persistent project knowledge, decisions, plans, and research in markdown.
• Cross-tool instruction files: AGENTS.md is the single real instruction file; CLAUDE.md, .cursorrules, and .github/copilot-instructions.md are symlinks to it.

Agent Architecture

10 agents with distinct roles, models, and permission profiles. See Agent Roster in AGENTS.md for the full table.

Permission Model

• Full edit access: lead, coder, librarian.
• Memory-only edit access: reviewer, tester, explorer, researcher, critic, sme, designer — these agents have permission.edit: allow but are instructed to keep code/source edits read-only. Their edit permission exists solely to support .memory/* writes for recording duties (verdicts, discoveries, research, guidance, design decisions).
• No edit access: none (all agents can write .memory/*).

See Decision: Agent Memory Write Access for rationale and guardrails.

Memory Write Guardrails

Agents with memory-only edit access are constrained by instruction-level guardrails (not path-scoped config, which OpenCode does not support):

1. Each agent's instructions explicitly state: ".memory/* writes are allowed for [specific duty]; code/source edits remain read-only."
2. Each agent's instructions list tool restrictions (e.g., "Disallowed: non-memory file edits").
3. The permission.edit: allow fallback is necessary because OpenCode's permission.edit does not support path-scoped allow/deny syntax.

Quality Pipeline

Tiered pipeline (Tier 1/2/3) defined in agents/lead.md. Standard flow: explorer/researcher → coder → reviewer → tester → librarian.

Documentation Skill Conventions

• skills/doc-coverage/SKILL.md section ### 3. Instruction File validates one canonical instruction file (AGENTS.md) plus symlink correctness for CLAUDE.md, .cursorrules, and .github/copilot-instructions.md, rather than treating all four as independently edited files.
• The checklist explicitly flags duplication of .memory/ tracking content (plans/research) inside instruction files as an anti-pattern.

See Cross-Tool Instruction Files and Doc coverage checklist section 3.