maestro-sync — onboard repositories added after /maestro-init
/maestro-init configures the repositories present when Maestro is adopted. When one is added
later (for example ./scripts/repository add <url> in the workspace template), preflight fails
until maestro.config.yaml has an entry for it with build and test commands, and design
steps know nothing about it until it is in the living docs. This skill does both for the new
repositories only, leaving every existing entry and every other repo's docs as they are.
The config diff, which repos count as new, and the provenance records are deterministic engine
work (project_config.py sync, codebase_scan.py, workspace_sync.py); this skill supplies
only the judgement steps, by delegating to detect-stack, project-config and build-knowledge.
When to use
Only after a new repository is added to the workspace (cloned into codebase/, usually after
registering it in registry.yaml), including after ./maestro sync already added its config
entry. Not for removals or other changes. Safe to re-run: when nothing is new, step 2 finds
no targets and the skill stops.
Steps
Run these in order, in this session. Each step consumes the previous step's result.
Config diff. Run
python3 .maestro/engine/project_config.py sync --root . --dry-run and read its JSON:
missing_clones — registered but not cloned. Tell the person to clone them first
(./scripts/repository refresh in the template); they are not configured until cloned.
unregistered — cloned but missing from registry.yaml. Report it; they are still
configured, since Maestro works on every repo on disk. Suggest registering them.
Then run the same command without --dry-run. Capture added, needs_commands and
needs_e2e (every repo without an e2e command, existing ones included, so a suite added
since the last check is found).
Pick the targets. Run python3 .maestro/engine/codebase_scan.py plan --root ..
- Config targets =
needs_commands (it includes every added repo).
- E2E targets =
needs_e2e minus the config targets (those get the E2E check with
their full detection).
- Docs targets = every repo whose entry has
prev_commit: null (no codebase map yet —
never documented), plus added, minus any whose mode is current (already documented
at its HEAD). An entry with an older prev_commit is an existing repo whose map is merely
out of date; it is not a target.
All three empty: stop and report that nothing new needs setting up.
Detect stack for the config targets; E2E only for the E2E targets. Skip when there are
none. Load and follow the
detect-stack skill, scanning only codebase/<name>/ for each target. When it runs the
installer, pass --stack as the union of the targets' tokens, the stack values already
in maestro.config.yaml, and the stacks recorded in .maestro/install.json — never just
the new tokens, so the recorded install stays complete. Skip the install when the targets
add no token beyond that set. For the E2E targets, follow only detect-stack's E2E suite
section, scanning codebase/<name>/ for each, and keep their repos entries (name, e2e).
Project config. Load and follow the project-config skill with the config and E2E
targets' detect-stack repos results only. Its apply fills empty stack / commands, never
overwrites a value already set, and records each E2E check (its output's e2e map). Do not report a worktree or environment section; the
existing ones cover new repos.
Write the new repos' docs with build-knowledge. Skip when there are no docs targets.
When docs/architecture.md does not exist, the workspace has never been documented: run
build-knowledge for the whole workspace exactly as /maestro-init does (its steps 5–6) and
go to step 6. Otherwise, with <targets> the docs targets comma-separated:
python3 .maestro/engine/codebase_scan.py snapshot --root . --repos <targets> --out .maestro/index/maestro-sync-map-snapshot.json
— capture snapshot_sha256. Then
python3 .maestro/engine/living_docs.py snapshot --root . --out .maestro/index/maestro-sync-docs-snapshot.json.
- Load and follow
build-knowledge, scoped to the targets. Its instruction to you:
read only codebase/<target>/ (plus its AGENTS.md / CLAUDE.md / .cursor/rules) and
the existing docs/; then
- write each target's full codebase map at
docs/codebase-maps/<name>.md (without
the marker line);
- for each domain a target implements: a domain with no page yet gets new
docs/technical/<domain>.md and docs/functional/<domain>.md; an existing domain
page the target takes part in is extended in place to cover it. Never rewrite what a
page says about other repos; never edit the team's invariants and change scenarios
(## Invariants and consistency, ## Change scenarios, ## Platform-wide invariants,
docs/impact/side-effects.yaml) — write what you find under
## Proposed rules and scenarios;
- update
docs/architecture.md: the target's row in System context and repos, each of its
connections in Cross-repo flows and contracts, and its domains in the Domain map —
within budget;
- do not seed review lessons.
Then run
python3 .maestro/engine/living_docs.py check --root . --write --locked-from .maestro/index/maestro-sync-docs-snapshot.json --report
and fix every error it reports in the docs you wrote, until valid is true; then
python3 .maestro/engine/living_docs.py stamp --root . --snapshot .maestro/index/maestro-sync-docs-snapshot.json.
python3 .maestro/engine/codebase_scan.py record --root . --snapshot .maestro/index/maestro-sync-map-snapshot.json --snapshot-sha256 <snapshot_sha256>
— stamps only the targets. If it refuses because a target's map was not written or did
not change, go back to 5.2 for that repo.
python3 .maestro/engine/workspace_sync.py record-knowledge --root . --evidence docs/architecture.md --repos <targets>
— records the docs as describing the targets' current commits. Other repos keep their
recorded commits, so one whose docs were already out of date stays flagged; name those
in the summary (/build-knowledge refreshes them) rather than refreshing them here.
Preflight. Run python3 .maestro/engine/maestroctl.py preflight. Report every error
verbatim; a missing build / test the evidence could not supply is for the person to fill
by hand in maestro.config.yaml.
Summarize. Report the repos added and still needing commands, each E2E suite confirmed
(or why none was), the stacks installed, the
docs written (codebase maps, new and extended domain pages, architecture.md), any other
repo whose docs are out of date, and the preflight result. Ask the person to review and
commit docs/ in the workspace. Newly installed skills become active after the host reloads its config. A
feature run already in progress keeps the repositories its workspace lock pinned; the new
repo joins the next feature.
Standards
- Never re-implement the config diff, detection, config writing or doc generation here —
delegate to
project_config.py sync, detect-stack, project-config and build-knowledge.
- Only target repos are scanned, and only empty fields are filled; an existing repo's entry
is never changed. Docs are written for the docs targets only; other repos' docs change only
where a page they share gains the new repo.
- Only adds. An entry for a repository that is no longer in the workspace is left for the
person to remove by hand (preflight warns about it).
Safety
- Writes are
maestro.config.yaml (via the engine and project-config), installer output in
harness config dirs, documentation, codebase-map markers and docs/provenance.yaml.
- Never clone, register or remove a repository; never edit application code; never touch
.maestro/runs/ state or a run's workspace lock.
Output contract
Return added (repo names, comma-separated), needs_commands (repos preflight still fails
on), e2e_confirmed (repos whose E2E suite was confirmed this run, comma-separated), documented (repos whose docs were written, comma-separated), domains_written (domain
pages created or extended), and summary (one line).
1---2name: maestro-sync3description: Bring Maestro up to date after a repository is added to the workspace — the engine adds a maestro.config.yaml entry for each newly cloned repo, then detect-stack and project-config fill only those repos' stack and commands, matching stack skills are installed, and build-knowledge writes the new repos' docs (codebase map, domain pages, architecture.md). Front door for /maestro-sync or $maestro-sync.4allowed-tools: Read, Grep, Glob, Bash, Write, Task, AskUserQuestion5tags: [maestro, bootstrap]6metadata:7 source: https://skillmd.com/skills/keyvaluesoftwaresystems/maestro-sync8---910# maestro-sync — onboard repositories added after `/maestro-init`1112`/maestro-init` configures the repositories present when Maestro is adopted. When one is added13later (for example `./scripts/repository add <url>` in the workspace template), preflight fails14until `maestro.config.yaml` has an entry for it with `build` and `test` commands, and design15steps know nothing about it until it is in the living docs. This skill does both for the new16repositories only, leaving every existing entry and every other repo's docs as they are.1718The config diff, which repos count as new, and the provenance records are deterministic engine19work (`project_config.py sync`, `codebase_scan.py`, `workspace_sync.py`); this skill supplies20only the judgement steps, by delegating to detect-stack, project-config and build-knowledge.2122## When to use23Only after a new repository is added to the workspace (cloned into `codebase/`, usually after24registering it in `registry.yaml`), including after `./maestro sync` already added its config25entry. Not for removals or other changes. Safe to re-run: when nothing is new, step 2 finds26no targets and the skill stops.2728## Steps29Run these **in order**, in this session. Each step consumes the previous step's result.30311. **Config diff.** Run32 `python3 .maestro/engine/project_config.py sync --root . --dry-run` and read its JSON:33 - `missing_clones` — registered but not cloned. Tell the person to clone them first34 (`./scripts/repository refresh` in the template); they are not configured until cloned.35 - `unregistered` — cloned but missing from `registry.yaml`. Report it; they are still36 configured, since Maestro works on every repo on disk. Suggest registering them.3738 Then run the same command without `--dry-run`. Capture `added`, `needs_commands` and39 `needs_e2e` (every repo without an `e2e` command, existing ones included, so a suite added40 since the last check is found).412. **Pick the targets.** Run `python3 .maestro/engine/codebase_scan.py plan --root .`.42 - **Config targets** = `needs_commands` (it includes every added repo).43 - **E2E targets** = `needs_e2e` minus the config targets (those get the E2E check with44 their full detection).45 - **Docs targets** = every repo whose entry has `prev_commit: null` (no codebase map yet —46 never documented), plus `added`, minus any whose `mode` is `current` (already documented47 at its HEAD). An entry with an older `prev_commit` is an existing repo whose map is merely48 out of date; it is not a target.4950 All three empty: stop and report that nothing new needs setting up.513. **Detect stack for the config targets; E2E only for the E2E targets.** Skip when there are52 none. Load and follow the53 **`detect-stack`** skill, scanning only `codebase/<name>/` for each target. When it runs the54 installer, pass `--stack` as the union of the targets' tokens, the `stack` values already55 in `maestro.config.yaml`, and the `stacks` recorded in `.maestro/install.json` — never just56 the new tokens, so the recorded install stays complete. Skip the install when the targets57 add no token beyond that set. For the E2E targets, follow only detect-stack's **E2E suite**58 section, scanning `codebase/<name>/` for each, and keep their `repos` entries (`name`, `e2e`).594. **Project config.** Load and follow the **`project-config`** skill with the config and E2E60 targets' detect-stack `repos` results only. Its `apply` fills empty `stack` / `commands`, never61 overwrites a value already set, and records each E2E check (its output's `e2e` map). Do not report a `worktree` or `environment` section; the62 existing ones cover new repos.635. **Write the new repos' docs** with **`build-knowledge`**. Skip when there are no docs targets.64 When `docs/architecture.md` does not exist, the workspace has never been documented: run65 build-knowledge for the whole workspace exactly as `/maestro-init` does (its steps 5–6) and66 go to step 6. Otherwise, with `<targets>` the docs targets comma-separated:67 1. `python3 .maestro/engine/codebase_scan.py snapshot --root . --repos <targets> --out .maestro/index/maestro-sync-map-snapshot.json`68 — capture `snapshot_sha256`. Then69 `python3 .maestro/engine/living_docs.py snapshot --root . --out .maestro/index/maestro-sync-docs-snapshot.json`.70 2. Load and follow **`build-knowledge`**, scoped to the targets. Its instruction to you:71 read only `codebase/<target>/` (plus its `AGENTS.md` / `CLAUDE.md` / `.cursor/rules`) and72 the existing `docs/`; then73 - write each target's **full** codebase map at `docs/codebase-maps/<name>.md` (without74 the marker line);75 - for each domain a target implements: a domain with no page yet gets new76 `docs/technical/<domain>.md` and `docs/functional/<domain>.md`; an existing domain77 page the target takes part in is extended in place to cover it. Never rewrite what a78 page says about other repos; never edit the team's invariants and change scenarios79 (`## Invariants and consistency`, `## Change scenarios`, `## Platform-wide invariants`,80 `docs/impact/side-effects.yaml`) — write what you find under81 `## Proposed rules and scenarios`;82 - update `docs/architecture.md`: the target's row in System context and repos, each of its83 connections in Cross-repo flows and contracts, and its domains in the Domain map —84 within budget;85 - do not seed review lessons.86 Then run `python3 .maestro/engine/living_docs.py check --root . --write --locked-from .maestro/index/maestro-sync-docs-snapshot.json --report`87 and fix every error it reports in the docs you wrote, until `valid` is true; then88 `python3 .maestro/engine/living_docs.py stamp --root . --snapshot .maestro/index/maestro-sync-docs-snapshot.json`.89 3. `python3 .maestro/engine/codebase_scan.py record --root . --snapshot .maestro/index/maestro-sync-map-snapshot.json --snapshot-sha256 <snapshot_sha256>`90 — stamps only the targets. If it refuses because a target's map was not written or did91 not change, go back to 5.2 for that repo.92 4. `python3 .maestro/engine/workspace_sync.py record-knowledge --root . --evidence docs/architecture.md --repos <targets>`93 — records the docs as describing the targets' current commits. Other repos keep their94 recorded commits, so one whose docs were already out of date stays flagged; name those95 in the summary (`/build-knowledge` refreshes them) rather than refreshing them here.966. **Preflight.** Run `python3 .maestro/engine/maestroctl.py preflight`. Report every error97 verbatim; a missing `build` / `test` the evidence could not supply is for the person to fill98 by hand in `maestro.config.yaml`.997. **Summarize.** Report the repos added and still needing commands, each E2E suite confirmed100 (or why none was), the stacks installed, the101 docs written (codebase maps, new and extended domain pages, architecture.md), any other102 repo whose docs are out of date, and the preflight result. Ask the person to review and103 commit `docs/` in the workspace. Newly installed skills become active after the host reloads its config. A104 feature run already in progress keeps the repositories its workspace lock pinned; the new105 repo joins the next feature.106107## Standards108- Never re-implement the config diff, detection, config writing or doc generation here —109 delegate to `project_config.py sync`, detect-stack, project-config and build-knowledge.110- Only target repos are scanned, and only empty fields are filled; an existing repo's entry111 is never changed. Docs are written for the docs targets only; other repos' docs change only112 where a page they share gains the new repo.113- Only adds. An entry for a repository that is no longer in the workspace is left for the114 person to remove by hand (preflight warns about it).115116## Safety117- Writes are `maestro.config.yaml` (via the engine and project-config), installer output in118 harness config dirs, documentation, codebase-map markers and `docs/provenance.yaml`.119- Never clone, register or remove a repository; never edit application code; never touch120 `.maestro/runs/` state or a run's workspace lock.121122## Output contract123Return `added` (repo names, comma-separated), `needs_commands` (repos preflight still fails124on), `e2e_confirmed` (repos whose E2E suite was confirmed this run, comma-separated), `documented` (repos whose docs were written, comma-separated), `domains_written` (domain125pages created or extended), and `summary` (one line).