Maestro - Orquestrador Multi-Agente para GitHub
neelneelpurk/maestro
Multi-agent para planejar e implementar features em paralelo no GitHub
Ver no GitHubAgent que planeja features com IA, quebra em sub-issues nativas com dependências, e executa em paralelo com workers autônomos que abrem PRs supervisionadas por um único portão de revisão humana. Plugin auto-contido para Claude Code com fluxo completo de planejamento, implementação e revisão.
Instalação
npx convez-ai neelneelpurk/maestro1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Orquestrar implementação de features complexas com múltiplos workers em paralelo
- Quebrar PRDs em sub-issues com dependências e executar em ordem
- Automatizar fluxo de planejamento, teste-first e revisão supervisionada
Veredito

Ferramenta robusta para times que querem orquestração multi-agente supervisionada em GitHub. Requer bash/gh/jq e disciplina no fluxo, mas elimina gargalos de implementação serial. Ideal para projetos complexos com múltiplas features em paralelo.
README
A tradução para o português deste README ainda está na fila.
This repo is a Claude Code marketplace (maestro) shipping one plugin (maestro). It's self-contained — it brings the whole workflow (planning, breakdown, strictly test-first implementation, review) plus the autonomous multi-agent orchestration layer, with no external skill dependencies.
flowchart TD
PLAN["/maestro:plan-with-agent<br/>grill the domain model → PRD parent issue"]
ISSUES["/maestro:issues<br/>PRD → native sub-issues + dependencies"]
SHIP["/maestro:ship<br/>one issue · supervised"]
DRAIN["/maestro:drain<br/>the whole ready queue"]
SPR["PR → default branch"]
WORK["background workers<br/>one worktree + PR per issue"]
IPR["per-issue PRs auto-merge<br/>→ integration branch"]
INTPR["one integration PR"]
GATE{{"👤 human review gate"}}
MAIN[("main")]
PLAN --> ISSUES
ISSUES --> SHIP
ISSUES --> DRAIN
SHIP --> SPR --> GATE
DRAIN --> WORK --> IPR --> INTPR --> GATE
GATE --> MAIN
Commands
| Command | What it does |
|---|---|
/maestro:init | One-time setup: labels, .maestro/ runtime, PR template — and a short discussion that writes your project context into CLAUDE.md, AGENTS.md, .claude/rules/maestro.md, docs/GLOSSARY.md. |
/maestro:plan-with-agent | Grill a feature against the domain model (updating CONTEXT.md + ADRs), then publish a PRD as a parent issue. |
/maestro:issues <prd#> | Break the PRD into sub-issues with native dependencies, labelled maestro:ready-for-agent, assigned to you. |
/maestro:share_implementation_plan <issue#> | Draft a test-first plan for an issue and post it as a comment — no code, no PR. Review the approach before building. |
/maestro:ship <issue#> | Implement one issue (supervised) — a background worker opens a PR to the default branch; awaits your review. |
/maestro:drain | Implement all your ready issues in dependency order on an integration branch; each per-issue PR auto-merges into it; the integration PR is your one review gate. |
/maestro:auto | Autonomous loop: maestro:roadmap → drain, repeatedly. Issues it creates are labelled maestro:auto and skip the human maestro:ready-for-agent gate. |
/maestro:roadmap | Analyze what's already shipped → propose next features + tech-debt → create issues under a roadmap parent + milestone. |
/maestro:code-feedback [pr#] | Review a PR (inline GitHub review) or the whole codebase (report + optional maestro:ready-for-agent maestro:tech-debt issues). Asks you for scope + focus. |
/maestro:code-architecture-map | Map the codebase (modules, seams, dependencies) → docs/architecture-map.md + optional HTML report. |
/maestro:status [close-integrated] | The pipeline board (now with a recent-runs summary); or close out a merged integration run. |
/maestro:merge_pr [pr#] | Merge a PR and close the issues it covers in one step. No number → the integration PR + its whole run. Your manual review gate. |
The coordinator commands (ship, drain, maestro:auto) only coordinate — they dispatch background issue-implementer workers and stay responsive, so you can keep participating in the same session.
Install
claude plugin marketplace add neelneelpurk/maestro # or: add ./ (local checkout)
claude plugin install maestro@maestro
# RESTART Claude Code (or /reload-plugins) — required so the issue-implementer
# agent type and /maestro:* commands load (the agent registry is fixed at session start)
/maestro:init # set up the repo you want to drive
The marketplace is
maestro; the plugin ismaestro— hence/maestro:*and the install targetmaestro@maestro.
Prerequisites
ghauthenticated withreposcope, andjq.- That's all — the plugin is self-contained (no external skill dependencies).
Integration-branch model
A run is fully autonomous below the default branch, with one human gate at it:
drain/maestro:autoopen one integration branch off the default branch and one integration PR (integration → default). That PR is never auto-merged — it is your single review gate, and it collects a running checklist of integrated issues.- Each issue gets its own branch (created with
gh issue develop, natively linked) off the integration branch; its per-issue PR targets the integration branch and is merged automatically once the quality gate is green. Dependents build on already-integrated work, so the dependency queue self-progresses. - Issues are never auto-closed — they move to
maestro:waiting-for-human-closure. When you merge the integration PR, run/maestro:status close-integratedto close them.
gitGraph
commit id: "main"
branch integration
checkout integration
commit id: "seed (empty commit)"
branch issue-41
checkout issue-41
commit id: "test #41"
commit id: "impl #41"
checkout integration
merge issue-41
branch issue-42
checkout issue-42
commit id: "test #42"
commit id: "impl #42"
checkout integration
merge issue-42
checkout main
merge integration tag: "human merge"
/maestro:ship is the simpler supervised path: one issue, a PR straight to the default branch with Closes #n, awaiting your review.
See docs/GLOSSARY.md for the full label state machine and docs/ARCHITECTURE.md for the design.
What's inside
| Block | Where | What |
|---|---|---|
| Scripts | plugins/maestro/scripts/ | bash + gh + jq: native sub-issues/dependencies, gh issue develop links, worktrees, the integration run, quality gate, queue queries |
| Subagents | plugins/maestro/agents/ | issue-implementer — dispatched in the background, one per issue |
| Skills | plugins/maestro/skills/ | plan-with-agent, ship, drain, maestro:auto, maestro:roadmap, code-feedback, code-architecture-map, implement-issue |
| Hooks | plugins/maestro/hooks/ | PR quality-gate backstop + AI-disclaimer guard (PreToolUse) |
| Rules | seeded into the repo | .claude/rules/maestro.md + CLAUDE.md — inherited by every worker, even inside worktrees |
| Loops | /maestro:drain, /maestro:auto | self-paced via background-worker completion + /loop / ScheduleWakeup |
Safety
- You are the merge gate — the integration PR is never auto-merged;
shipPRs await your review. - No red PRs — the quality gate runs before any PR opens (and a PreToolUse hook backstops manual
gh pr create). - No auto-close — issues move to
maestro:waiting-for-human-closure; you close them when you merge the integration PR. - Isolation — one git worktree + branch per issue; concurrency capped by
MAESTRO_MAX_PARALLEL.
Further reading
- docs/ARCHITECTURE.md — the full design (coordinator + background workers, the GitHub-native data model).
- docs/GLOSSARY.md — labels and the complete state machine.
- docs/TESTING.md — the quality gate and the pure-bash test suite.
- docs/TROUBLESHOOTING.md — failure modes and how to recover (stuck runs, conflicts, gate, worktrees).
- CONTRIBUTING.md — project layout and pull-request conventions.
- blog/one-human-gate.md — the story behind the design.
License
MIT — see LICENSE. Self-contained: no external skill dependencies.