Aegis

Stop babysitting your agent. Aegis makes your agent plan against your real baseline before it edits, prove completion with fresh evidence, and leave simple tasks alone — you get fewer reworks, safer changes, and less blind trust in "done".

What You Get

Aegis is a method pack that makes AI coding agents work like disciplined engineers — so you don't have to watch them.

• Fewer reworks. Your agent aligns with your project's real baseline — owners, contracts, boundaries — before touching code. It stops guessing, and so do you.
• Safer changes. Measured on a frozen held-out A/B benchmark: contract pass rate 60% → 90%, unsafe outcomes 11.67% → 5%.
• Proof before "done". Completion claims ship with fresh verification evidence, covered scope, and residual risk. You read evidence, not vibes.
• No ghost code. Retired fallbacks and old paths are tracked or removed with a retirement trigger — technical debt stops accumulating silently.
• Simple tasks stay simple. Trivial requests stay on the fast path; ceremony only appears when the task genuinely needs it.
• One method pack, every host. The same discipline works across Codex, Claude Code, OpenCode, Kimi, and other skill-aware hosts.

The numbers above are bounded advisory evidence from the frozen benchmark below, not a universal-quality or completion-authority claim.

Measured Agentic Benchmark

A frozen held-out A/B benchmark (Aegis 2.5.5, 2026-07-31) used the same Codex client, gpt-5.6-sol model, xhigh effort, prompts, projects, and tool policy in both arms; only the Aegis projection differed. Across 120 valid runs on 20 cases: contract pass rate 60% → 90% (+30 pp); unsafe outcomes 11.67% → 5%.

Bounded advisory evidence, not a universal-quality or completion-authority claim; full details in the published report and methodology.

Measurement status: this snapshot covers Aegis 2.5.5. A re-measurement of the current release is pending and will be published here only after a validated held-out batch completes; numbers from older snapshots must not be read as evidence for newer releases.

Sanitized JSON · English table · 中文表格 · Methodology and evidence boundary

Quick Install

New here? The fastest start is one prompt to your agent — the full install-and-verify flow is below.

Give this prompt to your AI coding agent:

Read https://github.com/GanyuanRan/Aegis, identify my current AI coding host, and install Aegis globally using the correct host guide. Restart or reload the host if needed, then run complete-install verification from the installed Aegis method-pack root. Do not run the doctor command from the target project directory. First locate `<aegis-method-pack-root>`, then run `cd <aegis-method-pack-root> && python scripts/aegis-doctor.py --write-config --json`. Treat the install as complete only if the JSON includes `"ok": true`, `"workspaceSupport": "available"`, and `"configStatus": "configured"`; if the host uses a separate skill discovery directory, also verify it with `--discovery-root <path>`; if the host guide declares a skill directory name prefix, also pass `--discovery-name-prefix <prefix>`.

Updating Aegis

After a complete install has registered the current host, later updates can use natural language such as update Aegis or the explicit skill request aegis:update. The agent can route either form through the local update path: locate the installed method-pack root, use the host-scoped registry, and call scripts/aegis-update.py for the current host by default. Updating every registered host requires an explicit --all request. Aegis does not run background automatic updates by default.

Before You Use It

Aegis is currently:

Aegis Method Pack (runtime-ready)

It is not the full Aegis Platform, a daemon, a background runner, a runtime core, an authoritative GateDecision, an authoritative PolicySnapshot, or final completion authority. User instructions and target-project rules outrank Aegis guidance.

The following files are optional, manually copied host/profile projections. They do not install Aegis or prove skill discovery. If the host already has reliable Aegis bootstrap and routing, no extra global rule is usually needed for routing. Otherwise, copy Lite as the complete base profile. Advanced is a non-standalone additive overlay; append only the rules needed for persistent governance preferences:

• Lite global rules
• Advanced governance overlay

These copied rules are not managed by aegis:update. Lite owns the default auto activation profile and its explicit-mode replacement; Advanced inherits that choice instead of repeating it. When switching to explicit, update the copied Lite profile too; host-native skill matching may still remain host-controlled.

Activation mode defaults to automatic. To switch to explicit mode, run this from the installed method-pack root:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py activation-mode explicit

Restart the host after changing activation mode. Details and host caveats live in docs/current/AEGIS_ACTIVATION_MODE.md.

TDD mode defaults to off: Aegis does not automatically require TDD, and completion verification still applies. To enable automatic TDD routing when you want Aegis to choose strict, light, or skipped by task risk:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py tdd-mode auto

You can also request strict TDD directly in a query with explicit markers such as TDD Route: strict, strict TDD, test-first, or RED / GREEN / REFACTOR.

Details live in docs/current/AEGIS_TDD_MODE.md.

Supported Hosts

Aegis keeps a multi-host, plugin-installable distribution goal.