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.
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

Use symlinks to share ONE instruction file across all agentic coding tools:

project/
├── .github/
│   └── copilot-instructions.md    # Real file (edit this one)
├── AGENTS.md -> .github/copilot-instructions.md
├── CLAUDE.md -> .github/copilot-instructions.md
└── .cursorrules -> .github/copilot-instructions.md

Rules:

• Edit .github/copilot-instructions.md — changes propagate automatically via symlinks
• Never edit symlinked files directly (changes would be lost)
• Symlinks are committed to git (git tracks them natively)

Content of the instruction file:

• Project overview and purpose
• Tech stack and architecture
• Coding conventions and patterns
• Build/test/lint commands
• Project structure overview

Do NOT duplicate .memory/ contents — instruction files describe how to work with the project, not active plans, research, or decisions.

When initializing a project:

1. Create .github/copilot-instructions.md with project basics
2. Create symlinks: ln -s .github/copilot-instructions.md AGENTS.md (etc.)
3. Commit the real file and symlinks to git

When joining an existing project:

• Read .github/copilot-instructions.md (or any of the symlinked files) to understand the project
• If instruction file is missing, create it and the symlinks

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 code/source review; writes .memory/* for verdict records.	github-copilot/claude-opus-4.6
tester	Validation agent for standard + adversarial testing; writes .memory/* for test outcomes.	github-copilot/claude-sonnet-4.6
explorer	Fast read-only codebase mapper; writes .memory/* for discovery records.	github-copilot/claude-sonnet-4.6
researcher	Deep technical investigator; writes .memory/* for research findings.	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; writes .memory/* for verdicts.	github-copilot/claude-opus-4.6
sme	Subject-matter expert for domain-specific consultation; writes .memory/* for guidance cache.	github-copilot/claude-opus-4.6
designer	UI/UX specialist for interaction and visual guidance; writes .memory/* for design decisions.	github-copilot/claude-sonnet-4.6

All agents except lead, coder, and librarian are code/source read-only but have permission.edit: allow scoped to .memory/* writes for their recording duties. The lead and librarian have full edit access; coder has full edit access for implementation.

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.