What Is aegis? Aligning Coding Agents with the Real Baseline

aegis is an architecture-aware method pack for DeepSeek Harness (DSH) that makes AI coding agents work like disciplined engineers: align with the real baseline before editing, prove completion with fresh evidence, and keep simple tasks simple — fewer reworks, safer changes, and no blind trust in "done". This article explains what aegis is, its core features, the complete install/update/uninstall commands, typical usage, and troubleshooting, so you can make agents more reliable in the DSH Plugin ecosystem.

What Is aegis?

aegis addresses the problem of AI coding agents acting before thinking: it makes the agent align with the real baseline of the project (owners, contracts, boundaries) first, then prove completion with fresh evidence instead of saying "done" on vibes. The positioning and facts below all come from the official README (source):

aegis (GitHub repo GanyuanRan/Aegis) is maintained by GanyuanRan and open-sourced under the MIT license. It derives from Superpowers, created by Jesse Vincent (obra), and is a method pack rather than a full platform: no daemon, background runner, or runtime core, and no authoritative GateDecision or PolicySnapshot — user instructions and target-project rules always outrank it. It applies the same discipline across skill-aware hosts such as Codex, Claude Code, OpenCode, and Kimi; in DeepSeek Harness (DSH) it loads as a thin bundle registered as aegis-method-pack. Its current status is Aegis Method Pack (runtime-ready), and it is part of the DSH Plugin ecosystem.

What Are the Core Features of aegis?

aegis's core capabilities revolve around "baseline-first + evidence verification + drift checking + retirement triggers": align with the real baseline before editing, speak with fresh evidence on completion, keep simple tasks simple in long sessions, and reuse the same discipline across hosts. These capabilities all come from the official README (source):

• Baseline-first: align with the project's owners, contracts, and boundaries before editing, avoiding rework from the agent's blind guessing.
• Evidence verification: completion claims ship with fresh verification evidence, covered scope, and residual risk, so you judge completion by evidence rather than vibes.
• Drift checking: on a frozen A/B benchmark (120 valid runs, 20 cases), contract pass rate improved from 61.67% to 93.33% and unsafe outcomes dropped from 13.33% to 0%; this is bounded advisory evidence, not a universal quality or completion authority claim.
• Retirement triggers: track or remove retired fallbacks and old paths so ghost code and technical debt stop accumulating silently.
• Simple tasks stay simple: trivial requests stay on the fast path and are not slowed by heavyweight process.
• Cross-host consistency: the same discipline applies on Codex, Claude Code, OpenCode, Kimi, and more; on DSH it ships as a thin bundle registered as aegis-method-pack.

How to Install and Enable aegis?

Installing aegis requires running dsh plugin commands in DeepSeek Harness with the explicit git+https:// form, then passing three verification gates: plugin list, dump-config, and doctor. Prerequisite: pnpm must be on PATH — Harness forwards dsh plugin operations to pnpm (source):

1. Install aegis: run the install command on the target profile (web in the examples). The official guide requires the explicit git+https:// form; do not shorten it to github:GanyuanRan/Aegis, because some DSH/pnpm combinations resolve that shorthand through SSH and would require GitHub SSH credentials for this public repository:

dsh plugin --profile web add "git+https://github.com/GanyuanRan/Aegis.git"

The headless profile must be installed separately (a dependency in one profile is not automatically active in another):

dsh plugin --profile headless add "git+https://github.com/GanyuanRan/Aegis.git"

2. Verify the install: first confirm the plugin list shows aegis, then confirm dump-config enables exactly one aegis-method-pack row:

dsh plugin --profile web list --depth 0
dsh --profile web --dump-config

The dump must contain exactly one row with id: aegis-method-pack and name: aegis/extensions/dsh/index.js; the profile manifest (default ~/.dsh/profiles/web/package.json) must list aegis in both dependencies and dsh.profile.bundles — a package in dependencies only is not an active bundle.

3. Re-verify with doctor: cd into the aegis package root (normally ~/.dsh/profiles/web/node_modules/aegis) and run the doctor — not from a target project directory:

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py --write-config --json

The JSON output must include "ok": true, "workspaceSupport": "available", and "configStatus": "configured". Then restart the profile and confirm the skill catalog includes using-aegis, systematic-debugging, and verification-before-completion.

4. Update aegis: update through the plugin manager of each profile where it is installed:

dsh plugin --profile web update aegis

