Maestro Card Agent Skill

Maestro Card

Maestro uses three work levels: High = Card, Mid = CardKind / workflow kind,

and Low = Task. Feature, Bug, Chore, Custom, Decision, Idea, and Progress are

CardKinds, not separate high-level objects. Progress is a lightweight CardKind

that stores many low Tasks in progress.yml; legacy type: task cards remain

readable for compatibility. This skill covers the active-work cluster: the task

work loop, card/feature lifecycle, proof, and QA gates. Design

(maestro-design), audit (maestro-audit), and setup (maestro-setup) have

their own skills.

Activate with a known session id:

maestro hook record --event skill_activation --skill maestro-card --session <session_id>

First step in a session: run maestro active (pull-only) to see what other

live sessions are working on before you claim. If a peer is on a related card,

connect yours with maestro link add <your-card> <their-card>; maestro never

auto-links. Once linked, coordinate through the channel: `maestro msg send

<their-card> "<text>" and maestro msg read. An [inbox] N new (...) ->

maestro msg read` line on STDERR before any command means a linked peer is

waiting -- clear it with maestro msg read (see reference/work.md).

Inbox messages are advisory coordination only: they can suggest an ordering

relationship, but they do not block work. Record an explicit Task blocker when

execution order matters. Reply when the message poses a question or needs a

decision; an FYI needs no reply.

Phase 0: design-to-card gate. Before task setup, feature prepare, source

edits, implementation tests, or other work verbs, ask:

• Am I coming from design or brainstorm?
• What card/feature owns this work?
• Is that card/feature handoff finalized and fresh?

If the answer starts in design and the owning card/feature or fresh handoff is

missing, stop. Bind chat-only or standalone Decision records to a Feature/card

contract and refresh/finalize the handoff through the supported feature

lifecycle path first. Progress rows cannot be used to implicitly end design.

If the design approval included "lock all", "all rec", or all-recommendations

decisions, confirm they landed as a DecisionSet or separate child decisions. Do

not build on a compressed summary lock; run maestro decision audit --compressed

and route repair through maestro decision set repair or back to

maestro-design.

When you start implementation, apply the session-owned main fast path first:

if only your session is fresh, and dirty paths are current-session Maestro state

or unrelated files you will not touch, stay on main. Worktree-isolate only for

a fresh non-self same-card/path overlap, unknown source/test dirt,

release/install clean-tree proof, or explicit user isolation. If you split,

follow the conflict-handoff protocol in HARNESS.md: link + maestro conflict

on a file you will share, merge back then --clear. The full dance (including

a conflicted merge-back) is maestro loop show conflict-handoff.

Recipe checkpoint: Maestro's main workflow is the loop. Use maestro status

for current state, maestro loop next as the read-only router when the next

recipe is not obvious, and maestro loop show <recipe> for the selected

lifecycle grammar. Use maestro loop show work for task/card implementation,

maestro loop show ship before close/release/archive gates,

maestro loop show unattended for away-mode autonomy, and

maestro loop show learning when recording reusable lessons. Writes still use

the existing Maestro verbs named by the recipe. Rule: loop next recommends;

outcome/proof/memory verbs write. Use maestro loop next --chain to explain

current chain position without writing, maestro loop outcome to append

structured attempt outcomes and transition receipts after native work,

maestro loop trace <card> to audit card-scoped receipts, and `maestro loop

improve` for read-only improvement proposals whose apply commands must be run

explicitly. Do not use hidden stores, hidden schedulers, silent recipe mutation,

or proof/QA bypass. Custom card/run recipes are

allowed only when no shipped recipe fits, and must keep the same six phases,

current Maestro verbs, hard stops, and continue output. Work Lease is only a

choose-phase helper; it may select or reserve one safe unit, but it is not a

scheduler, daemon, queue, worker launcher, executor, hidden store, or second

lifecycle.

Loop readiness is an evidence gate. For production loop patterns or any

unattended/away-mode claim, read maestro loop validate <pattern> and

maestro status; report the effective L0/L1/L2/L3 level, gaps, operating-limit

sources, scheduler stance, liveness, and blocked_from_next_level. Do not

claim L3 or use unattended wording unless the readouts say L3 and no blockers

remain. External schedulers stay external; Maestro stays passive/local-first.

Route

Pick one branch, read its reference, then apply the shared ground rules below.

Load extra references only when the chosen branch points at them.

• Pick up, progress, finish, or unblock executable Tasks:

reference/work.md. Its implement step is test-first

(red-green-refactor) whenever the task's --check names observable

behavior: reference/tdd.md.

• Track simple work with the low-ceremony Task surface (task setup or `task

add -> task start -> task done`, no separate todo namespace): this

creates or reuses a Progress card and stores low Tasks in progress.yml.

Installed hooks block write-like tool use until a visible Progress checklist

exists; see the "Simple Task Board" section of

reference/work.md.

• Tidy a card's diff before proving it (quality cleanup, applied in place):

