Skip to main content
skill CX Codex

maestro-design — Claude Code skill: what it does, how to install

maestro-design — a skill that resolves blocking unknowns before implementation: architecture choice, modeling, prototyping, and recording durable decisions.

MIT ★ 238 updated 2026-10-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ReinaMacCredy/maestro --skill maestro-design -a claude-code
Open on GitHub

What maestro-design does

maestro-design picks a method based on the unknown type: grill for interdependent user-owned choices, research to look up facts in docs and code, prototype to validate state models, domain-modeling to pin terminology, wayfinder for multi-session efforts wrapped in fog. Each pass closes at least one fork.

The skill operates on design artifacts only and never edits production code. Decisions are drafted via maestro decision draft with rationale and rejected alternatives, then locked with maestro decision lock. For hard-to-reverse forks with wide blast radius, it runs the council protocol: neutral brief, sealed seats, one cross-examination round, and a binding verdict recorded with dissent. Before proposing anything, the skill searches the store for precedent using maestro search and maestro bundle show.

What it helps with

  • choose between several architectures and record the rationale
  • validate a state model with a prototype before coding
  • look up an API fact or library behavior without asking the user
  • record a hard-to-reverse decision with dissent via council
  • pin domain terminology and model boundaries

Example prompts for the agent

  • Run grill to pick between REST and GraphQL, I need to settle several linked choices
  • Use research to find out if pg library supports streaming replication
  • Prototype the order state model to check I haven't missed statuses

How to install maestro-design

1Skills CLI (Vercel)

npx skills add ReinaMacCredy/maestro --skill maestro-design -a claude-code

2Manually: put the files in place

~/.claude/skills/maestro-design/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/maestro-design/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about maestro-design

How to install maestro-design in Claude Code?

Run npx skills add ReinaMacCredy/maestro --skill maestro-design -a claude-code, then check ~/.claude/skills/maestro-design/SKILL.md.

What does maestro-design do?

Resolves blocking design unknowns: architecture choice, modeling, fact lookup, prototyping. Records decisions via maestro decision and never touches production code.

When do you need council mode?

For hard-to-reverse forks with wide blast radius: neutral brief, sealed seats, cross-examination, binding verdict with dissent recorded.

Source text

SKILL.md · MIT
---
name: maestro-design
description: Resolve material unknowns blocking the next authorized slice, using research, grilling, prototypes, models, or wayfinding. Record durable decisions and apply the shared workflow tier rule.
review-date: 2026-11-28
---
<!-- maestro-skill-version: dev -->

# maestro-design

