dotfiles/.config/opencode/AGENTS.md

# OpenCode Global Workflow

## Operating Model

- Default to `planner`. Do not implement before there is an approved plan.
- `planner` owns discovery, decomposition, verification oracles, risk tracking, and the handoff spec.
- `builder` executes the approved spec exactly, delegates focused work to subagents, and escalates back to `planner` instead of improvising when the spec breaks.
- Parallelize aggressively for research, exploration, review, and isolated implementation lanes. Do not parallelize code mutation when lanes share files, APIs, schemas, or verification steps.
- Use explicit `allow` or `deny` permissions only. Do not rely on `ask`.
- Keep `external_directory` denied. Real project repos may use repo-local `/.worktrees`, but this global config must not relax that rule.

## Agent Roster

| Agent | Mode | Model | Responsibility |
| --- | --- | --- | --- |
| `planner` | primary | `github-copilot/gpt-5.4` | Produce approved specs and decide whether execution is ready |
| `builder` | primary | `github-copilot/gpt-5.4` | Execute approved specs and integrate delegated work |
| `researcher` | subagent | `github-copilot/gpt-5.4` | Deep research, external docs, tradeoff analysis |
| `explorer` | subagent | `github-copilot/claude-sonner-4.6` | Fast read-only repo inspection and fact gathering |
| `reviewer` | subagent | `github-copilot/claude-opus-4.6` | Critique plans, code, tests, and release readiness |
| `coder` | subagent | `github-copilot/gpt-5.3-codex` | Implement narrowly scoped code changes |
| `tester` | subagent | `github-copilot/gpt-5.4` | Run verification, triage failures, capture evidence |
| `librarian` | subagent | `github-copilot/claude-opus-4.6` | Maintain docs, `AGENTS.md`, and memory hygiene |

## Planner Behavior

- `planner` must use the `question` tool proactively when scope, defaults, approval criteria, or critical context are ambiguous. Prefer asking over assuming.
- `planner` may use bash and Docker commands during planning for context gathering (e.g., `docker compose config`, `docker ps`, inspecting files, checking versions). Do not run builds, installs, tests, deployments, or any implementation-level commands — those belong to builder/tester/coder.

## Planner -> Builder Contract

- Every build starts from a memory note under `plans/` with `Status: approved`.
- Approved plans must include: objective, scope, constraints, assumptions, concrete task list, parallelization lanes, verification oracle, risks, and open findings.
- `builder` must follow the approved plan exactly.
- `builder` must stop and escalate back to `planner` when it finds a spec contradiction, a hidden dependency that changes scope, or two failed verification attempts after recording root cause and evidence.

## Commands

- `/init` initializes or refreshes repo memory and the project `AGENTS.md`.
- `/plan` creates or updates the canonical implementation plan in memory.
- `/build` executes the latest approved plan and records execution progress.
- `/continue` resumes unfinished planning or execution from memory based on the current primary agent.
- Built-in `/sessions` remains available for raw session browsing; custom `/continue` is the workflow-aware resume entrypoint.

## Memory System (Single: basic-memory)

Memory uses one persistent system: **basic-memory**.

- All persistent knowledge is stored in basic-memory notes, split across a **`main` project** (global/shared) and **per-repo projects** (project-specific).
- The managed per-repo basic-memory project directory is `<repo>/.memory/`.
- Do not edit managed `.memory/*` files directly; use basic-memory MCP tools for all reads/writes.

### `main` vs per-repo projects

1. **`main` (global/shared knowledge only)**
   - Reusable coding patterns
   - Technology knowledge
   - User preferences and workflow rules
   - Cross-project lessons learned

2. **Per-repo projects (project-specific knowledge only)**
   - Project overview and architecture notes
   - Plans, execution logs, decisions, findings, and continuity notes
   - Project-specific conventions and testing workflows

**Hard rule:** Never store project-specific plans, decisions, research, gates, or sessions in `main`. Never store cross-project reusable knowledge in a per-repo project.

### Required per-repo note taxonomy

