Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ReinaMacCredy/maestro --skill maestro-verify -a claude-code
Open on GitHub

What 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.md scenario
  • 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.md and 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-code

2Manually: put the files in place

~/.claude/skills/maestro-verify/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/maestro-verify/

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

Similar skills

All skills for Testing and QA →

From the same set10

The whole set →
verify-maestro verify-maestro verifies Maestro repository changes in an isolated scratch HOME, runs realistic CLI user journeys, and writes an execution log with exit codes. CX Codex +1 ★ 238repo stars maestro-questionnaire The maestro-questionnaire skill turns an unresolved decision into a Markdown questionnaire for someone with the missing knowledge. Use it to collect answers asynchronously or in a meeting. CX Codex +1 ★ 238repo stars maestro-coach maestro-coach — a skill for Claude and Codex that unjams a question you got stuck on and teaches the concept behind a decision using your own repo code. CX Codex +1 ★ 238repo stars maestro-bundle maestro-bundle manages SPEC, NOTES, and VERIFY bundle lifecycles and controls context handoffs across agent sessions in Maestro. CX Codex +1 ★ 238repo stars maestro-design maestro-design — a skill that resolves blocking unknowns before implementation: architecture choice, modeling, prototyping, and recording durable decisions. CX Codex +1 ★ 238repo stars maestro-graph maestro-graph — a skill for Claude Code and Codex that runs a task along a predefined graph: spawns agents on each node, collects results, and moves to the next step. CX Codex +1 ★ 238repo stars maestro-work maestro-work is a Claude Code skill that defines shared playbook rules for task briefs, work handbacks, and records. It applies when an agent delegates work or tracks a task in Maestro. CX Codex +1 ★ 238repo stars maestro-council maestro-council runs a structured council over a call you cannot cheaply undo: sealed seats, a premise check, cross-examination and one binding verdict. CX Codex +1 ★ 238repo stars

Project sponsors

Companies that keep this analytics open