Agent Operating Substrate (AOS)

The Universal AI Behavior Firewall & Vendor-Agnostic Control Plane across Gemini, Claude, Codex, Copilot, Cursor, and Windsurf.

[!NOTE] Autonomous Agent Project Notice: The Agent Operating Substrate is designed, implemented, and maintained autonomously by AI agents (AOS Agent). The agents identify codebase improvements, conduct failure autopsies, synthesize invariant rules, and maintain repository health under human supervisory oversight. All post-initial release contributions follow a strict Pull Request / Merge Request model to support parallel multi-agent and human collaboration.

The Universal AI Behavior Firewall & Memory Layer

Enterprises and developers cannot afford AI vendor lock-in or model-specific behavioral drift. Whether your engineers prompt Google Gemini 1.5 Pro, Anthropic Claude 3.5 Sonnet, OpenAI GPT-4o / Codex, Amazon Q Developer, or run local DeepSeek and Llama models, each model interprets prompts differently, hallucinates distinct anti-patterns, and loses context once the session ends.

AOS eliminates vendor lock-in by decoupling repository guardrails from the model provider.

No matter which AI assistant your team selects today or migrates to tomorrow, AOS guarantees the exact same repository invariants, institutional memory, and deterministic pre-commit enforcement.

Three Structural Roadblocks AOS Solves

1. Day-One Amnesia: Every agent session starts from a blank slate. When an agent violates an architectural invariant, introduces memory bugs, or breaks an unspoken convention, an engineer manually intervenes. Once that context window closes, the lesson evaporates. The next agent invocation repeats the identical mistake.
2. The Human Air-Traffic Controller Bottleneck: Multi-agent development remains strictly hub-and-spoke. Engineers spend hours manually shuttling diffs, error traces, and prompts between worker, critique, and test agents.
3. Broken Commits and Silent Regressions: AI agents hallucinate deprecated APIs, alter adjacent imports, and introduce diff bloat that slips past human reviewers and pollutes Git history.

AOS turns your repository into a self-defending, self-improving substrate. It provides an Autonomous Behavior Firewall that deterministically blocks invalid agent commits, and Permanent Memory that records failures as machine-enforced invariants compiled directly into every agent harness.

Before AOS vs After AOS

Supported AI Ecosystems & Models

AOS is engineered for complete AI vendor neutrality. By decoupling repository invariants and verification from any specific model provider, AOS guarantees consistent guardrails across every tool in your stack:

Architecture

AOS operates across three integrated planes: prompt projection, live agent context tools, and deterministic git enforcement.

┌─────────────────────────────────────────────────────────────────────────────┐
│                          AGENT HARNESS INTERACTION                          │
│                                                                             │
│  Gemini / Antigravity     Claude Code     Codex / ChatGPT    GitHub Copilot │
│  Cursor (.cursorrules)    Windsurf IDE    Aider / Cline      Amazon Q       │
└───────────────────────────────────────▲─────────────────────────────────────┘
                                        │ (aos sync: prompt projection)
┌───────────────────────────────────────┴─────────────────────────────────────┐
│                           AGENT OPERATING SUBSTRATE                         │
│                                                                             │
│   ┌───────────────────────────┐         ┌───────────────────────────────┐   │
│   │    Active Invariants      │         │   Asynchronous Blackboard     │   │
│   │ (.agents/substrate/active)│         │ (.agents/blackboard/events)   │   │
│   └─────────────┬─────────────┘         └───────────────┬───────────────┘   │
│                 │                                       │                   │
│   ┌─────────────▼─────────────┐         ┌───────────────▼───────────────┐   │
│   │   Runtime MCP Server      │         │    Autonomous Peer Mesh       │   │
│   │ (aos_rules_check, etc.)   │         │ (worker, auditor, critic)     │   │
│   └───────────────────────────┘         └───────────────────────────────┘   │
└───────────────────────────────────────┬─────────────────────────────────────┘
                                        │
┌───────────────────────────────────────▼─────────────────────────────────────┐
│                         DETERMINISTIC GIT BARRIER                           │
│                                                                             │
│   Developer / Agent Commit ───> .git/hooks/pre-commit (aos hook run)        │
│                                  ├── Invariant Rules Evaluation             │
│                                  ├── Contiguous Diff Limits (<30 lines)     │
│                                  └── Punctuation & Style Enforcement        │
│                                  └── PASSED: Commit Recorded in Git Graph   │
│                                  └── FAILED: Deterministic Exit Code 1      │
└─────────────────────────────────────────────────────────────────────────────┘

Core Architecture Components

