maestro-setup
Maestro Setup -- Project Context Scaffolding
Interview the user to create persistent project context documents. These files are referenced by all maestro:* skills for deeper project understanding.
Arguments
$ARGUMENTS
--reset: Delete all existing context files and start fresh.- Default (no args): Run setup interview. If context already exists, offer to update or skip.
Step 1: Handle --reset
If $ARGUMENTS contains --reset:
- Confirm with user before deleting
.maestro/context/,.maestro/tracks.md,.maestro/setup_state.json - If confirmed: delete and report. Stop.
Step 2: Check Setup State (Resume Protocol)
See reference/resume-protocol.md for full state machine, step name registry, and skip logic.
Check .maestro/setup_state.json. If interrupted run found, offer resume or start over.
Step 3: Check Existing Context
Skip if resumed past this step.
Search for .maestro/context/*.md. If exists, ask: Update / View / Cancel.
Step 4: Detect Project Maturity
Skip if resumed past this step.
Classify as Brownfield (existing code) or Greenfield (new project).
Brownfield indicators: package manifest exists, src//app//lib/ has code, .git with 5+ commits.
Brownfield flow:
- Warn if uncommitted changes exist
- Ask scan permission (read-only codebase analysis)
- If granted: scan via
git ls-files | head -200, read README, manifests, CLAUDE.md, linter configs - Store inferences for pre-filling interview answers
Greenfield flow: Announce new project. Offer git init if no .git/.
Step 5: Create Context Directory
mkdir -p .maestro/context
5a: Bootstrap Beads Workspace
If .beads/ does not exist and br is available: br init --prefix maestro --json && br doctor --json. Skip silently if br is not installed.
Steps 6-10: Interview & File Generation
Each step generates one context file via an interactive or autogenerate flow.
See reference/interviews.md for all questions and branching logic.
See reference/templates.md for all file formats.
| Step | File Generated | State Key |
|---|---|---|
| 6 | .maestro/context/product.md |
product_definition |
| 7 | .maestro/context/tech-stack.md |
tech_stack |
| 8 | .maestro/context/guidelines.md |
coding_guidelines |
| 9 | .maestro/context/product-guidelines.md |
product_guidelines |
| 10 | .maestro/context/workflow.md (use reference/workflow-template.md) |
workflow_config |
Write state after each step completes.
Step 11: Initialize Tracks Registry
Create .maestro/tracks.md with registry header. See reference/templates.md.
Step 12: Code Style Guides (Optional)
Offer to copy style guides from reference/styleguides/ to .maestro/context/code_styleguides/.
See reference/interviews.md for the question format.
Step 13: Generate Index File
Write .maestro/context/index.md linking all context files and the tracks registry. See reference/templates.md.
Step 14: First Track (Optional)
Offer to create the first track. See reference/interviews.md for the flow and reference/templates.md for file formats.
Step 15: Summary and Commit
Display summary of all generated files. See reference/templates.md for output format and commit messages.
Remove .maestro/setup_state.json on successful completion.
Step 16: Auto-Generate AGENTS.md
After the commit succeeds, check if AGENTS.md exists. If it does NOT exist, automatically invoke /maestro:AGENTS.md (no arguments, no user prompt). If AGENTS.md already exists, skip silently.
Relationship to Other Commands
Recommended workflow:
/maestro:setup-- You are here. Scaffold project context (run first)/maestro:AGENTS.md-- Generate AGENTS.md context file (offered at end of setup)/maestro:new-track-- Create a feature/bug track with spec and plan/maestro:implement-- Execute the implementation/maestro:review-- Verify implementation correctness/maestro:status-- Check progress across all tracks/maestro:revert-- Undo implementation if needed/maestro:note-- Capture decisions and context to persistent notepad
Setup is the entry point for all maestro workflows. All other commands depend on the context files it creates. Run this once per project, then use /maestro:new-track to start building.