Spec-Driven Development

The idea

Your coordination logic should survive a model swap. If switching from GPT-4 to Claude breaks your multi-agent system, the problem isn’t the model — it’s that coordination is tangled with implementation.

ACP separates what agents do (protocol) from how they do it (implementation). Protocols are declarative YAML. The runtime executes them. Change the model, keep the protocol.

YAML vs Python

Here’s the same coordination pattern — a code review workflow — expressed two ways.

Imperative (Python orchestrator)

class CodeReviewOrchestrator:
    def __init__(self):
        self.reviewer = Agent("reviewer", model="claude-sonnet")
        self.author = Agent("author", model="claude-haiku")
        self.state = {}

    async def run(self):
        while self.state.get("phase") != "done":
            if self.state.get("phase") == "review":
                result = await self.reviewer.run(
                    f"Review this code: {self.state['code']}"
                )
                self.state["feedback"] = result
                self.state["phase"] = "revision"
            elif self.state.get("phase") == "revision":
                result = await self.author.run(
                    f"Address feedback: {self.state['feedback']}"
                )
                self.state["code"] = result
                self.state["phase"] = "review"
                # How do we know when to stop?
                # How do we handle reviewer disagreement?
                # How do we enforce budget limits?
                # How do we handle agent failure?

Declarative (ACP protocol)

acp: "1.0"
name: code-review
title: Collaborative Code Review

roles:
  reviewer:
    description: Review code changes for correctness and style
    count: "2+"
    model_hint: sonnet
  author:
    description: Address review feedback
    model_hint: haiku

phases:
  review:
    description: Reviewers examine changes
    exit_condition:
      state_key: phase
      equals: revision
  revision:
    description: Author addresses feedback
    exit_condition:
      state_key: phase
      equals: done

governance:
  budget:
    max_cost: 5.00
    warn_at: 0.8
  heartbeat:
    dead_after_ms: 60000
    auto_release_claims: true

50 lines of YAML replaces hundreds of lines of imperative code. And the YAML answers all the questions the Python left open — budget limits, failure handling, governance, phase transitions.

Benefits of protocols

Portable across providers

The same protocol coordinates Claude, GPT, Gemini, Llama, and local Ollama models. Mix providers freely within a single run — Opus for architecture decisions, Haiku for CSS, Cerebras for fast iteration.

Versionable in git

Protocols are files. Put them in source control. Diff them. Review changes. Roll back. The entire coordination pattern is visible and auditable.

Shareable on the marketplace

Good protocols are reusable. A code review protocol works for any project. A social deduction game protocol works with any theme. Share protocols on the marketplace, install them with wgl marketplace install.

Validatable before running

wgl protocol validate my-spec.acp.yaml

Catch structural errors, missing roles, invalid governance rules — before spending a single token. The ACP parser validates the full schema.

Self-documenting

The protocol IS the documentation. Roles describe what each agent does. Phases describe the workflow. Rules describe the constraints. New team members read the YAML and understand the system.

38 example protocols

The ACP spec includes a library of protocols covering:

• Development: Code review, pair programming, refactoring
• Research: Literature review, hypothesis testing, data analysis
• Games: Chess, werewolf, debate, negotiation
• Operations: Incident response, deployment, monitoring
• Creative: Story writing, brainstorming, design review
• Education: Tutoring, exam generation, curriculum design

Browse them on the ACP examples page or install directly:

wgl marketplace search "code review"
wgl marketplace install code-review