orchestraguard

# orchestraguard

**Agent orchestration never drifts.**

Describe a task. A fleet of agents builds it. They come back with work that is
finished, tested and documented — and that agrees with itself, because none of
them was allowed to contradict a decision another had already made.

Parallel agents don't scale past the human in the middle. You run five to go
faster, four of them are right, the product is broken, and the only thing that
catches it is you — reading everything, holding the whole picture,
re-explaining choices that were already settled.

That isn't a prompting problem. Your agents have **memory** and they have
**verification**, and neither answers the question that actually breaks a
parallel run:

> Did these two agents just settle the same question differently?

orchestraguard answers it by comparison, never by a model, and refuses the
second answer at the moment it is written.

[![A real Claude Code session: a refunds feature is split across four workers, two of them settle the error format differently, and the second is refused with the decision already in force, who made it and why.](assets/brag.gif)](https://github.com/harsh-chandak/orchestraguard/blob/main/assets/brag.gif)

<sub>Recorded, not drawn. `brag/record.mjs` runs the real CLI and captures its
output verbatim; `brag/video.html` only renders what was captured.</sub>

## What a decision is

This is the part that gets undersold. A "decision" is not a variable name. It
is **any question two agents could answer differently and both be reasonable** —
and the cost is never the question itself, it's that nothing goes red.

| Kind | Real examples |
| --- | --- |
| `convention` | money is integer minor units, never a float · timestamps are UTC ISO-8601 strings · pagination is cursor-based · every non-2xx body is `{"error":"<message>"}` · retries are idempotent and capped at 3 · migrations ship in two reversible stages |
| `api-contract` | `POST /api/orders` returns 201, not 200 · tenant scoping lives in the path, not a header |
| `enum` | order status is `pending\|paid\|shipped` · roles are `owner\|admin\|member` · webhook events are a closed set |
| `schema` | `id` is a uuid and not null · `amount_cents` is an integer · soft deletes use `deleted_at`, not a boolean |
| `naming` | the identifier is `user_id` · the destination field is `url`, not `target` |

Four agents implementing four reasonable answers to "what does an error body
look like" produce four green test suites and one broken product. That is the
whole category, and it is much wider than route paths.

## The failure it stops

A refunds feature, split across a backend worker and a client worker. The
backend settles the error shape. The client, working in parallel and with no
visibility into the backend's files, reaches a different answer:

```
$ orchestraguard decide --unit client --kind convention \
    --subject "error response body shape" \
    --value 'every non-2xx body is {"code":"<slug>","detail":"<message>"}' --as client

refused this contradicts a decision already in force.
  d-003  api (lead): error response body shape = every non-2xx body is {"error":"<message>"}
  because: the client shows it to a person
  yours:   every non-2xx body is {"code":"<slug>","detail":"<message>"}

  Adopt the existing value, or supersede it deliberately:
    --supersedes d-003 --layer pm      (an override, recorded as one)
    --force                            (record the disagreement for `check` to surface)
```

<sub>Verbatim from the recording above.</sub>

The agent is stopped at the moment it tries to disagree, and told what is in
force, who decided it, why, and the two legitimate ways out. Not at
integration. Not by you.

## Three ways to run it

**As a skill, which is how most people will use it.** Describe the task; the
agent runs the whole loop — authors the contract, binds it, briefs each
worker, fans out, gates every decision, runs the acceptance checks, writes the
design doc.

```
/orchestraguard:orchestraguard add refunds across the API, the client and the schema
/orchestraguard:orchestraguard migrate us off the legacy auth tables, five workers
/orchestraguard:orchestraguard rename the tenant concept to workspace everywhere
```

Nothing about the task has to be small, and nothing has to be a route.

**As an MCP server**, so an agent already mid-task can reach the gate without
being handed a workflow. Twelve tools: `write_contract`, `bind_contract`,
`brief_unit`, `fleet_plan`, `run_acceptance`, `generate_docs`, `cost_report`,
plus `record_decision`, `binding_decisions`, `open_conflicts`,
`record_attempt`, `status`.

**As a CLI**, for humans and for CI. `orchestraguard check` exits non-zero
when anything contradicts, which is a one-line pipeline step.

## Why this isn't another memory tool

| Tool | Answers | Doesn't answer |
| --- | --- | --- |
| Handoff / memory tools | "what did the last agent know?" | "do these two agree?" |
| Orchestrator verification | "did this worker do its task?" | "do these two agree?" |
| Edit-conflict detection | "did two agents touch one file?" | "do these two agree?" |

And the obvious way to answer it — store decisions as prose, ask a model whether
two of them conflict — is slow, costs a call per check, and is wrong often
enough that people stop trusting it. A coordination layer nobody trusts is
worse than none, because it adds latency and false alarms to a workflow that
had neither.

**orchestraguard decides agreement by comparison, never by a model.** Decisions are
typed and narrow, so a contradiction is a comparison: same subject, different
value. No API call exists anywhere in the decision path — there's a test that
fails if any file in that path can reach outside the process, and a second one
that fails if any file in the package, anywhere, calls a model.

## The loop

The gate above is one organ. v0.2 is the body around it: you describe a task,
and the fleet that builds it is bound to one set of decisions from before the
first line of code.

```
  describe a task
        |
   [1]  CONTRACT     the agent authors JSON to a published schema;
        |            the package validates it and stores it
        v
   [2]  BIND         the contract's decisions enter the log at PM layer,
        |            binding before any code exists
        v
   [3]  BRIEF        one brief per unit: its slice, the decisions it must
        |            honour, what it may not decide, how it will be judged
        v
   [4]  FAN OUT      the host spawns one worker per unit, each getting a
        |            brief and nothing else
        v
   [5]  GATE         a worker that tries to decide something contradictory
        |            is refused, told what is in force and who may override
        v
   [6]  ACCEPT       every acceptance criterion carries a command; the run
        |            is not done until all of them exit 0
        v
   [7]  DOCS         the design doc is generated from the decision log —
        |            what was decided, by whom, and why
        v
   [8]  COST         what the fan-out sent, in bytes
```

```bash
orchestraguard spec --schema              # the contract shape, as JSON Schema
orchestraguard spec --from contract.json  # validate and store it
orchestraguard bind   --contract add-refunds
orchestraguard fleet  --contract add-refunds            # every brief, as JSON
orchestraguard brief  --contract add-refunds api        # one worker's brief
orchestraguard accept --contract add-refunds            # run every check
orchestraguard docs   --contract add-refunds
orchestraguard cost   --contract add-refunds
```

Every loop command takes `--contract`. The MCP server exposes the same set as
`write_contract`, `bind_contract`, `brief_unit`, `fleet_plan`, `run_acceptance`,
`generate_docs` and `cost_report`.

## The contract

One JSON document. The agent writes it; the package decides whether it holds.

`openSubjects` is the part people skip and shouldn't. Naming a thing before
anyone decides it is what stops two workers inventing two different names for
it — see **Honest limits** for the run where that went wrong.

```jsonc
{
  "id": "add-refunds",
  "goal": "one sentence a reviewer can judge the result against",
  "scope": { "in": ["..."], "out": ["..."] },
  "decisions": [                      // binding from t=0, at PM layer
    { "kind": "api-contract", "subject": "refund endpoint",
      "value": { "method": "POST", "path": "/api/refunds", "status": 201 },
      "rationale": "why this and not the alternative" }
  ],
  "openSubjects": [                   // known to need deciding, not yet decided
    { "kind": "convention", "subject": "error response body shape",
      "note": "the server and the client both serialise this" }
  ],
  "units": [                          // one worker each
    { "id": "api", "goal": "...", "files": ["src/api/**"],
      "mayDecide": ["convention"],    // everything else must be requested
      "dependsOn": [] }
  ],
  "acceptance": [
    { "id": "a1", "statement": "refunds endpoint returns 201",
      "check": "npm test -- refunds", "unit": "api" }
  ]
}
```

Validation is not a formality. A contract is rejected when two of its own
decisions contradict each other, when a unit depends on one that doesn't exist,
when the dependency graph has a cycle, when a unit has no acceptance criterion,
or when a criterion has no command. All of it in one pass, because fixing one
error per round trip is the expensive way to find four:

```
$ orchestraguard spec --from contract.json

orchestraguard: contract is not valid:
  - unit "api" depends on "ui", which is not a unit in this contract
  - acceptance[a1] has no check — a criterion without a command is a wish
```

`bind` then puts the contract's decisions into the log at PM layer. If one of
them contradicts a decision already live, binding **refuses** — a new contract
quietly overriding decisions in force is the exact failure this tool exists to
prevent.

## What o