Overview

HAAO (Hybrid AI-Agile Orchestrator) is a governance layer for AI software agents. You chat with an orchestrator agent about what you want built; it files the work as backlog proposals; a cloud Tech Lead decomposes each into atomic, testable tickets; local (or cloud) models execute; two human gates keep you in control of scope and what ships; and accepted work goes out as a pull request. Every step is visible — a live board, an activity stream, cost and throughput insights, and a notifications inbox.

The core thesis: frontier models are best used sparingly for high-leverage reasoning (decomposition, audit), not for grinding out every line. Local open-weight coders are now good enough to do the bulk of execution cheaply and privately. HAAO is the orchestration layer that routes the right work to the right model and inserts human judgment where it matters.

Quickstart

Fastest path — Docker:

cp .env.example .env       # set CLAUDE_API_KEY / model keys as needed
docker compose up --build

Open http://localhost:3001 (API at :8000/health). On macOS/Windows the backend reaches local LM Studio via host.docker.internal. Adding encrypted cloud keys in Settings needs HAAO_SECRET_KEY in .env (generate with openssl rand -base64 32); set HAAO_API_TOKEN to require a bearer token on the API.

Or run locally for development:

python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn orchestrator.main:app --reload
pytest

Benchmark — real repos

The early pilot ran on a curated sandbox — an honest signal, not a benchmark. R-102 is the real-repo version: plain-language requirements decomposed, executed by a local model (qwen3-coder-next), and graded on two pinned open-source projects (pallets/click 8.1.8, jazzband/tablib 3.8.0). 14 tasks × 2 trials = 28 runs — small files edited whole-file, large files via patch-mode (search/replace).

Every run is gated to keep the benchmark honest: probe expectations are verified against the library's real behaviour (reference patch red→green plus semantic review), the unpatched baseline must fail first, the repo's existing tests must stay green, each ticket is graded in its own git worktree, and infra errors are excluded from the capability denominator.

The runs that didn't finish locally split into two modes: reasoning misses (the model edits the right place but gets a subtle behaviour wrong) and a small mechanical tail in the edit step — occasionally a whole-file rewrite truncates, or a patch's search/replace block is malformed. Patch mode brought large files into scope (e.g. a 1,000-line module now edits one-shot) and the mechanical tail is what's being hardened next.

Update (2026-06-29): a smaller 3-repo spot check (click, tablib, marshmallow) reproduced one-shot local completion end-to-end with the same harness; broader, higher-trial runs are ongoing before we update the headline figures.

Roles

HAAO maps Scrum roles onto a hybrid AI workforce. The non-obvious choice is that the human is the Product Owner, not the Scrum Master — process mechanics get automated, product judgment stays human.

Atomic tickets

The Atomic Ticket is the handover format between the cloud Tech Lead and a local coder — defined by a JSON Schema. Three properties make it work:

Machine-readable — the local model parses it without guessing intent. Self-contained — relevant code is injected directly into the ticket rather than referenced by filename, so a small-active-param model doesn't have to find or remember anything. Verifiable Definition of Done — the DoD is a set of test commands with expected outcomes, so "done" is a test result, not an opinion.

Hybrid cost routing

Work stays local and free by default. A retry budget governs self-correction; only when local attempts are exhausted does a ticket escalate to the cloud. Cheap machine checks gate the expensive cloud audit, so you never pay a frontier model to read every diff. The metric that matters is cost per accepted ticket.

Architecture

        You (Product Owner)
   write prompt │           │ approve / accept
                ▼           ▲
        ┌────────────────────────────────┐
        │   Orchestrator (Scrum Master)  │  state machine · routing · retry
        └───┬───────────┬───────────┬────┘
            │ decompose │ dispatch  │ run tests
            │ + audit   │           │
        ┌───▼────┐  ┌───▼────────┐  ┌▼───────────────┐
        │ Claude │  │ Local LLMs │  │ pytest/npm test│
        │ (Tech  │  │ (LM Studio)│  │ (validation)   │
        │  Lead) │  │  dev team  │  └────────────────┘
        └────────┘  └────────────┘

Stack: Python · FastAPI · SQLite · React · Tailwind · LM Studio (local inference) · Claude API (cloud).

The loop

From a conversation to a pull request:

1. Chat — tell the agent what you want; it restates and files the work as backlog proposals. The Tech Lead decomposes each into atomic tickets; you approve (Gate 1).
2. Execute — the orchestrator dispatches each ticket to its assigned model (local or cloud), which writes code and runs the ticket's tests in a sandbox.
3. Self-correct — on failure, the worker retries within budget; if exhausted, it escalates to the Tech Lead.
4. Audit — the Tech Lead checks the diff against the DoD (automatic).
5. Accept & ship — the PO accepts or rejects (Gate 2); on accept, HAAO opens a branch + PR to GitHub/GitLab.

Throughout, everything is observable: Activity streams every run event (model calls, diffs, retries, escalations, cost); Insights tracks throughput, cycle time, escalation rate, local-vs-cloud mix and cost; Inbox collects what needs you across projects.

Deployment

HAAO is split-plane by design: the control plane (board, chat, insights, coordination) can be hosted, while execution and your keys stay on your side. That means your code is never run on someone else's infrastructure and the vendor never holds your raw repos.

• Free / self-host — run the whole thing yourself, MIT licensed, bring your own keys. Code and inference stay on your machine.
• Team (hosted) — a hosted control plane plus a lightweight client-side runner that executes with your compute and keys.
• Enterprise — fully self-hosted / air-gapped image with SSO, role-based access, policy guardrails (what agents may touch, egress controls), and bring-your-own model/cloud. Execution stays local; the cloud Tech Lead only sees ticket scope and diffs for audit. Contact us to scope a deployment.

Security throughout: sandboxed (network-disabled) test execution, AES-GCM-encrypted secrets at rest, prompt-injection-aware context handling, secret redaction in logs, and optional API token auth.