Agent Skills: Maestro Design

Maestro Design

Use this when the deliverable is the design of record, not code. The feature stays proposed while the contract is still editable. feature reconcile writes or refreshes the pre-finalize receipt, feature finalize writes the clean continuation handoff, and feature accept later freezes the contract only after the user has approved the build transition.

Maestro work has three levels:

High = Card
Mid  = CardKind / workflow kind
Low  = Task

Card is the only high-level durable work object. Feature, Bug, Chore, Custom, Decision, Idea, and Progress are CardKinds / workflow kinds on cards. A Task is the low executable unit, not a CardType in the target model; legacy type: task cards stay readable for compatibility. For tiny same-session work, design toward the low-ceremony task add/start/done/list surface backed by a Progress card's progress.yml. Use facets (design.md, qa.md, notes.md) for any card type that needs contract, evidence, or history, not only features.

Activate with a known session id: maestro hook record --event skill_activation --skill maestro-design --session <session_id>

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. Never chain a guessed id: use only ids read from verb output, and when a lookup misses, re-list instead of retrying spelling variations.

Native harness layer design route: when an external plan, repository-harness idea, prompt pack, PRD, or forked workflow is still unsettled, decide forks here before card work, then route settled text through maestro intake. Use maestro capability and maestro maturity only as read-only evidence when a fork depends on optional providers, proof gaps, UX friction, or next owner. Generated CLI references prove command shape; Harness and targeted skills teach the workflow.

Research entry gate: for zero-context, unfamiliar-domain, externally pasted, stakeholder-heavy, or hosting-unclear ideas, route through maestro-research before opening design forks. maestro-design may start only from fresh research.md, an explicit skip receipt, or clearly settled context recorded with evidence. When maestro research check <card-id> exists, use it as a read-only receipt validator and route to maestro-research if research is missing, stale, risky-skipped, or hosting-incompatible.

Native Maestro MCP tools may be used for supported orientation reads (maestro_status, maestro_feature_show, maestro_card_list, and related list/show tools) when the host exposes them. Design authoring still uses the CLI because feature design, feature set, and decision lock are not MCP tools yet. After the design hand-off, maestro-card prefers MCP for supported work-card and feature-lifecycle steps.

Routing: choose the matching branch and load only its reference first.

• External PRD with open forks -> decide forks in design, then intake per maestro-card.
• PRD synthesis from settled context -> use reference/prd.md.
• Grill/stress-test session -> use reference/grilling.md.
• Domain-modeling session -> use reference/domain-model.md.
• Grill With Docs session -> use reference/grilling.md, plus reference/domain-model.md for Maestro design/decision updates.
• Chosen architecture deepening candidate -> use reference/deepening-candidate.md.

Conversation Driver

Keep a working thesis from the user's latest correction, selected text, sidechat paste, example, and preference. Before opening or revising a fork, fold that thesis into the option framing instead of treating the new detail as a loose comment.

Before technical forks, decide scope depth before offering options. Default to Full Durable Design: lock the complete intended system. Scope target and implementation staging are separate.

Anti-MVP scope authority: if the user says "anti-MVP", "full", "deep", "complete", "make one forever", "full framework", or rejects MVP, treat Full Durable Design as the scope authority. Do not offer MVP, first-slice, or reduced product scope unless the user explicitly asks for MVP. If risk is high, stage the build, proof, or delivery; do not shrink the design target.

When anti-MVP authority applies, every design answer separates:

• Full target: the complete system being designed.
• Build stages: safe implementation phases.
• Proof gates: how each stage is verified.
• Deferred work: only implementation sequencing, not reduced vision.

Keep a short fork queue. After each locked decision or clarified user answer, derive the next unresolved fork from the feature design, open questions, locked decisions, and working thesis. If a concrete next fork exists, present it in the same turn; do not make the user send "next fork" just to continue. If no fork remains, do not go straight to build approval. First run a bounded edge sweep chained to Maestro's shipped Unknowns Lens as the no-fork edge sweep: pressure-test the locked design for edge cases that could change acceptance, proof, non-goals, ownership, or safety; then read maestro loop next or maestro loop next --json and compare unknown_gap against locked decisions, feature questions, acceptance, affected areas, removals, proof gates, and shared-state risks. Use the shipped loop next unknown_gap framing to decide whether remaining unknowns are material. Material unknowns reopen a fork. If the sweep finds only implementation risk, add acceptance/proof wording. If it finds no material issue, say: "No forks remain. Edge sweep found no material unresolved choices. Waiting for explicit build approval." Only a clean sweep reaches the explicit build-approval gate. Do not run maestro feature reconcile <id> or maestro feature finalize <id> until the user approves the build transition.

Every material fork needs a detail floor:

