ATOBAR pixel-art wolf emblem in a navy crest ring, wearing a pink shirt and royal cobalt tie
[AS-BUILT: Hub-and-Spoke Factory] [VISION: Per-Invoking-User BYOK & Equity Ledger]

Agentic Teams On BYOK And Repos (ATOBAR)

ATOBAR (Agentic Teams On BYOK And Repos) is a Hub-and-Spoke software factory built around GitHub. Co-founders and collaborators bring their own KMS-encrypted LLM API keys (BYOK), route costs and models per repository and per role today ([AS-BUILT]) with per-invoking-user billing and profile default keys next ([VISION]), coordinate strictly through GitHub Jumbo Issues and Pull Requests, and let isolated AWS EC2 Spot roles (PLANNER → DEVELOPER → EVALUATOR → ARBITRATOR) write, visually verify in X11, and squash-merge code with a one-commit exit.

Fully Forkable for Any Use-Case: ATOBAR is 100% open-source (MIT) and domain-neutral. You can fork the monorepo, connect your own GitHub App, database, and cloud account, and adapt the roles or verification checks for any workflow: building web and mobile apps, automating internal company tools, running security or compliance fixes, maintaining data pipelines, or keeping documentation in sync with code.

BYOK Cost Routing Per-Repo & Role Live · Per-User [VISION]
GitHub Workspace Jumbo Issues & PRs (No Custom IDE)
Unattended QA Web X11 Live · Android KVM [VISION]
1-Commit Exit Delete 2 YAML Files → Zero Lock-In
PROOF 1
2 YAML Files in Client Repo: Client repositories hold only .github/workflows/flow-trigger.yml and flow-metrics.yml. Zero Atobar runtime SDKs. Delete those two files and your repository is 100% standalone.
[AS-BUILT]
PROOF 2
0 LLM Calls in State & Merge Gates: step() (machine.py), assess_issue_sufficiency() (sufficiency.py), and arbitrate() (arbitration.py) are 100% deterministic Python. CI enforces tests/test_boundaries.py blocking LLM SDK imports in contracts and flow-engine.
[AS-BUILT]
PROOF 3
Fresh Spot VM for Visual QA: WARM_HANDOVER_FORBIDDEN_ROLES = {"evaluator", "arbitrator"} guarantees EVALUATOR never reuses a DEVELOPER VM, holds a contents: read token, and verifies live X11 windows via xwininfo and ps.
[AS-BUILT]
Step Through the 6 User Journeys (Slow-Mo) ↓ Open Standalone code-slowmo Explainer Inspect Package & DB Boundaries
$curl -fsSL https://raw.githubusercontent.com/atobar-flow/atobar-flow/main/scripts/onboard.sh | bash

Target Personas (P1 & P2), Forkability & Explicit Anti-Goals

ATOBAR (Agentic Teams On BYOK And Repos) is built around two core personas that absorb planning, swarm wrangling, unattended QA, and contribution tracking directly inside GitHub. Because ATOBAR itself is the deterministic ledger, every turn's token usage, cost guardrail, and merged pull request is recorded automatically.

Two Target Personas (P1 & P2)

[AS-BUILT] [VISION]
ID Persona How They Work User Journeys & Capabilities (Including Wrangler & QA Workflows)
P1 Co-Founder / Founding Early Architect Builds iteratively on GitHub, minimizes operational and tool surfaces, and proportionally calculates contributions with co-founders. Journeys J1, J2, J5, J6: 5-minute repo onboarding with only 2 workflow YAML files and a 1-commit exit (J1, J6); KMS AES-GCM BYOK key routing per repo/role ([AS-BUILT]) and per invoking user ([VISION]); iterative architecture via GitHub Jumbo Issues, Spec-Sufficiency Gate, and living Mermaid SotaWiki (J2); deterministic arbitrate() merge gates and proportional Fiscal Share + Architectural Yield contribution ledger (J5).
P2 Software Builder (Long-Running Agentic Jobs) Dispatches, steers, and verifies long-running autonomous coding and visual QA jobs across web, API, and mobile repositories. Journeys J2, J3, J4, J5: Warm EC2 Spot VM git worktree handovers across PLANNER → DEVELOPER and rework rounds (J3, J38); live pinned-comment telemetry and plain-English @atobar-flow-agent PR course-corrections (J49); hard-isolated EVALUATOR runs on fresh Spot VMs (WARM_HANDOVER_FORBIDDEN_ROLES, contents: read token) with Stage 1 file:#L citations and Stage 2 live X11 window/process screenshot proof ([AS-BUILT]) or headless Android KVM emulators ([VISION], J4).