1. Prompt Sync: aos sync compiles all active machine-readable invariants from .agents/substrate/active/ into your team's existing agent configuration files (.cursorrules, .cursor/rules/aos-invariants.mdc, .windsurfrules, .github/copilot-instructions.md, and CLAUDE.md). Rules stay bounded within deterministic HTML comment tags without overwriting custom prompt instructions.
2. Model Context Protocol (MCP) Server: aos mcp provides a native stdio protocol server. Any MCP-compatible tool (Cursor, Claude Desktop, Antigravity, Gemini Code Assist, Cline) can dynamically query active rules, inspect file blast radius, post intents, and record failure autopsies.
3. Git Pre-Commit Barrier: aos hook run acts as the repo bouncer. Every staged diff is evaluated against active invariants before a commit is created. Violations halt execution immediately with exact file and line references.
4. Stigmergic Blackboard: Agents communicate asynchronously by reading and appending events in .agents/blackboard/events.jsonl. When a worker announces an intent, an auditor injects invariants, and an adversarial critic generates edge-case tests, entirely without human intervention.
5. Execution Autopsy Engine: aos exec -- <command> intercepts build or test failures, diagnoses root causes, and inscribes candidate rules under .agents/substrate/candidate/ for peer review.

flowchart LR
    subgraph S1["1. Knowledge Substrate"]
        R["Active Rules<br/>(.agents/substrate/active/)"]
        B["Blackboard Events<br/>(.agents/blackboard/events.jsonl)"]
    end

    subgraph S2["2. Developer & Agent Tooling"]
        P["Prompt Sync<br/>(Cursor, Copilot, Claude)"]
        M["MCP Server<br/>(Live Invariant Query Tools)"]
    end

    subgraph S3["3. Enforcement & Verification"]
        H["Git Pre-Commit Hook<br/>(Deterministic Barrier)"]
        CI["Continuous Integration<br/>(aos ci check)"]
    end

    R -->|aos sync| P
    R -->|stdio protocol| M
    P --> H
    M --> H
    H -->|Passed| CI
    CI -->|Failure Autopsy| R

60-Second Quickstart

Get your repository running with autonomous agent enforcement in four simple commands:

1. Install AOS

AOS is built with pure Python and zero external runtime services:

pip install -e .

2. Initialize the Substrate

Create the local substrate structure under .agents/:

aos init

Output:

Created config: .agents/config.yaml
Created event stream: .agents/blackboard/events.jsonl
Substrate initialized under .agents/

3. Install a Curated Rule Pack

Bootstrap production-grade guardrails for security or architecture:

aos pack install security-owasp

Output:

Installed 3 rule(s) into active substrate:
- .agents/substrate/active/sec-sql-injection-001.yaml
- .agents/substrate/active/sec-secret-leak-002.yaml
- .agents/substrate/active/sec-ssrf-003.yaml

4. Sync Agent Prompts

Compile all active invariants into Cursor, Windsurf, Copilot, and Claude Code:

aos sync

Output:

Synced 5 agent harness configuration(s):
- cursor: .cursorrules
- cursor_mdc: .cursor/rules/aos-invariants.mdc
- windsurf: .windsurfrules
- copilot: .github/copilot-instructions.md
- claude: CLAUDE.md

5. Install the Universal Git Pre-Commit Hook

Enforce active invariants on every commit automatically:

aos hook install

6. Verify Files Instantly

Check any file or staged diff against active invariants:

aos rules check src/

3 Real-World Proofs

AOS is running right now in production repositories. Here are three machine-enforced proofs executing directly inside this codebase:

Proof 1: SIMD 32-Byte Alignment Crash Prevention

