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