Aegis

Production-grade governance framework making AI coding agents trustworthy through observable, self-evolving constraints.

Aegis (formerly Soma) replaces static, unverified prompt rules (.cursorrules, CLAUDE.md) with a closed-loop governance engine: JIT context injection, deterministic AST verification, and Wilson-bounded rule evolution. Rules prove their value or decay to zero.

flowchart LR
    A["Agent Action"] --> B["1. JIT Rule Injection<br/><i>Relevant constraints & traps</i>"]
    B --> C["Code Generation"]
    C --> D["2. Two-Layer Verification<br/><i>Deterministic AST + Adversarial Arbiter</i>"]
    D --> E["3. Ambient Telemetry<br/><i>Trigger & outcome signals</i>"]
    E --> F["Self-Evolving Lifecycle<br/><i>Rules promote or decay</i>"]
    F -.-> B

📖 Documentation Portal & Guides

Explore deep-dive guides for production architecture, workflows, and specifications:

Quick Start

pip install aegis-guardrails   # Pure Python (3.9+), zero runtime dependencies
aegis init                     # Auto-detects Gemini, Claude Code, Cursor, Copilot
aegis status                   # View active rules and fitness stats
aegis check                    # Run Layer 1 deterministic AST checks

MCP Server (Recommended)

Add Aegis to your agent's configuration (AEGIS_WORKSPACE points to your project):

{
  "mcpServers": {
    "aegis": {
      "command": "python3",
      "args": ["-m", "aegis_mcp"],
      "env": {
        "AEGIS_WORKSPACE": "/path/to/project",
        "AEGIS_EXECUTION_ENABLED": "1"
      }
    }
  }
}

Receipt flow: Call soma_request_receipt with the operation and arguments to obtain a single-use, state-bound token (300s TTL). See MCP Gateway Guide.

SDK

from aegis_sdk import Governance

gov = Governance(project_root='.')
print(gov.grade(), gov.fitness_landscape(bayesian=True))

📐 Core Rules

The system's foundational rules — 19 inherited behavioral defaults:

🔧 Agent Skills

15 specialized skills coordinate complex behaviors via typed envelopes and file-buffered handoffs. See the Skill Graph Guide for schemas and coordination workflows.

📋 Adaptive Rules & Verification

Adaptive rules live in .aegis/rules/ (invariant, boundary, trap, persona, contract). Rules evolve using Wilson-bounded fitness intervals and decay to zero when unreinforced. See the Rule Lifecycle Guide.

All changes are gated by aegis check:

• Layer 1: Deterministic AST analysis (call graph reachability, mutation testing, import guards, branch coverage).
• Layer 2: Adversarial Rebuttal Protocol with Spec Agent prosecution, Code Agent defense, and binding Arbiter verdict (SHIP / REVISE / BLOCK). See the Verification Pipeline Guide.

⚙️ Core Architecture

• Zero Runtime Dependencies: Pure Python standard library (dependencies = []).
• Scale-to-Zero: Zero daemons, zero background threads, zero persistent idle consumption.
• Local Privacy: Telemetry and evidence remain strictly local in .aegis/evidence/.
• Complete script, tool, and module reference catalog is available in SCRIPTS.md.

License & Privacy

Apache 2.0 — Copyright 2026 Nicholas Seney. See NOTICE, PRIVACY.md, and SECURITY.md.