maestro-design - SKILL.md Agent Skill

name: maestro-design version: 1.5.0 description: "Use for design or brainstorming in a Maestro repo before implementation starts. Map current behavior, decide one fork at a time, record decisions and notes, then hand the approved contract to maestro-feature."

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 accept ends design and freezes the contract.

Activate: maestro hook record --event skill_activation --skill maestro-design

Do

Open one feature for the topic: maestro feature new "<topic>" --description "<problem>" --question "<loose question>".
Map the current state from real evidence before options: files, commands, outputs, screenshots, or repo artifacts with file:line where code is involved.
Put the problem and open questions on the feature: maestro feature set <id> --description "<problem>" --question "<loose question>".
Decide one fork at a time. For each fork, give the concrete example, the options, the tradeoff, and the chosen answer.
Lock each decision durably: maestro decision new "<decision title>" --feature <id> --context "<why>" opens the fork; maestro decision lock <decision-id> --decision "<chosen>" --rejected "<option: why>" [--preview "<example>"] [--supersedes <id>] fills and locks it. The lock echoes the entry and appends the dated feature-note pointer automatically; do not add a manual duplicate note.
If a chosen answer removes a field, file, command, behavior, or workflow, enumerate consumers before locking the removal.
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>".

Taste Forks

Use a generate-and-filter pass for naming, UX wording, API shape, report structure, or other judgment-heavy forks.

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.

Stop

Do not implement from this skill.
Do not batch unrelated decisions into one lock.
Do not keep a contradicted decision silently. Reopen or supersede it in the Decision record.
Do not resume from chat memory. Resume from maestro feature spec <id>, .maestro/features/<id>/notes.md, and maestro decision list.

Hand-off

Pipeline: [maestro-design] -> qa-baseline -> maestro-feature -> maestro-task -> maestro-verify -> qa-slice -> feature ship

Next: decisions locked and contract authored -> qa-baseline, then maestro-feature for feature accept.