convez.ai
AgenteDesenvolvimento WebAvançado
indiekitai

Claude Orchestrator

indiekitai/claude-orchestrator

Orquestrador de agentes paralelos para builds de features com Claude Code

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent que orquestra a construção paralela de features decompostas em tarefas isoladas. Coordena múltiplos agentes Claude em worktrees paralelos, aplicando gates de qualidade e mesclando resultados de forma segura, eliminando esperas sequenciais e conflitos de merge.

Instalação

$npx convez-ai indiekitai/claude-orchestrator

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 3 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Acelerar desenvolvimento de features grandes que atravessam múltiplos subsistemas
  • Coordenar trabalho paralelo entre agentes sem conflitos ou sobreposições
  • Aplicar gates de qualidade automáticos (testes, type-check, builds) antes de merge

Veredito

Ferramenta sofisticada que transforma o fluxo de desenvolvimento com Claude de sequencial para paralelo, reduzindo drasticamente o tempo de build de features complexas. Exige compreensão profunda de arquitetura de código e workflows de CI/CD, mas entrega ganhos reais de produtividade em projetos grandes.

README

A tradução para o português deste README ainda está na fila.

English | 中文

claude-orchestrator

Parallel AI agents building your feature while you review. A Claude Code skill that decomposes large features into bounded task contracts, dispatches them to isolated worktree agents in parallel, enforces quality gates, and merges the results — all in one orchestration cycle.

🤔 The Problem

Building a feature that spans multiple subsystems with Claude Code usually means:

  • Running one agent at a time, waiting, reviewing, then starting the next
  • Manually tracking which files each agent is allowed to touch
  • Hoping two agents don't edit the same shared contract simultaneously
  • No systematic way to enforce "shared contract first, consumers after"
  • Shallow slices that look done but don't connect end-to-end

You end up as an ad-hoc project manager, juggling agent outputs in your head.

🔧 How It Works

┌─────────────────────────────────────────────────────┐
│                   ORCHESTRATOR                      │
│                                                     │
│  1. Reconnaissance   — read repo state              │
│  2. Decompose        — identify task contracts      │
│  3. Anti-shallow gate — reject placeholder slices   │
│         │                                           │
│         ▼                                           │
│  4. Serialize shared contracts (if any)             │
│         │                                           │
│         ▼                                           │
│  5. Parallel fan-out ─┬─ Agent A (worktree)         │
│                       ├─ Agent B (worktree)         │
│                       └─ Agent C (worktree)         │
│         │                                           │
│         ▼                                           │
│  6. Review each branch (boundary + gates + evidence)│
│         │                                           │
│         ▼                                           │
│  7. Merge + integration test                        │
│         │                                           │
│         ▼                                           │
│  8. Next batch (or stop)                            │
└─────────────────────────────────────────────────────┘

✨ Key Features

FeatureDescription
Serial → ParallelShared contracts (proto, migrations, APIs) are built first, then consumers fan out in parallel
Worktree IsolationEach agent works in its own git worktree — no merge conflicts during development
Anti-Shallow-Slice GateRejects placeholder pages, read-only shells, and duplicate first-slices. Every dispatched task must be a vertical-completion, runtime-proof, blocked-removal, or owner-gated
Bounded Task ContractsEach agent gets explicit allowed/forbidden paths, gates (test/typecheck/build), and evidence requirements
4-Level Evidence DisciplineProof is labeled direct, proxy, local, or blocked — no upgrading between levels (local test ≠ staging test ≠ production proof)
Claim VerificationAgent self-reports ("tests pass", "no forbidden paths touched") are verified against actual command output and diff — not blindly trusted
Quality GatesEvery branch is reviewed for boundary violations, gate results, evidence strength, and idempotency before merge
Post-Merge Integration TestAfter merging a batch, cross-layer tests run to catch issues that individual gates miss
Concurrency ControlSmart limits: 2 agents default, 3 max when safe, 1 when shared contracts are in play
State Transition VerificationDispatch prompts require agents to verify ALL consumers handle ALL state transitions, not just their own layer
Package Lane GuardPrevents slot-filling with unrelated backlog items — keeps work focused on one feature package at a time
Decision Brief DisciplineWhen blocked, produces structured consultation briefs with evidence, options, and recommendations — not bare blocker text
Anti-Pattern Checklist10 named orchestration mistakes (ORC-01 through ORC-10) for systematic review — evidence upgrade, slot-filling, constraint amnesia, etc.
Roadmap-Driven ModeContinuously build features from a roadmap doc — done → pick next → continue, until stop condition

🚀 Quick Start

1. Install the skill

# Copy to your Claude Code skills directory
cp -r . ~/.claude/skills/build-orchestrator/

# Or symlink it
ln -s "$(pwd)" ~/.claude/skills/build-orchestrator

2. Use it

Single feature (build one thing and stop):

/build-orchestrator <describe the feature or milestone to build>

Roadmap-driven (continuously build features from a priority list):

/build-orchestrator --roadmap docs/roadmap.md

Or trigger it naturally in conversation:

"I need to build the payment integration across 3 subsystems. Dispatch parallel agents."

"拆开做,并行推这个功能"

📦 Real Example

A real-world feature requiring 4 agents across 3 subsystems, producing 1,400+ lines of production code in one orchestration cycle:

Phase 1 — Serial (shared contract)
┌──────────────────────────────────┐
│  Agent 0: Proto Contract         │
│  Define shared types & interfaces│
│  ✓ merged to main               │
│  ✓ pushed (worktree base trap!)  │
└──────────────┬───────────────────┘
               │