• the concrete problem being decided
• A/B/C options with artifact-level previews
• one real Maestro example
• edge-case pressure: what each option could miss; edge pressure must state the failure mode, safety boundary, stale-state risk, or unknown that would make the option wrong, and whether it creates a known_unknown, unknown_known, or unknown_unknown_risk for the final sweep
• the tradeoff and why rejected options lose
• a clear recommendation
• the exact answer format expected from the user

Completion criterion: a fork is ready to ask only when the user can answer in the requested format and the eventual lock context can cite a real artifact, command output, or explicit user statement.

If the user asks for more detail, examples, or clarification, answer by improving the current fork or thesis first. Only open a new fork after the clarified point is settled or explicitly becomes the next decision.

Recipe checkpoint: Maestro's main workflow is the loop. Use maestro status for current state and maestro loop next as the read-only router when the next recipe is not obvious. Design work normally uses the shipped design lifecycle recipe. Before deciding or changing the proposed contract, read or cite maestro loop show design and keep the work inside perceive -> choose -> act -> observe -> learn -> continue. If the user is unavailable but gave a bounded design mandate, read or cite maestro loop show design-relay first: the main session may make only in-mandate design decisions, subagents/advisors provide evidence only, and the relay returns to the parent design loop. Writes still use the existing Maestro verbs named by the recipe. Custom recipes are allowed only for the current card/run, and only when no shipped recipe fits; they must use the same six phases, current Maestro verbs, hard stops, and continue output. Rule: loop next recommends; outcome/proof/memory verbs write. Use maestro loop next --chain to explain the current chain position, transition trigger, next native command, and return conditions without writing. Use maestro loop outcome for structured attempt evidence and transition receipts after native work, maestro loop trace <card> to audit card-scoped chain receipts, and maestro loop improve for read-only improvement proposals; do not silently edit recipes or skills from router output. Do not use hidden stores, hidden schedulers, silent recipe mutation, or proof/QA bypass. When designing loop automation, map it into native Maestro pattern packs, recipe templates, readiness levels, and operating limits. Name the intended readiness target (L0 draft, L1 report, L2 assisted, or L3 unattended), the evidence maestro loop validate <pattern> and maestro status must show, and the cadence/max-attempts/max-subagents/denylist/budget/kill-switch/connector permission limits. Do not design a separate daemon, cron owner, queue, hidden executor, STATE.md, LOOP.md, or scheduler inside Maestro; external schedulers stay external and Maestro reports readiness for them.

First step in a session: run maestro active (pull-only) to see what other live sessions are working on -- their card, mode, and progress -- before you open anything. If a peer session is on a related card, connect yours with maestro link add <your-card> <their-card> once you have created it; maestro never auto-links. Linked cards exchange messages with maestro msg send <their-card> "<text>" and maestro msg read; an [inbox] N new line on STDERR before any command means a linked peer is waiting. Act on the banner before unrelated work and run maestro msg read, as maestro-card already does. Inbox is advisory coordination: it can suggest a cross-card Task dependency, but it never blocks execution by itself. Record explicit Task blockers/dependencies when ordering matters. Reply when the message poses a question or needs a decision; an FYI needs no reply. maestro never auto-reads or auto-replies; you do.

Do

1. Open one feature for the topic: maestro feature new "<topic>", seeding --description with the problem.
2. Map the current state from real evidence before options: files, commands, outputs, screenshots, or repo artifacts with file:line where code is involved. Write what you map into the design facet as you go: maestro feature design <id> --section "Current state" --append "<finding>". The same verb fills Problem and creates any new section; --replace rewrites a section wholesale. For a complex core domain, model it here: run the DDD fitness gate in reference/ddd.md before reaching for domain-driven design (most cards do not need it; stop at the first NO). When the design turns on domain language, bounded contexts, or business concepts, run the domain-model branch in reference/domain-model.md.
3. Put the problem and open questions on the feature: maestro feature set <id> --description "<problem>" --question "<loose question>". When the request is to turn settled context into a PRD, use reference/prd.md and do not open a new discovery interview.
4. Decide one fork at a time. For each fork, give the concrete example, the options, the tradeoff, and the chosen answer. Sketch every option inline as ASCII before asking, so the preview is readable in the terminal. When the user asks to grill, stress-test, or challenge a plan before build, use reference/grilling.md: walk branches one by one, give a recommended answer, and ask exactly one question at a time.
5. Lock each decision durably: maestro decision new (with --feature and --context) opens the fork; maestro decision lock records the chosen answer, the rejected options, and optionally a preview and superseded decisions. A fork the user already settled opens and locks in one call: maestro decision new --lock --decision "<chosen>". Put the chosen ASCII sketch into --preview as multiline text. The lock echoes the entry and appends the dated feature-note pointer automatically; do not add a manual duplicate note. For "lock all", "all rec", or all-recommendations batches, use maestro decision set draft / maestro decision set lock, or lock each child decision separately. Do not compress multiple independent forks into one summary maestro decision lock.
6. If a chosen answer removes a field, file, command, behavior, or workflow, enumerate consumers before locking the removal.
7. Before locking a material or hard-to-reverse fork, get an independent adversarial review from a fresh context. Use an advisor-class tool or a skeptic sub-agent as peers, then incorporate or explicitly rebut its points in the lock context.
8. Keep feature questions current: open decisions are for real forks; --question is for loose questions not yet forks. A question that becomes a fork is opened as a decision and removed from questions.
9. Author the implementation contract only after decisions are stable: maestro feature set <id> --acceptance "<observable behavior>" --area "<surface>".
10. When design is done, stop at the build-approval gate. After the user approves build, run maestro feature reconcile <id> first to write or refresh the pre-finalize receipt, then write the canonical clean handoff with maestro feature finalize <id>. The next agent starts at .maestro/cards/<id>/handoff.md; raw design.md, legacy spec.md, notes.md, and decision cards stay preserved for audit.

