{"id":50770970,"url":"https://github.com/neelneelpurk/maestro","last_synced_at":"2026-06-11T18:30:41.481Z","repository":{"id":362775174,"uuid":"1259187361","full_name":"neelneelpurk/maestro","owner":"neelneelpurk","description":"A multi-agent AI maestro for any GitHub repo: PRD → native sub-issues → parallel background workers that each open a PR, behind one human review gate. A self-contained Claude Code plugin.","archived":false,"fork":false,"pushed_at":"2026-06-05T21:45:56.000Z","size":1977,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-05T22:12:32.340Z","etag":null,"topics":["agentic-ai","ai-agents","anthropic","autonomous-agents","claude-code","claude-code-plugin","developer-tools","github-automation","multi-agent","orchestration","sdlc","tdd"],"latest_commit_sha":null,"homepage":"https://soumyadeeppurkait.xyz","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neelneelpurk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-04T09:14:28.000Z","updated_at":"2026-06-05T21:46:01.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/neelneelpurk/maestro","commit_stats":null,"previous_names":["neelneelpurk/maestro"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/neelneelpurk/maestro","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neelneelpurk%2Fmaestro","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neelneelpurk%2Fmaestro/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neelneelpurk%2Fmaestro/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neelneelpurk%2Fmaestro/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neelneelpurk","download_url":"https://codeload.github.com/neelneelpurk/maestro/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neelneelpurk%2Fmaestro/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34213179,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","ai-agents","anthropic","autonomous-agents","claude-code","claude-code-plugin","developer-tools","github-automation","multi-agent","orchestration","sdlc","tdd"],"created_at":"2026-06-11T18:30:40.616Z","updated_at":"2026-06-11T18:30:41.474Z","avatar_url":"https://github.com/neelneelpurk.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003ch1\u003e🤖 maestro\u003c/h1\u003e\n\n\u003cp\u003e\u003cb\u003eA downloadable, multi-agent AI maestro for any GitHub repo.\u003c/b\u003e\u003c/p\u003e\n\n\u003cp\u003e\nPlan a PRD with the agent → break it into native sub-issues → fan out\n\u003cb\u003ebackground workers, one per issue\u003c/b\u003e → land them on an\n\u003cb\u003eintegration branch\u003c/b\u003e behind a single human review gate.\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg alt=\"License: MIT\" src=\"https://img.shields.io/badge/License-MIT-blue.svg\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Plugin v0.1.0\" src=\"https://img.shields.io/badge/plugin-v0.1.0-orange.svg\"\u003e\n  \u003ca href=\"https://docs.claude.com/en/docs/claude-code/overview\"\u003e\u003cimg alt=\"Claude Code plugin\" src=\"https://img.shields.io/badge/Claude%20Code-plugin-7C3AED.svg\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Built with bash + gh + jq\" src=\"https://img.shields.io/badge/built%20with-bash%20%2B%20gh%20%2B%20jq-1f425f.svg\"\u003e\n  \u003ca href=\"CONTRIBUTING.md\"\u003e\u003cimg alt=\"PRs welcome\" src=\"https://img.shields.io/badge/PRs-welcome-brightgreen.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"#commands\"\u003eCommands\u003c/a\u003e ·\n  \u003ca href=\"#install\"\u003eInstall\u003c/a\u003e ·\n  \u003ca href=\"#integration-branch-model\"\u003eIntegration model\u003c/a\u003e ·\n  \u003ca href=\"#whats-inside\"\u003eWhat's inside\u003c/a\u003e ·\n  \u003ca href=\"#safety\"\u003eSafety\u003c/a\u003e ·\n  \u003ca href=\"docs/ARCHITECTURE.md\"\u003eArchitecture\u003c/a\u003e ·\n  \u003ca href=\"docs/GLOSSARY.md\"\u003eGlossary\u003c/a\u003e\n\u003c/p\u003e\n\n\u003c/div\u003e\n\n---\n\nThis 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.\n\n```mermaid\nflowchart TD\n    PLAN[\"/maestro:plan-with-agent\u003cbr/\u003egrill the domain model → PRD parent issue\"]\n    ISSUES[\"/maestro:issues\u003cbr/\u003ePRD → native sub-issues + dependencies\"]\n    SHIP[\"/maestro:ship\u003cbr/\u003eone issue · supervised\"]\n    DRAIN[\"/maestro:drain\u003cbr/\u003ethe whole ready queue\"]\n    SPR[\"PR → default branch\"]\n    WORK[\"background workers\u003cbr/\u003eone worktree + PR per issue\"]\n    IPR[\"per-issue PRs auto-merge\u003cbr/\u003e→ integration branch\"]\n    INTPR[\"one integration PR\"]\n    GATE{{\"👤 human review gate\"}}\n    MAIN[(\"main\")]\n\n    PLAN --\u003e ISSUES\n    ISSUES --\u003e SHIP\n    ISSUES --\u003e DRAIN\n    SHIP --\u003e SPR --\u003e GATE\n    DRAIN --\u003e WORK --\u003e IPR --\u003e INTPR --\u003e GATE\n    GATE --\u003e MAIN\n```\n\n## Commands\n\n| Command | What it does |\n|---|---|\n| `/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`. |\n| `/maestro:plan-with-agent` | Grill a feature against the domain model (updating `CONTEXT.md` + ADRs), then publish a **PRD** as a parent issue. |\n| `/maestro:issues \u003cprd#\u003e` | Break the PRD into **sub-issues** with **native dependencies**, labelled `maestro:ready-for-agent`, assigned to you. |\n| `/maestro:share_implementation_plan \u003cissue#\u003e` | Draft a **test-first plan** for an issue and post it as a comment — no code, no PR. Review the approach before building. |\n| `/maestro:ship \u003cissue#\u003e` | Implement **one** issue (supervised) — a background worker opens a PR to the default branch; awaits your review. |\n| `/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. |\n| `/maestro:auto` | Autonomous loop: `maestro:roadmap` → `drain`, repeatedly. Issues it creates are labelled `maestro:auto` and skip the human `maestro:ready-for-agent` gate. |\n| `/maestro:roadmap` | Analyze what's already shipped → propose next features + tech-debt → create issues under a roadmap parent + milestone. |\n| `/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. |\n| `/maestro:code-architecture-map` | Map the codebase (modules, seams, dependencies) → `docs/architecture-map.md` + optional HTML report. |\n| `/maestro:status [close-integrated]` | The pipeline board (now with a **recent-runs** summary); or close out a merged integration run. |\n| `/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. |\n\nThe 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.\n\n## Install\n\n```bash\nclaude plugin marketplace add neelneelpurk/maestro     # or: add ./  (local checkout)\nclaude plugin install maestro@maestro\n# RESTART Claude Code (or /reload-plugins) — required so the issue-implementer\n# agent type and /maestro:* commands load (the agent registry is fixed at session start)\n/maestro:init                                             # set up the repo you want to drive\n```\n\n\u003e The marketplace is `maestro`; the plugin is `maestro` — hence `/maestro:*` and the install target `maestro@maestro`.\n\n### Prerequisites\n- [`gh`](https://cli.github.com/) authenticated with `repo` scope, and `jq`.\n- That's all — the plugin is self-contained (no external skill dependencies).\n\n## Integration-branch model\n\nA run is fully autonomous below the default branch, with one human gate at it:\n\n- `drain`/`maestro:auto` open **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.\n- 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.\n- Issues are **never auto-closed** — they move to `maestro:waiting-for-human-closure`. When you merge the integration PR, run `/maestro:status close-integrated` to close them.\n\n```mermaid\ngitGraph\n   commit id: \"main\"\n   branch integration\n   checkout integration\n   commit id: \"seed (empty commit)\"\n   branch issue-41\n   checkout issue-41\n   commit id: \"test #41\"\n   commit id: \"impl #41\"\n   checkout integration\n   merge issue-41\n   branch issue-42\n   checkout issue-42\n   commit id: \"test #42\"\n   commit id: \"impl #42\"\n   checkout integration\n   merge issue-42\n   checkout main\n   merge integration tag: \"human merge\"\n```\n\n`/maestro:ship` is the simpler supervised path: one issue, a PR straight to the default branch with `Closes #n`, awaiting your review.\n\nSee [docs/GLOSSARY.md](docs/GLOSSARY.md) for the full label state machine and [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the design.\n\n## What's inside\n\n| Block | Where | What |\n|---|---|---|\n| **Scripts** | `plugins/maestro/scripts/` | bash + `gh` + `jq`: native sub-issues/dependencies, `gh issue develop` links, worktrees, the integration run, quality gate, queue queries |\n| **Subagents** | `plugins/maestro/agents/` | `issue-implementer` — dispatched in the **background**, one per issue |\n| **Skills** | `plugins/maestro/skills/` | `plan-with-agent`, `ship`, `drain`, `maestro:auto`, `maestro:roadmap`, `code-feedback`, `code-architecture-map`, `implement-issue` |\n| **Hooks** | `plugins/maestro/hooks/` | PR quality-gate backstop + AI-disclaimer guard (PreToolUse) |\n| **Rules** | seeded into the repo | `.claude/rules/maestro.md` + `CLAUDE.md` — **inherited by every worker**, even inside worktrees |\n| **Loops** | `/maestro:drain`, `/maestro:auto` | self-paced via background-worker completion + `/loop` / `ScheduleWakeup` |\n\n## Safety\n- **You are the merge gate** — the integration PR is never auto-merged; `ship` PRs await your review.\n- **No red PRs** — the quality gate runs before any PR opens (and a PreToolUse hook backstops manual `gh pr create`).\n- **No auto-close** — issues move to `maestro:waiting-for-human-closure`; you close them when you merge the integration PR.\n- **Isolation** — one git worktree + branch per issue; concurrency capped by `MAESTRO_MAX_PARALLEL`.\n\n## Further reading\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the full design (coordinator + background workers, the GitHub-native data model).\n- [docs/GLOSSARY.md](docs/GLOSSARY.md) — labels and the complete state machine.\n- [docs/TESTING.md](docs/TESTING.md) — the quality gate and the pure-bash test suite.\n- [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) — failure modes and how to recover (stuck runs, conflicts, gate, worktrees).\n- [CONTRIBUTING.md](CONTRIBUTING.md) — project layout and pull-request conventions.\n- [blog/one-human-gate.md](blog/one-human-gate.md) — the story behind the design.\n\n## License\nMIT — see [LICENSE](LICENSE). Self-contained: no external skill dependencies.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneelneelpurk%2Fmaestro","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneelneelpurk%2Fmaestro","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneelneelpurk%2Fmaestro/lists"}