Skip to content

quickstart.md

Latest commit

 

History

History
185 lines (124 loc) · 7.81 KB

quickstart.md

File metadata and controls

185 lines (124 loc) · 7.81 KB

5-minute quickstart

This path is for a first run of the published CLI. It shows the practical workspace lifecycle we validated: init, edit maestro.yaml, workspace install, generate maestro.code-workspace, open the workspace root for contract edits, open a task worktree for active work, run repo bootstrap, then finish with workspace doctor.

Prerequisites:

  • Node.js >=22.12 if you install or run the CLI through npm, pnpm, npx, or pnpm dlx
  • git available on PATH

The generated maestro command is still a Node program after installation, so Node is part of the runtime requirement, not just the development toolchain.

Command output is human-readable (tables and colored summaries) when run in a terminal, and stable JSON when stdout is piped or redirected. Pass --json or set MAESTRO_FORMAT=json to force JSON in a TTY; see Output formats for the full precedence matrix and envelope spec.

1. Install or run once

Use any of these entry points:

npm install -g @th3mouk/maestro
pnpm add -g @th3mouk/maestro
npx @th3mouk/maestro@latest init my-workspace

On macOS with Homebrew, use the tap-qualified path:

brew tap th3mouk/maestro https://github.com/Th3Mouk/maestro
brew install th3mouk/maestro/maestro

2. Create a workspace

If you installed Maestro globally, run:

maestro init my-workspace
cd my-workspace

3. Check the generated files

You should see a skeleton like this:

my-workspace/
|- maestro.yaml
|- package.json
|- README.md
|- AGENTS.md
|- maestro.json
|- .gitignore
`- .maestro/

What those files mean:

  • maestro.yaml: the main workspace file Maestro reads.
  • package.json: local helper scripts plus the maestro dependency range for the workspace.
  • README.md: the generated workspace note. If a README already exists, Maestro appends the installation note at the end.
  • AGENTS.md: the generated Maestro CLI map for AI agents.
  • maestro.json: the neutral workspace descriptor for agents, headless harnesses, and scripts.
  • .maestro/: the internal state, reports, and lock-protected execution data generated by Maestro.

This workspace root is the canonical directory. It versions the workspace contract and local files, while maestro workspace install initializes the workspace root as a Git repository when needed and materializes managed Git repositories under repos/. After install, the root repository holds the workspace contract, and task worktrees become the normal entrypoint for active work across the root and managed repositories. If a repository entry omits spec.repositories[].sparse, Maestro clones it in full; add includePaths, excludePaths, or both when you want a narrower checkout.

4. Add repositories to maestro.yaml

After init, the normal next step is to declare the repositories you want Maestro to manage.

Example:

spec:
  repositories:
    - name: foodpilot-api
      remote: git@github.com:Foodpilot/foodpilot-api.git
      branch: main
    - name: sure-api
      remote: git@github.com:Foodpilot/sure-api.git
      branch: main

If a repository entry omits spec.repositories[].sparse, Maestro clones it in full. Add includePaths, excludePaths, or both only when you want a narrower checkout.

5. Install the workspace

Start with a dry run of the install plan, then run the real install:

maestro workspace install --dry-run
maestro workspace install

The dry run shows the install plan only. It does not initialize Git, create the boot commit, clone repositories, or install repository dependencies.

maestro workspace install initializes the workspace root as a Git repository when needed, creates a 🪄 booted by Maestro commit when the repository is unborn, materializes the managed repositories under repos/, refreshes maestro.json, and generates runtime projections for the enabled tools. By default, the scaffold enables Codex and Claude Code, so install writes .codex/ and .claude/ for the workspace. That gives you a root repository and managed repositories that are ready for task worktrees from the start.

If you want the AI-agent CLI map for this workspace, read AGENTS.md in the workspace root:

sed -n '1,200p' AGENTS.md

If you want the neutral workspace contract for an agent, harness, or script, read:

cat maestro.json

If you want the structural meaning of maestro.yaml, repos/, generated files, projections, and fragment layering, read Workspace Manifest and Manifest Fragments.

6. Generate the VS Code workspace

If you want named multi-root folders in editors that support .code-workspace, generate one after install:

maestro editor-workspace

The generated file includes the workspace root plus each materialized repository, which is the most explicit way to open the environment in VS Code.

7. Open the workspace in VS Code

You can open the workspace root directly in VS Code or JetBrains when you are editing the workspace contract itself. If you want the explicit multi-root projection, open the generated file instead:

code maestro.code-workspace

If you want to inspect a fuller example before cloning repositories, run:

maestro workspace install --workspace ../examples/ops-workspace --dry-run

The same materialized workspace can then be consumed by VS Code, Codex, Claude Code, or JetBrains. Maestro stays upstream: it prepares the governed workspace and the runtime projections, then those tools operate on the result.

For task-scoped work, create a task worktree after install and open that folder instead of jumping into repo roots directly:

maestro worktree create --task release-prep
code .maestro/worktrees/release-prep

That task folder contains the workspace-root worktree plus one worktree for each managed repository. That is the normal day-to-day entrypoint for a task, whether you use VS Code or JetBrains.

8. Bootstrap repository dependencies

Run dependency bootstrap after the real install:

maestro repo bootstrap

If the repositories declare bootstrap.strategy: auto, Maestro detects the local toolchain from the materialized checkout. In the validated Symfony backend flow, both repositories resolved to Composer and repo bootstrap ran composer install --no-interaction --prefer-dist.

repo bootstrap is not a generic dependency upgrade command. In auto mode, it chooses strict install/sync commands from each repository's manifests and lockfiles. For example, npm repositories with a package-lock.json run npm ci. Repositories that declare a managed manifest without the expected lockfile are reported as warnings instead of falling back to a resolver command that could rewrite the lockfile.

9. Validate the installed workspace

Run workspace doctor once the repositories and projections are present:

maestro workspace doctor

If you want Maestro to install dependencies automatically, declare spec.repositories[].bootstrap.strategy: auto or manual in maestro.yaml and use maestro repo bootstrap as the execution step. Add --dry-run first when you want to inspect the exact commands before they touch repository lockfiles or virtual environments. The workspace file does not run instantiation scripts by itself.

10. If something goes wrong

  • If maestro is not found after a global install, open a new shell or use npx @th3mouk/maestro@latest init my-workspace to verify the package directly.
  • If you used Homebrew, keep the tap-qualified formula name: th3mouk/maestro/maestro.
  • If you are working on this repository rather than using the published package, switch to the source workflow in CLI install.

For broader command details, see CLI reference. For installation-specific checks, see CLI install.