maestro-init — set Maestro up for this codebase
Bootstrap a repository for Maestro in one command: safely align its repositories with their
current upstreams, run detect-stack (install only — it does not touch
maestro.config.yaml), then run project-config to write that file from the detect-stack
result and from registry.yaml when it exists, then document the exact commits that will
be used — skipping knowledge authoring when docs are already current.
Sync facts and provenance come from deterministic engine scripts; detect-stack, project-config,
and build-knowledge each own one job.
When to use
The first time you adopt Maestro in a repo (or after a big stack change). For a repository
added later, use /maestro-sync instead — it handles only the new ones. Safe to re-run —
both underlying skills are idempotent (refresh, don't duplicate). On a template umbrella
that already ran /workspace-index, this should usually install stacks and skip docs.
Steps
Run these in order, in this session. On Claude Code or Codex you may dispatch a step to
a subagent when that keeps bulky scanning out of the lead context; otherwise follow it
inline. Never parallelize these steps because each consumes the previous step's result.
- Fetch + consolidated sync gate — run
python3 .maestro/engine/workspace_sync.py plan --root . --remote-only --out .maestro/index/workspace-sync-init-plan.json.
If needs_attention=false, continue without asking. Otherwise show its summary in ONE
AskUserQuestion: Update safe repos before indexing, Continue at current local
commits, or Abort. On update, run workspace_sync.py apply with the exact returned
plan path/hash and --out .maestro/index/workspace-sync-init-result.json. It fast-forwards
only clean, non-diverged current branches; never stash, merge, rebase or update an unsafe
repo. Do not ask one question per repository.
- Detect stack + install — load and follow the
detect-stack skill. It installs
matching skills and returns repos (name, stacks, evidence). It must not write
maestro.config.yaml. Capture stacks, installed_count, and repos.
- Project config — load and follow the
project-config skill with that repos
result. It writes maestro.config.yaml (registry names when registry.yaml exists;
stack and commands from the detect-stack evidence; the worktree commands from a workspace
sandbox script and the environment commands from a workspace infra script when there is
one; each repo's e2e command only after the engine confirmed detect-stack's E2E proposal).
It does not scan again and does not read the knowledge base. Capture created, updated
and its e2e map, and show the person any worktree or environment commands it set.
- Docs freshness gate — before authoring, run a full (not
--remote-only) plan:
python3 .maestro/engine/workspace_sync.py plan --root . --no-fetch --out .maestro/index/workspace-sync-init-knowledge.json
and python3 .maestro/engine/codebase_scan.py plan --root ..
Provenance is docs/provenance.yaml (shared with the template workspace-index skill);
no separate knowledge-state import step.
Skip step 5 (build-knowledge) when refresh_needed=false, maps are not stale, and
docs/architecture.md is present — set domains_written=0 and note “docs already current”.
Still run step 6b (ensure-index-state) so template-written state gets docs_sha256.
- Build the knowledge base (only if stale / missing) — load and follow the
build-knowledge skill (or start the build-knowledge workflow): read the code and
write the per-domain technical + functional docs, the architecture diagram, and a
codebase map per repo under docs/codebase-maps/. Capture domains_written and architecture_path.
- Record exact provenance
- 6a (after authoring in step 5): run
python3 .maestro/engine/codebase_scan.py record --root ., then
python3 .maestro/engine/workspace_sync.py record-knowledge --root . --evidence <architecture_path>.
(The build-knowledge workflow already does this when you run it as a workflow.)
- 6b (always when docs are current, including skip of step 5): run
python3 .maestro/engine/workspace_sync.py ensure-index-state --root . --evidence docs/architecture.md.
No-op if docs_sha256 already present; fills it when template indexed first. Do not skip
this on the “docs already current” path — without it, doc-content drift is invisible.
This makes later /maestro or $maestro starts a fast fetch + local SHA comparison with
zero model call when nothing changed.
- Domain rules (optional) — run
python3 .maestro/engine/living_docs.py status --root ..
Invariants that must never break (<PREFIX>-INV-NNN) and change scenarios
(<PREFIX>-CS-NNN) are written by the project's people in docs/technical/<domain>.md
(## Invariants and consistency, ## Change scenarios) and docs/impact/side-effects.yaml;
Maestro uses them when they exist and runs fine without them.
present=true — run python3 .maestro/engine/living_docs.py rules --root . and report
its summary. When valid=false, show its issues_summary and say the docs or the code need
fixing; do not fix them here and do not stop init.
present=false — ask ONE question (AskUserQuestion on Claude Code; a numbered choice on
Cursor, answered in the next message): Maestro can use domain rules and change scenarios if
the team adds them under docs/. Options: Create the starter file (run
python3 .maestro/engine/living_docs.py scaffold --root ., then point them at
docs/impact/side-effects.yaml, the ## Invariants and consistency / ## Change scenarios
sections of each docs/technical/<domain>.md, and the proposals build-knowledge left under
## Proposed rules and scenarios, as described in .maestro/docs/domain-rules.md) or
Skip, no domain rules. Either answer finishes init.
Never write or invent rules yourself: the team decides what the rules are.
- Summarize + next step. Report the stacks installed, whether docs were written or
skipped, whether domain rules were found (and checked), and whether the project-config skill
created or updated
maestro.config.yaml.
Show each repo's build and test and ask the user to confirm them before a
feature run. Report each confirmed E2E suite; when none was found, say QA will check the
test cases directly instead of writing an E2E suite. Then tell them that newly installed skills/agents
become active after their host reloads the config, and that they can start a feature
with /maestro <slug> or $maestro <slug>.
Standards
- Do not re-implement detection, config writing, or doc-generation here — delegate to
detect-stack, project-config, and build-knowledge. Remote status, safe update and
provenance stay engine-owned.
- If step 2 detects no stack, still run step 3 and finish; report that no per-stack skills
were added.
- Never run a second full
/workspace-index “to be safe” when Maestro’s gate says current.
Safety
- Writes are installer output into harness config dirs (
.claude/, .cursor/, .agents/), documentation,
codebase-map markers, docs/provenance.yaml, the empty starter
docs/impact/side-effects.yaml only when the person asks for it, and — only via the
project-config skill — maestro.config.yaml. Never edit application code; never touch
.maestro/runs/ state.
Repository updates are explicit-user-approved, verified fast-forwards only.
Output contract
Return stacks (detected stack tokens, comma-separated), installed_count (skills + agents
installed), domains_written (count from build-knowledge, or 0 if skipped), and summary
(one line).
1---2name: maestro-init3description: One-shot onboarding for a repo — detect-stack installs matching skills, then the project-config skill writes maestro.config.yaml from that result (registry.yaml names when present), then build the living-docs knowledge base only when docs are stale. Run once when adopting Maestro in a codebase. Front door for /maestro-init or $maestro-init.4allowed-tools: Read, Grep, Glob, Bash, Write, Task, AskUserQuestion5tags: [maestro, bootstrap]6metadata:7 source: https://skillmd.com/skills/keyvaluesoftwaresystems/maestro-init8---910# maestro-init — set Maestro up for this codebase1112Bootstrap a repository for Maestro in one command: safely align its repositories with their13current upstreams, run **detect-stack** (install only — it does not touch14`maestro.config.yaml`), then run **project-config** to write that file from the detect-stack15result and from `registry.yaml` when it exists, then document the exact commits that will16be used — **skipping knowledge authoring when docs are already current**.17Sync facts and provenance come from deterministic engine scripts; detect-stack, project-config,18and build-knowledge each own one job.1920## When to use21The first time you adopt Maestro in a repo (or after a big stack change). For a repository22added later, use **`/maestro-sync`** instead — it handles only the new ones. Safe to re-run —23both underlying skills are idempotent (refresh, don't duplicate). On a template umbrella24that already ran `/workspace-index`, this should usually install stacks and skip docs.2526## Steps27Run these **in order**, in this session. On Claude Code or Codex you may dispatch a step to28a subagent when that keeps bulky scanning out of the lead context; otherwise follow it29inline. Never parallelize these steps because each consumes the previous step's result.30311. **Fetch + consolidated sync gate** — run32 `python3 .maestro/engine/workspace_sync.py plan --root . --remote-only --out .maestro/index/workspace-sync-init-plan.json`.33 If `needs_attention=false`, continue without asking. Otherwise show its `summary` in ONE34 AskUserQuestion: **Update safe repos before indexing**, **Continue at current local35 commits**, or **Abort**. On update, run `workspace_sync.py apply` with the exact returned36 plan path/hash and `--out .maestro/index/workspace-sync-init-result.json`. It fast-forwards37 only clean, non-diverged current branches; never stash, merge, rebase or update an unsafe38 repo. Do not ask one question per repository.392. **Detect stack + install** — load and follow the **`detect-stack`** skill. It installs40 matching skills and returns `repos` (`name`, `stacks`, `evidence`). It must not write41 `maestro.config.yaml`. Capture `stacks`, `installed_count`, and `repos`.423. **Project config** — load and follow the **`project-config`** skill with that `repos`43 result. It writes `maestro.config.yaml` (registry names when `registry.yaml` exists;44 stack and commands from the detect-stack evidence; the `worktree` commands from a workspace45 sandbox script and the `environment` commands from a workspace infra script when there is46 one; each repo's `e2e` command only after the engine confirmed detect-stack's E2E proposal).47 It does not scan again and does not read the knowledge base. Capture `created`, `updated`48 and its `e2e` map, and show the person any worktree or environment commands it set.494. **Docs freshness gate** — before authoring, run a **full** (not `--remote-only`) plan:50 `python3 .maestro/engine/workspace_sync.py plan --root . --no-fetch --out .maestro/index/workspace-sync-init-knowledge.json`51 and `python3 .maestro/engine/codebase_scan.py plan --root .`.52 Provenance is `docs/provenance.yaml` (shared with the template workspace-index skill);53 no separate knowledge-state import step.54 **Skip** step 5 (build-knowledge) when `refresh_needed=false`, maps are not stale, and55 `docs/architecture.md` is present — set `domains_written=0` and note “docs already current”.56 Still run step 6b (`ensure-index-state`) so template-written state gets `docs_sha256`.575. **Build the knowledge base (only if stale / missing)** — load and follow the58 **`build-knowledge`** skill (or start the `build-knowledge` workflow): read the code and59 write the per-domain technical + functional docs, the architecture diagram, and a60 codebase map per repo under `docs/codebase-maps/`. Capture `domains_written` and `architecture_path`.616. **Record exact provenance**62 - **6a (after authoring in step 5):** run63 `python3 .maestro/engine/codebase_scan.py record --root .`, then64 `python3 .maestro/engine/workspace_sync.py record-knowledge --root . --evidence <architecture_path>`.65 (The `build-knowledge` workflow already does this when you run it as a workflow.)66 - **6b (always when docs are current, including skip of step 5):** run67 `python3 .maestro/engine/workspace_sync.py ensure-index-state --root . --evidence docs/architecture.md`.68 No-op if `docs_sha256` already present; fills it when template indexed first. Do **not** skip69 this on the “docs already current” path — without it, doc-content drift is invisible.70 This makes later `/maestro` or `$maestro` starts a fast fetch + local SHA comparison with71 zero model call when nothing changed.727. **Domain rules (optional)** — run `python3 .maestro/engine/living_docs.py status --root .`.73 Invariants that must never break (`<PREFIX>-INV-NNN`) and change scenarios74 (`<PREFIX>-CS-NNN`) are written by the project's people in `docs/technical/<domain>.md`75 (`## Invariants and consistency`, `## Change scenarios`) and `docs/impact/side-effects.yaml`;76 Maestro uses them when they exist and runs fine without them.77 - **`present=true`** — run `python3 .maestro/engine/living_docs.py rules --root .` and report78 its `summary`. When `valid=false`, show its `issues_summary` and say the docs or the code need79 fixing; do not fix them here and do not stop init.80 - **`present=false`** — ask ONE question (AskUserQuestion on Claude Code; a numbered choice on81 Cursor, answered in the next message): Maestro can use domain rules and change scenarios if82 the team adds them under `docs/`. Options: **Create the starter file** (run83 `python3 .maestro/engine/living_docs.py scaffold --root .`, then point them at84 `docs/impact/side-effects.yaml`, the `## Invariants and consistency` / `## Change scenarios`85 sections of each `docs/technical/<domain>.md`, and the proposals build-knowledge left under86 `## Proposed rules and scenarios`, as described in `.maestro/docs/domain-rules.md`) or87 **Skip, no domain rules**. Either answer finishes init.88 Never write or invent rules yourself: the team decides what the rules are.898. **Summarize + next step.** Report the stacks installed, whether docs were written or90 skipped, whether domain rules were found (and checked), and whether the project-config skill91 created or updated `maestro.config.yaml`.92 Show each repo's `build` and `test` and ask the user to confirm them before a93 feature run. Report each confirmed E2E suite; when none was found, say QA will check the94 test cases directly instead of writing an E2E suite. Then tell them that newly installed skills/agents95 become active after their host reloads the config, and that they can start a feature96 with `/maestro <slug>` or `$maestro <slug>`.9798## Standards99- Do not re-implement detection, config writing, or doc-generation here — delegate to100 detect-stack, project-config, and build-knowledge. Remote status, safe update and101 provenance stay engine-owned.102- If step 2 detects no stack, still run step 3 and finish; report that no per-stack skills103 were added.104- Never run a second full `/workspace-index` “to be safe” when Maestro’s gate says current.105106## Safety107- Writes are installer output into harness config dirs (`.claude/`, `.cursor/`, `.agents/`), documentation,108 codebase-map markers, `docs/provenance.yaml`, the empty starter109 `docs/impact/side-effects.yaml` only when the person asks for it, and — only via the110 project-config skill — `maestro.config.yaml`. Never edit application code; never touch111 `.maestro/runs/` state.112 Repository updates are explicit-user-approved, verified fast-forwards only.113114## Output contract115Return `stacks` (detected stack tokens, comma-separated), `installed_count` (skills + agents116installed), `domains_written` (count from build-knowledge, or `0` if skipped), and `summary`117(one line).