maestro-bundle
Use WORKFLOW.md for method rules and routing. This skill owns record creation, resume, and handoff procedures.
Tier rule
Apply 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.
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. 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; a skill transition is internal, not another user approval gate.
Resume protocol
Follow 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. 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:
- 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. - 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. - 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 -> maestro-work.
Verification and close -> maestro-verify.