Forkable for Any Use-Case (Plain-English Design)

[MIT OPEN-SOURCE · DOMAIN-NEUTRAL]
SELF-HOST OR FORK

Run Your Own Factory Instance

Nothing in ATOBAR is tied to a single hosted domain. Fork atobar-flow, point environment variables at your own GitHub App, Supabase project, and AWS account, and run your own private or public software factory.

ADAPT THE ROLES

Swap Prompts, Tools, or Sandboxes

Use the 4-role loop out of the box for web and backend repos, or customize role prompts and Spot VM images for mobile apps, data pipelines, security patching, test generation, or documentation maintenance.

BUILT-IN LEDGER

ATOBAR Is the Ledger Itself

You do not need a separate billing team or spreadsheet. Every turn automatically logs tokens, cost, and merged PRs in loop_rounds and arbitration_decisions, enforcing budget caps in pure Python.

Explicit Anti-Goals: What ATOBAR Refuses to Build

[ARCHITECTURAL INVARIANTS]
ANTI-GOAL 1

No Custom IDE or Proprietary Chat App

All human planning and code review happen in GitHub Issues and Pull Requests. Collaborators plan in Jumbo Issues, inspect visual screenshots in PRs, and steer active runs with @atobar-flow-agent comments.

ANTI-GOAL 2

No Atobar SDK Inside Client Repos

Client repositories never import atobar-flow packages at runtime. Only two standard GitHub Actions YAML files live in .github/workflows/, guaranteeing a 1-commit exit at any time.

ANTI-GOAL 3

No LLM in Merge or Budget Decisions

State machine transitions (step()), circuit breakers, Spec-Sufficiency checks, and metric gate merges (arbitrate()) are 100% deterministic Python.

End-to-End User Journeys (J1–J6) in Slow Motion

Each journey below is powered by the repository's code-slowmo engine (.pi/skills/code-slowmo). Press Next >, Play ▶, or click any sequence arrow to step through the runtime in slow motion and watch the screen preview and database state update live.

JOURNEY J1 P1 Co-Founder / Founding Architect FR-1 · FR-5 · FR-6
[AS-BUILT: Per-Repo / Per-Role KMS BYOK] [VISION: Per-Invoking-User Billing & Profile Keys]

J1: Repo Onboarding & Shared / Per-User BYOK Routing (~5 Minutes)

A collaborator signs into the Control Panel via GitHub OAuth, installs the atobar-flow-agent GitHub App on the client repository, and runs onboard.sh (J1.1). API keys (gemini, claude, openai, deepseek, grok) are envelope-encrypted with AWS KMS (AES-GCM) using (tenant_id, provider) AAD in control-panel/src/control_panel/llm_keys.py and routed per repository and per role in tenant_role_llm (J1.2, [AS-BUILT]).

The onboarder Spot role generates the initial SotaWiki (including a validated Mermaid architecture diagram, J50) and opens a PR adding .github/workflows/flow-trigger.yml and flow-metrics.yml (J1.4, [AS-BUILT]). On the Vision roadmap (J1.3, J53), keys transition to per-invoking-user repository keys (tenant_id, user_login, provider) and profile-level Default Keys (user_llm_keys, GET /profile), while EC2 Spot provisioning is gated by a per-user feature flag (platform_users.ec2_enabled, defaulting to false with a thin dim-grey ✕-closable top ribbon listing the admin user(s) to ping, toggled by a Superuser in GET /admin/users) and a 2-item trigger hold comment (<!-- atobar:byok-hold:{user_login} -->).

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J1
JOURNEY J2 P1 Founding Architect & P2 Software Builder FR-1 · FR-3 · FR-7
[AS-BUILT: Spec-Sufficiency Gate J38] [VISION: Multi-Repo Venture Links]