Completion criterion: design is ready for build approval when every material fork is locked or left as an explicit feature question, acceptance criteria and affected areas exist, and the next gate is explicit. The implementation handoff is complete only after the user approves build and feature reconcile plus feature finalize refresh handoff.md.

Taste Forks

Use a generate-filter pass for naming, UX wording, API shape, report structure, or other judgment-heavy forks. Full orchestration HOW (generator angles, judge, pairwise): maestro loop show generate-filter.

1. Write a 3-5 point rubric into notes.md before generating options.
2. Ask 3-5 fresh-context generators for one concrete option each from different angles, such as minimal, user-first, or consistency-first.
3. Use a fresh judge to score against the rubric and remove duplicates.
4. If scores cluster, run pairwise matches until one option survives.
5. Lock the survivor with maestro decision new then maestro decision lock; record why rejected options lost. Generators do not become durable outputs. Only the conductor locks, one decision at a time: parallel decision lock calls on one feature collide on the shared decisions.yaml (HARNESS Orchestration). Generators return their option as data; they never lock.

Grilling Forks

When the user says "grill me", "grilling", "stress-test this plan", or asks for relentless challenge before building, run a grilling session inside the design loop. Ask one question at a time, provide your recommended answer, and answer explorable questions from code/docs/artifacts instead of asking. If the user asks for docs while grilling, combine this with the domain-model branch. Full branch: reference/grilling.md.

PRD Synthesis

When the user asks to turn the current conversation into a PRD, synthesize only from existing conversation, codebase evidence, domain language, and decisions. Do not interview for new scope. Full branch: reference/prd.md.

Architecture Deepening

When the user picks a deepening opportunity from maestro-audit, design the chosen module, interface, seam, dependency strategy, and surviving tests in maestro-design. Full branch: reference/deepening-candidate.md.

Probe Forks

When a fork hinges on runtime or state-machine behavior you cannot settle by reading, build a throwaway runnable harness, drive it through the edge cases, record the answer in the decision context or notes.md, then delete the harness. Preserve the answer, not the code.

Domain Model Forks

When a fork hinges on project language or boundaries, challenge the terms before locking the design. Use maestro grep "<topic>" as the native search path, then read the feature design, handoff, notes, decisions, memory, and relevant code before asking; if evidence can answer a question, inspect it instead. Resolved domain terms are captured in the feature design and material trade-offs are locked as Maestro decisions. Full branch: reference/domain-model.md.

Stop

• Do not implement from this skill.
• Do not batch unrelated decisions into one lock.
• Do not turn "lock all" or all-recommendations replies into one compressed summary decision. Use a DecisionSet or separate child decisions.
• Do not keep a contradicted locked decision silently. To reopen a locked ruling, supersede it with maestro decision supersede; never edit or unlock the locked Decision record.
• Do not resume from chat memory. Resume from maestro feature design <id>, .maestro/cards/<id>/handoff.md first when it exists, then raw design.md, legacy spec.md, notes.md, and maestro decision list --feature <id> for audit or deeper context (the bare list windows to recent decisions, so scope it to your feature).

Hand-off

Pipeline: [maestro-design: explicit build approval -> feature reconcile -> feature finalize] -> maestro-card (qa-baseline -> feature accept -> prepare -> work -> verify -> qa-slice -> feature close)

Next: decisions locked and contract authored -> stop at explicit build approval. After build approval, run maestro feature reconcile <id>, then maestro feature finalize <id>, then hand to maestro-card (its qa-baseline reference, then feature accept). The hand-off is a lifecycle gate: feature accept and feature prepare fail when .maestro/cards/<id>/handoff.md is missing or stale. When the user authorizes building, do not re-ask -- flow straight through reconcile -> finalize -> qa-baseline -> accept -> prepare -> work.

As you cross into 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 shared file; merge back then --clear); maestro loop show conflict-handoff is the full dance.