Maestro Setup

---
name: maestro-setup
description: Set up a repository as a long-running agent harness. Use when a project needs Maestro-owned context docs, evidence-first onboarding, root AGENTS.md guidance, language style guides, host-runtime session hooks, drift detection, or a setup report before implementation work begins.
---

# 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:

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

Generated context section:

```md
<!-- 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`](./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):

```md
<!-- 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.