J2: Jumbo Issue Planning & Deterministic Spec-Sufficiency Gate

Collaborators configure repository Target Metrics, Guardrails, and Goal Budgets (tenant_goals) and open a GitHub Issue (J2.1). When labeled flow:feature / flow:plan or mentioned via @atobar-flow-agent, flow-engine runs resolve_delegated_issue_number() and the deterministic Spec-Sufficiency Gate (assess_issue_sufficiency() in flow-engine/src/flow_engine/conductor/sufficiency.py, J38) with zero LLM calls (J2.2).

Well-specified issues with concrete file targets and acceptance criteria fast-track straight to DEVELOPER; broad issues route to PLANNER, which reads the repository's SotaWiki, posts a flow-plan Task Ledger comment, and pauses at flow:needs-approval. On the Vision roadmap (J2.3), a parent Venture Jumbo Issue links child spoke issues across api, web, and mobile client repos (venture_jumbo_links).

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J2
JOURNEY J3 P2 Software Builder (Long-Running Jobs) FR-2 · NFR-1
[AS-BUILT: Warm Worktrees J38 & Hard QA Boundary J43]

J3: Long-Running Execution, Warm Handover & Plain-English PR Steering

On approval (flow:approved or @atobar-flow-agent approve), CONDUCTOR launches an EC2 Spot VM. PLANNER → DEVELOPER transitions and rework turns reuse the warm Spot VM inside isolated git worktree directories (prepare_role_worktree() in flow-agent/src/flow_agent/runtime/sandbox.py) via POST /v1/runs/{run_id}/turn-complete (J3.1).

Verifying roles (EVALUATOR, ARBITRATOR) never accept a warm handover from DEVELOPER: WARM_HANDOVER_FORBIDDEN_ROLES = {"evaluator", "arbitrator"} (contracts/src/atobar_contracts/conductor_io.py, J43) terminates the warm developer VM and forces a fresh Spot VM launch for QA (J3.2). Throughout execution, live tool calls, heartbeats, and spend stream into the pinned GitHub telemetry comment, and collaborators steer active or escalated PRs using @atobar-flow-agent comments (J3.3, J49).

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J3
JOURNEY J4 P2 Software Builder (Unattended QA) FR-4 · NFR-1
[AS-BUILT: Two-Stage Web X11 QA J39/J49] [VISION: Android Studio KVM Profile]

J4: Unattended Visual & Mobile QA on a Fresh Spot VM

EVALUATOR boots cold on a dedicated Spot VM with a read-only (contents: read) GitHub token, checks out the exact head_sha, waits for external GitHub Actions CI, and runs Stage 1 static/contract checks requiring exact file:<path>#L<start>-L<end> citations (J4.1, J39).

In Stage 2 (J4.2, [AS-BUILT]), EVALUATOR starts the app inside X11 (Xvfb :99 + Fluxbox + Playwright on web-x11-arm64), records active windows (xwininfo) and OS processes (ps), uploads encrypted screenshots tagged with sha256 and data_mode (live | synthetic | hybrid, J49), and posts flow-verdict + flow/eval. On the Vision roadmap (J4.3), setting machine_image_profile: android-studio-kvm-x86 boots a KVM Spot AMI with headless Android Emulator and ADB.

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J4
JOURNEY J5 P1 Founding Architect & P2 Software Builder FR-3 · FR-5 · FR-6 · NFR-3
[AS-BUILT: Pure arbitrate(), SotaWiki & Turn Ledger] [VISION: Price Catalog & Co-Founder Equity Ledger]

J5: Deterministic Metric Gate, Built-In Ledger & Living SotaWiki

