Aegis: a method pack that makes coding agents plan against your baseline before they edit
Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.
At a glance
- What is it?
- Aegis is a host-agnostic skill pack that forces AI coding agents to read a project's real contracts and boundaries before changing code, then prove completion with fresh evidence. The README reports a frozen A/B benchmark where contract pass rate rose from 61.67% to 93.33%, with the caveat that review was arm-hidden technical review rather than independent human review.
- Who is it for?
- Adopt Aegis if your agent already writes plausible code but keeps breaking contracts, reviving retired paths, or declaring done without evidence, and you are willing to spend one setup pass on host activation plus doctor verification. Do not adopt it for throwaway scripts or one-file edits, where the baseline and evidence steps cost more than the change.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The failure mode Aegis is built around: agents that edit before they understand
The problem named in the README is not bad code generation. It is an agent that starts editing without knowing the project's owners, contracts and boundaries, then reports success in language the user cannot check. The README's own framing is "Stop babysitting your agent" and the promise is fewer reworks, safer changes, and less blind trust in "done". The intended user is someone running a coding agent such as Codex, Claude Code, OpenCode or Kimi on a codebase with real architectural constraints, where a plausible-looking diff that violates an existing contract is worse than no diff at all. A second stated target is long tasks: the description calls for behaviour that stays "safe across long tasks", which is where an agent's early assumptions tend to harden into changes nobody re-examines. If your agent only ever touches isolated files with no contracts to respect, this problem does not exist for you and the method pack has nothing to fix.
Baseline-first, evidence-verified, drift-checked: the three mechanisms in the pack
The README describes three interlocking behaviours. Baseline-first means the agent aligns with the project's real baseline, which the README enumerates as owners, contracts and boundaries, before touching code. Evidence-verified means completion claims ship with fresh verification evidence, covered scope and residual risk, so the reviewer reads evidence rather than assertion. Drift-checked appears in the repository description and connects to the README's claim of "no ghost code": retired fallbacks and old paths are tracked or removed with a retirement trigger, which is the mechanism that stops technical debt from accumulating silently when an agent re-adds a path the team already deleted. A fourth rule constrains the other three: simple tasks stay simple, and the README states that ceremony only appears when the task genuinely needs it. That last rule matters more than it looks. A method pack that applies its full protocol to a typo fix gets disabled within a week, so the fast path is what makes the heavy path tolerable. The README points to a Fast-Track Playbook at docs/current/AEGIS_FAST_TRACK_PLAYBOOK.md for the abbreviated flow.
What the benchmark measures and what the README says it does not
The README reports a frozen held-out A/B benchmark for Aegis 2.7.6 dated 2026-08-11. Both arms kept the same Codex client, prompts, projects and tool policy, and requested the same gpt-5.6-sol model at xhigh; only the Aegis projection differed. Across 120 valid runs on 20 cases, contract pass rate moved from 61.67% to 93.33%, a gain of 31.67 percentage points, and unsafe outcomes fell from 13.33% to 0%. The 95% case-cluster interval is given as +15.00 pp to +50.00 pp. The README is unusually explicit about the limits: it calls the numbers "bounded advisory evidence", notes that review was arm-hidden technical review rather than independent human review, and states that host events did not return the observed model identity. That last point is the one to hold onto. If the harness could not confirm which model actually served the requests, the comparison rests on the assumption that both arms were served identically. Twenty cases is also a small base, which the case-cluster interval reflects. Sanitized JSON, English and Chinese tables, and a methodology document are linked from the README under benchmarks/results/ and docs/current/, so the run can be inspected rather than taken on faith.
Installation: one agent prompt, then a doctor check that must return three specific fields
The README's recommended path is to hand your agent a single prompt that tells it to read the repository, identify the current host, and install Aegis globally using the correct host guide. For the official DeepSeek Harness the prompt prescribes a native profile-plugin install: dsh plugin --profile <profile> add "git+https://github.com/GanyuanRan/Aegis.git". It explicitly warns against silently falling back to a direct-child compatibility path unless the plugin manager is unavailable and the user approves compatibility mode. Verification is a separate step with real preconditions. The prompt says not to run the doctor from the target project directory, and instead to locate the method-pack root and run cd <aegis-method-pack-root> && python scripts/aegis-doctor.py --write-config --json. Installation counts as complete only when the JSON contains "ok": true, "workspaceSupport": "available" and "configStatus": "configured". Two optional flags cover host variation: --discovery-root <path> when the host uses a separate skill discovery directory, and --discovery-name-prefix <prefix> when the host guide declares a skill directory name prefix. The prompt closes with a warning that file discovery or a generic doctor result alone is not sufficient, and that the host guide's native activation and automatic-entry checks must also pass.
The cost you are actually paying: host guides, activation checks and version churn
Aegis is a method pack, not a library, so the maintenance surface is the host integration rather than an API. The install depends on a per-host guide that defines skill discovery directories, name prefixes, activation steps and automatic-entry checks, and the doctor's optional flags exist precisely because those details differ between hosts. Every host update that changes skill discovery or plugin loading can invalidate an installation that the doctor previously passed. The release cadence visible in the repository supports that reading: v2.9.8 on 2026-09-05, v2.9.9 on 2026-09-07, and v2.10.0 later the same day. Three releases in five days is a fast-moving surface, and the benchmark is pinned to a specific version, 2.7.6, which is several minor versions behind the latest release. The README's own install prompt is written to be re-runnable by an agent, which is a reasonable adaptation to that churn, but it also means your setup is partly delegated to the agent you were trying to discipline. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained; this is a description of the licence text, not legal advice, and you should read the LICENSE file and your own obligations rather than rely on this summary.
Where Aegis is the wrong tool, and what to use instead
The README's own carve-out is the clearest boundary: trivial requests stay on the fast path and ceremony only appears when a task genuinely needs it. That means Aegis is the wrong tool for one-off scripts, exploratory notebooks, and small edits in repositories with no contracts worth protecting, because the baseline and evidence steps add overhead without a corresponding risk to reduce. A more consequential mismatch is the single-agent, single-session workflow. If you already run a spec-driven pipeline, the closest alternative approach is a specification toolkit that front-loads requirements into a written spec before any code is generated, then treats that spec as the source of truth. The difference in approach is where the constraint lives. A spec toolkit constrains the agent by making it author and follow a plan; Aegis constrains the agent by making it read the existing architecture as the baseline and attach verification evidence to the result. Aegis is retrospective about your codebase and prospective about proof of completion; a spec toolkit is prospective about intent. If your problem is that nobody agreed what to build, a spec toolkit addresses it. If your problem is that the agent keeps violating agreements your team already made, Aegis is aimed at that. The README also positions Aegis as working across Codex, Claude Code, OpenCode, Kimi and other skill-aware hosts, so if your host is not skill-aware, no part of this applies.
Who should adopt it, and the three checks to run first
Adopt Aegis if you run a skill-aware coding agent against a codebase with contracts, ownership boundaries and retired paths that must stay retired, and if you have been burned by a completion claim that did not hold. The evidence-verified rule is the part with the clearest payoff, because it changes what you read at review time. Do not adopt it for throwaway work, for repositories where the agent is the only consumer of the code, or on a host that is not skill-aware, where the install path described in the README does not apply. Before trusting an installation, run the three checks the README itself demands. First, run python scripts/aegis-doctor.py --write-config --json from the method-pack root, not the target project, and confirm the JSON shows "ok": true, "workspaceSupport": "available" and "configStatus": "configured". Second, complete the selected host guide's native activation and automatic-entry checks, adding --discovery-root or --discovery-name-prefix if the guide calls for them, because file discovery alone is not treated as sufficient. Third, read the frozen benchmark's methodology at docs/current/AEGIS_AGENTIC_BENCHMARK_BASELINE.md and decide whether twenty cases on gpt-5.6-sol at xhigh resemble your workload; the README labels the result bounded advisory evidence, and the reported interval of +15.00 pp to +50.00 pp is wide enough that the honest expectation is a real but unquantified improvement on tasks like the ones tested.
Editorial conclusion
Adopt Aegis if your agent already writes plausible code but keeps breaking contracts, reviving retired paths, or declaring done without evidence, and you are willing to spend one setup pass on host activation plus doctor verification. Do not adopt it for throwaway scripts or one-file edits, where the baseline and evidence steps cost more than the change. Verify three things before trusting it: that the doctor JSON returns ok true, workspaceSupport available and configStatus configured from the method-pack root rather than the target project, that your host guide's native activation and automatic-entry checks pass rather than file discovery alone, and that the benchmark's frozen settings (Codex client, gpt-5.6-sol, xhigh, 20 cases, 120 runs) resemble your own workload, since the README itself calls the result bounded advisory evidence.
Community notes