maestro-setup

name	maestro-setup
version	1.11.6
description	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.

Maestro Setup

Tune a Maestro-enabled repository harness from current repository evidence.

Activate with a known session id: maestro hook record --event skill_activation --skill maestro-setup --session <session_id>

Recipe checkpoint: Maestro's main workflow is the loop. Use maestro status for current state and maestro loop next as the read-only router when the next lifecycle is not obvious. Setup writes still use the existing Maestro verbs named by this skill (init, install, sync, doctor, upgrade, uninstall, and shell-init), not hidden setup state. Rule: loop next recommends; outcome/proof/memory verbs write. maestro loop next --chain explains current chain position without writing; maestro loop outcome appends structured outcomes and transition receipts after native work; maestro loop trace <card> audits card-scoped receipts; maestro loop improve is a read-only proposer. Do not use hidden stores, hidden schedulers, silent recipe mutation, or proof/QA bypass.

Use

• After maestro init.
• After maestro install.
• When an already-initialized repo needs its Maestro setup updated to the running binary with minimal repeated token cost.
• When maestro doctor reports setup or local agent integration problems.
• When a repo's build/test/harness instructions are missing or stale.

Do

1. Run pwd, then maestro status.
2. If the repo is already initialized and the request is only to update Maestro setup, take the cheap rerun path before any broader read-in:
   • Run maestro sync --dry-run.
   • If it reports only current/skipped resources, do not run maestro sync.
   • If it reports drift, run maestro sync, then report only changed resources, backup paths, and blockers.
   • Run maestro sync --global-skills only when the user asks for global skills or maestro doctor reports global skill drift.
   • Finish with maestro doctor, then maestro status.
3. If the repo is not initialized, run maestro init --dry-run.
4. If dry-run prints operating on <path> and that path is not the intended current project root, stop and ask the user to pick or create the root before any write.
5. Only after the root is correct, run maestro init --yes.
6. Run maestro doctor.
7. If no agent integration is installed, run maestro install --agent codex unless the user asked for another agent.
8. Inspect repo structure, build/test commands, and workflow constraints.
9. Read in the existing agent and doc instructions as a BOUNDED set: at the repo root, and under each folder matched by the projects: globs in .maestro/harness/harness.yml, read AGENTS.md, CLAUDE.md, README.md, and top-level docs/*.md. Stay shallow (one level per location, no deep crawl) and skip outsized files (roughly 64 KB and up) so a vendored doc dump cannot flood context. With no projects: declared, this is the repo root alone.
10. Synthesize what you read into the SINGLE root harness guidance, one section per project (a single section when nothing is declared). This is read-in only: never write maestro-managed guidance into a sub-project's own AGENTS.md/CLAUDE.md -- maestro install/sync write managed blocks at the repo root alone. Cite the inspected files; do not tune from guesses.
11. Run maestro doctor, then maestro status.

Stop

• maestro init --dry-run writes nothing; use it before init writes.
• Native harness layer setup route: use maestro install --dry-run before agent mirror writes, maestro sync --dry-run before setup refresh writes, maestro capability to explain optional provider state, and maestro maturity to read context, proof gaps, friction, maturity level, and next owner before claiming setup readiness. Generated CLI references prove command shape; Harness and targeted skills teach the workflow.
• maestro init --yes keeps existing files and creates missing files.
• maestro sync --dry-run is the cheap already-initialized update check; do not run broader setup read-in when it proves the setup is current and no doctor blocker remains.
• Use maestro init --force only for deliberate refresh; it backs up managed files first.
• Do not tune the harness from guesses, package-manager defaults, or stale chat memory.
• Per-project docs are read-in only. Maestro owns one root scope; never write maestro-managed guidance into a sub-project's AGENTS.md/CLAUDE.md.

Done

• Setup is healthy, or the remaining setup blocker is explicit.
• The next handoff is visible from maestro status.
• Harness guidance changes cite inspected files or commands.
• Completion criterion: every write was preceded by the matching dry-run or current-state read, and every changed managed resource is named with its backup path or blocker.