/maestro-work

name: maestro-work
description: The contract every playbook shares - the brief a writer receives, the rules it writes by, the handback it returns, and the store record the holder keeps. Reuse existing checks and add tests only for concrete uncovered behavior or risk.
review-date: 2026-11-28

<!-- maestro-skill-version: dev -->

maestro-work

The matched playbook (`maestro recipe show <name>`, chosen by [Routing](~/maestro/WORKFLOW.md#routing)) owns the steps of a task. This skill owns what every playbook shares: the brief a writer receives, the rules it writes by, the handback it returns, and the record the holder keeps. A writer is a `delegate` subagent, a lane in a Herdr pane, or the main chat on a quickfix. Apply [WORKFLOW.md](~/maestro/WORKFLOW.md) for method rules; pause only the slice blocked by scope or authority.

Dispatch

When work is handed to a writer (a `delegate` subagent, or a lane in a Herdr pane in the room), send this envelope:

Objective: <observable outcome>
Owned scope: <paths or responsibility>
Excluded scope: <explicit non-goals>
Mutation: <no-write | write-bounded: paths>
Stop condition: <done or blocked boundary>
Lane: scout | decision | delivery | challenge | shadow
Evidence required: <proof and layer>

A tiny task may collapse the envelope to three lines, but it never drops `Excluded scope` or `Mutation`. Name the playbook and step the work serves, and point at files rather than pasting their content. Standing orders that apply to every writer of one run go in one file every brief points at.

• `scout` reads and reports state, never writes.
• `delivery` may write and is the only lane that holds the lease; a

subagent's brief borrows the lane word but never takes the lease.

• `decision` investigates, compares, and recommends without writing.
• `challenge` breaks the premise or candidate and returns findings only, with

no fixes or redesign.

• `shadow` runs beside the owner without writing and returns comparison

evidence that is never a candidate or a work write lease.

No-write names the file boundary only. `maestro dispatch accept` and `maestro handback file` are the lane's own two writes and are never in the excluded scope, so a scout or shadow lane can still accept and return. A subagent opens no dispatch: the holder that briefed it reviews its diff and keeps the item.

The canonical parallel shapes are delivery and challenge on the same scope, or a council of decision lanes run by `maestro-council`.

Handback

Return this packet when the writer stops. `maestro dispatch accept` leaves the dispatch claimed, not held, and `maestro handback file` refuses with `DISPATCH_UNCONFIRMED` until the opener runs `maestro dispatch confirm`, so ask for the confirm at acceptance rather than at the stop condition.

Status: <DONE | BLOCKED | UNTESTABLE | UNKNOWN | FAILED | CHALLENGE | REOPEN_REQUEST | DEPENDENCY_REQUEST | COUNCIL_REQUEST>
Claim: <what is now believed true>
Proof: <evidence with its layer named>
Assumptions not verified: <items or None>
Residual risks: <items or None>
Incidental findings: <items or None>

Unknown is a valid result; it is never rounded up to PASS.

A writer that discovers a dependency stops the mutation that depends on the new assumption and hands back `DEPENDENCY_REQUEST` with evidence and impact. The holder re-scopes the work. A never silently becomes A+B+C.

Record

The holder of a work item keeps its record; a subagent never does.

• New work gets `--acceptance "<observable result>"` and `--kind`:

`feature`, `task`, `bug`, `chore`, `implement` are execution units; `idea` and `research` are scope notes under a parent and never hold it open. A parentless item the agent creates carries its why in the title or acceptance; a longer why is a `maestro work note <id> "why: <one paragraph>"`.

• `maestro work start <id>`. With `policy-breakdown` enabled it refuses a

parentless write-like item: pass `--atomic-reason "<why this is one unit>"` when it truly is one, otherwise `maestro work add ... --parent <id>` first and start the child; a parent with open children never starts.

• A pass that failed gets exactly one line,

`maestro work note <id> "failed: <one line>"`; the lowercase `failed: ` prefix is what `maestro attention` counts. For repeated failures, apply [Recovery and verification](~/maestro/WORKFLOW.md#recovery-and-verification) and record the episode in one `failed:` note carrying:

Attempted: <approaches tried>
Invariant assumed: <belief shared by the attempts>
Exact failure: <literal evidence>
What changed between attempts: <delta>
What did not change: <stable conditions>
Smallest new information needed: <next fact that would change the approach>

• Keep a checkpoint on the held item when state or the next action

meaningfully changes, and before any handoff: `maestro work note <id> "checkpoint:\nplaybook: <name> step <n>\nstate: <where it stands>\nnext: <concrete action>\navoid: <what not to repeat>"`. Include the base, task-owned dirty paths, original authorization and retained gates for a successor. Only the latest one counts; the brief prints it back after a compaction, and `maestro handoff` renders it into NOTES.md.

• Otherwise note only a reusable correction, decision, or failed approach;

keep ordinary command output out of notes.

• `maestro work done <id>` with `--claim`/`--proof` naming the real

falsifier (the check that would have failed if the claim were wrong). `--evidence` records one opaque blob; paired claims are preferred when a pair-checking gate is enabled, with the gate's tag prefix (`test:`, `qa:`) on the claim. Report pending delivery approval separately from completion. In a bundle, run `maestro handoff <bundle-id>` before releasing the work item: it renders NOTES.md from the store (work, decisions, handbacks, `failed:` and `checkpoint:` notes, base commit); hand-edit only Authority and whatever the store cannot