maestro

Pre-design research for Maestro cards: creates or validates a same-card research.md receipt, maps context, stakeholders, hosting, unknowns, and the first design fork. Use before maestro-design when the user brings a new idea, zero-context feature, external/pasted plan, unfamiliar domain, stakeholder-heavy request, hosting-unclear work, or when research is missing, stale, skipped-risky, or needed for READY_FOR_DESIGN.

Witness feature close: use after Maestro feature proof and QA pass, before feature close, to write current witness.md/advisor.md receipts, auto-invoke an independent advisor when allowed, apply risk-tier and human-demo policy, and emit Gate: APPROVED.

Card work in a project using Maestro after design approval: use for implement, fix, verify, QA, close, release, continue, or unattended prompts like use loop, keep looping, work while away/asleep.

Audit a project using Maestro read-only: use for code review, architecture review, deepening opportunities, backlog proposals, harness-improvement findings, or repo-wide improvement audits without fixes.

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.

Router for choosing the next Maestro skill or lifecycle recipe.

Setup Maestro in a project using or adopting Maestro: use for init/install/sync/doctor, global skills, hooks, harness setup, or agent integration diagnosis/repair.

Update repository documentation to match the current state of the codebase. Local replacement for the remote /docs command (which needs the Claude GitHub app). Use when the user says /docs, "update the docs", "sync the README", "document this feature", or asks you to refresh docs to reflect current code. Works inline in the current session and edits files in the working tree.

Designs or reviews MCP servers so AI agents can use them reliably: outcome-oriented tools, flat constrained parameters, actionable errors via isError, token-efficient responses, composable outputs, and disciplined tool surfaces. Use when building an MCP server, adding tools to one, reviewing MCP tool design, or when the user mentions MCP optimization, tool descriptions, MCP best practices, or agent-friendly MCP design. Also use when the user has too many tools causing agent confusion, bloated responses wasting tokens, or agents picking the wrong tool.

Strengthen a raw user prompt into an execution-ready instruction set for Amp, Claude Code, Codex, or another AI agent. Use when the user wants to improve an existing prompt, build a reusable prompting framework, wrap the current request with better structure, add clearer tool rules, or create a hook that upgrades prompts before execution.