Phase 2 — Parallel fan-out (3 consumers)
               │
    ┌──────────┼──────────┐
    ▼          ▼          ▼
┌────────┐┌────────┐┌────────┐
│Agent 1 ││Agent 2 ││Agent 3 │
│Subsys A││Subsys B││Subsys C│
│        ││        ││        │
│✓ review││✓ review││✓ review│
│✓ merge ││✓ merge ││✓ merge │
└────────┘└────────┘└────────┘
               │
Phase 3 — Post-merge
┌──────────────────────────────────┐
│  Integration test across all     │
│  subsystems                      │
│  Independent cross-agent review  │
│  → caught 2 critical bugs       │
└──────────────────────────────────┘

Result: 4 agents, 1,400+ lines, one cycle

The orchestrator handled the entire dependency graph: the shared contract had to land first (serial) and be pushed (so parallel agents' worktrees would include it), then the three consumer agents ran simultaneously (parallel), each in its own worktree with disjoint file sets. After all returned, each branch was reviewed against its task contract, merged, and a cross-layer integration test validated the combined result.

⚠️ Lessons Learned (from production use)

These are baked into the skill, but worth knowing:

TrapWhat happenedRule added
Worktree base trapParallel agents' worktrees are created from origin/main, not local main. After merging a serial batch locally but not pushing, parallel agents didn't see the serial changes and redid the workPush after serial batch merge, before dispatching parallel batch
Agent self-review misses cross-layer bugs3 agents all self-reviewed, but an independent review found 2 critical state transition bugs across layersIndependent cross-agent review required for state machine / cross-layer features
Out-of-bounds agent can't mergeAn agent modified forbidden paths due to stale base. git merge would include the out-of-bounds changesUse cherry-pick --no-commit to extract only in-scope changes
Individual gates pass but integration failsEach agent's tests passed, but combined code had cross-layer gapsPost-merge integration test after every batch
Blind self-report trustAgent claimed "all tests pass" in handoff but no command output was provided. Orchestrator merged without verifyingClaim verification: verify self-reported completion against actual command output and diff
Slot-filling scatters progressAvailable concurrency slot → grabbed unrelated backlog item → daily progress read as random cleanup instead of coherent feature advancePackage lane guard: stay in current feature package, don't scatter
Evidence upgradeLocal unit test passing was labeled as proxy proof in review docs. Over time, proxy drifted to be treated as direct4-level evidence discipline with strict no-upgrade rule
Contract-only branch unmergeableDispatched a proto-only branch, but the repo's sync check required consumers to update in the same change. Branch could never merge aloneContract sync gate: include minimal consumer updates in serial contract task
Same-module parallelism2 agents adding new pages to the same Android app. Both touched strings.xml + navigation + DI. 43% of batches had merge conflicts costing 10-15 min each — more than parallelism savedSerialize same-module tasks. Parallel only across different modules
Phantom commitAgent reported "done" but never ran git commit. Orchestrator assumed commit existed and tried to merge — got "Already up to date"Always git status before merge. Commit enforcement rule in dispatch prompt (#1 failure mode, 40%→100% fix rate)
Codex review catches what orchestrator can't4 Codex reviews found 10 findings (2×P1 + 8×P2): version conflict, regression, date crash, float truncation, fake success toast. Zero found by agent self-review or orchestrator diff reviewCross-model review is mandatory, not optional. Budget 600s timeout for large diffs

⚙️ Execution Model

Claude Code agents are synchronous — they run within the current session and return results. This is not fire-and-forget.

Dispatch → Agents run concurrently → All return → Review → Merge → Integration test → Next batch

Each agent call uses isolation: "worktree", which gives it a dedicated git worktree. The orchestrator waits for all agents in a batch to complete, then reviews and merges before dispatching the next batch.

📊 vs Other Approaches

build-orchestratorSingle agentManual multi-agentCI/CD workflow
ParallelismSerial deps → parallel fan-outSequential phasesAd-hoc, hope for the bestPipeline stages
IsolationGit worktrees per agentSingle worktreeShared worktree (conflict risk)Separate repos/branches
Quality gatesPer-branch review + evidence + integration testSelf-review onlyManual reviewAutomated tests only
Anti-shallow-sliceBuilt-in classification gateN/AN/AN/A
Shared contractsSerialized first, then fan-outN/AManual coordinationN/A
Continuous modeRoadmap-driven auto-selectionN/AN/AN/A
Best forWidth (many tasks)Depth (one complex task)Simple changesPost-merge validation

🔢 Concurrency Rules

AgentsWhen
1 (serialize)Shared contract being edited, hardware/payment involved, next step depends on current result, overlapping write sets
2 (default)Standard parallel work with disjoint modules
3 (max)All clean: no shared contracts active, main is clean, fully disjoint write sets, no hardware/payment tasks

The goal is to reduce calendar time without increasing merge risk. Don't open more agents just because you can.

🔗 Related Projects

  • codex-orchestrator — The sibling project for Codex App users. Same orchestration philosophy (bounded contracts, evidence discipline, anti-shallow-slice), but adapted for Codex App's async session model with a Go CLI helper for persistent ledger, heartbeat, routines, and policy/eval.

📄 License

MIT — see LICENSE


Built by IndieKit.ai — open-source developer tools for the AI-native workflow.

Ver o original no GitHub

Bom para

Relacionados