Blog/Specs

Specs

One approved spec, many agents

Koushik RamaniCo-founder, EnWithAI

3 min read

Talk to us

One change, three repositories

  1. Spec v2Locked by the engineering lead
  2. api-gatewayStory 1: per-tenant limits
  3. billingStory 2: usage counted per tenant
  4. admin-consoleStory 3: limits shown and editable

Every agent builds to the same version. A change to the spec is a new version, not a chat message.

One agent on one repository is easy to manage. Three agents on three repositories, building one feature, is where things drift. Each agent fills the gaps differently, and the pieces stop fitting.

The short answer

When several AI agents work on one change, give them one approved, versioned spec. Split it into stories per repository with their own acceptance criteria, have every agent read the spec rather than each other’s prompts, and route changes through a new spec version.

How drift happens

Give three agents three prompts written from one conversation, and you get three interpretations. The gateway agent decides limits are per minute; the billing agent counts per hour; the admin console shows per day. Every piece passes its own tests. Together they are wrong.

Agents do not drift from each other. They drift from a spec that was never written down.

One spec, versioned

The fix is boring and it works: one spec, locked by a named person, with a version. Every agent reads the same version. Shared decisions (the limit unit, the error code, the field names) live in the spec once, not in three prompts.

Split by repository, not by agent

  1. Write the spec once

    Requirements and shared decisions for the whole change.

  2. Split into stories per repository

    Each story has its own acceptance criteria and a clear finish line in one repository.

  3. Name the contracts between them

    The API shape, events and fields that cross repositories, written into the spec so every story builds to the same contract.

  4. Check each story against its criteria

    Then check the contracts across stories before anything merges.

Changes go through the spec

Halfway through, someone realizes limits should be per hour after all. The tempting fix is to tell the one agent that is building the gateway. Do not. Change the spec, lock a new version, and let every story that depends on it pick up the change. Otherwise the spec stops being the truth, and you are back to three interpretations.

What the reviewer sees

With one spec, review gets easier, not harder. Each pull request links to the story and the spec version it was built to. A reviewer checks the diff against the acceptance criteria, not against their memory of a meeting.

In CrewPE

One locked spec drives every story, with acceptance criteria for each repository it touches. Your coding agents build to it, and CrewPE checks each story against every criterion.

See how CrewPE works

Questions teams ask

How do you coordinate multiple AI coding agents on one feature?
Give them one approved, versioned spec. Split it into stories per repository with their own acceptance criteria, write the contracts between repositories into the spec, and route any change through a new spec version.
Why do multiple agents produce inconsistent code?
Each agent fills unstated details differently, such as units, names or error handling. When those decisions live only in separate prompts, the pieces stop fitting even if each passes its own tests.
What if the spec changes mid-build?
Change the spec and lock a new version rather than correcting one agent directly. Every story built to the earlier version is then updated against the same new truth.

Koushik Ramani

Co-founder of EnWithAI, working on how AI-built changes get approved, governed and accepted.

Keep reading

Bring one real change. See how it would be specified, built and proven.

Start with a 45-minute call about your system: how it is built, how work is agreed today, and a sensible first step.