What Aegis is — and what it is not
Under its Before You Use It heading the README gives a deliberately narrow self-description: Aegis Method Pack (runtime-ready). It is a method pack — a body of agent instructions and skills — not a program that inspects your repository. In the README’s own words 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 it.
Mechanically, the package is aegis at 2.10.1, "type": "module", ESM, with main pointing at .opencode/plugins/aegis.js. Its dsh field declares exactly one thing — a bundle patch, ./extensions/dsh/cordis.patch.yml — so on DeepSeek Harness it installs as a profile plugin that contributes a composition patch, plus the skills it ships. It also declares pi and omp extension paths and lists pi-package, agent-skills, dsh-plugin and deepseek-harness among its keywords.
The idea: baseline, evidence, and the blockquote that is not a feature
Aegis is built around an architecture-and-evidence discipline. Its blockquote summarises the mechanism: the agent should plan against your real baseline before it edits, prove completion with fresh evidence, and leave simple tasks alone. The README spells the first part out as aligning with a project’s real baseline — “owners, contracts, boundaries” — before touching code. The evidence half is stated as completion claims shipping with “fresh verification evidence, covered scope, and residual risk”. The third half is a routing promise: “Trivial requests stay on the fast path; ceremony only appears when the task genuinely needs it.”
Note what is not in the README: the word “drift” never appears in it. This listing’s tags and useCases mention drift-check, and the previous tagline claimed drift checking, but the only “drift”-adjacent machinery the README actually names is contract pass rate in its benchmark, plus tracking of retired fallbacks and old paths “with a retirement trigger”. Treat “drift detection” as a reasonable reading of that discipline rather than as a documented feature name.
What it actually produces — guidance, not a gate
This is the distinction worth being precise about, because the README is precise about it. On the harness the pack contributes skills and a composition patch. Its effect is on what the agent is instructed to do, and its outputs are prose artefacts: a baseline alignment, a completion claim carrying verification evidence, and a decision interview when you ask for one. It is not a linter, not a CI gate, and not a checker binary that returns pass/fail on your repository. The README’s own phrasing — no “authoritative GateDecision”, no “final completion authority” — is the clearest statement available that it does not block anything. Nothing in the README claims Aegis can refuse an edit, refuse a commit, or fail a pipeline.
Layered on top are user-steerable modes, all requested in normal language: Aegis goal: ... frames scope, success evidence and boundaries; Grill me ... / 审问我 ... runs a one-question-at-a-time decision interview that explicitly “does not plan or implement”; aegis:first-principles-review pressure-tests a direction before implementation. Two defaults matter: activation mode defaults to automatic, and TDD mode defaults to off — the README says Aegis “does not automatically require TDD”, and that completion verification still applies either way.
Is the verification automated, or model-driven?
Model-driven and instruction-enforced, not tool-enforced. The pack is a set of skills plus a patch; the README nowhere describes a verification engine that runs on its own and inspects your diff. It describes requesting evidence from the agent, and it describes the maintainers’ own test scripts, which are checks on the method pack itself rather than on your code: tests/e2e/boundary-compliance-check.sh, workflow-quality-check.sh, install-verification-policy-check.sh, and layer1-fast-check.sh. It also documents a trigger-chain diagnosis for when a capability does not fire — install/version visibility, host skill discovery, activation mode, using-aegis routing, task-to-skill matching and context pressure.
There is one more mechanism in the README that is genuinely file-based and worth naming: for non-trivial project work Aegis can passively reuse canonical language from CONTEXT.md or a bounded context selected by CONTEXT-MAP.md, activating domain modeling only when a term is resolved, ambiguous, renamed, deprecated or conflicting. Files are “created lazily on the first resolved term and remain glossary-only”, and unresolved domain decisions stay user-owned. It also says stable bytes can be cache-friendly but that Aegis “does not guarantee provider cache hits or savings”.
The benchmark numbers, and how far they go
The README reports a frozen held-out A/B benchmark for Aegis 2.7.6 (2026-08-11): same Codex client, prompts, projects and tool policy in both arms, with only the Aegis projection differing. Across 120 valid runs on 20 cases, contract pass rate was 61.67% → 93.33% and unsafe outcomes were 13.33% → 0%, with a 95% case-cluster interval of +15.00 pp to +50.00 pp.
The README immediately bounds this, and so should any listing: it is “bounded advisory evidence”, the review was arm-hidden technical review, not independent human review, and host events did not return the observed model identity. It is also a 20-case sample reporting a specific model and effort setting. Do not read it as a general accuracy claim about Aegis on your project, or as a security guarantee. Note separately that the package in this listing is at 2.10.1 while the benchmark measures 2.7.6; the README does not state that the numbers were re-measured for later versions.
Requirements
The README documents installation as a native profile-plugin install on DeepSeek Harness, then a Python verification step run from the installed method-pack root: python scripts/aegis-doctor.py --write-config --json, with scripts/aegis-update.py handling later updates. So a working Python interpreter on the install path is implied by the commands, though the README does not state a Python version, and neither the README nor package.json declares a minimum Node version — the package has no engines field at all.
There is also no stated harness version floor in the README. The concrete version constraint that exists is in package.json: three peer dependencies — @deepseek-ai/dsh-agent, @deepseek-ai/dsh-llm and @deepseek-ai/dsh-skill-filesystem, all at ^0.1.0-rc.6 — and all three are marked optional in peerDependenciesMeta. An optional peer range is an install requirement, not a compatibility declaration, and no source states a harness floor, so this listing records no dshTarget and stops at verification L2. No specific model, account, key or external service is required, and the README states no telemetry or credential requirement.
Known limits, in the README’s own terms
- Host support is uneven. The README grades its own matrix: Codex and OpenCode have “fresh evidence”; DeepSeek Harness, Claude Code, CodeBuddy, Trae, GitHub Copilot, Qoder, Kimi Code CLI, ZCode and Grok Build have install guides but “release-level fresh host smoke is still pending”; Antigravity IDE/App and the CC GUI layer are structural targets; Gemini CLI is retired. Read that row before assuming the harness path is battle-tested.
- It can fail to trigger at all. Trigger health is an explicit documented concern, with a diagnosis chain rather than a guarantee.
- Its scope is bounded by its own framing: not a daemon, not a background runner, not completion authority, and outranked by your instructions and project rules. It also does not run background automatic updates by default.
- The optional global routing prefix is a manually copied host projection: it “does not install Aegis or prove skill discovery”, it is not managed by
aegis:update, and host-native skill matching “may still remain host-controlled”. - Unstated but assumable: the README says nothing about a telemetry policy, a privacy policy, a security review process, or a star count. Stars and forks appear in this listing’s frontmatter as registry metadata and cannot be verified from the two permitted sources.
Trust: what it reads and writes, and what it sends
Reads: your project’s baseline context, CONTEXT.md / CONTEXT-MAP.md when present. Writes: glossary-only context files created lazily on the first resolved term, and its own configuration through scripts/aegis-doctor.py --write-config, run from the method-pack root — the README warns explicitly not to run the doctor from the target project directory. Installs: a composition patch plus skill files into the host profile.
On outbound behaviour the README is silent. It documents no telemetry, no phone-home, no analytics, and no credential handling, in either direction — absence of a claim here is not a claim of no network access. One README detail is nonetheless a real instruction to exercise care: it tells you to hand your agent a prompt that has the agent read a GitHub URL and install from git+https://github.com/GanyuanRan/Aegis.git, which is a network fetch and a remote install, and it asks you to name your profile. Licensing is stated in the README as MIT; package.json carries no license field. language: Python in this listing reflects the doctor and update scripts, not the whole pack, which is predominantly markdown skills plus extension files.
When to use it — and when not to
Reach for Aegis if you already run skill-aware agent hosts and want a discipline layer that pushes an agent to state its assumptions against your project’s contracts before editing, and to justify “done” with evidence instead of assertion. It is host-agnostic by design — the README’s goal is “one method pack, every host” — and its fast-path promise means you are not committing to ceremony on one-line changes. It is derived from Superpowers by Jesse Vincent, with additional inspiration from mattpocock/skills, re-implemented in Aegis format rather than copied.
Do not adopt it as a control. It does not gate merges, it does not replace tests, review, linters or CI, and the README declines completion authority outright. Do not adopt it expecting an automated architecture-drift scanner on your repo; what exists is instructed discipline plus a benchmark measuring contract pass rate in a 20-case study. And if your host is DeepSeek Harness specifically, weigh the README’s own “fresh host smoke is still pending” entry before you depend on it for anything load-bearing.
FAQ
Does Aegis block a change that violates the baseline?
No. The README describes it as a method pack and explicitly disclaims being an authoritative GateDecision, an authoritative PolicySnapshot, or final completion authority, and it says user instructions and target-project rules outrank its guidance. Expect a documented expectation and a request for evidence, not an enforced refusal.
Is “drift checked” automated?
No dedicated drift checker is documented, and the README never uses the word. What it does describe is aligning to a baseline of owners, contracts and boundaries before edits, tracking retired fallbacks and old paths with a retirement trigger, and measuring contract pass rate in its benchmark. The “drift” framing in this listing’s tags is an interpretation of that discipline, not the README’s own term.
Do the benchmark numbers mean it improves my project?
They are bounded advisory evidence from one frozen study — 120 runs over 20 cases, arm-hidden technical review rather than independent human review, and an unspecified observed model identity. The README itself calls them advisory and not a universal-quality claim. It also does not say the numbers were re-measured for the version published here.
Does it upload my code anywhere?
The README documents no telemetry, analytics or remote service, and equally documents no privacy or security review. Treat the answer as “not stated” rather than “no”. The install path the README prescribes does fetch from GitHub and asks you to identify your profile.
Do I need a particular Node or Python version?
The package declares no engines field and the README names no Node version; neither states a Python version. The only documented version constraints are three optional peer dependencies on @deepseek-ai/dsh-* at ^0.1.0-rc.6, and the Python usage implied by the doctor and update scripts.