Once CI is green, flow-verdict is approved, and flow-ack has zero open disputes on head_sha, the serverless ARBITRATOR verifies flow-metrics.json provenance from GitHub Actions and runs pure Python arbitrate(policy, observations) (contracts/src/atobar_contracts/arbitration.py, zero LLM) (J5.1). Based on arbitration.mode (shadow → recommend → auto_merge), the PR is recorded, recommended, or squash-merged, and repository_wikis queues a coalesced Mermaid SotaWiki refresh after N merges (J5.2, J50).

ATOBAR itself is the ledger: every turn automatically records token usage and spend in loop_rounds.cost_usd and tenant_goals.spent_usd ([AS-BUILT]). On the Vision roadmap (J5.3, [VISION]), server-side price snapshots and per-user lineage attribute Fiscal Share (key_contributor_login / invoking_user) and Architectural Yield (architect_github_login authoring Jumbo Issues and PR course-corrections).

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J5
Interactive Co-Founder BYOK Equity Simulator (50% Fiscal Share + 50% Architectural Yield) [VISION: Equity Attribution]
@cofounder-1 (P1 Founding Architect) Fiscal 26.7% · Arch 25.0% → Combined Share 25.8%
@builder-2 (P2 Software Builder) Fiscal 40.0% · Arch 50.0% → Combined Share 45.0%
@cofounder-3 (P1 Co-Founder) Fiscal 33.3% · Arch 25.0% → Combined Share 29.2%
TOTAL BYOK USAGE $150
SHIPPED FEATURES 12 Merged PRs
WEIGHTING RULE 50% Fiscal / 50% Arch
JOURNEY J6 P1 Co-Founder / Founding Architect FR-3 · NFR-4
[AS-BUILT: Goal Loop, Circuit Breakers & 1-Commit Exit] [VISION: Contribution Ledger Export]

J6: Goal Completion, Circuit Breakers & Zero-Lock-In Sunset

After each merge, goal_step() (flow-engine/src/flow_engine/conductor/goal.py) re-evaluates default-branch metrics against tenant_goals. When all target metrics pass, the goal moves to met and regression guardrails protect future PRs (J6.1). Hard deterministic circuit breakers (max_pr_cost_usd default $25, max_goal_cost_usd default $100, max_review_rounds default 4, max_repeat_finding, max_pr_wall_clock_minutes) prevent runaway loops.

Collaborators can export the Contribution Ledger ([VISION]) and hand off or sunset any client repository by deleting .github/workflows/flow-trigger.yml and flow-metrics.yml in a single commit (J6.2, [AS-BUILT]).

CODE-SLOWMO INTERACTIVE WALKTHROUGH · JOURNEY J6

Functional (FR-1–FR-7) & Non-Functional Requirements (NFR-1–NFR-4)

Complete requirement specification grounded against the atobar-flow codebase, badged strictly as [AS-BUILT] (live on main) or [VISION] (roadmap & open Jumbo specs).

Functional Requirements (FR-1–FR-7)

