Conducting agents like an orchestra: how agents-concerto works

A developer built agents-concerto, a multi-agent orchestrator on top of Claude Code that enforces behavior-driven development (BDD) and Tidy First discipline. The system uses four agents—orchestrator, classifier, implementer, and reviewer—to produce open pull requests ready for human review, with acceptance criteria automatically turned into tests that assert only observable behavior.

For months I had the same problem with coding agents: the session drops a pile of changes, and by review time I no longer know what it touched or why. The agent writes, the agent validates, the agent congratulates itself. The human signs blind. And when the agent did write tests, it got worse — green tests that proved nothing. Mocks of the very code under test, assertions on private fields, snapshots of incidental structure. Suite green, confidence zero. So I built agents-concerto https://github.com/moruno21/agents-concerto : a multi-agent orchestrator on top of Claude Code. The name is literal: there's a The repo isn't an application. It's an orchestration brain: one CLAUDE.md , four agents in Markdown, four Bash scripts. Its product is open PRs ready for human review . config.md . One repo or fifteen take the same code path. backend-dev / frontend-dev .Rule 3 is the one you feel. When the author isn't the approver, the verdict means something. This is the part that changed the system most: a criterion isn't a note for humans, it's a test spec. Shaping /shape , or inline in /run refuses to emit a wishlist. Criteria come out in Given-When-Then — given <context , when <action , then <observable result — inside a tiered contract where Task and Acceptance criteria are mandatory and Scope / Non-goals are optional, included only when they add signal.A Given-When-Then criterion already names a context, a trigger, and an observable result. That's a test. And because the "then" must be observable, the criterion is hard to satisfy by asserting on internals. So the criterion travels the pipeline: written at shaping, turned into a test at implementation, verified as a criterion→test mapping at review. orchestrator classifier complex → opus for gnarly logic, concurrency, or sensitive paths; trivial|standard → sonnet. When torn, pick higher. implementer model: in its frontmatter reviewer Read, Grep, Glob, Bash : Write , no Edit Every criterion becomes at least one test asserting observable behavior — outputs, rendered UI, persisted state, HTTP responses, emitted events. Never internals: no private fields, no mocks of internal helpers, no asserting a function was called. Tests are driven from the public entry point, named from the user's view it "shows an error when the email already exists" , and only genuinely external dependencies get mocked — network, clock, third parties. Never the code under test. It all compresses into one rule: If a behavior-preserving refactor breaks the test, the test is wrong. That's why Tidy First and BDD belong together. The structural commit, by definition, doesn't change behavior — so if a test breaks there, either the "refactor" wasn't one, or the test was coupled to internals. Every PR proves both at once. Correctness against the criteria, tests green, Tidy First discipline a mixed commit is NEEDS FIXES , named , and the BDD gate: a criterion with no covering test, or a test asserting on internals, blocks the PR. That last gate has a qualifier I think is the most important decision in it: it applies only to tests added or modified in the diff. Pre-existing tests the PR leaves alone aren't judged. Without that, a three-line change gets blocked demanding a suite rewrite — or the implementer tries to fix the old tests and scope creep eats the run. The standard applies going forward; old debt gets paid when you actually touch it. The verdict is a consolidated comment citing path:line plus structured output. And CLEAN means "ready for a human to review" , not "approved". The reviewer never formally approves. It can't. Task ──► /run ──► Step 0: shape it inline if it's vague ▼ Step 1 load config + open run log RUN ID Step 2 read the task per task source Step 3 scope: which repos? filter over repos Step 4 plan.md: sub-tasks + Blocked by ▼ Step 5 dependency waves sub-tasks in parallel : 5a classifier ──► tier → model sonnet|opus 5b worktree-create.sh branch off base branch 5c implementer tier's model ─ TDD + Tidy First ▼ opens PR 5d reviewer ──► CLEAN | NEEDS FIXES path:line 5e fix loop ≤ max fix cycles CLEAN ──────────────► ready for human review cap reached ────────► ready-for-human escalate 5f worktree-cleanup.sh branch and PR untouched ▼ Step 6 run-log summary + notify + STOP The human reviews the PRs and merges. Sub-tasks don't run in plan order — a wave is everything currently unblocked, and a wave runs in parallel, each sub-task in its own worktree. Because nothing auto-merges, there's no conflict worker and none is needed: two branches touching the same file only collide at merge time, and the human picks the order. Two config fields stay deliberately orthogonal here: task source is where a task is read from none , github , gitlab , linear , jira , while each repo's own host is where its PR gets opened . So a single run can read from Linear and open PRs on GitHub and GitLab at the same time. The invariants don't live only in prompts. .claude/settings.json denies them at the tool level: gh pr merge ← never merge gh pr review ← it drags --approve along git merge ← never merge locally git push --force ← never rewrite pushed history A denied command is a deliberate boundary, not an obstacle to route around. An agent that hits one escalates the sub-task as ready-for-human and the run continues. Worth knowing: an agent team costs roughly 4–6× a single Claude Code session . Every run writes a summary with that reminder plus PR, cycle, and escalation counts. claude plugin marketplace add moruno21/agents-concerto claude plugin install agents-concerto@moruno-plugins /agents-concerto:setup /agents-concerto:run <task description Most of the value isn't in the agent that writes code — it's in the boundaries around it . The worktree. The reviewer with no write access. The cycle cap. The deny rules. And with tests, the boundary isn't a permission, it's an entry point . An agent told "write tests" writes tests coupled to what it just wrote, because that's what's in front of it. An agent told "exercise this through its public interface and assert what a user observes" can't. The fix wasn't banning mocks — it was moving where you stand to look. The agents play. The human holds the baton.