Getting Started

Install the CLI globally or into the current project:

# global
bun add -g aos-harness
# or
npm i -g aos-harness

# project-local
bun add aos-harness
# or
npm install aos-harness

AOS does not replace your AI CLI. It orchestrates on top of it.

Install the adapter package that matches the vendor CLI you already use:

# global
bun add -g @aos-harness/claude-code-adapter
bun add -g @aos-harness/codex-adapter
bun add -g @aos-harness/gemini-adapter
bun add -g @aos-harness/pi-adapter

# project-local
bun add @aos-harness/codex-adapter
# or
npm install @aos-harness/codex-adapter

The adapter is the runtime boundary. You can optionally add host-native install surfaces on top of it:

• Codex — install the local plugin bundle under plugins/aos-harness/
• Claude Code — install the project command pack from plugins/aos-harness/claude-code/
• Pi — use the @aos-harness/pi-adapter extension package directly

# Codex local plugin metadata
plugins/aos-harness/.codex-plugin/plugin.json

# Claude Code command-pack installer
bash plugins/aos-harness/claude-code/install.sh

Initialize AOS inside the project you want to work on:

# global install
cd your-project
aos init

# project-local install
bunx aos init
# or
npx aos init

The init flow scans environment readiness and writes:

.aos/config.yaml
.aos/memory.yaml
.aos/scan.json

Useful variants:

aos init --apply
aos init --non-interactive
aos init --non-interactive --adapter codex

Before you run a session, verify both config and discovered assets:

aos validate
aos list

The init flow checks vendor CLI readiness, adapter-package readiness, and writes a machine-readable report to .aos/scan.json.

Run the built-in Strategic Council with the sample brief:

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

This assembles 11 specialist agents — Catalyst, Sentinel, Architect, Provocateur, Navigator, Advocate, Pathfinder, Strategist, Operator, Steward, and Auditor — under a neutral Arbiter. The agents debate your brief from opposing perspectives. Tension pairs (Catalyst vs. Sentinel, Architect vs. Pathfinder) create productive conflict.

The Arbiter synthesizes the discussion into a structured memo with:

• Ranked recommendations
• Agent stances and dissent
• Trade-offs and risks
• Concrete next actions

Output is written under output/, and the transcript is appended under .aos/sessions/<session-id>/transcript.jsonl.

Execution profiles go beyond deliberation — they produce implementation-ready artifacts:

aos run cto-execution --brief core/briefs/sample-cto-execution/brief.md

The CTO Execution profile uses a structured 8-step workflow with review gates and artifact assembly:

1. Requirements Analysis — Advocate and Strategist extract requirements from your brief
2. Architecture Design — Architect produces an architecture decision record
3. Challenge and Review — operators and reviewers push back on weak spots
4. Phase Planning — Strategist and Operator sequence the work
5. Task Breakdown — Operator turns the plan into execution-ready tasks
6. Security Review — Sentinel checks for trust, abuse, and system risk
7. Stress Test — Provocateur challenges assumptions and the timeline
8. Final Assembly — the orchestrator produces the execution package

Output is rendered from the workflow result into the profile's configured output path template, typically under:

output/executions/<date>-<brief>-<session>/
  executive-summary.md
  architecture-decision-record.md
  task-breakdown.md
  risk-assessment.md
  implementation-checklist.md

All session types write a local transcript. When you provide a platform endpoint, sessions also stream transcript events live:

aos run strategic-council \
  --brief core/briefs/sample-product-decision/brief.md \
  --platform-url http://localhost:3001

This is useful for replay, observability, and downstream tooling:

aos replay .aos/sessions/<session-id>/transcript.jsonl

A brief is the input document that frames the problem for the agents. The required sections depend on the profile type.

Deliberation brief (for strategic-council):

## Situation
We are a B2B SaaS platform with 2,400 customers and $8M ARR.
Our largest competitor just raised $50M and announced a free tier.

## Stakes
If we respond poorly, we risk losing 15-20% of our SMB segment.
If we respond well, we can capture switchers from their disrupted user base.

## Constraints
- $200K budget for competitive response
- 3-person product team, no new hires until Q3
- Cannot break existing API contracts

## Key Question
Should we launch a free tier to match, or double down on our
premium positioning and invest in switching-cost features?

Execution brief (for cto-execution):

## Feature / Vision
Build a real-time collaborative editing system for our
document workspace product.

## Context
Current architecture is a monolithic Rails app with PostgreSQL.
Documents are stored as Markdown blobs. No WebSocket infrastructure exists.
Team has experience with Redis but not with CRDTs or OT.

## Constraints
- Ship MVP in 8 weeks with 2 backend + 1 frontend engineers
- Must support up to 50 concurrent editors per document
- Cannot migrate existing document storage format

## Success Criteria
- Users can see each other's cursors and edits in real time
- No data loss on concurrent edits
- Latency under 200ms for edit propagation
- Graceful degradation when a user loses connection