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:**

```text
.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:

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