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

• Open one feature for the topic: maestro feature new "<topic>",

seeding --description with the problem.

• 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.

• 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.

• 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.

• 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.

• If a chosen answer removes a field, file, command, behavior, or workflow,

enumerate consumers before locking the removal.

• 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.

• 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.

• 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.

• Write a 3-5 point rubric into notes.md before generating options.
• Ask 3-5 fresh-context generators for one concrete option each from different

angles, such as minimal, user-first, or consistency-first.

• Use a fresh judge to score against the rubric and remove duplicates.
• If scores cluster, run pairwise matches until one option survives.
• 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.