Skip to main content

AAOS — Architecture Overview

AAOS — Architecture Overview

AAOS = ALAI Agent Operating System — Redesigned 2026-04-03 to collapse 10 virtual companies into 4 functional groups with pure orchestration.

The Transformation: 10 → 4

Before AAOS, we had 10 virtual companies with overlapping responsibilities. Now we have 4 functional groups with clear boundaries.

graph LR subgraph "Before (10 companies)" CC[CodeCraft] VZ[Vizu] DV[Datavera] FV[Finverge] SB[Skybound] PV[Proveo] SC[Securion] FF[FlowForge] AF[AgentForge] RS[Resolver] LX[Lexicon] end subgraph "After (4 groups)" BUILD["BUILD
(CodeCraft)"] REVIEW["REVIEW
(Proveo)"] OPS["OPS
(FlowForge)"] PLATFORM["PLATFORM
(AgentForge)"] end CC --> BUILD VZ --> BUILD DV --> BUILD FV --> BUILD SB --> BUILD PV --> REVIEW SC --> REVIEW FF --> OPS AF --> PLATFORM RS --> PLATFORM LX --> PLATFORM

Group Definitions

Group Identity Absorbs Role
BUILD CodeCraft CodeCraft, Vizu, Datavera, Finverge, Skybound Writes code — backend, frontend, data, fintech, product
REVIEW Proveo Proveo, Securion READ-ONLY validation, QA, security audit
OPS FlowForge FlowForge Infrastructure only — Docker, CI/CD, IaC, monitoring
PLATFORM AgentForge AgentForge, Resolver, Lexicon AI system maintenance — RAG, HiveMind, docs

Key principle: John is a pure orchestrator. He delegates ALL execution to specialist agents.

CodeCraft Agent Board — 8 Specialists

Within the BUILD group, CodeCraft operates an agent board with 8 specialist agents:

graph TD A["Alem (CEO)"] --> J["John — Orchestrator"] J --> AL["architect-lead
(Opus)
decomposition, blueprint"] AL --> KA["kotlin-architect
(Sonnet)
Kotlin/Ktor backend"] AL --> NS["nextjs-specialist
(Sonnet)
Next.js 15 App Router"] AL --> DB["database-specialist
(Sonnet)
PostgreSQL, Flyway"] AL --> AA["api-architect
(Sonnet)
OpenAPI, REST, SDK"] J --> SR["security-reviewer
(Sonnet)
READ-ONLY security audit"] J --> QA["qa-specialist
(Sonnet)
Functional tests, DOM"] J --> DO["devops-specialist
(Haiku)
Docker, CI/CD, deploy"] J --> PL["PLATFORM group
(Sonnet)
RAG, HiveMind, docs"]
Agent Domain Model Notes
architect-lead Decomposition, blueprint, delegation Opus 4.6 Can spawn other specialists
kotlin-architect Kotlin/Ktor backend, services, DB Sonnet ALAI unified stack
nextjs-specialist Next.js 15 App Router, RSC, Tailwind Sonnet Frontend + React
database-specialist PostgreSQL, Flyway, migrations Sonnet Data layer
api-architect OpenAPI, REST, SDK design Sonnet Integrations
security-reviewer OWASP, auth, secrets Sonnet READ-ONLY audit
qa-specialist Functional tests, DOM visibility Sonnet Quality gates
devops-specialist Docker, CI/CD, Nginx, deploy Haiku Infrastructure

Model budget:

  • Opus 4.6 — Architect agents (system design, tech spec) + team leads
  • Sonnet — All builders and validators (default for implementation)
  • Haiku — Trivial tasks (file search, lint, git, DevOps)

John's Role: Pure Orchestrator

What John DOES:

  1. Create MC task (node ~/system/tools/mc.js add)
  2. Write GOTCHA gate (/tmp/gotcha-task-{id}.md)
  3. Run RAG query before any action
  4. Select correct specialist agent from routing.json
  5. Read short agent reports (max 8 lines)
  6. Run qa-19.js check after build
  7. Report to Alem in max 5 sentences

What John NEVER does:

  • Write code in ~/projects/**
  • Edit files in ~/projects/**
  • Run tests directly
  • Fix bugs manually
  • Deploy any service
  • Call Bash commands on project source files

John is blocked from touching project source code. All implementation goes through specialist agents.

Pipeline Flow

SPEC → REVIEW → BUILD → REVIEW → OPS → PLATFORM
       spec check  specialist  qa-specialist   devops   learn
                               + security-reviewer
  1. SPEC — John creates MC task + GOTCHA gate
  2. REVIEW (H/CRIT only) — Spec validation before build
  3. BUILD — Specialist agent writes code
  4. REVIEW — qa-specialist + security-reviewer audit
  5. OPS — devops-specialist deploys
  6. PLATFORM — agentforge extracts learnings to HiveMind

Review cycles: Max 2 cycles before escalating to John → Alem

Task Metrics

Every MC task tracks metrics in mission-control.db table task_metrics:

Field Type Purpose
task_id INTEGER FK to tasks.id
qa_score INTEGER /19 from qa-19.js
token_cost_usd REAL Anthropic API cost
duration_seconds INTEGER Wall time
cache_hits INTEGER RAG cache hits
agents_spawned INTEGER How many subagents
rework_count INTEGER How many review cycles

Purpose: Learning agent uses this to flag inefficient patterns.

Learning Agent

Tool: ~/system/tools/learning-agent.js

Runs: Nightly at 02:00 via cron

Capabilities:

  1. Analyzes task metrics (high token cost, low QA score, many rework cycles)
  2. Flags patterns to HiveMind
  3. Updates flywheel cache with common queries
  4. Suggests agent improvements
  5. Generates weekly summary report

Goal: System learns from its own execution.

RAG Flywheel

Question → SHA256 cache (flywheel.db) → HiveMind FTS/Qdrant → Ollama (ANVIL/FORGE) → Anthropic (fallback) → save answer back to cache

Databases:

  • flywheel.db (36MB) — SHA256-keyed cache, fast hits
  • knowledge.db (187MB) — Full RAG knowledge base
  • hivemind.db (14K+ entries) — Structured intel + memory

Models:

  • ANVIL — localhost:11434 (Mac Studio M3 Ultra, 96GB)
  • FORGE — 10.0.0.2:11434 (deepseek-r1:70b, qwen3:32b)
  • Anthropic — Cloud fallback if local fails

Cache hit rate: 61% (as of 2026-02-24)

Config Files

File Purpose
~/system/agents/definitions/john-orchestrator.yaml John's identity + agent board definitions
~/system/config/john-routing.json Domain → Group → Agent routing map
~/system/rules/company-first-protocol.md Routing rules + group boundaries

Source of truth hierarchy:

  1. john-orchestrator.yaml (agent board + groups)
  2. john-routing.json (routing map)
  3. company-first-protocol.md (protocol docs)

If drift is detected, john-orchestrator.yaml wins. Update routing → docs.

Archive

10-company model: Preserved in ~/system/archive/companies-pre-collapse-2026-04-03/

Why collapsed: Too much routing complexity, unclear boundaries, token waste.

When collapsed: 2026-04-03 (AAOS v1.0)

No comments to display

Back to top