maestro-verify — Claude Code skill for verification
The maestro-verify skill checks acceptance criteria against verification evidence, records a verdict, and guides bundle closure. Use it before handing work back or closing a task.
MIT ★ 238 updated 2026-10-17
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a claude-codeWhat maestro-verify does
The skill compares the evidence plan with acceptance criteria and risks, runs the scenarios in VERIFY.md, and records what supports each result. It separates evidence into source, artifact, installed version, live process, and end-to-end user journey. Any link that was not checked must be marked NOT TESTED.
A full verification pass requires an open bundle with a drafted VERIFY.md. The skill does not fix failures: it records a failed result and returns it to the implementation owner. Local test results do not establish that an installed copy or running process is correct, so claims should stop at the last layer actually checked.
Before closing, it guides the user through retaining durable decisions and notes, running maestro handoff <bundle-id>, then closing the bundle with maestro bundle close <id>. Commit, installation, and release remain separate gates and need their own authorization.
What it helps with
- compare test coverage with acceptance criteria and risks
- record evidence for each
VERIFY.mdscenario - separate source test results from installed-version checks
- route a failed verification back to its implementation owner
- preserve durable decisions before closing a bundle
Example prompts for the agent
- Check the bundle against the scenarios in
VERIFY.mdand record evidence for each row. - Compare the acceptance criteria with the checks, run verification, and record the verdict.
- Prepare the bundle for closure by preserving durable decisions and running
maestro handoff <bundle-id>.
How to install maestro-verify
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a claude-code2Manually: put the files in place
~/.claude/skills/maestro-verify/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/maestro-verify/
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a codex2Manually: put the files in place
.agents/skills/maestro-verify/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a cursor2Manually: put the files in place
.cursor/skills/maestro-verify/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ReinaMacCredy/maestro src/plugins/skills/maestro-verify2Manually: put the files in place
.github/skills/maestro-verify/SKILL.md1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a gemini-cli2Platform CLI
gemini skills install https://github.com/ReinaMacCredy/maestro --path src/plugins/skills/maestro-verifyManually: put the files in place
.devin/skills/maestro-verify/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about maestro-verify
How do I install maestro-verify in Claude Code?
Run npx skills add ReinaMacCredy/maestro --skill maestro-verify -a claude-code. The skill file is at ~/.claude/skills/maestro-verify/SKILL.md.
What does maestro-verify do?
It checks verification scenarios against acceptance criteria, records evidence by layer, and delivers a verdict. When a check fails, it leaves a note for the implementation owner rather than making a fix.
What is required for a full verification pass?
The bundle must be open and have a drafted VERIFY.md. Local test results alone do not confirm the installed version or live process.
Source text
SKILL.md · MIT
--- name: maestro-verify description: Verify and close - cross-check coverage, run the VERIFY table, deliver the verdict, harvest durable lessons into decisions, close the bundle, and never claim remote state from local evidence. review-date: 2026-11-28 --- <!-- maestro-skill-version: dev --> # maestro-verify Use for verification and close. Read [WORKFLOW.md](~/maestro/WORKFLOW.md) for testing, recovery, authorization, and completion rules. Delivery actions such as commit, install, push, or release remain separate gates. Precondition: an open bundle with a drafted VERIFY.md. Without a bundle, verify inline and close a tracked item with `maestro work done`; an untracked quickfix needs no record. This skill's table pass is for Full work. The evidence-layer vocabulary below still applies to any claim at any tier. ## Evidence layers Proof follows five links. Claim only as far as the last proven link. - `source` - source-level tests, lint, type checks, or direct inspection. - `artifact` - the built or packaged output is present and has been read back. - `installed` - the installed stamp, version, or files match the intended artifact. - `live` - the running process, pid, or active runtime matches the installed layer. - `journey` - the real user path reaches the observable outcome end to end. The repository's `verify-<repo>` skill is the route to `live` and `journey`; `maestro recipe show verification-skill` creates or maintains it. "Tests pass" is a source claim. A claim that touches install or runtime must include a readback at that layer. A suite that is green only on this machine is not a `source` claim about the repo: before any commit, release, or handback gate, re-run the touched suite with the developer environment removed (`HOME=$(mktemp -d)`, `env -u HERDR_ENV`). A test that reads the installed copy, the room, or a home config passes for you and fails in CI. Every proof and VERIFY result lists untested links explicitly as `NOT TESTED`, never by omission: ```text proof: "suite 135 pass @ a52bd4a7 (source); runtime stamp readback a52bd4a7 (installed); live: NOT TESTED" Assumptions not verified: None Residual risks: None ``` ## Verify - Cross-check the evidence plan against acceptance and relevant risks. Map existing tests, necessary new checks, readbacks, or baselines to VERIFY.md. A missing behavior check is a gap; the absence of a newly written test is not. - Run every VERIFY.md scenario against its work item's acceptance/claims and fill its unit, live, and perf cells with evidence or `n/a: <reason>`; run each anti-goal check (grep, diff, readback). Stamp each row with its commit and the pass with its date, then run `maestro bundle check <id> --final`. Results hold this run only: a re-run replaces prior results wholesale, and a failed pass leaves its one-line `failed:` note on the work item, never accumulated rounds in VERIFY.md. Apply [Recovery and verification](~/maestro/WORKFLOW.md#recovery-and-verification) when a scenario cannot run as written: document and execute an equivalent check without changing acceptance, or report the gap if equivalence is unknown. - Run the repo's checks for the touched surface (tests, lint, types, build), then freeze and review the task-owned diff: every changed line traces to the SPEC's scope or a linked work item; nothing unrelated is staged. - For a concrete assertion-strength concern, inspect whether the existing check distinguishes the approved outcome from the suspected wrong behavior. A focused mutation can establish that; restore it before continuing. Do not expand verification into an unrelated edge-case or coverage campaign. - Re-read the user's exact delivery authority and target before any gate. - Select one legal next gate at a time: final verification, independent QA or witness, scoped commit, local install, external delivery, or stop. Do not bundle gates whose authority differs. - Read back the actual result: test output, commit hash, installed version. A started or interrupted command is not delivery evidence. For substantial diffs, verify in a fresh context: dispatch a subagent that reads only the bundle and the diff - the implementer verifying their own work invites confirmation bias. The subagent never fixes anything: mutants it flips are reverted before reporting, and on FAIL it records the verdict and stops; routing back to implementation belongs to the parent turn that holds the user's ask. A subagent that fails to start or report is a dispatch failure, not evidence: run the checklist in this session instead of polling for it. On FAIL, leave `maestro work note <id> "failed: <one line>"` and return the evidence to the implementation owner. Use the shared recovery rule to choose the next action from the cause, not a failure count. Read prior failed notes so a new session does not repeat the same uninformative attempt. Read-only review method: [references/audit.md](references/audit.md). When the failure location is unclear, follow [references/triage.md](references/triage.md). ## Red flags | The thought | The reality | |---|---| | "It obviously passes - running it is a formality" | Scenarios exist because "obviously" has been wrong before. Run every one and record the output. | | "The scenario command is stale, so I can skip the check" | Repair it or demonstrate an equivalent measurement; preserve acceptance and record the change. | | "The mutant survived, but the code is clearly fine" | If the mutant violates acceptance, the check is weak; report the gap rather than filling PASS. | | "I wrote this diff - I know it works" | That is the confirmation bias the fresh-context rule exists for. | | "I'll just fix this small failure while I'm verifying" | Verify delivers a verdict, never fixes. A FAIL routes back to the playbook's fix step. | ## Learn, then close Before closing, harvest what outlives the bundle ([references/learning.md](references/learning.md)): a verified correction or durable constraint becomes a locked decision or a work note - never only chat. Use [Completion and delivery](~/maestro/WORKFLOW.md#completion-and-delivery) to decide whether the accepted scope is complete or an authorized transfer is ready. Close procedure: 1. Run `maestro handoff <bundle-id>` one last time, then add a dated close-out line citing verification evidence and the candidate (base commit plus task-owned diff if uncommitted), or the explicit handoff/cancellation. Record pending delivery actions and retained authority in the handoff. 2. Harvest: any mid-flight choice that is hard to reverse, surprising without context, and a real trade-off is a locked decision with its rejected alternative; a new domain term is `maestro term add`. 3. `maestro bundle close <id>`: snapshots the trio into the store and archives the directory. The snapshot is the durable memory; after close the directory is disposable and `maestro search` still recalls the text. If acceptance includes delivery not yet authorized or proven, leave the work open with that exact next action and blocker. Otherwise a verified implementation may close without a commit. Do not mark failed acceptance complete; an explicit transfer or cancellation records the unresolved failure rather than calling it PASS. Never stage or commit bundle contents. Use the shared [review routing](~/maestro/WORKFLOW.md#per-tool-adapters). A code change after the verdict reruns the affected VERIFY.md scenarios before close; the old verdict does not cover the new diff. ## Definition of done Acceptance met, changed surface verified, available test/lint/type/build checks pass, claims name their falsifier, risky changes carry rollback notes. Never claim push, release, or publish from local state; those gates are the user's.
© ReinaMacCredy · MIT · ReinaMacCredy/maestro