Help us improve
Share bugs, ideas, or general feedback.
From maestro
Walks users through an interview-driven product-spec authoring process, producing a committed markdown spec ready for planning or implementation.
npx claudepluginhub reinamaccredy/maestro --plugin maestroHow this skill is triggered — by the user, by Claude, or both
Slash command
/maestro:maestro-designThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill to author or refine a product-spec via the grill protocol. The output is a committed `.maestro/specs/<slug>.md` with YAML frontmatter that `maestro task from-spec` will consume.
Leads a conversational design workshop for new features: interviews one question at a time, explores approaches with trade-offs, and produces a focused spec.
Generates project specs at optimal depth: quick Linear issues for tasks, lite PRDs for features, AI specs with context, evals. Use /spec shortcuts like --quick or --ai.
Orchestrates spec-driven development workflow (Requirements → Design → Tasks → Implementation) with approval gates. Activates for structured feature planning or 'use spec-driven'.
Share bugs, ideas, or general feedback.
Use this skill to author or refine a product-spec via the grill protocol. The output is a committed .maestro/specs/<slug>.md with YAML frontmatter that maestro task from-spec will consume.
The grill protocol is the design skill's interview loop. It is the same pattern named by ADR-0016. Entering this skill IS running the grill — there is no separate spec grill verb.
Track which state you are in throughout the session. Surface the state to the user when it changes, when you are stuck, or when the handoff is imminent. Do not invent additional states.
needs-clarification — the most recent answer was vague, contradicted committed context, or reused a defined term in a new way. You cannot advance the decision tree until it resolves. Re-ask the same branch with the conflict named.design-in-progress — the decision tree has open branches (acceptance_criteria, non_goals, risk_class, mode, work_type, dependencies). Walk them one question per turn.ready-for-planning — the spec is written to .maestro/specs/<slug>.md and maestro spec validate passed. The next phase is maestro-mission (heavy) or maestro-task (light). Surface the state and the slug, then hand off.CONTEXT.md. If they reuse a defined term in a new way, name the conflict before refining the spec.CONTEXT.md inline when a term resolves. Don't batch glossary edits to the end..maestro/specs/<slug>.md and confirming the spec validates (maestro spec validate <path>).Before asking the first question, read:
CONTEXT.md (if present) — the canonical glossary and domain model.docs/adr/ — committed architectural decisions. Recent ADRs frame what the user can and can't change without contradiction.docs/architecture.yaml — the layered architecture rules that any code change will be linted against.src/ if the spec touches existing code.If CONTEXT.md does not exist, create one lazily as the first term resolves — do not stub a blank file up front.
Ask one open question that surfaces the user's intent in their own words. Examples:
Don't ask multiple framing questions in one turn. Pick the one that most narrows the design tree.
For each branch — acceptance criteria, non-goals, risk class, mode, work-type, dependencies — ask one question with a recommended answer. Resolve it before moving to the next.
For each question:
Branches to walk, in roughly this order:
low, medium, high, critical. Default by what the change touches (auth/secrets/payments/policies/migrations → critical or high; src under a single feature → medium; docs-only → low).light (single agent, in-tree) or heavy (worktree-per-task, ADR-0008). Default light unless the change spans multiple features or contracts..maestro/docs/FEATURE_INTAKE.md (six values: new-spec, spec-slice, change-request, initiative, maintenance, harness-improvement).When the user uses a defined term in a new way, stop and name the conflict:
"Your
CONTEXT.mddefines<term>as X. You just used it to mean Y. Which is right — should I update the glossary, or do you mean the existing X?"
When the user states how something works, verify against the code:
"You said
task verifyre-runs all lints. The code insrc/service/task-verify.usecase.tsonly runs architecture lints. Did you mean that, or do you want to broaden the verifier?"
Surface contradictions in the next turn. Don't hide confusion behind plausible spec language.
When a new term is resolved, append it to CONTEXT.md in the same turn it was decided. Keep entries short — a definition and one example.
Do not couple CONTEXT.md to implementation details. Only include terms that are meaningful to domain experts.
Only offer to author an ADR when all three are true:
If any of the three is missing, skip the ADR. The protocol is the deliberate human-driven counterpart to memory-auto-promotion (ADR-0015); ADRs land as committed artifacts the agent commits, not as background captures.
When the decision tree is resolved, write the product-spec markdown to .maestro/specs/<slug>.md. Use the YAML frontmatter that maestro spec validate expects.
Slug rules:
.maestro/specs/<slug>.md already exists, append a numeric suffix (<slug>-2.md).Example frontmatter (refer to src/types/product-spec.ts for the authoritative shape):
---
slug: <kebab-case>
acceptance_criteria:
- <falsifiable criterion>
- <falsifiable criterion>
non_goals:
- <out-of-scope item>
risk_class: medium
mode: light
work_type: new-spec
---
# <title>
## Why
<2–3 sentences on the problem and the consumer.>
## What
<the change, grounded in committed context — link to CONTEXT.md terms and ADRs where relevant.>
## How (optional)
<the rough shape if a particular implementation is required; otherwise leave to plan.>
## Notes
<risks, dependencies, cut lines, references.>
Run maestro spec validate .maestro/specs/<slug>.md. Fix any frontmatter errors before declaring the spec ready.
The next phase after this skill is maestro-mission (for mode: heavy specs) or maestro-task (for mode: light specs).
Pass an approved, validated spec — not a vague direction.
Do not invoke planning or implementation from this skill.
Tell the user the slug, the spec path, and the matching next verb:
maestro mission new "<title>" --from-spec .maestro/specs/<slug>.md, then load maestro-mission.maestro task from-spec .maestro/specs/<slug>.md, then load maestro-task and maestro task claim <id>.Routing the wrong verb at the wrong mode is a silent footgun: task from-spec will accept a heavy spec and materialize an orphan task instead of a mission. Match the verb to the spec's mode:.
maestro spec grill. Entering this skill IS running the grill.maestro principle promote (Phase 1.5).CONTEXT.md compounds; one missed term becomes ten over a quarter.CONTEXT.md, and new ADRs are committed artifacts — not session logs.