Maestro

Maestro is a multi-agent development orchestration platform with 39 specialists, an Express path for simple work, a 4-phase standard workflow for medium and complex work, persistent session state, and standalone review/debug/security/perf/seo/accessibility/compliance entrypoints. It runs from one canonical src/ tree across Antigravity, Claude Code, Codex, and Qwen Code.

Runtime Targets

Getting Started

Prerequisites

• One supported runtime: Antigravity (the agy CLI or the Antigravity app), Claude Code, Codex, or Qwen Code
• Node.js 20+ for the MCP server and helper scripts

Installation

Antigravity

agy plugin install https://github.com/josstei/maestro-orchestrate/tree/main/antigravity

Restart agy afterwards: Antigravity discovers a newly installed plugin only on startup. Verify with agy plugin list.

Local development (link the plugin directory, then restart agy; a linked plugin loads but is not listed by agy plugin list):

git clone https://github.com/josstei/maestro-orchestrate
mkdir -p ~/.gemini/config/plugins
ln -s "$PWD/maestro-orchestrate/antigravity" ~/.gemini/config/plugins/maestro

More Antigravity-specific setup and runtime details live in antigravity/README.md and docs/runtime-antigravity.md.

Claude Code

Marketplace install:

claude plugin marketplace add josstei/maestro-orchestrate
claude plugin install maestro@maestro-orchestrator --scope user

Development / temporary loading:

git clone https://github.com/josstei/maestro-orchestrate
claude --plugin-dir /path/to/maestro-orchestrate/claude

More Claude-specific setup and plugin management lives in claude/README.md.

Codex

Register the marketplace:

codex plugin marketplace add josstei/maestro-orchestrate

Then start Codex, run /plugins to browse, select Maestro, and choose Install.

Local development (path must start with ./, ../, /, or ~/ — Codex otherwise treats bare owner/repo as a GitHub source):

git clone https://github.com/josstei/maestro-orchestrate
codex plugin marketplace add /absolute/path/to/maestro-orchestrate
# then: start Codex, run `/plugins`, select Maestro → Install

More Codex-specific setup and runtime details live in plugins/maestro/README.md and docs/runtime-codex.md.

Qwen Code

qwen extensions install https://github.com/josstei/maestro-orchestrate

Local development:

git clone https://github.com/josstei/maestro-orchestrate
cd maestro-orchestrate
qwen extensions link .

Verify with qwen extensions list. Qwen Code reads QWEN.md as its context file and loads the /maestro:* commands from commands/maestro/*.toml.

Quick Start

Start a full orchestration with the runtime-specific entrypoint:

Maestro classifies the task, chooses Express or Standard workflow, asks the required design questions, produces an implementation plan when needed, delegates execution to specialists, runs a quality gate, and archives the session state in docs/maestro/.

Examples

Usage examples: EXAMPLES.md. Qwen Code forms shown:

• Full orchestration: /maestro:orchestrate Build a REST API for a task management system with user authentication
• Standalone review: /maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests
• Security audit: /maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks

Configuration

Defaults work; these settings tune behavior:

Commands

For Claude Code and Codex, Maestro intentionally avoids bare skill names that collide with host commands. Use /review-code, /debug-workflow, and /resume-session in Claude Code, and $maestro:review-code, $maestro:debug-workflow, and $maestro:resume-session in Codex, so built-in /review, /debug, and /resume commands keep working.

Antigravity has a built-in /resume, so it uses the same remapped names under its plugin namespace: /maestro:review-code, /maestro:debug-workflow, and /maestro:resume-session.

Qwen Code does not remap any entry point; it keeps /maestro:review, /maestro:debug, and /maestro:resume.

Workflow

• Express: For simple work. Maestro asks 1-2 clarifying questions, proposes a brief, delegates to one specialist, runs code review, and archives without a design doc or implementation plan.
• Standard: For medium and complex work. Maestro runs Design, Plan, Execute, and Complete phases with explicit approval gates, phased execution, and final review blocking on unresolved Critical or Major findings.

Outputs and Success Criteria

Maestro writes orchestration outputs under MAESTRO_STATE_DIR, usually docs/maestro/. Standard workflow outputs include active session state, design documents, implementation plans, phase reports, validation output, and archived records.

A successful run must have an approved plan when Standard workflow is used, completed phase reports, validation results for the changed surface, and no unresolved Critical or Major review findings. If a phase cannot complete, Maestro records the blocker and the next required action instead of silently continuing.

Security and Permissions

Maestro follows the host runtime's tool permissions, sandboxing, and confirmation model. It does not require committed secrets or long-lived credentials, and orchestration session state stays inside MAESTRO_STATE_DIR unless configured otherwise. Use MAESTRO_DISABLED_AGENTS to restrict specialists in sensitive repositories, and run $maestro:security-audit or the equivalent runtime command before adopting changes that touch authentication, authorization, secrets, or data exposure paths.

Documentation

• EXAMPLES.md for copyable usage scenarios across all runtimes
• docs/overview.md for the project model and generated structure
• docs/architecture.md for orchestration internals and architecture layout
• docs/usage.md for development workflow, settings, and command surfaces
• docs/flow.md for the orchestration workflow steps and hard gates
• docs/maestro-cheatsheet.md for a one-page command and runtime quick reference
• docs/cicd.md for CI/CD pipeline workflows, release process, and Mermaid diagrams
• docs/runtime-antigravity.md for Antigravity runtime specifics
• docs/runtime-claude.md for Claude runtime specifics
• docs/runtime-codex.md for Codex runtime specifics
• docs/runtime-qwen.md for Qwen runtime specifics

Development and Release Validation

Canonical source lives under src/. The generator writes the agent stubs, commands, skills, manifests, hook registrations, policy pack, and detached src/ payloads under agents/, commands/, policies/, antigravity/, claude/, plugins/maestro/, and qwen/; update src/ first, then regenerate. A few runtime files are maintained by hand, mainly the thin MCP-server and hook-runner shims, the READMEs, and QWEN.md (CONTRIBUTING.md lists them).

npm ci
node scripts/generate.js
git diff --exit-code --name-only
npm test
npm run pack:verify
npm run release:artifacts
npm run release:verify-artifacts

Release validation creates dist/release/maestro-vX.Y.Z-extension.tar.gz. The archive is intentionally generic: it unpacks with qwen-extension.json, .claude-plugin/marketplace.json, and .agents/plugins/marketplace.json at the root, plus the runtime payloads needed by Antigravity (antigravity/), Claude Code, Codex, and Qwen Code.

Stable releases publish three aligned outputs:

• Git tag vX.Y.Z
• npm package @josstei/maestro@X.Y.Z
• GitHub Release asset maestro-vX.Y.Z-extension.tar.gz

Codex plugin releases launch the MCP server through the matching npm package version. The Antigravity plugin is self-contained: an installed copy runs the MCP server and hooks from its bundled antigravity/src/. Hook installation is explicit via npm run install-hooks; package, pack, and publish flows do not install git hooks.

License

Apache-2.0