dotfiles/.config/opencode/AGENTS.md

Project Knowledge Graph

You have access to a project knowledge graph via the megamemory MCP server and skill tool. You have no implicit memory of this project between sessions, so this graph is your only continuity for concepts, architecture, decisions, and relationships.

Workflow: understand → work → update

1. Session start: You must call megamemory with action overview (or megamemory:list_roots directly) before you begin work.
2. Before each task: You must call megamemory with action query (or megamemory:understand directly) before reading source files for project understanding.
3. After each task: You must call megamemory with action record to create/update/link concepts for what you built.

Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts max 3 levels deep.

Recording discipline: Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If a concept would only say "we started phase X", don't create it. Megamemory exists to preserve knowledge, not to log activity.

Query discipline:

• Use top_k=3 for megamemory:understand calls unless you have a specific reason to retrieve more. Large result sets bloat context without proportional value.
• Skip understand when the graph has no relevant content. If list_roots already showed no concepts in the relevant domain, do not call understand with rephrased queries hoping for different results.
• Never re-query concepts you just created. After calling create_concept, you already know the content — do not immediately call understand to retrieve it.
• Treat megamemory as a tool, not a ritual. Every query should have a specific information need; if you cannot articulate what you expect to find, skip the query.

Linking is required. When creating or updating concepts, always create edges (megamemory:link) to related existing concepts. A concept with no edges is a dead end — always ask: "What existing concept does this depend on, implement, or connect to?" and link accordingly.

Session Continuity

• Treat megamemory as the persistent tracking system for work across sessions.
• At session start, identify prior in-progress work items and pending decisions before doing new implementation.
• After implementation, record what changed, why it changed, and what remains next.

Clarification Rule

• If requirements are genuinely unclear, materially ambiguous, or have multiple valid interpretations that would lead to materially different implementations, use the question tool to clarify before committing to an implementation path.
• Do not ask for clarification when the user's intent is obvious. If the user explicitly states what they want (e.g., "update X and also update Y"), do not ask "should I do both?" — proceed with the stated request.
• Implementation-level decisions (naming, file organization, approach) are the agent's job, not the user's. Only escalate decisions that affect user-visible behavior or scope.

Agent Roster

Agent	Role	Model
lead	Primary orchestrator that decomposes work, delegates, and synthesizes outcomes.	github-copilot/claude-opus-4 (global default)
coder	Implementation-focused coding agent for reliable code changes.	github-copilot/gpt-5.3-codex
reviewer	Read-only quality gate for correctness and security review.	github-copilot/claude-opus-4.6
tester	Validation agent for standard + adversarial testing and Playwright UI checks.	github-copilot/claude-sonnet-4.6
explorer	Fast read-only codebase mapper for impact surface and dependencies.	github-copilot/claude-sonnet-4.6
researcher	Deep technical investigator across code, docs, and external references.	github-copilot/claude-opus-4.6
librarian	Documentation coverage and accuracy specialist.	github-copilot/claude-opus-4.6
critic	Pre-implementation gate and blocker sounding board.	github-copilot/claude-opus-4.6
sme	Subject-matter expert for domain-specific consultation.	github-copilot/claude-opus-4.6
designer	UI/UX specialist for interaction and visual guidance.	github-copilot/claude-sonnet-4.6

Parallelization

• Always parallelize independent work. Any tool calls that do not depend on each other's output must be issued in the same message as parallel calls — never sequentially. This applies to bash commands, file reads, subagent delegations, and megamemory queries alike.
• Before issuing a sequence of calls, ask: "Does call B require the result of call A?" If not, send them together.

Human Checkpoint Triggers

When implementing features, the Lead must stop and request explicit user approval before dispatching coder work in these situations:

1. Security-sensitive design: Any feature involving encryption, auth flows, secret storage, token management, or permission model changes.
2. Architectural ambiguity: Multiple valid approaches with materially different tradeoffs that aren't resolvable from codebase conventions alone.
3. Vision-dependent features: Features where the user's intended UX or behavior model isn't fully specified by the request.
4. New external dependencies: Adding a service, SDK, or infrastructure component not already in the project.
5. Data model changes with migration impact: Schema changes affecting existing production data.

The checkpoint must present the specific decision, 2-3 concrete options with tradeoffs, a recommendation, and a safe default. Implementation-level decisions (naming, file organization, code patterns) are NOT checkpoints — only user-visible behavior and architectural choices qualify.