dotfiles/.config/opencode/AGENTS.md

Project Memory

Use markdown files in .memory/ as the persistent project memory across sessions. This is the source of truth for architecture, decisions, plans, research, and implementation state.

Directory structure:

.memory/
  knowledge.md      # Persistent project knowledge (architecture, patterns, key concepts)
  decisions.md      # Architecture decisions, SME guidance, design choices
  plans/            # One file per active plan/feature
    <feature>.md    # Plan with tasks, statuses, acceptance criteria
  research/         # Research findings
    <topic>.md      # Research on a specific topic

Workflow: read files → work → update files

1. Session start: Read .memory/ directory contents and skim .memory/knowledge.md. Also check for cross-tool instruction files (CLAUDE.md, .github/copilot-instructions.md, .cursorrules) — they may contain project knowledge added by other tools.
2. Before each task: Read relevant .memory/*.md files before reading source files for project understanding.
3. After each task: Update the appropriate .memory/*.md files with what was built.

Be specific in summaries: include parameter names, defaults, file locations, and rationale. Keep concepts organized as markdown sections (## Heading) and keep hierarchy shallow.

Recording discipline: Only record outcomes, decisions, and discoveries — never phase transitions, status changes, or ceremony checkpoints. If an entry would only say "we started phase X", don't add it. Memory files preserve knowledge, not activity logs.

Read discipline:

• Read only the .memory/ files relevant to the current task; avoid broad re-reads that add no new signal.
• Skip redundant reads when .memory/ already has no relevant content in that domain this session.
• Do not immediately re-read content you just wrote. You already have that context from the update.
• Treat .memory/ as a tool, not a ritual. Every read should have a specific information need.

Linking is required. When recording related knowledge across files, add markdown cross-references (for example: See [Decision: Auth](decisions.md#auth-approach)). A section with no references becomes a dead end.

Cross-Tool Instruction Files

• Maintain tool-specific instruction files so multiple agentic coding tools share the same project working context.
• Required instruction files:
  • AGENTS.md (OpenCode)
  • CLAUDE.md (Claude Code)
  • .github/copilot-instructions.md (GitHub Copilot)
  • .cursorrules (Cursor)
• These files should contain the same core project knowledge: purpose, stack, conventions, commands, and structure.
• .memory/knowledge.md is the source of truth; instruction files are derived views for tool consumption.
• When project knowledge changes significantly, update all cross-tool instruction files.
• When initializing or bootstrapping a project, create all cross-tool instruction files.
• Do not duplicate .memory/ internals in these files; they describe how to work with the project, not project tracking state.
• Read existing instruction files at session start or when joining a new project. Other tools/people may have added project knowledge to CLAUDE.md or .cursorrules that isn't yet in .memory/. Merge any new knowledge into .memory/knowledge.md as the canonical source.

Session Continuity

• Treat .memory/ files 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, update .memory/ files with 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, and subagent delegations 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.