- `project/overview` - stack, purpose, important entrypoints
- `project/architecture` - major modules, data flow, boundaries
- `project/workflows` - local dev, build, test, release commands
- `project/testing` - verification entrypoints and expectations
- `plans/<slug>` - canonical specs with `Status: draft|approved|blocked|done`
- `executions/<slug>` - execution log with `Status: in_progress|blocked|done`
- `decisions/<slug>` - durable project-specific decisions
- `findings/<slug>` - open findings ledger with evidence and owner

### Per-repo project setup (required)

Every code repository must have its own dedicated basic-memory project.

Use `basic-memory_create_memory_project` with:
- `project_name`: short kebab-case repo identifier
- `project_path`: `<repo-root>/.memory`

## Skills

Local skills live under `skills/<name>/SKILL.md` and are loaded on demand via the `skill` tool. See `skills/creating-skills/SKILL.md` for authoring rules.

### First-Batch Skills

| Skill | Purpose |
| --- | --- |
| `systematic-debugging` | Root-cause-first debugging with findings, evidence, and builder escalation |
| `verification-before-completion` | Evidence-before-claims verification for tester and builder handoffs |
| `brainstorming` | Planner-owned discovery and design refinement ending in memory-backed artifacts |
| `writing-plans` | Planner-owned authoring of execution-ready `plans/<slug>` notes |
| `dispatching-parallel-agents` | Safe parallelization with strict isolation tests and a single integrator |
| `test-driven-development` | Canonical red-green-refactor workflow for code changes |

### Ecosystem Skills

| Skill | Purpose |
| --- | --- |
| `docker-container-management` | Reusable Docker/compose workflow for builds, tests, and dev in containerized repos |
| `python-development` | Python ecosystem defaults: `uv` for packaging, `ruff` for lint/format, `pytest` for tests |
| `javascript-typescript-development` | JS/TS ecosystem defaults: `bun` for runtime/packaging, `biome` for lint/format |

### Agent Skill-Loading Contract

Agents must proactively load applicable skills when their trigger conditions are met. Do not wait to be told.

- **`planner`**: `brainstorming` (unclear requests, design work), `writing-plans` (authoring `plans/<slug>`), `dispatching-parallel-agents` (parallel lanes), `systematic-debugging` (unresolved bugs), `test-driven-development` (specifying code tasks), `docker-container-management` (repo uses Docker), `python-development` (Python repo/lane), `javascript-typescript-development` (JS/TS repo/lane).
- **`builder`**: `dispatching-parallel-agents` (before parallel fan-out), `systematic-debugging` (bugs, regressions, flaky tests), `verification-before-completion` (before any completion claim), `test-driven-development` (before delegating or performing code changes), `docker-container-management` (containerized repo), `python-development` (Python lanes), `javascript-typescript-development` (JS/TS lanes).
- **`tester`**: `systematic-debugging` (verification failure diagnosis), `verification-before-completion` (before declaring verification complete), `test-driven-development` (validating red/green cycles), `docker-container-management` (tests run in containers), `python-development` (Python verification), `javascript-typescript-development` (JS/TS verification).
- **`reviewer`**: `verification-before-completion` (evaluating completion evidence), `test-driven-development` (reviewing red/green discipline).
- **`coder`**: `test-driven-development` (all code tasks), `docker-container-management` (Dockerfiles, compose files, containerized builds), `python-development` (Python code lanes), `javascript-typescript-development` (JS/TS code lanes); other skills when the assigned lane explicitly calls for them.
- **`librarian`**: Load relevant skills opportunistically when the assigned task calls for them; do not override planner/builder workflow ownership.

### TDD Default Policy

Test-driven development is the default for all code changes. Agents must follow the red-green-refactor cycle unless a narrow exception applies.

**Narrow exceptions** (agent must state why TDD was not practical and what alternative verification was used):
- Docs-only changes
- Config-only changes
- Pure refactors with provably unchanged behavior
- Repos that do not yet have a reliable automated test harness

## Documentation Ownership

- `librarian` owns project docs updates, `AGENTS.md` upkeep, and memory note hygiene.
- When a workflow, command, or agent contract changes, update the docs in the same task.
- Keep command names, agent roster, memory taxonomy, and skill-loading contracts synchronized across `AGENTS.md`, `agents/`, `commands/`, and `skills/`.