One-Line Description

Aegis is a workflow methodology package for AI programming assistants, containing 22 method skills (diagnosis, planning, review, verification, wrap-up, etc.). After installation, it injects a concise routing guide at the start of each session, allowing the Agent to decide based on task risk whether to act directly or first analyze/gather evidence.

Core Capabilities

• Enables Agents to read existing project conventions and identify the correct modules to modify before touching code, reducing rework from fixing the wrong areas
• When encountering errors, regressions, or behavioral anomalies, requires following a root cause定位流程 before proposing fixes instead of guessing
• Requires Agents to provide actual verification content run, coverage scope, and remaining risks when claiming "done"
• Provides packaged method skills: requirement interrogation brainstorming, plan creation and execution, independent code reviews, architecture decision records, long-running task checkpoint resumption, legacy logic retirement
• Automatically injects routing guidance at four points: session start, recovery, clearing, and compression; simple tasks still allow Agents to directly declare taking the fast path
• Provides project workspace scripts to generate baselines, plans, checkpoints, and evidence records in the target project's docs/aegis/ directory as needed

Technical Implementation

• Language: JavaScript (ESM modules) + Python 3 scripts, method bodies are Markdown
• Key Dependencies: @deepseek-ai/dsh-skill-filesystem (reusing host's skill discovery capability), @deepseek-ai/dsh-llm (constructing injection messages), both declared as optional peerDependencies provided by the host
• Architecture Pattern: Uses dsh.bundle.patch in package.json to insert a Cordis record into host configuration, mounting an independent skill provider without a default root directory pointing to the package's skills/; also listens to the host's native agent/session-start lifecycle to prepare routing text and synchronously inject during plugin loading, avoiding race conditions from first-step file reading; sub-agents are not injected
• Entry File: extensions/dsh/index.js (mounted via extensions/dsh/cordis.patch.yml)

Use Cases

Suitable for people who want AI to make large-scale changes to real projects without watching全程: Agents tend to act before understanding the existing structure and then claim completion. It solidifies "first check baseline, first determine root cause, provide evidence on completion" into reusable workflows while ensuring trivial requests aren't slowed down by processes.

Prerequisites & Compatibility

Installation

dsh plugin --profile web add github:GanyuanRan/Aegis

Configuration

Configuration is written to ~/.config/aegis/config.toml in the user directory, usually automatically generated by python scripts/aegis-doctor.py --write-config.

Also supports temporary overrides via environment variables: AEGIS_ACTIVATION_MODE, AEGIS_TDD_MODE, AEGIS_WORKSPACE_HELPER. After modifying automatic switches, need to restart the corresponding profile.

FAQ

Q: Can it be used immediately after installation?

A: Need to restart the corresponding DSH profile. Installation instructions require first using dsh plugin --profile web list --depth 0 to confirm the package is installed, then using dsh --profile web --dump-config to confirm aegis-method-pack appears in the configuration, then restart the session.

Q: How to determine if installation was successful?

A: Beyond the configuration readback above, also locate the method pack directory (typically ~/.dsh/profiles/web/node_modules/aegis), run python scripts/aegis-doctor.py --write-config --json there, and the output must simultaneously contain "ok": true, "workspaceSupport": "available", "configStatus": "configured". Note: do not run this command in your business project directory.

Q: Will every question go through a full process after installation?

A: No. Routing rules allow Agents to directly declare taking the fast path for simple tasks; only higher-risk tasks like multi-step implementations, shared module changes, or contract changes trigger the full methodology.

Q: Will it write files to my project?

A: No by default. Only when the workflow needs to retain baselines, plans, checkpoints, or verification evidence does it create files on demand in the target project's docs/aegis/ directory; regular Q&A, status queries, and small changes do not generate files.

Q: Where are configuration and records stored?

A: Global configuration is in ~/.config/aegis/config.toml; project-related records are written to docs/aegis/ in your project directory, following project version control, not centrally uploaded elsewhere.

Q: Will it force me to write tests by default?

A: No, TDD mode is off by default. When needed, run python scripts/aegis-doctor.py tdd-mode auto to enable automatic risk-based routing, or directly write strict TDD or test-first in your question for one-time requests.

Q: Installed on web profile, can headless profile also use it?

A: No. DSH plugin dependencies are isolated by profile; need to run the installation command separately for each profile you want to use; also do not register it to other skill directories like ~/.dsh/skills, otherwise duplicate sources will occur.

Q: Is there data supporting the effectiveness?

A: The repository includes a frozen A/B comparison dataset (20 test cases, 120 valid runs) and publishes raw JSON with methodology descriptions, while explicitly stating this is bounded reference evidence, evaluated as technical review with hidden groups rather than independent human review, and cannot be used as a general quality conclusion.

Learning Curve

Advanced — installation requires only one command, but properly setting up pnpm and Python, understanding profile isolation concepts, and completing configuration readback plus self-check script verification are needed to truly get it working.

Known Issues & Limitations

• Official DSH host adaptation currently has only structural support: session injection wiring has deterministic test coverage, but lacks production-level real session routing verification
• DSH itself is in developer preview stage, with official statements that there will be breaking changes; adaptation may become invalid with host upgrades
• Plugin installation and old direct-child compatible installation cannot be enabled simultaneously, otherwise duplicate skill sources and unreliable routing results will occur
• Versions installed via plugin should not be updated with scripts/aegis-update.py update --host deepseek-harness; that command only handles compatible mode installations; for plugin installations use dsh plugin update aegis
• It is not a runtime kernel and does not do hard tool interception: fast path declarations are model self-reported behaviors and are not forcibly blocked when misjudged
• Completeness of project workspace records depends on workflows correctly invoking workspace scripts; when not invoked, index files may have missing entries
• Project baseline quality depends on whether repository content is sufficient; projects with too sparse content cannot generate useful baselines
• Some dimensions of architecture review (like entropy flow, cascade propagation) rely on Agent qualitative judgment without quantitative measurement tools
• Upstream Gemini CLI host adaptation has been retired and is no longer provided or verified with the package

Aegis

Aegis Method Pack
Make your AI coding agent trustworthy: fewer reworks, safer changes, proof before "done".

English · 中文 · Fast-Track Playbook · 速通秘籍

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 61.67% → 93.33%, unsafe outcomes 13.33% → 0%.
• 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 for Aegis 2.7.6 (2026-08-11) kept the Codex client, prompts, projects, tool policy, and requested the same gpt-5.6-sol / xhigh setting in both arms; only the Aegis projection differed. Across 120 valid runs on 20 cases, contract pass rate was 61.67% → 93.33% (+31.67 pp) and unsafe outcomes were 13.33% → 0%. The 95% case-cluster interval was +15.00 pp to +50.00 pp. This is bounded advisory evidence; review was arm-hidden technical review, not independent human review, and host events did not return the observed model identity.

Sanitized JSON · English table · 中文表格 · Methodology

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. If the host is the official DeepSeek Harness (`dsh`), treat global/minimal installation as native profile-plugin installation with `dsh plugin --profile <profile> add github:GanyuanRan/Aegis`; do not silently substitute the direct-child compatibility path unless the plugin manager is unavailable and I explicitly approve compatibility mode. 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>`. Also complete the selected host guide's native activation and automatic-entry checks; file discovery or a generic doctor result alone is not sufficient when the host provides a plugin, hook, or session-start bootstrap contract.

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.

Read the current host verdict before making support claims:

• Host compatibility matrix
• Known limitations

Start Fast With Aegis

After installation and host restart, use normal language. Aegis matches the method to the work; name a mode directly when you want less ambiguity.

Why does this login failure happen? Diagnose it before changing code.
Grill me on whether we should ship a hosted version first.
Aegis goal: Fix the auth refresh bug without rewriting the auth system.
Review this diff independently before I merge it.

Read the Fast-Track Playbook for Aegis's lightweight operating model, how it differs from standalone skill packs, its five engineering moats, project workspace lifecycle, natural trigger phrases, controls, and troubleshooting. The Chinese version is Aegis 速通秘籍.

Use these explicit requests when you need tighter control:

• Aegis goal: ... frames scope, success evidence, and boundaries.
• Grill me ... or 审问我 ... starts a decision interview; it asks one decision question at a time and does not plan or implement.
• TDD Route: strict, strict TDD, or test-first explicitly requests strict test-first work. TDD is otherwise off by default.
• aegis:first-principles-review or review this from first principles pressure-tests a complex direction before implementation.
• aegis:update updates the installed method pack through its host-aware path.

For non-trivial project work, Aegis can passively reuse relevant canonical language from CONTEXT.md or a bounded context selected by CONTEXT-MAP.md. It activates domain modeling only when a term is resolved, ambiguous, renamed, deprecated, or conflicting. High-confidence existing facts may synchronize directly; unresolved domain decisions remain user-owned. Files are created lazily on the first resolved term and remain glossary-only. Stable bytes can be cache-friendly, but Aegis does not guarantee provider cache hits or savings.

Aegis preserves Workflow Quality by keeping simple work light and expanding only when risk warrants it. For deeper method detail, read the Workflow Guide, Workflow Quality Baseline, Complexity Governance Baseline, and TDD mode.

If a capability does not trigger as expected, use trigger-chain diagnosis: install/version visibility, host skill discovery, activation mode, using-aegis routing, task-to-skill matching, and context pressure. Read the Trigger Health Baseline.

For Maintainers

Primary verification entry:

bash tests/e2e/run-all.sh --full --host-profile fast

Focused docs / method-pack checks:

bash tests/e2e/boundary-compliance-check.sh
bash tests/e2e/workflow-quality-check.sh
bash tests/e2e/install-verification-policy-check.sh
bash tests/e2e/layer1-fast-check.sh --host-profile none

Read:

• docs/testing.md
• Release checklist
• Current authority map
• Contributing

Community & Extending

• Feedback and discussion: GitHub Discussions · Issues · LINUX DO · DEV.to
• Extend Aegis: write your own skill with aegis:writing-skills; see the Workflow Guide.
• Follow along: RELEASE-NOTES.md · Releases

Relationship To Superpowers

Aegis is derived from Superpowers, created by Jesse Vincent. Superpowers pioneered composable, multi-harness agent skills. Aegis keeps that foundation and adds an architecture- and evidence-focused method layer for real software projects.

Additional inspiration comes from mattpocock/skills, especially concise communication, shared language, and disciplined debugging patterns. These ideas were re-implemented in Aegis format rather than copied verbatim.

License

MIT License. See LICENSE.