Use when a material choice blocks the next slice. Read
[Decisions and readiness](~/maestro/WORKFLOW.md#decisions-and-readiness) and
[Authorization boundaries](~/maestro/WORKFLOW.md#authorization-boundaries).
Design is read-only toward production code and authorizes nothing.

## Mode per unknown

Identify what kind of unknown blocks progress, then load only the reference
that resolves it:

| The unknown | Mode | Reference |
|---|---|---|
| Decisions only the user can make, several and interdependent | grill | [references/grilling.md](references/grilling.md) |
| A decision owned by someone not in the conversation | route to `maestro-questionnaire` | |
| A fact in docs, APIs, or source outside this repo | research | `maestro recipe show investigation` |
| "Does this state model feel right?" or "What should it look like?" | prototype | `maestro recipe show prototype` |
| Fuzzy terminology, or a hard-to-reverse choice worth recording | model | [references/domain-modeling.md](references/domain-modeling.md) |
| The effort exceeds one session and is wrapped in fog, or the user does not know what to do next | wayfind | [references/wayfinder.md](references/wayfinder.md) |

Facts are yours to find; material product and scope choices are the user's.
Never ask the user for anything you could look up. Modes compose: grill runs with the glossary in
hand; wayfind dispatches grill, research, and prototype per child work item.
Each design pass must close at least one fork; a pass that closes none
surfaces the blocker to the user instead of looping.

## Intake

Pin the problem before choosing a method:

> For [who], reach [observable outcome] within [boundary], because [impact],
> without [excluded effect].

Route uncertainty to a lane:

| Current uncertainty | Lane |
|---|---|
| state unknown | scout, no-write |
| several architectures | two or three decision lanes |
| contract clear | delivery |
| candidate needs breaking | challenge |
| hard-to-reverse fork | council |

Weigh the ROI of independent judgment on five questions:

1. Would wrong framing be costly?
2. Is the decision hard to reverse?
3. Is the domain new to the owner?
4. Can independent judgment produce a materially different option?
5. Is human attention fragmented?

Mostly no: the direct session. Mixed: a Lead plus one peer. Mostly yes:
several lanes. Yes on every question including hard to reverse: a council.
Before launching any lane, pin the branch and commit, active writers, and
dirty paths.

## Recall pass first

Before proposing anything, search the store for precedent:

```
maestro search "<topic keyword>"        # hits labeled work/decision/note/bundle
maestro bundle show <id>                # deep-read a bundle hit
maestro decision list                   # locked choices that bind this scope
```

A past bundle that settled the same fork is evidence; cite it instead of
re-deriving the argument.

## Working method

- Read the current `maestro work show`, linked decisions, notes, and source.
- Present a blocking user-owned fork with a concrete recommendation;
  resolve reversible implementation details within the approved scope directly.
- Record durable decisions under WORKFLOW.md's threshold:
  `maestro decision draft "<choice>" --rationale "<why, with the rejected alternative>" --work <id>`
  then `maestro decision lock <id>`. Supersede an old decision with
  `--supersedes`; never rewrite its history.
- Keep acceptance, non-goals, and authority visible on the work item.
- A Full-tier `maestro bundle open <id> --work <workId>` tells the reviewer
  above you that a design has begun, and the answer may be a question-back
  pass opened on it: a read-only seat that reads the draft SPEC, the decisions
  not yet locked, and the code the SPEC cites, and returns one to three
  questions, each naming the claim it doubts and the evidence that would settle
  it. It reaches no verdict and edits nothing. Before `maestro decide` locks a
  point one of those questions doubts, answer that question - a work note on
  the design item, or a change to the SPEC - and carry the answer into the
  decision's `--why`. A point locked over an unanswered question is a decision
  taken without the evidence it asked for.
- Do not edit code during a design-only engagement.

## Council

A hard-to-reverse fork with wide blast radius runs the `maestro-council`
protocol: neutral brief, sealed seats, one premise verifier on unanimity,
bounded verifiers, one cross-examination round, an audit by tier, and one
binding verdict recorded with `maestro decision draft --rationale` carrying
the dissent. The candidate under review stays frozen; a new finding creates
a new candidate.

## Readiness gate and exit

Check readiness of the next bounded slice, not the number of open questions
about the whole project. Keep later questions visible without blocking an
independent slice. If the problem itself is unclear, wayfind. Forks already
settled are synthesized, never re-asked. An external claim entering a decision
(API behavior, library semantics, versions) comes from research against
primary sources, never from memory.

Then exit by [Tiers](~/maestro/WORKFLOW.md#tiers):

- Light: design ends with a work item with clear acceptance,
  `maestro work add "<title>" --acceptance "<observable result>" --kind <kind>`,
  plus any durable decisions. Kind routes the policies: `feature`, `task`,
  `bug`, `chore`, `implement` are execution units; `idea` and `research` are
  scope notes under a parent and never hold it open. The why lives in the
  title or acceptance; when it needs a paragraph, add
  `maestro work note <id> "why: <paragraph>"`, and record findings from the
  research mode as `research: <finding>` notes (what `policy-research` reads
  when enabled). No SPEC is required; the work is verified inline by
  its playbook (`maestro recipe show <name>`). A quickfix never reaches design.
- Full: `maestro bundle open <id> --work <workId>`, opened in the
  store whose checkout will change (a walk run in the Hub room still opens
  its bundle where the code lives; note the bundle on the Hub map and the map
  on the bundle's work item), then fill SPEC.md as a pure contract: Problem,
  Solution, Scope, Anti-goals (each traces to a real risk in this repo and gets a matching
  VERIFY.md check; an anti-goal that cannot be checked is a wish, not a
  constraint), Decisions (ids only, Hub decisions as `hub:<id>`;
  `maestro bundle show <id>` renders them). Plan checks using
  [Testing discipline](~/maestro/WORKFLOW.md#testing-discipline), including
  existing checks and necessary new tests, not a test quota. Draft VERIFY.md
  from acceptance, relevant risks, and anti-goals; seed NOTES.md with Current
  State, Next Action, original authorization, and `Base:`.

A SPEC that locks a decision on a derived artifact - a module map, a dependency
graph, a measured table - ships that artifact in the bundle beside SPEC.md,
under `## Derived artifacts`, with the script or command that produced it and a
plain statement of what the method over- or under-approximates. The conclusion
is not the evidence: a stated table nobody can re-run reads as settled
precisely because it is stated with confidence, and a VERIFY check that asks a
later reviewer to re-derive what the design claimed to have settled is the sign
the artifact is missing. l7, d880: an 11-module split was locked on a hand
tally that had asserted away a real cycle and missed the per-module counts by
up to 56 lines, and only reconstruction - the thing the design existed to make
unnecessary - exposed it.

If the next slice's acceptance or authority needs guessing, resolve that
blocker. Otherwise continue implementation when the user's original request
already authorizes it; do not ask again merely because design is complete.
For a design-only request, finish with the proposed scope and implementation
gate. A SPEC authorizes nothing.

For unattended/away-mode design constraints, read
`maestro recipe show unattended`.

© ReinaMacCredy · MIT · ReinaMacCredy/maestro

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set10

The whole set →
maestro-questionnaire The maestro-questionnaire skill turns an unresolved decision into a Markdown questionnaire for someone with the missing knowledge. Use it to collect answers asynchronously or in a meeting. CX Codex +1 ★ 238repo stars maestro-coach maestro-coach — a skill for Claude and Codex that unjams a question you got stuck on and teaches the concept behind a decision using your own repo code. CX Codex +1 ★ 238repo stars maestro-bundle maestro-bundle manages SPEC, NOTES, and VERIFY bundle lifecycles and controls context handoffs across agent sessions in Maestro. CX Codex +1 ★ 238repo stars maestro-verify The maestro-verify skill checks acceptance criteria against verification evidence, records a verdict, and guides bundle closure. Use it before handing work back or closing a task. CX Codex +1 ★ 238repo stars maestro-graph maestro-graph — a skill for Claude Code and Codex that runs a task along a predefined graph: spawns agents on each node, collects results, and moves to the next step. CX Codex +1 ★ 238repo stars maestro-work maestro-work is a Claude Code skill that defines shared playbook rules for task briefs, work handbacks, and records. It applies when an agent delegates work or tracks a task in Maestro. CX Codex +1 ★ 238repo stars maestro-council maestro-council runs a structured council over a call you cannot cheaply undo: sealed seats, a premise check, cross-examination and one binding verdict. CX Codex +1 ★ 238repo stars maestro-improve maestro-improve converts filed lessons into minimal doctrine edits. Keeps project rules up to date without losing incident records. CX Codex +1 ★ 238repo stars

Project sponsors

Companies that keep this analytics open