/maestro-bundle

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