Your First Deliberation

From map to territory

You have the four primitives and a diagram of how they snap together. Diagrams are cheap. Let's make them do something.

Under twenty minutes, from an empty directory to a council arguing about a real decision and handing you a memo. I am going to leave the ugly parts in. A transcript that installs clean on the first try and never prompts you for anything is a transcript someone edited. When your run does not look like that, that is the tool working as shipped, not a mistake you made.

Install and init

The harness is open source and the package is on npm. Install it into a project.

# project-local install
bun add aos-harness

Now the part the quickstart glosses over. aos run does not talk to a model directly. It drives a vendor CLI you already have installed and authenticated (Claude Code, Codex, Gemini, or Pi), and since 0.6.0 those adapters ship as separate packages. So you install the one that matches your CLI.

# adapters are separate. pick the one for the CLI you already use.
bun add -g @aos-harness/claude-code-adapter

Then wire it up.

aos init --adapter claude-code
# run bare `aos init` and it lists the adapters and asks. --apply installs
# any that are missing. aos run needs the vendor CLI already authenticated,
# so sort that out now, not three minutes into a paid run.

Before you spend anything, look at the plan. A sample brief ships in the repo, and --dry-run prints it without a paid run.

aos run strategic-council --dry-run --brief core/briefs/sample-product-decision/brief.md

That is the whole setup. No orchestration code, no glue. The next command is the one that costs money, so it deserves a real question.

The question

We are carrying one decision through this whole arc, and it is one every senior engineer has argued about in a review channel:

Should our deployment agent be allowed to merge and ship to production on its own, and for which change-classes?

