/maestro-design

name: maestro-design
version: 1.36.16
description: "Design in a project using Maestro before implementation: use for brainstorm, plan, PRD synthesis, grilling/stress-test, domain model, deepening candidate, wording, workflow, skill/harness, card/task/feature, architecture, UX, or agent-process decisions."

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](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](reference/prd.md).
• Grill/stress-test session -> use [reference/grilling.md](reference/grilling.md).
• Domain-modeling session -> use [reference/domain-model.md](reference/domain-model.md).
• Grill With Docs session -> use [reference/grilling.md](reference/grilling.md),

plus [reference/domain-model.md](reference/domain-model.md) for Maestro design/decision updates.

• Chosen architecture deepening candidate -> use

[reference/deepening-candidate.md](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