[AS-BUILT] [VISION]
ID Requirement Status Implementation Summary & Codebase Anchor
FR-1 Bare-Bones GitHub Hub & Spoke Ingress [AS-BUILT] Client repos hold only flow-trigger.yml and flow-metrics.yml. All webhooks and OIDC/Bearer events enter via POST /v1/events and POST /v1/metrics (control-panel/src/control_panel/app.py).
FR-2 4-Role Loop & Warm Developer Handover [AS-BUILT] PLANNER, DEVELOPER, EVALUATOR, and ARBITRATOR coordinate through GitHub comments. DEVELOPER reuses a warm Spot VM across turns (J38); EVALUATOR always runs on a fresh Spot VM (J43).
FR-3 Deterministic Conductor & Circuit Breakers [AS-BUILT] Pure step() state machine (contracts/src/atobar_contracts/machine.py) enforces max_review_rounds, max_repeat_finding, max_pr_cost_usd, max_pr_wall_clock_minutes, and tenant_goals budgets without calling an LLM.
FR-4 Unattended Visual QA & Spot Image Profiles [AS-BUILT] [VISION] Stage 1 static file:#L check + Stage 2 Web X11 screenshot capture with xwininfo/ps proof (J39, J49, [AS-BUILT]). [VISION] adds android-studio-kvm-x86 and fullstack-compose image profiles.
FR-5 KMS BYOK Vault, Granular Key Routing & Built-In Ledger [AS-BUILT] [VISION] KMS AES-GCM keys with (tenant_id, provider) AAD, per-repo/per-role model routing (tenant_role_llm), single-use /llm-key claim, and turn spend in loop_rounds.cost_usd ([AS-BUILT]). [VISION] adds per-invoking-user billing, profile default keys, and Superuser EC2 provisioning gate (platform_users.ec2_enabled, dim-grey top ribbon & /admin/users in J53), verifiable price snapshots, and Fiscal + Architectural equity attribution.
FR-6 Living Architecture Wiki (SotaWiki) [AS-BUILT] onboarder synthesizes structured repo knowledge with a validated Mermaid diagram (validate_mermaid_diagram in contracts/src/atobar_contracts/wiki.py) and auto-refreshes it after N default-branch merges (J50).
FR-7 Multi-Repo Venture Grouping [VISION] Group multiple microservice tenants under one venture_id and track cross-repo Jumbo Issue dependencies (venture_jumbo_links).

Non-Functional Requirements (NFR-1–NFR-4)

[AS-BUILT · CI ENFORCED]
ID Requirement Status Architectural Rule & Verification Guard
NFR-1 Zero-Trust Sandbox Isolation [AS-BUILT] Spot VMs hold zero database keys, authenticate via single-run FLOW_RUN_CREDENTIAL + X-Instance-ID, receive role-scoped GitHub tokens (contents: read for EVALUATOR), and wrap GitHub text in <untrusted_content> delimiters.
NFR-2 Single-Writer Table Ownership [AS-BUILT] control-panel writes only CP_OWNED_TABLES; flow-engine writes only FE_OWNED_TABLES and FE_OWNED_RPCS (enforced by tests/test_table_ownership.py).
NFR-3 Deterministic Control & Arbitration [AS-BUILT] atobar_contracts and flow_engine never import LLM SDKs (enforced at CI time by tests/test_boundaries.py).
NFR-4 1-Commit Client Repo Exit [AS-BUILT] Deleting .github/workflows/flow-trigger.yml and flow-metrics.yml completely disconnects a client repo with zero broken imports or runtime dependencies.

Monorepo Package & Single-Writer Database Boundaries

All factory logic lives in five Python packages inside atobar-flow, with strict package import and database write boundaries enforced in CI by tests/test_boundaries.py and tests/test_table_ownership.py.

1. Five-Package Monorepo Responsibilities (tests/test_boundaries.py)

[AS-BUILT]
Package Monorepo Path Core Responsibilities & Key Modules LLM Imports Allowed?
atobar_contracts contracts/src/atobar_contracts/ Schemas (manifest.py, goal.py, envelopes.py, wiki.py), pure step() state machine (machine.py), pure arbitrate() gate (arbitration.py), WARM_HANDOVER_FORBIDDEN_ROLES (conductor_io.py), Spot launcher (github_rest.py). NO (CI Blocked)
flow_engine flow-engine/src/flow_engine/ Internal FastAPI service (api.py), single-writer SupabaseStore (store.py), deterministic Spec-Sufficiency Gate (conductor/sufficiency.py), outer goal loop (conductor/goal.py), Spot GC reaper (conductor/gc.py). NO (CI Blocked)
control_panel control-panel/src/control_panel/ Public FastAPI gateway & Web UI (app.py, web.py), AWS KMS AES-GCM BYOK vault (llm_keys.py), GitHub OIDC & tenant token auth (oidc.py, tokens.py), encrypted screenshot storage. NO (CI Blocked)
flow_agent flow-agent/src/flow_agent/ Isolated EC2 Spot sandbox runner (main.py), agent roles (planner, developer, evaluator, arbitrator, onboarder, metric_compiler), nanobot loop (agents/), stdio MCP tool server (tools_mcp/). YES (Spot Sandbox Only)
atobar_ops atobar-ops/src/atobar_ops/ Operator & harness CLI (verify, ship, review, watch, rerun, ssm, db, cp, ci, jumbo, labels, sessions). NO (CI Blocked)