reference/simplify.md. On a test-first card this is

the red-green-refactor step, not a second pass.

• Work the backlog unattended, including "use loop", "keep looping",

"I am going away", "I am going to sleep", "work while I am away", or broad

user goals that must first compile into Maestro records while the user is

away or asleep:

reference/loop.md

• Finalize, accept, prepare, amend, close, or archive a feature card after design:

reference/feature.md

• Prove a claim, repair failed proof, or verify adversarially:

reference/verify.md

• Capture the behavior contract before feature accept:

reference/qa-baseline.md

• Replay scenarios and record slice evidence before feature close:

reference/qa-slice.md

• Intake an external spec, plan, or PRD after design approval:

reference/intake.md

Shared Ground

• Prefer native Maestro MCP tools for lifecycle reads and writes when the host

exposes them. The host-loaded tool schema is authoritative. Use CLI commands

when MCP is unavailable, for verbs not yet exposed as MCP tools, or when

debugging unsupported behavior.

• Native harness layer work route: run maestro intake for settled external

specs or plans before creating executable tasks; run maestro capability

when work depends on optional tools, files, connectors, or host receipts; run

maestro maturity before proof or close when context, acceptance, proof gaps,

UX friction, maturity level, or next owner is unclear. Generated CLI

references prove command shape; Harness and targeted skills teach the

workflow.

• Exact command signatures live in reference/cli.md,

generated from the binary. A verb or flag not listed there does not exist;

read it instead of probing --help. CLI remains the compatibility and

human-facing contract; MCP is the agent ergonomic contract.

• Discover executable work with maestro task list, maestro task next, and

maestro card list for card-container context. Progress-backed low Tasks

appear in task views as routine REF rows; use task list --json when you

need stable ids. The Progress card itself appears in card views. Take and annotate tasks with

maestro task start/maestro task claim, maestro task update, and

maestro task note.

• Record implementation discoveries with maestro task note <task-id> "<text>"

for decisions not in the handoff/spec. Record plan changes, tradeoffs, gotchas, risks, and follow-up work; use maestro note <card-id> only for card-store notes. Scope or acceptance changes still require Feature/Card contract amendment.

• Ids are stable and opaque (card-<hash>; features keep their creation

slug). The dotted alias show prints is display-only; never address a card

with it.

• Never chain a guessed id: use only refs read from task list for immediate

Task subcommands, or ids read from verb output (task add --id-only, `task

list --json, card list, card show`). When a lookup misses, re-list and

read the real id; do not retry spelling variations.

• Do not hand-edit card.yaml or the verb-guarded sidecars (qa.md,

state history). Use verbs so gates and audit trails stay intact.

• Terminal words are per type — feature closed/cancelled, task

verified/rejected/abandoned/superseded, decision

locked/superseded, and Bug/Chore/Custom card containers closed after

owned tasks verify — and all of them read as coarse closed on the board.

maestro card close fits only legacy task cards or task-owning

Bug/Chore/Custom containers whose owned tasks are verified.

When the user says "close" a feature, branch on its state: a live feature

means feature close or feature cancel; a feature already terminal

(closed/cancelled) means archive it. If the current request, accepted

contract, SPEC, or run record grants bounded ship or auto-archive authority

for this target, do not finish at "closed" and do not ask again: after the

requested push/publish/release/local-install/handoff boundary completes and

the delivered commit hash is known, run maestro feature auto-archive <id>

as the next lifecycle step. If no such authority exists, run

maestro card archive <id> only when the user's terminal "close" wording is

explicit archive intent. Archive is never a blind close/cancel side effect,

and a non-terminal feature is never archived.

• For preauthorized auto-archive, use maestro feature auto-archive <id> with

a current target-scoped authority (--authority-ref, --authority-target,

--authority-head, --authority-state current), exact QA evidence

(--tested-head, --qa-result pass, repeat --qa-evidence), the owning

run/worktree disposition (--run, --multi-agent, --worker-source), and

the current store that owns the target card

(--canonical-store <path-to-current/.maestro>). A linked implementation

worktree may auto-archive when its current .maestro store owns the target,

the work is done, and evidence names the exact current HEAD. Stop instead of

archiving if the helper refuses, if relevant worktree state is dirty, if

worker changes are not represented in the current target HEAD, if the

current store does not own the target card, if relevant Maestro conflicts are

still asserted, or if terminal archive preflight fails.

• When the user corrects or steers active work, do not pause just because they

corrected you. If the correction is clear, record it with `maestro event

intervention --note "<what changed>" [--topic <slug>]` and apply it. If it is

unclear but low-risk, state the assumption, record it, and continue. Ask only

when the ambiguity can change scope, contract, schema, lifecycle, release

behavior, or other hard-to-reverse work. Full routing lives in

reference/work.md.

Pipeline

maestro-design -> feature reconcile -> feature finalize -> [maestro-card: design-to-card gate -> qa-baseline -> feature accept -> prepare -> work -> verify -> qa-slice -> feature close]