# Aegis

> Add work discipline to the AI coding assistant: read the project baseline before modifying code, investigate root causes when errors occur, attach

## Metadata

- Author: [@GanyuanRan](https://github.com/GanyuanRan)
- Repo: <https://github.com/GanyuanRan/Aegis.git>
- GitHub: [GanyuanRan/Aegis](https://github.com/GanyuanRan/Aegis)
- Stars: 1,040
- Language: Python
- License: [MIT](https://spdx.org/licenses/MIT.html)
- Homepage: <https://github.com/GanyuanRan/Aegis>
- Topics: `agent-skills`, `ai-agents`, `ai-coding`, `architecture-driven-development`, `awsome-coding-plugin`, `baseline-first`, `claude-code`, `codex`, `coding-agents`, `dive`, `dsh-plugin`, `evidence-driven`, `first-principles`, `opencode`, `software-architecture`, `spec-driven-development`, `spec-kit`
- Forks: 47
- Open Issues: 0
- Last push: 2026-08-17T07:02:05.000Z
- Added: 2026-08-17T00:00:00.000Z

## Install

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

## Wiki

## 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

| Dependency | Min Version | Description |
|---|---|---|
| DeepSeek Harness (dsh) | 0.1.0-rc.6+ | Declared as optional peerDependencies: `@deepseek-ai/dsh-agent`, `dsh-llm`, `dsh-skill-filesystem` |
| pnpm | No specific version declared | `dsh plugin` operations are forwarded to pnpm, using npx to start the UI alone is insufficient for plugin installation |
| Python 3 | CI verified with 3.11 | Self-check scripts and project workspace scripts are written in Python; without it, full verification cannot be completed |
| Node.js | Not declared | No engines field in `package.json` |
| Running Platform | Cross-platform | Repository provides `.cmd`, PowerShell hooks, and Windows junction link mode simultaneously |
| Native Modules | None | No dependencies on native extensions requiring compilation |

## Installation

```bash
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`.

| Config | Type | Description | Default |
|---|---|---|---|
| `activation_mode` | String (auto / explicit) | Whether to automatically remind Agents to use this methodology at each session start; after changing to explicit, it only takes effect when you explicitly invoke | `auto` |
| `tdd_mode` | String (auto / off) | Whether to automatically require test-first based on task risk | `off` |
| `method_pack_root` | Path | Records where this method pack is located, for self-check and update process locating | Written by `--write-config` |
| `workspace_helper` | Path | Records workspace script location, for generating records in target project | Written by `--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

---

This document is auto-generated by [deepseek-plugin.org](https://deepseek-plugin.org). HTML page: [Aegis](https://deepseek-plugin.org/plugins/GanyuanRan/Aegis)
Wiki generated by AI (model: `MiniMax-M2.5`)