• The Incident: High-throughput vector geometry kernels (AVX2/AVX-512) crash with general protection faults when fed unaligned memory pointers. Standard LLMs frequently generate naive allocations, causing runtime panics.
• The Active Invariant (perf-simd-012.yaml): Requires 32-byte alignment on all buffers in src/geometry/simd/**.
• The Interception: When an agent attempts to edit vector code:

  aos rules check src/geometry/simd/kernel.cpp
  

  AOS flags the rule, binding the agent to emit alignas(32) buffers before code reaches the compiler.

Proof 2: Surgical Diff & Punctuation Pre-Commit Bouncer

• The Incident: Coding agents frequently over-refactor code, reformatting adjacent imports, changing comments, or injecting stylistic typography like em dashes that violate conventions.
• The Active Invariants (aos-diff-002 and aos-punct-001): Mandate surgical changes (<30 contiguous lines without justification) and zero em dashes across all prose and code.
• The Interception: When an agent stages a file containing forbidden punctuation:

  git commit -m "docs: update notes"
  

  The pre-commit hook runs aos hook run and blocks the commit deterministically:

  [AOS Hook] Evaluating staged files against active substrate invariants...
  - [aos-punct-001] Violation: Forbidden em dash detected. (reject_diff)
  Commit blocked by AOS invariant enforcer.
  

  The agent reads the rejection message, corrects the punctuation, and re-commits without human intervention.

Proof 3: Unprompted Peer Mesh Convergence

• The Incident: Coordinating worker, auditor, and adversarial critic agents traditionally requires manual human dispatching or expensive cloud orchestrators.
• The Stigmergic Mesh: Agents collaborate asynchronously through .agents/blackboard/events.jsonl:

  aos mesh simulate --desc "Optimize vector boundary conditions" --files src/geometry/simd/kernel.cpp
  

  Output:

  Peer Mesh Simulation: Intent 'intent-e41c30' - Status: CONVERGED
  Emitted 5 event(s) to blackboard:
  - [INTENT_ANNOUNCEMENT] From: worker-agent
  - [INVARIANT_INJECTION] From: auditor-agent
  - [ADVERSARIAL_CHALLENGE] From: adversarial-critic-agent
  - [PEER_CRITIQUE] From: auditor-agent
  - [PEER_CONVERGENCE] From: consensus-orchestrator
  

  The engineering team is alerted only when consensus is reached.

Enterprise & Commercial Readiness

As enterprises deploy hundreds of AI coding agents across engineering teams, they face Distributed Agent Amnesia: team A discovers and patches a critical security flaw, but team B and team C repeat the exact same vulnerability next week. AOS provides an enterprise-grade control plane designed for commercial reliability and governance.

1. SOC2 & AI Audit Compliance

Every autonomous agent modification, intent declaration, invariant check, and consensus decision is permanently recorded in a tamper-proof, append-only event stream (.agents/blackboard/events.jsonl).

• Immutable Audit Trail: Track which model proposed a diff, which invariant validated or rejected it, and which human or peer agent approved the change.
• Cryptographic & Git Provenance: Invariants record originating incident IDs, git commit hashes, author agent signatures, and verification timestamps.
• Compliance Ready: Satisfies SOC2 Type II, ISO 27001, and enterprise AI safety audits without transmitting proprietary code to third-party clouds.

2. Eliminating AI Regression Costs

AI code generation velocity is meaningless if senior engineers spend hours diagnosing hallucinations and fixing broken builds.

• Halting Hallucinations at the Source: Intercepts hallucinated third-party dependencies, invalid imports, and deprecated API calls before code reaches pull request review.
• Preventing Secret Leaks: Built-in OWASP rules (sec-secret-leak-002) deterministically block API tokens, credentials, and private keys before they enter git history.
• Pre-Commit Enforcement: The universal git pre-commit hook runs in milliseconds locally, cutting CI re-run costs and preventing broken commits from reaching master branches.

3. Centralized Fleet Governance Across 100+ Repositories (aos fleet)

Connect isolated repositories into an institutional knowledge network:

• Global Policy Propagation: Platform teams broadcast promoted invariants into a shared fleet mesh (.agents/fleet.db) with aos fleet publish.
• Zero Policy Drift: Microservices and product repositories ingest organizational security and architectural rules with aos fleet sync.
• Sovereign & Local-First: 100% offline-capable, backed by local SQLite and Git. Zero source code or proprietary schemas are transmitted to external SaaS platforms.

Without Fleet Synchronization (Isolated & Vulnerable):
Team A fixes critical bug ──> Knowledge stays trapped in Team A repo
Team B AI writes same bug  ──> Re-enters codebase, redundant debugging
Team C AI writes same bug  ──> Reaches production incident

With AOS Enterprise Fleet Synchronization:
Team A (Origin) ──> Inscribes Rule ──> aos fleet publish
                                            │
                                            ▼
                              ┌───────────────────────────┐
                              │   Enterprise Fleet Mesh   │
                              │     (.agents/fleet.db)    │
                              └─────────────┬─────────────┘
                                            │
                                            ▼ (aos fleet sync)
               ┌────────────────────────────┴────────────────────────────┐
               ▼                                                         ▼
    Team B (Active Guardrail)                                 Team C (Active Guardrail)
    Agent blocked from mistake                                Agent blocked from mistake

Key Enterprise Capabilities

• Zero Policy Drift: Platform and security teams publish global compliance rules (sec-sql-injection-001, sec-secret-leak-002) into the fleet mesh with aos fleet publish. Downstream repositories synchronize them instantly with aos fleet sync.
• Auditable Provenance: Every invariant records full compliance metadata: originating incident ID, git commit hash, author agent identity, and verification timestamps.
• SOC2 & ISO 27001 Ready: Invariants serve as living, version-controlled evidence that security constraints are deterministically enforced on every local commit and in CI.
• Air-Gapped & Local-First: Backed by local SQLite and Git. Zero source code or proprietary schemas are transmitted to external third-party cloud services.

CLI Command Reference

Documentation

• Overview & Core Thesis: Motivation, failure modes, and stigmergic solution.
• Getting Started Guide: Step-by-step setup, harness sync, and MCP configuration.
• AI Vendor Abstraction: Decoupling repository invariants and control planes from LLM model providers.
• IDE & Tool Integration: Setup Cursor, Claude Code, Copilot, Windsurf, and Git pre-commit hooks.
• Control Plane Web Dashboard: Visual tour of real-time guardrail controls, diff testing, and incident autopsies.
• Curated Rule Packs: Catalog of security, clean architecture, and SIMD performance invariant packs.
• Architecture & Theoretical Foundations: The three inscription loops, blackboard event bus, and mathematical model.
• CLI Reference: Complete reference of all subcommands, arguments, and environment variables.
• Enterprise Fleet Synchronization: Cross-repository governance and fleet mesh management.
• System Specification: Formal YAML schemas and protocol specifications.
• Agent Guidelines: Strict operating rules for autonomous agents working in this repository.

License

Distributed under the standard MIT License.