Skip to main content
skill CX Codex

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

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

What 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-code

2Manually: put the files in place

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

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

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

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-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