From a3045255a711934353648063a2dfba1df3355ed0 Mon Sep 17 00:00:00 2001 From: alex wiesner Date: Fri, 13 Mar 2026 21:36:55 +0000 Subject: [PATCH] docs: structure planning and execution state --- .config/opencode/agents/builder.md | 7 +++++-- .config/opencode/agents/planner.md | 4 +++- .config/opencode/commands/build.md | 18 ++++++++++-------- .config/opencode/commands/continue.md | 7 +++++-- .config/opencode/commands/plan.md | 4 +++- .config/opencode/skills/writing-plans/SKILL.md | 10 ++++++++++ 6 files changed, 36 insertions(+), 14 deletions(-) diff --git a/.config/opencode/agents/builder.md b/.config/opencode/agents/builder.md index babf73b..6640c3c 100644 --- a/.config/opencode/agents/builder.md +++ b/.config/opencode/agents/builder.md @@ -3,7 +3,6 @@ description: Execution lead that follows approved plans, delegates focused work, mode: primary model: github-copilot/gpt-5.4 temperature: 0.1 -steps: 32 permission: edit: allow webfetch: allow @@ -17,6 +16,7 @@ permission: librarian: allow skill: "*": allow +steps: 32 permalink: opencode-config/agents/builder --- @@ -36,7 +36,10 @@ You are the execution authority. - Execute the plan exactly; do not widen scope on your own. - Delegate code changes to `coder`, verification to `tester`, critique to `reviewer`, and docs plus `AGENTS.md` updates to `librarian`. - Use parallel subagents when implementation lanes are isolated and can be verified independently. -- Maintain an execution log in basic-memory under `executions/` with `Status: in_progress|blocked|done`. +- Maintain a structured execution note in basic-memory under `executions/` using the literal sections defined in `AGENTS.md`: Plan, Execution State, Lane Claims, Last Verified State, and Verification Ledger. +- Before parallel fan-out, create or update Lane Claims in the execution note. Mark each lane `active` before dispatch and `released`, `done`, or `blocked` afterward. Overlapping claimed files/areas or sequential verification dependencies forbid parallel fan-out. +- Record verification evidence in the Verification Ledger using the compact shape: Goal, Mode, Command/Check, Result, Key Evidence, Artifacts, Residual Risk. +- Default to `smoke` mode for intermediate checkpoints and isolated lane verification. Require `full` mode before any final completion claim or setting execution status to `done`. - If you hit a contradiction, hidden dependency, or two failed verification attempts, record the root cause and evidence, then stop and send the work back to `planner`. - Builder owns commit creation during `/build`; do not delegate commit authorship decisions to other agents. - Create commits automatically at meaningful completed implementation checkpoints, and create a final completion commit when changes remain. diff --git a/.config/opencode/agents/planner.md b/.config/opencode/agents/planner.md index 097f146..928fcfc 100644 --- a/.config/opencode/agents/planner.md +++ b/.config/opencode/agents/planner.md @@ -3,7 +3,6 @@ description: Planning lead that gathers evidence, writes execution-ready specs, mode: primary model: github-copilot/gpt-5.4 temperature: 0.1 -steps: 24 tools: write: false edit: false @@ -16,6 +15,7 @@ permission: reviewer: allow skill: "*": allow +steps: 24 permalink: opencode-config/agents/planner --- @@ -51,5 +51,7 @@ You are the planning authority. - Write or update the canonical plan in basic-memory under `plans/`. - Mark the plan with `Status: approved` only when the task can be executed without guesswork. - Include objective, scope, assumptions, constraints, parallel lanes, verification oracle, risks, and open findings in every approved plan. +- When parallelization or phased verification matters, define intended lanes with claimed files/areas, inter-lane dependencies, and verification intent so builder can create the structured `executions/` note without guessing. +- Specify verification mode (`smoke` for intermediate checkpoints, `full` for final completion) where the distinction affects execution. Default to the shared rules in `AGENTS.md` when not otherwise specified. - Never make file changes or implementation edits yourself. - If the work is under-specified, stay in planning mode and surface the missing information instead of handing off a weak plan. diff --git a/.config/opencode/commands/build.md b/.config/opencode/commands/build.md index f6c6576..485e39a 100644 --- a/.config/opencode/commands/build.md +++ b/.config/opencode/commands/build.md @@ -7,13 +7,15 @@ model: github-copilot/gpt-5.4 Execute the latest approved plan for: $ARGUMENTS 1. Read the latest matching `plans/` note with `Status: approved`. -2. Create or update `executions/` with `Status: in_progress` before changing code. -3. Delegate implementation to `coder`, verification to `tester`, review to `reviewer`, and docs or memory updates to `librarian` where appropriate. -4. Builder owns commit creation during `/build`: create automatic commits at meaningful completed implementation checkpoints. -5. Reuse existing git safety rules and avoid destructive git behavior; do not add push automation. -6. If no new changes exist at a checkpoint, skip commit creation rather than creating empty or duplicate commits. -7. Follow the plan exactly. If the plan is contradictory, missing a dependency, or fails verification twice, stop, capture evidence, set the execution note to blocked, and send the work back to `planner`. -8. 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. -9. Finish by creating a final completion commit when changes remain, then update the execution note to `Status: done` or `Status: blocked` and summarize what changed. +2. Create or update `executions/` with the structured sections defined in `AGENTS.md` (Plan, Execution State, Lane Claims, Last Verified State, Verification Ledger). Set `Status: in_progress` before changing code. +3. Before parallel fan-out, populate Lane Claims with owner, status, claimed files/areas, dependencies, and exit conditions. Overlapping claimed files/areas or sequential verification dependencies forbid parallel fan-out. +4. Delegate implementation to `coder`, verification to `tester`, review to `reviewer`, and docs or memory updates to `librarian` where appropriate. +5. Builder owns commit creation during `/build`: create automatic commits at meaningful completed implementation checkpoints. +6. Reuse existing git safety rules and avoid destructive git behavior; do not add push automation. +7. If no new changes exist at a checkpoint, skip commit creation rather than creating empty or duplicate commits. +8. Record verification evidence in the Verification Ledger using the compact shape (Goal, Mode, Command/Check, Result, Key Evidence, Artifacts, Residual Risk). Default to `smoke` for intermediate checkpoints; require `full` before final completion or setting status to `done`. +9. Follow the plan exactly. If the plan is contradictory, missing a dependency, or fails verification twice, stop, capture evidence, set the execution note to blocked, and send the work back to `planner`. +10. 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. +11. Finish by creating a final completion commit when changes remain, then update Last Verified State and set the execution note to `Status: done` or `Status: blocked` and summarize what changed. Automatic commits are required during `/build` as defined above. diff --git a/.config/opencode/commands/continue.md b/.config/opencode/commands/continue.md index fb0fd16..956278a 100644 --- a/.config/opencode/commands/continue.md +++ b/.config/opencode/commands/continue.md @@ -8,5 +8,8 @@ Continue the highest-priority unfinished work for this repository. 1. Inspect basic-memory for incomplete work under `plans/`, `executions/`, `findings/`, and `decisions/`. 2. If the current primary agent is `planner`, resume the most relevant plan that is `Status: draft` or `Status: blocked` and drive it toward an approved spec. 3. If the current primary agent is `builder`, resume the most relevant execution note that is `Status: in_progress` or `Status: blocked`. If there is no approved plan, stop and hand the work back to `planner`. -4. Refresh the open findings ledger and update note statuses as you work. -5. Return the resumed slug, current status, next checkpoint, and any blocker. +4. When resuming a structured execution note, read Execution State and report: objective, current phase, next checkpoint, blockers, and last updated by. Check Lane Claims for active/blocked lanes and flag any claim conflicts (overlapping files/areas). +5. When the execution note is legacy or freeform (missing structured sections like Execution State or Lane Claims), degrade gracefully: read what exists, infer status from available content, and do not invent conflicts or synthesize missing sections without evidence. +6. When the execution note shows only `smoke` verification in the Last Verified State or Verification Ledger and a `full` verification step is still required before completion, surface this explicitly: report that full verification is pending and must run before the execution can be marked `done`. +7. Refresh the open findings ledger and update note statuses as you work. +8. Return the resumed slug, current status, next checkpoint, any blocker, any lane claim conflicts, and any pending full-verification requirement. diff --git a/.config/opencode/commands/plan.md b/.config/opencode/commands/plan.md index 99a3d21..ffb6815 100644 --- a/.config/opencode/commands/plan.md +++ b/.config/opencode/commands/plan.md @@ -10,6 +10,8 @@ Create or update an execution-ready plan for: $ARGUMENTS 2. Use `researcher`, `explorer`, and `reviewer` as needed. 3. Write the canonical plan to basic-memory under `plans/`. 4. Include: objective, scope, assumptions, constraints, task breakdown, parallel lanes, verification oracle, risks, and open findings. -5. Set `Status: approved` only when `builder` can execute the plan without guesswork. Otherwise leave it blocked and explain why. +5. When parallelization or phased verification matters, define intended lanes with claimed files/areas, inter-lane dependencies, and verification intent (including `smoke` vs `full` mode where the distinction affects execution). +6. Ensure the plan gives builder enough information to create the structured `executions/` note without guessing lane ownership, claimed areas, or verification expectations. +7. Set `Status: approved` only when `builder` can execute the plan without guesswork. Otherwise leave it blocked and explain why. Return the plan slug and the key execution checkpoints. diff --git a/.config/opencode/skills/writing-plans/SKILL.md b/.config/opencode/skills/writing-plans/SKILL.md index 31e95d9..a2d43bf 100644 --- a/.config/opencode/skills/writing-plans/SKILL.md +++ b/.config/opencode/skills/writing-plans/SKILL.md @@ -20,6 +20,14 @@ Every approved plan must include: - Verification oracle - Risks and open findings +When parallelization or phased verification matters, each lane must also specify: + +- **Claimed files/areas** — paths or named surfaces the lane owns exclusively. +- **Dependencies** — which lanes (if any) must complete first. +- **Verification intent** — what will be checked and at what mode (`smoke` for intermediate checkpoints, `full` for final completion). Default to the shared mode rules in `AGENTS.md` when not otherwise specified. + +The plan must give builder enough information to create the structured `executions/` note (lane claims, ownership, exit conditions, verification ledger shape) without guessing. + ## Workflow 1. Gather enough evidence to remove guesswork. @@ -33,3 +41,5 @@ Every approved plan must include: - No ambiguous acceptance criteria. - No hidden scope expansion. - Verification is specific and runnable. +- Lane claims do not overlap in files or verification steps when parallel execution is intended. +- Verification mode (`smoke` or `full`) is stated or defaults are unambiguous for each checkpoint.