Getting Started

Clone the repository and install dependencies:

git clone https://github.com/AOS-Framework/aos-framework.git
cd aos-framework
bun install

Set your API key:

export ANTHROPIC_API_KEY="sk-ant-..."
# or
export OPENAI_API_KEY="sk-..."

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

aos run strategic-council --brief briefs/sample-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 saved to:

output/memos/2026-03-25-sample-brief-abc123/memo.md

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

aos run cto-execution --brief briefs/feature-brief.md

The CTO Execution profile uses a structured 8-step workflow:

1. Requirements Analysis — Advocate and Strategist extract requirements from your brief
2. Architecture Design — Architect produces an architecture decision record
3. Review Gate — You approve or send back with feedback
4. Task Breakdown — Operator breaks the plan into concrete engineering tasks
5. Risk Assessment — Sentinel reviews for security, reliability, and maintainability
6. Stress Test — Provocateur challenges the timeline, finds gaps
7. Final Assembly — CTO Orchestrator synthesizes everything
8. Output — Complete execution package saved to disk

Output is saved to:

output/executions/2026-03-25-feature-brief-abc123/
  executive-summary.md
  architecture-decision-record.md
  task-breakdown.md
  risk-assessment.md
  implementation-checklist.md

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