Verify Plan

Verify Plan

Relies on BDK foundation (STARTUP_INSTRUCTIONS.md) for project context and MCP tool preference.

Verify plans against real code before execution. Spawns one Opus subagent (bdk:plan-verifier) that runs a six-section checklist and returns a YAML verdict envelope.

Invocation

/bdk:verify-plan docs/plans/2026-03-17-some-plan.md

$ARGUMENTS = plan file path. Read file first.

Decision Flow

flowchart TB
    start([Read plan file]) --> spawn[Spawn bdk:plan-verifier<br/>opus, six-section checklist]
    spawn --> parse[Parse YAML verdict envelope]
    parse --> status{status?}
    status -- PASS or<br/>PASS_WITH_WARNINGS --> save([Render verdict-template<br/>Write report])
    status -- FAIL --> iter_check{iteration < 2?}
    iter_check -- YES --> delta[Build delta message<br/>SendMessage verifier_agent_id]
    delta -- reply --> parse
    iter_check -- NO 2 failures --> escalate([Plan needs rethink.<br/>Suggest /bdk:design])

    classDef good fill:#d4edda,stroke:#3aa055
    classDef bad fill:#f8d7da,stroke:#c25a1b
    class start,save good
    class escalate bad

Step 1 — Locate Plan File

Parse $ARGUMENTS. Validate the path exists. Read the full content. Compute plan-slug = basename without .md extension. If the path is missing or empty, abort with a clear error and stop.

Step 2 — Spawn bdk:plan-verifier

Use the Agent tool with subagent_type: "bdk:plan-verifier" and this message body:

PLAN FILE: <path>
ITERATION: 1
FULL PLAN CONTENT:
---
<plan content verbatim>
---
For each task, run all six checklist sections (signature_drift, data_trace,
edge_cases, regression_flows, test_coverage, plan_completeness). Emit the
YAML verdict envelope as the LAST block of your reply — no prose after it.

Capture agent_id from the spawn envelope. Store as verifier_agent_id — needed for iteration 2 SendMessage.

Step 3 — Parse YAML Envelope

Extract the final yaml ... block from the agent's reply. Parse it. Required keys: status, iteration, per_task, must_fix.

Malformed YAML handling: respawn the agent once with the identical message. If the second reply is also malformed, abort and report the parse error to the user — do not silently continue.

Step 4 — Decide Next Action

Branch on status:

Delta message template (iteration 2):

Iteration 2.
Task IDs to re-verify: <deduped task_ids from must_fix>
Other tasks are unchanged — carry forward iteration-1 verdicts.
Run all six checklist sections only on the listed tasks. Emit the YAML
verdict envelope as the LAST block, with iteration: 2.

Step 5 — Write Verification Report

First stamp the plan's identity:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/bdk_run_state.py hash-plan <plan-path>

Render the report using references/verdict-template.md, filling the returned plan_sha256 into the header. Save to:

.bdk/verify-plan/<plan-slug>-verification.md

The hash is over the plan file's bytes, so it identifies exactly the plan that was verified. /bdk:subagent-execute-plan re-computes it with the same subcommand at Step 0 and compares: equal means it is running the verified plan, different means the plan was edited after verification and the verdict above no longer describes it. Do not compute the hash any other way - one source keeps the two sides from disagreeing over an algorithm or a trailing newline.

Confirm in chat with the report path and the pass/fail summary line.

Step 6 — Hand Off

On PASS or PASS_WITH_WARNINGS, print the next step and stop:

  Verdict:  PASS | PASS_WITH_WARNINGS
  Report:   .bdk/verify-plan/<plan-slug>-verification.md
  Plan sha: <first 12 chars>

  Next: /bdk:subagent-execute-plan <plan-path>

Do not execute the plan. On PASS_WITH_WARNINGS, name the warnings in the chat line - they are worth reading before execution, but they do not block it.

On FAIL after two iterations, the handoff is /bdk:design, not the executor (Step 4 already covers this).

Notes

• Loop cap = 2 iterations. Third would be wasted work; escalation is the intended path.
• The agent retains plan content + iteration-1 findings across SendMessage. Pass only the delta — do not re-include the full plan.
• See STARTUP "Continuing a Spawned Agent" for the 5-min warm-cache window. If iteration 2 is delayed beyond that, the SendMessage still works but pays a cache miss.
• SendMessage iteration is same-session only. verifier_agent_id is not addressable from a later session, so a re-verification after any session boundary is a fresh Step 2 spawn with the full plan - there is no cheap cross-session resume. If the plan changed, that is the correct behaviour anyway: the verdict is about specific bytes, and a fresh pass is what re-establishes it.