maestro-setup

Maestro Setup

Use this skill to create or refresh a long-running agent harness in a project. Skill and CLI mirror each other: maestro setup is the single idempotent entrypoint that scaffolds the project; the skill owns the content-generation flow that lives on top of it.

Core Contract

• Skill owns content; CLI owns audit + scaffold + self-test.
• Non-interactive by default. Do not ask questions during ordinary setup.
• Evidence-first. Infer from repo files and mark uncertain facts as TODO.
• Keep substantial setup content under .maestro/context/.
• Root AGENTS.md is generated by Step 5 (init-deep workflow): a hierarchical PROJECT KNOWLEDGE BASE with the Maestro pointer absorbed inside, still wrapped by <!-- maestro-setup:start --> / <!-- maestro-setup:end --> markers.
• Preserve user content outside managed markers.
• Overwrite .maestro/setup-report.md on each run.
• Do not fetch from the web. Use frozen snapshots in reference/styleguides/.

Setup CLI Surface

The setup verb is a single idempotent state machine. Re-running it is safe.

• maestro setup — default action. Runs the full sequence in order: bootstrap-dirs, write-project-config, drop-templates, write-project-pointers, seed-principles, sync-skills. Each step is idempotent; existing artifacts are left in place unless --reset-templates is passed.
• maestro setup --global — write ~/.maestro/config.yaml only; does not touch the current project.
• maestro setup --dry-run — preview the state machine's writes (would-create, would-overwrite, would-delete) without mutating the filesystem.
• maestro setup --resync-skills — additionally remove any managed skill directories under .claude/skills/ and .codex/skills/ that are not in the current shipped set, then re-drop the canonical ones.
• maestro setup --reset-templates — re-emit any project bootstrap templates that the user previously customized back to their shipped defaults (asks before overwriting unless run with --json).
• maestro setup --no-git-ok — allow setup outside a git working tree. Without this flag, setup refuses to run when .git/ is absent.
• maestro setup --json — emit the structured SetupReport instead of the human-readable step listing.
• maestro setup check [--json] — read-only audit of the .maestro/{tasks,missions,evidence,runs} layout, docs/principles/, and .maestro/config.yaml. Exit 1 only when an entry is missing; warn (empty principles pack, absent config.yaml) is informational.

Cold-start trigger

One of the drop-templates outputs is init.sh at the repo root. It is emitted exactly once (mode 0755 on non-Windows) and never overwritten on rerun. The body invokes maestro doctor followed by maestro status, so a fresh session can resume by running ./init.sh. To regenerate, delete the file and rerun maestro setup. Full template body and contract: docs/init-sh-template.md.

Managed Markers

Use these exact markers.

Root AGENTS.md block:

<!-- maestro-setup:start -->
...
<!-- maestro-setup:end -->

Generated context section:

<!-- maestro-setup:generated:start -->
...
<!-- maestro-setup:generated:end -->

If a managed block exists, replace only the block body. If it does not exist, append a new block. Never rewrite the whole file unless the file is new.

Setup Flow

1. Inspect Current State

Read:

• root AGENTS.md, CLAUDE.md, README*, and package manifests when present
• manifests such as package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, build.gradle, Makefile, CMakeLists.txt, Package.swift
• config files that reveal lint, format, test, build, and deployment behavior
• top-level source/test directories and representative file extensions
• existing .maestro/context/ docs when present

Record every evidence source used for .maestro/setup-report.md.

2. Detect Languages

Detect languages from manifests first, then file extensions. Always copy general.md. Copy only matched language guides from reference/styleguides/ to .maestro/context/code_styleguides/.

Use this map:

Guide	Signals
general.md	Always copied
cpp.md	.cc, .cpp, .cxx, .hh, .hpp, CMakeLists.txt
csharp.md	.cs, .csproj, .sln
dart.md	.dart, pubspec.yaml
go.md	go.mod, .go
html-css.md	.html, .css, .scss, .sass, .less
javascript.md	.js, .jsx, JavaScript package metadata
python.md	.py, pyproject.toml, requirements.txt, setup.py
rust.md	.rs, Cargo.toml, Cargo.lock
typescript.md	.ts, .tsx, tsconfig.json

For languages without a bundled guide (Java, JSON, Markdown, Objective-C, R, Shell, Swift, VimScript, XML, Kotlin, AngularJS, Common Lisp, etc.), record the detection in the setup report and skip copying a guide.

3. Install CI Workflow (when applicable)

If .github/workflows/ exists in the target repo and maestro-verify.yml is not already present, copy reference/github-workflow/maestro-verify.yml.template to .github/workflows/maestro-verify.yml. Leave existing workflow files untouched. Do not create .github/workflows/ if it does not already exist; note in the setup report that CI integration was skipped because the repo has no GitHub Actions configuration.