For a bundle-managed installation, do not use scripts/aegis-update.py — that updater owns only the direct-child compatibility mode.

5. Uninstall aegis: remove it only from the intended profile:

dsh plugin --profile web remove aegis

After removal the dump must no longer contain aegis-method-pack; uninstalling does not authorize deleting directories such as $DSH_HOME/skills.

Typical aegis Usage

Typical aegis usage is declaring goals and boundaries in natural language (Aegis goal), running decision interviews (Grill me), enabling TDD routing on demand, and requesting first-principles reviews when needed; the default activation is automatic after install, with no extra command required. (source) The four steps below cover daily usage from declaring a goal to switching activation mode.

1. Declare a goal with Aegis goal: frame the scope, success evidence, and boundaries, and write the task constraints clearly before sending them to the agent. For example:

Aegis goal: Fix the auth refresh bug without rewriting the auth system.

2. Run a decision interview: use Grill me ... to have the agent ask one decision at a time, without planning or implementing. For example:

Grill me on whether we should ship a hosted version first.

3. Enable TDD routing on demand: TDD is off by default; request it explicitly in the query with markers such as TDD Route: strict or test-first, or let aegis choose strict, light, or skipped by task risk. Run the command:

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

4. Switch activation mode and request a first-principles review: the default auto mode injects the bootstrap after session start, resume, clear, and compact boundaries; switch to explicit mode for manual triggering, or use aegis:first-principles-review to review a design from first principles. Run the command:

python scripts/aegis-doctor.py activation-mode explicit

aegis Troubleshooting

The four most common aegis issues are a failing doctor check, skills not triggering, installing into the wrong profile or a manifest missing bundles, and bundle plus direct-child both active — solved by the three verification keys, the trigger-chain diagnosis, fixing the manifest, and cleaning up duplicate installs. (source)

1. Doctor check fails: symptom: aegis-doctor.py output is missing one of ok, workspaceSupport, configStatus; cause: running it from a target project directory, or the profile manifest not listing both dependencies and dsh.profile.bundles. Fix: cd into the aegis package root first, then check both fields in ~/.dsh/profiles/web/package.json. 2. Skills do not trigger: symptom: the injected Aegis bootstrap never enters the decision path; cause: activation mode, host skill discovery, or task-to-skill matching. Fix: walk the trigger chain — install/version visibility, host skill discovery, activation mode, using-aegis routing, task-to-skill matching, context pressure — and explicitly request loading using-aegis:

dsh --profile web --dump-config

3. Wrong profile or manifest missing bundles: symptom: dump-config has no aegis-method-pack row; cause: a dependency in one profile is not automatically active in another, or the package appears only in dependencies and not in dsh.profile.bundles. Fix: run the install command for the target profile separately and confirm the package name appears in both places. 4. Bundle and direct-child both active: symptom: duplicated skills and unreliable routing evidence; cause: both installation views exist, creating duplicate skill owners. Fix: keep exactly one — a bundle-managed installation must not also register the direct-child view with scripts/aegis-update.py.

Use Cases and Notes

aegis fits every scenario where you want AI coding agents to align with a baseline first and prove completion with evidence, but it is currently Aegis Method Pack (runtime-ready), not a full platform, and it is not final completion authority — DeepSeek Harness itself is a developer preview. (source)

Use cases include: agents reworking frequently, unclear project owners/contracts/boundaries, keeping one discipline across Codex, Claude Code, OpenCode, Kimi and other hosts, and long tasks where simple tasks should stay on the fast path. Notes:

1. Current status is Aegis Method Pack (runtime-ready) — not the full Aegis Platform, a daemon, or a runtime core; it provides no authoritative GateDecision or PolicySnapshot and is not final completion authority.
2. User instructions and target-project rules always outrank aegis guidance; the host's native skill catalog, matcher, and execution policy stay host-controlled.
3. DeepSeek Harness is a developer preview; breaking changes are expected, and release-level live routing evidence is still pending.
4. Install and update per profile; a bundle-managed installation must not mix in the scripts/aegis-update.py compatibility mode.

Project Links

aegis is an MIT-licensed open-source project maintained by GanyuanRan. Plugin details: aegis plugin details.

This page is an independent guide rewritten from the plugin's official README — for authoritative documentation and the latest changes, please refer to the source: GanyuanRan/Aegis. A plugin is third-party code that runs on your machine at install time; inclusion is not an endorsement — review the source before installing.