/maestro-card

name: maestro-card
version: 1.37.24
description: "Card work in a project using Maestro after design approval: use for implement, fix, verify, QA, close, release, continue, or unattended prompts like use loop, keep looping, work while away/asleep."

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](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](reference/work.md). Its implement step is test-first (red-green-refactor) whenever the task's `--check` names observable behavior: [reference/tdd.md](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](reference/work.md).

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