The template is non-interactive and starter-grade: it pins MAESTRO_VERSION, installs the binary via curl-extract, and runs maestro ci verify on every pull_request. Users customize the version pin and runs-on label after install.

Record one of the following in .maestro/setup-report.md:

• Installed: Wrote .github/workflows/maestro-verify.yml from skill bundle.
• Skipped (existing): .github/workflows/maestro-verify.yml already present — left untouched.
• Skipped (no .github): Repo has no .github/workflows — CI integration skipped.

4. Create Or Refresh Context Docs

Ensure .maestro/context/ exists. Create or update these files using the templates in reference/context-templates/:

• index.md
• architecture.md
• product-sense.md
• quality-gates.md
• security.md
• workflow.md
• planning.md

Each new file must contain:

1. a generated block using the context managed markers
2. a ## User Notes section outside the managed block

For existing files, update only the generated block. Preserve all user-written content outside it.

5. Generate Hierarchical AGENTS.md (init-deep)

Run the workflow defined verbatim in reference/init-deep.md. This step owns the root AGENTS.md end-to-end and produces:

• a root PROJECT KNOWLEDGE BASE AGENTS.md
• complexity-scored child AGENTS.md files in qualifying subdirectories
• the <!-- AGENTS-HIERARCHY:START --> block per file linking parent and children

Relationship to the CLI seed. maestro setup always injects a minimal maestro-setup block into root AGENTS.md (and a @AGENTS.md reference into CLAUDE.md) before this skill runs. The seed references only files the CLI itself emits (.maestro/, init.sh, maestro doctor/status). This step's job is to replace that seed in place with the richer block below using the existing <!-- maestro-setup:start --> / <!-- maestro-setup:end --> marker pair, and to move the block to its canonical home immediately after ## OVERVIEW in the init-deep output.

Absorbed Maestro pointer block. The root AGENTS.md body must include the maestro-setup pointer placed immediately after the ## OVERVIEW section, wrapped in the start/end markers (text identical to the prior standalone pointer):

<!-- maestro-setup:start -->
## Maestro Context

Before non-trivial work:
- Load `.maestro/context/index.md` first.
- Open only the specific context docs relevant to the task.
- Follow detected language guides under `.maestro/context/code_styleguides/`.
- Preserve user content outside managed setup sections.
- If context docs conflict with closer repo instructions, follow the closer
  instruction file and report the conflict.
<!-- maestro-setup:end -->

The block content is identical to the prior standalone pointer; only its home moves. Preserve handwritten content elsewhere in the file.

Failure handling. Each background explore agent retries once on failure. Remaining failures degrade to bash + manifest-only scoring. Failed agents and the resulting fallback are listed in .maestro/setup-report.md.

Non-interactive. This step never prompts. Ambiguity becomes a warning in the setup report, not a question to the user.

--create-new is not exposed at the maestro-setup level. Default behavior is non-destructive update: edit AGENTS.md files in place and preserve handwritten content. The destructive mode described in reference/init-deep.md stays internal and is not advertised by this skill.

6. Write Setup Report

Overwrite .maestro/setup-report.md from reference/setup-report-template.md.

The report must include:

• timestamp
• files created, updated, and skipped
• languages detected and guides copied
• evidence sources used
• TODOs left in generated docs
• warnings
• recommended next action

7. Final Response

Report:

• what was created or updated
• detected languages
• copied guide files
• notable TODOs or warnings
• the next command or action the user should take

Do not claim setup is complete unless root AGENTS.md, context docs, language guides, and .maestro/setup-report.md have all been checked.

8. Hand off cleanly

The next phase after this skill is maestro-design (to author a new spec) or maestro-task (to resume work against an existing spec under .maestro/specs/).

Pass a bootstrapped repo with .maestro/setup-report.md written and maestro setup check returning a clean audit — not a half-installed harness. Do not invoke design, planning, or implementation from this skill.

Context Doc Intent

• architecture.md: current repo shape, owned modules, boundaries, known pressure points.
• product-sense.md: audience, product goals, UX/product guardrails.
• quality-gates.md: build/test/lint/typecheck commands and review bar.
• security.md: trust boundaries, sensitive files, approval gates.
• workflow.md: human/agent delivery loop, review expectations, completion bar.
• planning.md: thin policy bridge to maestro-design, maestro-mission, .maestro/missions/, and maestro-task.
• index.md: map of all context docs and copied style guides.

CLI ↔ skill mapping

The CLI mirrors this skill. When the skill says "set up the project", the binary's contract is:

• maestro setup [--global] [--dry-run] [--resync-skills] [--reset-templates] [--no-git-ok] [--json] — idempotent setup state machine.
• maestro setup check [--json] — read-only drift audit.

There are no other setup subverbs.

Do not design extra CLI behavior while running this skill.