Skip to main content
skill CX Codex

verify-maestro — Claude Code skill: what it does, how to install

verify-maestro verifies Maestro repository changes in an isolated scratch HOME, runs realistic CLI user journeys, and writes an execution log with exit codes.

MIT ★ 238 updated 2026-10-17

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

What verify-maestro does

The skill executes scripts/journey.sh <checkout> to test CLI modifications inside an isolated /tmp/maestro-verify.XXXX tree with an empty Git repository. The build installs via bun <checkout>/bin/maestro.ts install using env -i, keeping personal configurations in ~/.maestro and ~/.local/bin completely untouched.

The automated run executes diagnostic commands like maestro doctor, tests catalog recipes, exercises playbook execution, and confirms policy gates. Without pinned MAESTRO_SESSION_ID and MAESTRO_SESSION_PID values, every command acts as a separate anonymous session and causes work done to fail with LEASE_HELD.

Once all steps finish, the script deletes the temporary directory. The recorded transcript file tagged with [exit N] status codes remains in the topic directory as verifiable proof.

What it helps with

  • test Maestro CLI modifications without touching local ~/.maestro files
  • inspect maestro doctor diagnostics in a clean environment
  • record CLI command execution logs and exit codes as verification proof

Example prompts for the agent

  • Run verify-maestro against my local checkout and save the journey transcript
  • Execute scripts/journey.sh for this branch in a scratch home
  • Check maestro doctor output in the clean verification sandbox

How to install verify-maestro

1Skills CLI (Vercel)

npx skills add ReinaMacCredy/maestro --skill verify-maestro -a claude-code

2Manually: put the files in place

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

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

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about verify-maestro

How do I install verify-maestro in Claude Code?

Run npx skills add ReinaMacCredy/maestro --skill verify-maestro -a claude-code.

What does verify-maestro do?

It installs a Maestro checkout into a disposable scratch HOME, exercises real CLI workflows, and produces a complete execution transcript.

What runtime requirements does the verification script have?

The environment needs bun available in PATH to run the install script, while scripts/journey.sh manages session IDs and the scratch directory.

Source text

SKILL.md · MIT
---
name: verify-maestro
description: Verify a change in the maestro repository on the running product - install the checkout into a scratch HOME, doctor it, drive the CLI the way a user does, and capture the transcript as proof. Use before claiming a maestro change reached the installed, live, or journey layer.
---

# verify-maestro

Built from `maestro recipe show verification-skill`. Proves a change on an
installed runtime without touching the owner's `~/.maestro` or `~/.local/bin`.

## Launch

`scripts/journey.sh <checkout>` creates `/tmp/maestro-verify.XXXX` with its own
`home/` and an empty git repo, then runs `bun <checkout>/bin/maestro.ts install`
under `env -i` with that HOME and a PATH of the scratch shim dir, bun, and
`/usr/bin:/bin`. `MAESTRO_SESSION_ID`/`MAESTRO_SESSION_PID` are pinned so every
call is one session; without them each call is a new anonymous session and
`work done` fails with `LEASE_HELD`.

## Doctor

`maestro version` must print the checkout's commit, and `maestro doctor` must
report `healthy`, `source: ok <checkout>`, and the shim pointing into the
scratch HOME. A missing seat token and unverified Codex hooks are expected in
the scratch HOME.

## Drive

Add one block to `scripts/journey.sh` per journey the change touches, invoking
`maestro` exactly as a user types it. The script already drives:

- recipe catalog: `recipe list` shows the recipe, `recipe show` prints it.
- playbooks: 25 playbook and method recipes listed, bug-fix's steps shown,
  the retired `work` recipe refused; `~/maestro/PRINCIPLES.md` has 24
  sections; nine skills; the ten new agent renders; no PreToolUse hook.
- brief and grant: the SessionStart `method:` line routes by playbook; the
  `delivery grant:` line appears only while `policy-auto-pr` is enabled.
- bundle check: a fresh bundle's U1 skeleton is reported and exits 1.
- a policy gate: `plugin enable`, `work add|start|done` blocked, then passing.
- reinstall: a second install keeps the repository's policy choices.

## Capture

Run `scripts/journey.sh <checkout> > "$(maestro topic path verify-maestro)/journey-<n>.txt"`.
Each step prints its command output and `[exit N]`; read the exit codes, not
only the text. Cite the transcript path and the checkout commit in the proof,
tagged `(journey)`.

## Clean up

The script removes its scratch root last. The transcript in the topic folder
is the proof and stays.

## Feature map

| Feature | Journey | Observable outcome |
|---|---|---|
| install / update / uninstall | install, reinstall | doctor healthy; `.maestro/config` keeps enables |
| doctor, version | doctor | commit and source match the checkout |
| recipe | recipe catalog, playbooks | new recipe listed and shown; playbooks listed, `work` refused |
| PRINCIPLES.md, skills list, profiles, Claude hooks | playbooks | 24 sections, nine skills, ten renders, no PreToolUse |
| brief, policy-auto-pr | brief and grant | `method:` line; grant line only while enabled |
| plugin + policy gates | policy gate | blocked then passing `work done` |
| work lifecycle (add, start, note, done, show) | policy gate (partial) | `w1 done` |
| ready, status, trace, search | GAP | |
| bundle check | bundle check | U1 skeleton reported, exit 1 |
| bundle open/close, handoff | GAP | |
| decision, decide, term, lesson | GAP | |
| dispatch, handback | GAP | |
| memory, room, owner (Hub) | GAP | |
| topic, prompt, hook, brief, attention | GAP | |
| team, slp (Herdr panes) | GAP: needs a live herdr room | |
| graph, mcp | GAP | |

© ReinaMacCredy · MIT · ReinaMacCredy/maestro

Similar skills

All skills for Testing and QA →

From the same set10

The whole set →
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-verify 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. 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