Agents-Concerto: Orchestrating Claude Code for PRs

Blindly signing off on agent-generated PRs is a recipe for technical debt. I noticed a recurring pattern in our workflow: an agent would dump a massive set of changes, validate them itself, congratulate itself, and leave the human reviewer guessing why specific lines were touched. Worse, the "green" tests were often useless—mocking the very code they were supposed to test or asserting on private fields.

To fix this, I built agents-concerto. It isn't a standalone app, but an orchestration layer for Claude Code. Think of it as a conductor and a set of players; the conductor manages the flow but never touches an instrument, ensuring the final merge always stays in human hands.

The system relies on a strict set of constraints to maintain quality:

• Two-party authority: No agent that writes code is allowed to approve or merge it.
• Worktree isolation: Every agent operates in its own git worktree to avoid messing up the local checkout.
• No auto-merge: The process stops exactly at "PR ready."
• Model by complexity: The model isn't tied to a role; it's picked based on the complexity tier of the task.

The Logic of Acceptance Criteria

The biggest shift in my AI workflow was treating acceptance criteria as test specs rather than human notes. Using a Given-When-Then format (Given X, when Y, then Z), the system ensures that every requirement has an observable result.

This criterion travels through the pipeline: it's defined during the shaping phase, converted into a test during implementation, and verified by the reviewer. Because the "then" must be observable, it prevents the AI from cheating by asserting on internal state.

The Agent Pipeline

I've divided the labor across four distinct roles:

• Orchestrator (Opus): Handles decomposition and dispatching. It is strictly forbidden from writing application code.
• Classifier (Sonnet): A read-only agent that assigns a complexity tier (complex vs standard) to determine which model handles the task.
• Implementer: This agent uses a "Tidy First" approach—it submits a structural refactor commit first, then a separate behavioral commit. It never mixes the two.
• Reviewer (Opus): Limited to Read, Grep, Glob, and Bash. It has no Write or Edit permissions, meaning it can describe a fix but cannot apply it.

By forcing "outside-in" testing—asserting only on outputs, UI, or API responses—we've eliminated the "green tests, zero confidence" problem.

# Example of the lightweight orchestration structure
# CLAUDE.md (Instruction set)
# agents/ (Markdown definitions for the 4 roles)
# scripts/ (Bash wrappers for execution)

For those looking for a real-world LLM agent deployment, the full logic is available here:
https://github.com/moruno21/agents-concerto