{
  "markdown": "# Maestro\n\n[![Version](https://img.shields.io/badge/version-1.6.4-blue)](https://github.com/josstei/maestro-orchestrate/releases)\n[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)\n[![Gemini CLI](https://img.shields.io/badge/Gemini_CLI-extension-orange)](https://github.com/google-gemini/gemini-cli)\n[![Claude Code](https://img.shields.io/badge/Claude_Code-plugin-blue)](https://docs.anthropic.com/en/docs/claude-code)\n[![Codex](https://img.shields.io/badge/Codex-plugin-black)](docs/runtime-codex.md)\n[![Qwen Code](https://img.shields.io/badge/Qwen_Code-extension-purple)](https://github.com/QwenLM/qwen-code)\n\nMaestro 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 **Gemini CLI**, **Claude Code**, **Codex**, and **Qwen Code**.\n\n## Runtime Targets\n\n| Runtime | Location | Public Surface | Notes |\n|---------|----------|----------------|-------|\n| Gemini CLI | repo root | `/maestro:*` | Snake-case agents, TOML commands, hooks, TOML shell policies |\n| Claude Code | `claude/` | `/orchestrate`, `/review-code`, ... | Kebab-case agents with `maestro:` subagent names |\n| Codex | `plugins/maestro/` | `$maestro:*` | Plugin skills, `spawn_agent`, no runtime hooks |\n| Qwen Code | `qwen/` | `/maestro:*` | Gemini-CLI-compatible extension, `QWEN.md` context file, `SubagentStart`/`SubagentStop` hooks |\n\n## Getting Started\n\n### Prerequisites\n\n- One supported runtime: Gemini CLI, Claude Code, Codex, or Qwen Code\n- Node.js 20+ for the MCP server and helper scripts\n- Gemini CLI and Qwen Code only: enable experimental subagents in `~/.gemini/settings.json` (Gemini) or `~/.qwen/settings.json` (Qwen)\n\n```json\n{\n  \"experimental\": {\n    \"enableAgents\": true\n  }\n}\n```\n\nMaestro does not edit `~/.gemini/settings.json` or `~/.qwen/settings.json` for you.\n\n### Installation\n\n#### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/josstei/maestro-orchestrate\n```\n\nLocal development:\n\n```bash\ngit clone https://github.com/josstei/maestro-orchestrate\ncd maestro-orchestrate\ngemini extensions link .\n```\n\nVerify with `gemini extensions list`.\n\n#### Claude Code\n\nMarketplace install:\n\n```bash\nclaude plugin marketplace add josstei/maestro-orchestrate\nclaude plugin install maestro@maestro-orchestrator --scope user\n```\n\nDevelopment / temporary loading:\n\n```bash\ngit clone https://github.com/josstei/maestro-orchestrate\nclaude --plugin-dir /path/to/maestro-orchestrate/claude\n```\n\nMore Claude-specific setup and plugin management lives in [claude/README.md](claude/README.md).\n\n#### Codex\n\nRegister the marketplace:\n\n```bash\ncodex plugin marketplace add josstei/maestro-orchestrate\n```\n\nThen start Codex, run `/plugins` to browse, select **Maestro**, and choose **Install**.\n\nLocal development (path must start with `./`, `../`, `/`, or `~/` — Codex otherwise treats bare `owner/repo` as a GitHub source):\n\n```bash\ngit clone https://github.com/josstei/maestro-orchestrate\ncodex plugin marketplace add /absolute/path/to/maestro-orchestrate\n# then: start Codex, run `/plugins`, select Maestro → Install\n```\n\nMore Codex-specific setup and runtime details live in [plugins/maestro/README.md](plugins/maestro/README.md) and [docs/runtime-codex.md](docs/runtime-codex.md).\n\n#### Qwen Code\n\n```bash\nqwen extensions install https://github.com/josstei/maestro-orchestrate\n```\n\nLocal development:\n\n```bash\ngit clone https://github.com/josstei/maestro-orchestrate\ncd maestro-orchestrate\nqwen extensions link .\n```\n\nVerify with `qwen extensions list`. Qwen Code uses the same `/maestro:*` command surface as Gemini CLI and reads `QWEN.md` as its context file.\n\n### Quick Start\n\nStart a full orchestration with the runtime-specific entrypoint:\n\n| Runtime | Example |\n|---------|---------|\n| Gemini CLI | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |\n| Claude Code | `/orchestrate Build a REST API for a task management system with user authentication` |\n| Codex | `$maestro:orchestrate Build a REST API for a task management system with user authentication` |\n| Qwen Code | `/maestro:orchestrate Build a REST API for a task management system with user authentication` |\n\nMaestro 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/`.\n\n## Examples\n\nUsage examples: [EXAMPLES.md](EXAMPLES.md). Gemini/Qwen forms shown:\n\n- Full orchestration: `/maestro:orchestrate Build a REST API for a task management system with user authentication`\n- Standalone review: `/maestro:review Review the staged changes for correctness, regressions, security, maintainability risk, and missing tests`\n- Security audit: `/maestro:security-audit Audit authentication, authorization, data exposure, secret handling, and exploitability risks`\n\n## Configuration\n\nDefaults work; these settings tune behavior:\n\n| Setting | Default | Purpose |\n|---------|---------|---------|\n| `MAESTRO_STATE_DIR` | `docs/maestro` | Session, plan, and archive output path |\n| `MAESTRO_EXECUTION_MODE` | `ask` | Choose `parallel`, `sequential`, or prompt |\n| `MAESTRO_AUTO_ARCHIVE` | `true` | Archive successful sessions automatically |\n| `MAESTRO_MAX_RETRIES` | `2` | Retry limit for failed phases |\n| `MAESTRO_MAX_CONCURRENT` | `0` | Parallel-agent cap, where `0` means no Maestro cap |\n| `MAESTRO_DISABLED_AGENTS` | unset | Specialists to exclude from assignment |\n\n## Commands\n\n| Capability | Gemini CLI | Claude Code | Codex | Qwen Code |\n|------------|------------|-------------|-------|-----------|\n| Orchestrate | `/maestro:orchestrate` | `/orchestrate` | `$maestro:orchestrate` | `/maestro:orchestrate` |\n| Execute | `/maestro:execute` | `/execute` | `$maestro:execute` | `/maestro:execute` |\n| Resume | `/maestro:resume` | `/resume-session` | `$maestro:resume-session` | `/maestro:resume` |\n| Status | `/maestro:status` | `/status` | `$maestro:status` | `/maestro:status` |\n| Archive | `/maestro:archive` | `/archive` | `$maestro:archive` | `/maestro:archive` |\n| Review | `/maestro:review` | `/review-code` | `$maestro:review-code` | `/maestro:review` |\n| Debug | `/maestro:debug` | `/debug-workflow` | `$maestro:debug-workflow` | `/maestro:debug` |\n| Security Audit | `/maestro:security-audit` | `/security-audit` | `$maestro:security-audit` | `/maestro:security-audit` |\n| Performance Check | `/maestro:perf-check` | `/perf-check` | `$maestro:perf-check` | `/maestro:perf-check` |\n| SEO Audit | `/maestro:seo-audit` | `/seo-audit` | `$maestro:seo-audit` | `/maestro:seo-audit` |\n| Accessibility Audit | `/maestro:a11y-audit` | `/a11y-audit` | `$maestro:a11y-audit` | `/maestro:a11y-audit` |\n| Compliance Check | `/maestro:compliance-check` | `/compliance-check` | `$maestro:compliance-check` | `/maestro:compliance-check` |\n\nFor 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.\n\nQwen Code uses the same `/maestro:*` command surface as Gemini CLI.\n\n## Workflow\n\n- **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.\n- **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.\n\n## Outputs and Success Criteria\n\nMaestro 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.\n\nA 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.\n\n## Security and Permissions\n\nMaestro 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.\n\n## Documentation\n\n- [EXAMPLES.md](EXAMPLES.md) for copyable usage scenarios across all runtimes\n- [docs/overview.md](docs/overview.md) for the project model and generated structure\n- [docs/architecture.md](docs/architecture.md) for orchestration internals and architecture layout\n- [docs/usage.md](docs/usage.md) for development workflow, settings, and command surfaces\n- [docs/flow.md](docs/flow.md) for the orchestration workflow steps and hard gates\n- [docs/cicd.md](docs/cicd.md) for CI/CD pipeline workflows, release process, and Mermaid diagrams\n- [docs/runtime-gemini.md](docs/runtime-gemini.md) for Gemini runtime specifics\n- [docs/runtime-claude.md](docs/runtime-claude.md) for Claude runtime specifics\n- [docs/runtime-codex.md](docs/runtime-codex.md) for Codex runtime specifics\n- [docs/runtime-qwen.md](docs/runtime-qwen.md) for Qwen runtime specifics\n\n## Development and Release Validation\n\nCanonical source lives under `src/`. Runtime files in `agents/`, `commands/`, `hooks/`, `mcp/`, `policies/`, `claude/`, `plugins/maestro/`, and `qwen/` are generated; update `src/` first, then regenerate.\n\n```bash\nnpm ci\nnode scripts/generate.js\ngit diff --exit-code --name-only\nnode --test tests/unit/*.test.js tests/transforms/*.test.js tests/integration/*.test.js\nnpm run pack:verify\nnpm run release:artifacts\nnpm run release:verify-artifacts\n```\n\nRelease validation creates `dist/release/maestro-vX.Y.Z-extension.tar.gz`. The archive is intentionally generic: it unpacks with `gemini-extension.json`, `qwen-extension.json`, `.claude-plugin/marketplace.json`, and `.agents/plugins/marketplace.json` at the root, plus the runtime payload needed by Gemini CLI, Qwen Code, Claude Code, and Codex.\n\nStable releases publish three aligned outputs:\n\n- Git tag `vX.Y.Z`\n- npm package `@josstei/maestro@X.Y.Z`\n- GitHub Release asset `maestro-vX.Y.Z-extension.tar.gz`\n\nCodex plugin releases launch the MCP server through the matching npm package version. Hook installation is explicit via `npm run install-hooks`; package, pack, and publish flows do not install git hooks.\n\n## License\n\nApache-2.0\n",
  "bytes": 11173,
  "sha": "ddaf8b85ba031662d3bf8485aa44970deb74362f725ae2b683ed038fc4bf9e0a",
  "repo_slug": "josstei/maestro-orchestrate",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_josstei_maestro_orchestrate_73f4875e/readme"
}