diff --git a/.config/opencode/AGENTS.md b/.config/opencode/AGENTS.md index c942a86..192a674 100644 --- a/.config/opencode/AGENTS.md +++ b/.config/opencode/AGENTS.md @@ -82,10 +82,96 @@ Memory uses one persistent system: **basic-memory**. - `project/workflows` - local dev, build, test, release commands - `project/testing` - verification entrypoints and expectations - `plans/` - canonical specs with `Status: draft|approved|blocked|done` -- `executions/` - execution log with `Status: in_progress|blocked|done` +- `executions/` - structured execution log with `Status: in_progress|blocked|done` (see template below) - `decisions/` - durable project-specific decisions - `findings/` - open findings ledger with evidence and owner +### Execution note template (`executions/`) + +Every execution note must use these literal section names: + +``` +## Plan +- **Source:** plans/ +- **Status:** approved + +## Execution State +- **Objective:** +- **Current Phase:** +- **Next Checkpoint:** +- **Blockers:** +- **Last Updated By:** +- **Legacy Note Normalized:** + +## Lane Claims +Repeated per lane: + +### Lane: +- **Owner:** +- **Status:** planned | active | released | blocked | done +- **Claimed Files/Areas:** +- **Depends On:** +- **Exit Condition:** + +## Last Verified State +- **Mode:** none | smoke | full +- **Summary:** +- **Outstanding Risk:** +- **Related Ledger Entry:** + +## Verification Ledger +Append-only log. Each entry: + +### Entry: +- **Goal:** +- **Mode:** smoke | full +- **Command/Check:** +- **Result:** pass | fail | blocked | not_run +- **Key Evidence:** +- **Artifacts:** +- **Residual Risk:** +``` + +#### 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.