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-sonnet-4.6` | Read-only repo inspection; reports facts only, never plans or recommendations |
| `reviewer` | subagent | `github-copilot/gpt-5.4` | Critique plans, code, tests, and release readiness |
| `coder` | subagent | `github-copilot/gpt-5.3-codex` | Implement narrowly scoped code changes |
| `tester` | subagent | `github-copilot/claude-opus-4.6` | 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.

### Builder Commits

- `builder` automatically creates git commits at meaningful task checkpoints and at final completion when uncommitted changes remain.
- A "meaningful checkpoint" is a completed implementation chunk from the approved plan, not every file save.
- Skip commit creation when there are no new changes since the prior checkpoint.
- Commit messages should reflect the intent of the completed task from the plan.
- Before creating the final completion commit, clean up temporary artifacts generated during the build (e.g., scratch files, screenshots, logs, transient reports, caches). Intended committed deliverables are not cleanup targets.
- Standard git safety rules apply: review staged content, respect hooks, no force-push or destructive operations.
- Push automation is out of scope; the user decides when to push.

## 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>` - structured execution log with `Status: in_progress|blocked|done` (see template below)
- `decisions/<slug>` - durable project-specific decisions
- `findings/<slug>` - open findings ledger with evidence and owner

### Execution note template (`executions/<slug>`)

Every execution note must use these literal section names:

```
## Plan
- **Source:** plans/<slug>
- **Status:** approved

## Execution State
- **Objective:** <one-line goal from the plan>
- **Current Phase:** <planning|implementing|integrating|verifying|blocked|done>
- **Next Checkpoint:** <next concrete step>
- **Blockers:** <none|bullet-friendly summary>
- **Last Updated By:** <builder|coder|tester|reviewer|librarian>
- **Legacy Note Normalized:** <yes|no>

## Lane Claims
Repeated per lane:

### Lane: <lane-name>
- **Owner:** <builder|coder|tester|reviewer|librarian|unassigned>
- **Status:** planned | active | released | blocked | done
- **Claimed Files/Areas:** <paths or named workflow surfaces>
- **Depends On:** <none|lane names>
- **Exit Condition:** <what must be true to release or complete this lane>

## Last Verified State
- **Mode:** none | smoke | full
- **Summary:** <one-sentence status>
- **Outstanding Risk:** <none|brief risk>
- **Related Ledger Entry:** <entry label|none>

## Verification Ledger
Append-only log. Each entry:

### Entry: <checkpoint-or-step-label>
- **Goal:** <what is being verified>
- **Mode:** smoke | full
- **Command/Check:** <exact command or manual check performed>
- **Result:** pass | fail | blocked | not_run
- **Key Evidence:** <concise proof: output snippet, hash, assertion count>
- **Artifacts:** <paths to logs/screenshots, or `none`>
- **Residual Risk:** <known gaps, or `none`>
```

#### Verification summary shape

Each verification entry (in Last Verified State or Verification Ledger) uses these fields:

- **Goal** - what is being verified
- **Mode** - `smoke` or `full` (see mode rules)
- **Command/Check** - exact command or manual check performed
- **Result** - `pass`, `fail`, `blocked`, or `not_run`
- **Key Evidence** - concise proof (output snippet, hash, assertion count)
- **Artifacts** - paths to logs/screenshots if any, or `none`
- **Residual Risk** - known gaps, or `none`

#### Verification mode rules

- Default to **`smoke`** for intermediate checkpoint proof and isolated lane verification.
- Default to **`full`** before any final completion claim or setting execution status to `done`.
- If there is only one meaningful verification step, record it as `full` and note there is no separate smoke check.

#### Compact verification summary behavior

- The verification ledger shape is the default evidence format for builder/tester/coder handoffs.
- Raw logs should stay out of primary context unless a check fails or the user explicitly requests full output.
- When raw output is necessary, summarize the failure first and then point to the raw evidence.

#### Lane-claim lifecycle

- **Planner** defines intended lanes and claimed files/areas in the approved plan when parallelization is expected.
- **Builder** creates or updates lane-claim entries in the execution note before fan-out and marks them `active`, `released`, `done`, or `blocked`.
- Overlapping claimed files/areas or sequential verification dependencies **forbid** parallel fan-out.
- Claims are advisory markdown metadata, not hard runtime locks.

#### Reviewer and execution-note ownership

- `reviewer` is read-only on execution notes; it reports findings via its response message.
- `builder` owns all execution-note writes and status transitions.

#### Legacy execution notes

Legacy execution notes may be freeform and lack structured sections. `/continue` must degrade gracefully — read what exists, do not invent conflicts or synthesize missing sections without evidence.

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

### Design & Domain Skills

| Skill | Purpose |
| --- | --- |
| `frontend-design` | Distinctive, production-grade frontend UI with high design quality, accessibility, and performance |

### 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), `frontend-design` (frontend UI/UX implementation or redesign), `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), `frontend-design` (frontend UI/UX implementation lanes), `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), `frontend-design` (frontend component, page, or application implementation lanes), `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/`.