2. Single-Writer Database Ownership Matrix (tests/test_table_ownership.py)

[AS-BUILT: 15 Tables + 8 RPCs] [VISION: Per-User Keys & Venture Tables]

control-panel (CP_OWNED_TABLES)

4 As-Built Tables · KMS & Auth
Table Single-Writer Responsibility
tenant_tokens SHA-256 hashed atb_... client spoke bearer tokens.
tenant_llm_keys KMS AES-GCM encrypted BYOK keys with (tenant_id, provider) AAD ([AS-BUILT]) → (tenant_id, user_login, provider) per-collaborator keys ([VISION]).
tenant_role_llm Per-role (provider, model, reasoning_effort) bindings across Planner, Developer, Evaluator, Onboarder.
security_audit_log Append-only security audit log for BYOK key, token, and admin mutations.
user_llm_keys [VISION] Profile-level encrypted BYOK keys and single Default Profile Key (is_default = true) across repositories.

flow-engine (FE_OWNED_TABLES & FE_OWNED_RPCS)

11 As-Built Tables · 8 Atomic RPCs
Tables / RPCs Single-Writer Responsibility
tenants, tenants_manifest_history Tenant lifecycle state, manifest JSON, and immutable manifest audit history.
metric_definitions, metric_definitions_history, metric_observations Compiled metric specs, history, and append-only CI metric observations.
run_credentials, sessions, session_events, run_events Single-run token hashes, instance_id binding, llm_key_claimed, Spot heartbeats, and live telemetry stream.
loop_rounds, conductor_events, arbitration_decisions Per-turn token/cost ledger, envelope JSON state, webhook deduplication, and pure arbitrate() decisions.
repository_wikis, tenant_goals SotaWiki Mermaid content + coalesced refresh queue (J50), and outer-loop target budgets (goal_step()).
FE_OWNED_RPCS (8 Postgres Functions) approve_metric, flow_claim_wiki_refresh, flow_complete_wiki_refresh_run, flow_record_default_branch_merge_for_wiki, flow_update_wiki_policy, flow_upsert_wiki_content, goal_record_spend, goal_record_merge.

Onboard a Client Repository in 5 Minutes (J1.1–J1.4)

Run onboard.sh inside any git repository clone where you have GitHub admin permissions. The script verifies prerequisites (git, gh, curl), guides you through installing the atobar-flow-agent GitHub App, saves your repository's ATOBAR_TENANT_TOKEN secret, and opens the onboarding pull request.

$curl -fsSL https://raw.githubusercontent.com/atobar-flow/atobar-flow/main/scripts/onboard.sh | bash
  1. STEP J1.1: GITHUB APP & TOKEN [AS-BUILT]

    Install the atobar-flow-agent GitHub App on your client repo and save ATOBAR_TENANT_TOKEN via gh secret set.

  2. STEP J1.2: KMS BYOK & PER-ROLE ROUTING [AS-BUILT]

    Save your provider API keys (claude, gemini, openai, deepseek, grok) in the KMS AES-GCM vault and bind models per role in tenant_role_llm.

  3. STEP J1.3: PER-INVOKING-USER & PROFILE DEFAULT KEYS [VISION]

    Collaborators attach personal repo keys or a Default Profile Key (/profile) so every run bills the invoking GitHub user.

  4. STEP J1.4: SOTAWIKI & 2-FILE PR [AS-BUILT]

    The onboarder Spot role synthesizes your initial Mermaid SotaWiki and opens a PR with flow-trigger.yml and flow-metrics.yml.