Agent Skills: maestro-work

maestro-work

Use for one accepted implementation unit. Keep the change inside the work item's acceptance and authority. If the scope is unclear or must expand, stop and return to maestro-design.

Tier first, recon second

Decide the tier from the request alone, before reading bundle files, the store, or the rest of this skill (maestro-bundle tier rule):

• quickfix: a one-sentence diff with no Full trigger. Do it directly, verify inline with the smallest check that can falsify it, no work item, no test demanded, none of the machinery below.
• Light: one session, one branch, acceptance in a sentence. maestro work add|start|done is the whole record. Verify the changed surface inline; a regression test is written only for a real bug being fixed, never as ceremony: it reproduces the bug where it shows and lands with the fix, in the ordinary bugfix order, not through a red-green loop, and no TDD skill is loaded for it. No SPEC, no red list.
• Full: an open bundle. Preconditions before any edit: the user's explicit request to implement or fix this scope, and a SPEC whose Scope names this work; its Red tests, when present, are the only tests written. A SPEC that predates the requested scope (post-ship review findings, hardening follow-ups) counts as missing: return to maestro-design first. A throwaway prototype not yet approved to port is maestro-explore's scope: fix it there without opening production work.

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.

After two or three failures on the same mechanism, stop and record an episode packet as maestro work note <id> "failed: <one line>", 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. In a Full bundle, write the failing test the SPEC's red list names before production code and watch it fail for the expected reason; under Light, name the inline check that will falsify the change instead. New child work gets --acceptance "<observable result>".
3. Act - maestro work start <id>, 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. 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 reusable correction.
6. Continue - maestro work done <id> with --claim/--proof naming the real falsifier (the check that would have failed if the claim were wrong). In a bundle, overwrite NOTES.md (current state, next action, base commit) before releasing the work item.

Test-first root laws

1. Red tests only transcribe DECIDED behavior at an accepted seam. Having to guess the contract means you are still in the design lane - spike, decide, then test.
2. Test at the outermost stable seam (here: the CLI) so internals stay free to change.
3. Serve the behavior, never the test. A wrong test is shifted openly - make the deliberate change and record it with maestro decision draft - code is never contorted to please a test.
4. A test must be able to kill the bug: no tautologies, no asserting that a mock called a mock.
5. No silent test edits. Every shift or deletion of a test records its reason.

Concrete smells and fixes: references/tdd-antipatterns.md.

Hard rules

• No tests beyond the SPEC's red list (Full) or the real bug's regression (Light). After-the-fact confirmatory tests are bloat; add none.
• Never delete, skip, or weaken a failing test to make the suite pass. A failing test is information: fix the code or surface the conflict.
• Red must fail on an assertion at the agreed seam, not on a missing symbol. A test may name code that does not exist yet only when a locked decision already settles that contract's shape; a compile error over an undecided call shape is the test inventing the API. Never create the symbol to bridge it: treat the unsettled contract as a fork, ask one question, record the answer, then write the red test against the decided shape.
• Functionality outside the acceptance, or a fork no decision settled: pause the slice, ask the user exactly one question, record the answer with maestro decision draft ... --work <id> and lock, then continue. A fork needing more than one question is a maestro-design grill pass, not a mid-work detour.
• Scope the user cuts mid-loop leaves in the same turn: drop it from the red list and VERIFY.md, remove the tests and dead code written for it, and record the cut as a decision.
• When the failure's cause is unknown, diagnosis (maestro-diagnose steps) is the first phase of this authorized fix, done here, not as a separate engagement.
• A missing external fact (API behavior, library semantics, version differences) is not scope expansion: look it up against primary sources, record the finding and its link with maestro work note <id>, and continue. If the answer contradicts a locked decision, stop and supersede the decision first.
• A behavior-preserving change (dependency upgrade, refactor): red is the baseline captured via maestro-explore before the change; green is the baseline reproducing after. Add no new tests for behavior that is not changing. A request to change baselined behavior is new scope: re-capture that baseline and record which lines changed and why; editing it silently to match is weakening a test.
• Generated or vendored files are never the target: fix the generator or pin and regenerate.

Red flags

| The thought | The reality | |---|---| | "The test is basically right - I'll adjust the assertion to match the output" | That documents the current bug as expected behavior. Assert from the decision's promise and fix the code. | | "This one is hard to write red-first; I'll add the test after" | A never-red test proves nothing. Find the seam, or renegotiate it as a decision. | | "The test doesn't compile - I'll create the missing symbol so it can run" | That lets the test mint the API. If a decision settles the shape, implement toward it in Act; if not, it is a fork to settle first. | | "While I'm here, this nearby code could use a cleanup" | Not in the acceptance means not in scope. Mention it; do not touch it. | | "Skipping this failing test unblocks the suite" | A failing test is information. Fix the code or surface the conflict. | | "I'll batch all five open forks into one message" | One question per unsettled fork mid-loop; more than one is a maestro-design grill pass. | | "It's a small task, but the method says write a test first" | Ceremony scales with tier. Quickfix and Light verify inline; only a Full bundle's named risks get red tests. |

When the scope is done and the checks are green: Light closes with maestro work done; a Full bundle routes to maestro-verify.

Coordination

Isolated lanes and worktrees: references/worktree.md. Contested files or overlapping sessions: references/conflict-handoff.md.