/maestro-work

name: maestro-work
description: Implement or fix one authorized unit with minimal edits and sufficient evidence. Reuse existing checks and add tests only for concrete uncovered behavior or risk.
review-date: 2026-11-28

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

maestro-work

Use for one accepted implementation unit. Keep the change inside the work item's acceptance and authority. Apply [WORKFLOW.md](~/maestro/WORKFLOW.md) for method rules; pause only the slice blocked by scope or authority.

Recon and preconditions

Inspect the relevant source and existing checks, then apply [Tiers](~/maestro/WORKFLOW.md#tiers). Confirm the original implementation request and accepted scope; for Full, read the matching SPEC. A newly found in-scope test gap does not require a new design pass. A throwaway prototype not approved to port remains `maestro-explore`'s scope.

Before writing code, read any language-convention notes the user's setup provides for the language being edited. Repository conventions override them.

Dispatch

When work is handed to a lane (a Herdr pane in the room, or a sub-agent where no room exists), 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`.

• `scout` reads and reports state, never writes.
• `delivery` may write and is the only lane that holds 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.

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 lane 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 peer that discovers a dependency stops the mutation that depends on the new assumption and hands back `DEPENDENCY_REQUEST` with evidence and impact. The Lead re-scopes the work. A never silently becomes A+B+C.

For repeated failures, apply [Recovery and verification](~/maestro/WORKFLOW.md#recovery-and-verification). Record the episode in one `failed:` work 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>

Loop

1. **Perceive** - `maestro work show <id>`, `maestro ready`, relevant source, tests, and repository instructions. Name the task-owned dirty paths before editing. 2. **Choose** - the smallest behavior falsifiable at the accepted seam. Apply [Testing discipline](~/maestro/WORKFLOW.md#testing-discipline): identify existing evidence and the concrete gap before writing any test. New child 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>"`. 3. **Act** - `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. Then the minimum source and test edits for that behavior. Reach for what the repo already uses first: a helper, type, component, or installed dependency beats new code, and beats a native platform feature the repo has an established equivalent for. Minimum means the fewest concepts a maintainer meets at the seam, not the fewest lines; a wrapper that hides behavior to shorten a diff is a new concept, and the smallest change in the wrong layer is a second bug. A bug fix lands once where every caller routes through. Lazy about the solution, not about trust-boundary validation, error handling that prevents data loss, security, or anything explicitly requested. 4. **Observe** - run the focused test, then type/lint/build checks. A suite that takes minutes runs in the background; its completion notification wakes you, so never hold the turn on `sleep`, `osascript -e 'delay'`, or a poll loop against its log. Review the diff against acceptance; confirm the test could expose the defect. 5. **Learn** - a pass that failed gets exactly one line, `maestro work note <id> "failed: <one line>"`; the lowercase `failed: ` prefix is what `maestro attention` counts. Otherwise note only a reusab