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]