alex
33180d6e04
AGENTS.md is now the canonical instruction file, with CLAUDE.md, .cursorrules, and .github/copilot-instructions.md as symlinks to it. This is simpler and more intuitive - the main file is at the root, not buried in .github/. Updated all references across agents, commands, skills, and .memory/.
47 lines
3.1 KiB
Markdown
47 lines
3.1 KiB
Markdown
## 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](../AGENTS.md#agent-roster) 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](decisions.md#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](../AGENTS.md#cross-tool-instruction-files) and [Doc coverage checklist section 3](../skills/doc-coverage/SKILL.md#3-instruction-file).
|
|
|
|
## MCP Servers
|
|
|
|
- **Context7:** Remote documentation lookup (`https://mcp.context7.com/mcp`)
|
|
- **GitHub Grep:** Remote code search across public repos (`https://mcp.grep.app`)
|
|
- **Playwright:** Local headless Chromium for UI testing
|