That is the input. Not a prompt, a brief. strategic-council reads a specific shape (an H1 # Brief: title, then ## Situation, ## Stakes, ## Constraints, ## Key Question), and the shape is not decoration. It is the profile telling you what evidence it expects before it will argue. aos brief validate will reject a brief that skips the title or a required section. Here is how to write one. Ours, on the platform-engineering domain:

# Brief: Autonomous Deploy Authority

## Situation
Our deployment agent can already open, review, and merge its own pull
requests. Today a human approves every merge to production, and that
approval queue is now the slowest part of the pipeline.

## Stakes
Faster delivery against the risk of an autonomous bad ship reaching users.

## Constraints
Every production change must be reversible or gated behind a kill-switch.
We track the DORA metrics: deployment_frequency, lead_time_for_changes,
change_failure_rate, MTTR. Any autonomous authority can be revoked in one
command.

## Key Question
Should our deployment agent be allowed to merge and ship to production on
its own, and for which change-classes?

Run strategic-council

One command.

aos run strategic-council --domain platform-engineering --brief briefs/auto-deploy.md

I ran exactly that. Four rounds, about sixteen minutes, one Arbiter driving eleven specialists. The memo further down is what actually came back, trimmed for length. The profile budgets itself: 2 to 10 minutes, $1 to $10, 2 to 8 rounds, all declared in the profile, not my stopwatch. You are about to read its fingerprints in the output, so here is what runs the room.

The Arbiter runs the room. It is the neutral orchestrator: it frames the question, sets the specialists arguing, synthesizes what they produce, and writes the memo. (How synthesis actually works is Issue 5. For now, "synthesizes" is a plain verb, the thing the Arbiter does before it hands you the file.)

It does not ask the specialists to get along. strategic-council ships Tension Pairs: agents deliberately set in opposition so the disagreement is structural, not accidental. For our decision the live pair is Catalyst against Sentinel, which is velocity against blast radius. Catalyst carries a speed-and-monetization bias and treats the approval queue as pure cost. Sentinel carries a durability-and-trust bias and treats every autonomous ship as a loaded gun. And the Provocateur speaks last, on purpose, to stress-test whatever agreement the others drifted toward before it can harden into consensus.

Read the memo

When the run finishes, the memo is on disk in the session's output directory, at .aos/sessions/{date}-{profile}-{session_id}/memo.md. This is the real memo from that run, trimmed. The sections are the profile's, in the profile's order.

# Decision Memo: Autonomous Deploy Authority
Session: 2026-07-01-strategic-council-mr1k0uaj

Verdict in one line: Yes, but not yet, and not the way the brief framed it.
Build an independent ground-truth verification floor first, then grant
autonomy to a carved-out class of reversible boolean config flags behind a
closed stopping rule, and keep schema and infra human-gated indefinitely.
The gating variable is not the agent's competence. It is whether damage stops
automatically, fast, without a human, measured on a signal that does not lie.

## 1. Ranked Recommendations (Top 3)
1. Build the ground-truth verification floor before any class flips. The
   Auditor brought the pivotal finding: the deploy tool reports "done" on a
   non-swap and hides its failure logs. So "instant-revoke exists" and "CFR
   is computable" are assumptions, not facts, and an auto-rollback wired to a
   lying "done" signal is worse than the human it replaces.
2. Grant the first autonomy to reversible boolean config flags, behind a
   closed stopping rule (a fixed set of requirements, and not one more).
   Config flags are the one class whose revert is native: you flip the value
   back at the flag service, independent of the deploy agent by construction.
3. Treat docs autonomy as a zero-blast-radius test rig for the rollback
   machinery, not the first value rung. Schema and infra changes are one-way
   doors: human-gated indefinitely.

## 2. Agent Stances (excerpt)
- Catalyst (velocity): the gate's latency cost is uniform, its safety value
  is not. Warned the safety-first reorder can become a new infinite gate that
  reinstates the overnight queue with a safety story attached.
- Sentinel (durability): blast radius is bounded by MTTR and reversibility,
  not agent competence. MTTR is time-to-detect plus time-to-revert, and we
  had been costing only the second term.
- Provocateur (speaks last): every guardrail proposed is recovery, not
  detection. They all fire after a human notices.

## 3. Dissent & Unresolved Tensions (excerpt)
§1 Feasibility is the central unresolved risk. The stopping rule is agreed,
but whether it is buildable in a quarter is unverified, because the
execution-owner perspectives are not part of a deliberation assembly.
Recorded, not resolved. Action item one.
§3 How adversarial the game-day proof must be. N green passes prove only the
happy path; only a forced-failure drill proves a kill-switch. A dial for real
traffic, left open on purpose.

## 6. Deliberation Summary (excerpt)
The pivotal moment was the Auditor's evidence that the kill-switch is
cooperative and the "done" signal lies. Seven agents reordered their positions
in a single round. Then Catalyst named the mirror-image trap, safety rigor
hardening into an unfundable infinite gate. Forced to a bounded stopping rule,
the Provocateur and Auditor cut their own escalations, and the room converged:
config flags are the one class whose revert is native, so migration-grade
rigor is a category error applied to a boolean flip.

Look at the dissent section. Documented dissent is the minority view preserved in the memo instead of being smoothed away by the synthesis. The feasibility gap did not resolve, so the Arbiter recorded it as unresolved and made it action item one rather than papering it with false consensus. It even names what it could not answer: whether the plan is buildable in a quarter is an execution question this deliberation profile is not staffed to decide. That honesty is why the output is usable.

Why the dissent is the proof

If the council had returned one confident paragraph, you would have no way to tell whether it reasoned or just pattern-matched a plausible answer. The dissent is the tell. The whole memo pivoted on the Auditor's finding that the deploy tool's "done" signal lies, and seven agents visibly reordered around it in one round. That is not what a single model does when you ask it to role-play a debate. The machinery wrote the change and the leftover disagreement down instead of hiding them. You could read the profile end to end and never find that argument in it. The file did not hold it. Running it did.

The answer was never in any single agent. The Auditor brought the evidence, the Catalyst and Sentinel tension forced the room to reckon with it instead of arguing past it, and the decision formed in the space between all of them. The Arbiter just wrote it down. That is the point of running one instead of reading about it. A good council disagrees on the record and hands you the receipt, dissent attributed and all.

You just watched strategic-council work. Next issue, the uncomfortable part. I run the same auto-deploy decision through a second profile, security-review, and prove that a profile was never really the file it looks like.