maestro-bundle — Claude Code skill: what it does, how to install
maestro-bundle manages SPEC, NOTES, and VERIFY bundle lifecycles and controls context handoffs across agent sessions in Maestro.
MIT ★ 238 updated 2026-10-17
npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a claude-codeWhat maestro-bundle does
This skill routes incoming tasks into Maestro tiers and maintains the SPEC, NOTES, and VERIFY artifact trio. For Full tier tasks, it scaffolds the working bundle via maestro bundle open <id> --work <workId> inside the target repository checkout, mapping Hub decisions directly to the bundle.
It sets strict boundaries between context compaction and structured handoffs. Handoff takes precedence when task ownership changes, branches diverge, or the session context fills with dead ends. Because compaction provides no warning turn in CLI harnesses, the workflow relies on checkpoint: notes refreshed before every state change.
Direct creation of root SPEC-*, NOTES-*, or VERIFY-* files is explicitly disallowed by the trio contract. The skill packages completed work into archive snapshots with maestro bundle close <id> and manages paused states using maestro bundle pause.
What it helps with
- Scaffold SPEC, NOTES, and VERIFY files for Full tier engineering tasks
- Render structured NOTES.md summaries before handing work off to another session
- Link architectural decisions from the Hub to an active workspace bundle
- Resume interrupted workflows using checkpoint records
Example prompts for the agent
- Open a new bundle payment-api linked to work item 108
- Run maestro handoff on bundle payment-api and prepare NOTES.md
- Pause the active bundle worker-sync with reason waiting on review
How to install maestro-bundle
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a claude-code2Manually: put the files in place
~/.claude/skills/maestro-bundle/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/maestro-bundle/
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a codex2Manually: put the files in place
.agents/skills/maestro-bundle/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a cursor2Manually: put the files in place
.cursor/skills/maestro-bundle/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ReinaMacCredy/maestro src/plugins/skills/maestro-bundle2Manually: put the files in place
.github/skills/maestro-bundle/SKILL.md1Skills CLI (Vercel)
npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a gemini-cli2Platform CLI
gemini skills install https://github.com/ReinaMacCredy/maestro --path src/plugins/skills/maestro-bundleManually: put the files in place
.devin/skills/maestro-bundle/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-bundle
How to install maestro-bundle in Claude Code?
Run npx skills add ReinaMacCredy/maestro --skill maestro-bundle -a claude-code in your terminal.
What does maestro-bundle do?
It manages the lifecycle of Maestro task bundles, scaffolding the SPEC/NOTES/VERIFY file contract, handling session resumes, and driving handoffs across tools.
When does maestro-bundle require a handoff instead of compaction?
A handoff is triggered whenever task ownership transfers, a dependency moves into an isolated branch, the agent role shifts, or the conversation context accumulates failed attempts.
Source text
SKILL.md · MIT
--- name: maestro-bundle description: Route work into the right maestro tier and drive the SPEC/NOTES/VERIFY bundle lifecycle - open, resume, close, recall. review-date: 2026-11-28 --- <!-- maestro-skill-version: dev --> # maestro-bundle Use [WORKFLOW.md](~/maestro/WORKFLOW.md) for method rules and routing. This skill owns record creation, resume, and handoff procedures. ## Tier rule Apply [Tiers](~/maestro/WORKFLOW.md#tiers) after bounded reconnaissance. For tracked work use `maestro work add|start|done`. When Full is warranted, open the bundle in the store whose checkout will change, even when design runs in the Hub. List Hub decisions as `hub:<id>`; `maestro bundle show` renders them. Note the bundle on the Hub map and the map on its work item. ``` maestro bundle open <id> --work <workId> # scaffold SPEC/NOTES/VERIFY, link work ``` ## The trio contract Follow [Bundle contract](~/maestro/WORKFLOW.md#bundle-contract-tier-full). Use `maestro handoff <bundle-id>` to render NOTES.md from work, decisions, handbacks, failures, and the latest checkpoint. Fill only placeholders the store cannot prove, including original authorization and retained gates. Use `maestro bundle show <id>` to read the contract and linked decisions. Never create root `SPEC-*`, `NOTES-*`, or `VERIFY-*` files. ## Verbs ``` maestro bundle open <id> [--work <id>] # scaffold + active row maestro bundle close <id> # snapshot trio into the store, archive maestro bundle pause <id> [--reason] # active stays open, out of the way maestro bundle resume <id> # paused back to active maestro bundle list # states: active | paused | archived maestro bundle show <id> # trio + linked work + decisions maestro bundle save <dir> # ingest a foreign trio dir as archived maestro search "<term>" # recall: hits labeled (bundle, ...) ``` ## Authorization boundaries Follow [Authorization boundaries](~/maestro/WORKFLOW.md#authorization-boundaries). Put the original user instruction or retrievable reference on the work item so the successor can verify the grant, rather than relying on an agent's summary. ## Routing Use [Routing](~/maestro/WORKFLOW.md#routing); a skill transition is internal, not another user approval gate. ## Resume protocol Follow [Resume](~/maestro/WORKFLOW.md#resume). For Light, read the work and checkpoint without opening a bundle. For Full, locate and read the existing bundle, then reconcile it with the checkout before continuing. ## Concurrency and git Follow [Concurrency and git](~/maestro/WORKFLOW.md#concurrency-and-git). Record the work owner and task-owned paths in the handoff, not just the branch. ## Compact or hand off Hand off instead of compacting when: - the owner changes - a dependency becomes its own branch - the role changes - the context is full of false starts Compact only when ownership, scope, and role stay stable and the history still helps the same writer continue. Compaction gives no warning turn in either harness, so the checkpoint must already exist: keep a `checkpoint:` work note (state / next / avoid, latest wins) on each held item, rewritten at every meaningful change of state or next action; the SessionStart brief prints it back after the compaction. Nothing summarized is trusted over it. Use break-before-make when the writer on a moving scope changes: release the lease and refresh the handoff before the new session starts. The handoff packet must preserve the base, Current State, Next Action, Authority transferred and retained, Failed approaches, and Do not repeat. ## Hand-off Run `maestro handoff <bundle-id>` to seed untouched NOTES.md sections when a bundle exists. Then decide which of three cases this is; the destination differs: 1. **Continuation with a bundle.** A future session, in any tool, continues this bundle in this workspace. The handoff IS the rendered NOTES.md covering every section the trio contract names, with a `Driver:` line naming the tool expected to resume. The bundle stays active; the next session's resume protocol must find it. 2. **Transfer.** The work leaves this workspace, to a person, another repo, or an agent that will not resume the bundle. Write the standalone document below, then close the bundle per `maestro-verify`'s close order, citing the handoff target. 3. **No bundle.** For tracked work, save the continuation packet as a `checkpoint:` work note with original authorization and retained gates. If an untracked quickfix needs continuation, create a Light work item. For a transfer outside this workspace, provide a standalone document in the OS temporary directory, report its path, and transfer it to the recipient; a local path alone is not accessible from another machine. The standalone document (cases 2 and 3) names the suggested skills for the next agent, references specs, decisions, commits, and diffs by path or id instead of duplicating them, and redacts secrets and personal data. Design lane -> use the `maestro-design` skill. Implementation -> the matched playbook (`maestro recipe show <name>`). Verification and close -> `maestro-verify`.
© ReinaMacCredy · MIT · ReinaMacCredy/maestro