https://github.com/ganyuanran/aegis
Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.
https://github.com/ganyuanran/aegis
add agent-skills ai-agents ai-coding architecture-driven-development baseline-first claude-code codex coding-agents evidence-driven first-principles opencode software-architecture superpowers tdd
Last synced: about 9 hours ago
JSON representation
Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.
- Host: GitHub
- URL: https://github.com/ganyuanran/aegis
- Owner: GanyuanRan
- License: mit
- Created: 2026-04-30T17:40:49.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-24T05:34:10.000Z (4 days ago)
- Last Synced: 2026-06-24T07:26:28.847Z (4 days ago)
- Topics: add, agent-skills, ai-agents, ai-coding, architecture-driven-development, baseline-first, claude-code, codex, coding-agents, evidence-driven, first-principles, opencode, software-architecture, superpowers, tdd
- Language: Shell
- Homepage:
- Size: 3.62 MB
- Stars: 571
- Watchers: 0
- Forks: 30
- Open Issues: 0
-
Metadata Files:
- Readme: README.en.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Aegis
Aegis Method Pack
Baseline-first, evidence-driven workflow discipline for AI coding agents.
English
·
中文
·
Workflow Guide
·
工作流程说明
## Why Aegis
Aegis is a **Superpowers upgrade** for teams using AI coding agents on real
software work. It keeps the useful idea of composable skills, then adds:
- baseline-first planning before risky changes
- evidence before completion claims
- repair track plus retirement track for bugs, fallbacks, and compatibility paths
- workflow quality guardrails so simple tasks stay cheap
- portable method-pack skills across skill-aware hosts
Aegis is useful when agents otherwise start coding before the goal, owner,
architecture boundary, or verification path is clear.
## Quick Install
Give this prompt to your AI coding agent:
```text
Read https://github.com/GanyuanRan/Aegis, identify my current AI coding host, and install Aegis globally using the correct host guide. 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 ``, then run `cd && 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 `; if the host guide declares a skill directory name prefix, also pass `--discovery-name-prefix `.
```
## 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.
For smoother host-level behavior, use:
- [Lite global rules](GLOBAL_USER_RULES_LITE.md)
- [Advanced global rules template](GLOBAL_USER_RULES_TEMPLATE.md)
Activation mode defaults to automatic. To switch to explicit mode, run this
from the installed method-pack root:
```bash
cd
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](docs/current/AEGIS_ACTIVATION_MODE.md).
TDD mode defaults to `auto`: Aegis chooses strict TDD only when risk warrants,
uses light verification for tiny edits, and skips TDD where it does not fit. To
disable automatic TDD routing without disabling completion verification:
```bash
cd
python scripts/aegis-doctor.py tdd-mode off
```
Details live in [docs/current/AEGIS_TDD_MODE.md](docs/current/AEGIS_TDD_MODE.md).
## Supported Hosts
Aegis keeps a multi-host, plugin-installable distribution goal.
| Host group | Current status | Start here |
| --- | --- | --- |
| `Codex`, `OpenCode` | Fresh evidence exists for the current method-pack scope | [Codex](docs/README.codex.md), [OpenCode](docs/README.opencode.md) |
| `Claude Code`, `CodeBuddy`, `DeepSeek-TUI`, `Trae`, `GitHub Copilot`, `Qoder`, `ZCode` | Install guides exist; release-level fresh host smoke is still pending | [Claude Code](docs/README.claude-code.md), [CodeBuddy](docs/README.codebuddy.md), [DeepSeek-TUI](docs/README.deepseek-tui.md), [Trae](docs/README.trae.md), [GitHub Copilot](docs/README.copilot.md), [Qoder](docs/README.qoder.md), [ZCode](docs/README.zcode.md) |
| `CC GUI (JetBrains IDEA)` | Structural IDE plugin layer support for Claude Code / OpenAI-GPT provider paths; release-level fresh host smoke is still pending | [CC GUI](docs/README.cc-gui.md) |
| `Antigravity CLI`, `Antigravity IDE`, `Antigravity App` | `Antigravity CLI` is the current active closeout target; `IDE/App` remain structural targets and release-level fresh host smoke is still pending | [Antigravity](docs/README.antigravity.md) |
| `Pi CLI`, `OpenClaw`, `Hermes Agent` | Structural Agent Skills / `SKILL.md` skill-host adaptations; release-level fresh host smoke is still pending | [Pi CLI](docs/README.pi.md), [OpenClaw](docs/README.openclaw.md), [Hermes Agent](docs/README.hermes-agent.md) |
| `Gemini CLI` | Transitional compatibility surface while Antigravity support matures | [Compatibility Matrix](docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md) |
Read the current host verdict before making support claims:
- [Host compatibility matrix](docs/current/AEGIS_HOST_COMPATIBILITY_MATRIX_SNAPSHOT.md)
- [Known limitations](docs/current/AEGIS_KNOWN_LIMITATIONS.md)
## How To Use
After installation and host restart, use normal development requests. Aegis
skills should be selected when the task matches the method.
Use a portable goal frame before risky work. It frames the goal, then continues
into the routed workflow by default:
```text
Aegis goal: Fix the auth refresh bug without rewriting the auth system.
```
Use explicit skills when you want a specific method:
- `aegis:brainstorming`
- `aegis:systematic-debugging`
- `aegis:writing-plans`
- `aegis:first-principles-review`
- `aegis:requesting-code-review`
- `aegis:verification-before-completion`
If an expected skill does not trigger, treat it as trigger-chain diagnosis:
verify install/version visibility, host skill discovery, activation mode,
`using-aegis` routing, task-to-skill routing, and context pressure. Read
[docs/current/AEGIS_TRIGGER_HEALTH_BASELINE.md](docs/current/AEGIS_TRIGGER_HEALTH_BASELINE.md).
## Workflow Shape
Aegis routes work by complexity:
- Low-complexity: concise intent, baseline check, TDD Route, verification.
- Medium-complexity: baseline read set, Spec Brief or stable requirements,
writing plan, atomic tasks, verification.
- High-complexity: Design Spec, plan, user review when required, then execution.
The core discipline is:
- **Baseline first**: read current project authority before substantial changes.
- **Evidence before claims**: no completion claim without fresh verification.
- **Repair plus retirement**: fix the owner and state what old path remains or retires.
- **Workflow Quality**: keep simple tasks cheap and expand only when risk demands it.
For the full workflow, read:
- [Workflow Guide](docs/current/AEGIS_WORKFLOW_GUIDE.md)
- [Workflow Quality Baseline](docs/current/AEGIS_WORKFLOW_QUALITY_BASELINE.md)
- [Runtime-ready boundary](docs/current/AEGIS_RUNTIME_READY_BOUNDARY.md)
- [Artifact schema baseline](docs/current/AEGIS_ARTIFACT_SCHEMA_BASELINE.md)
## For Maintainers
Primary verification entry:
```bash
bash tests/e2e/run-all.sh --full --host-profile fast
```
Focused docs / method-pack checks:
```bash
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](docs/testing.md)
- [Release checklist](docs/current/AEGIS_METHOD_PACK_RELEASE_CHECKLIST.md)
- [Current authority map](docs/current/README.md)
- [Contributing](CONTRIBUTING.md)
## Relationship To Superpowers
Aegis is derived from **[Superpowers](https://github.com/obra/superpowers)**,
created by [Jesse Vincent](https://github.com/obra). 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](https://github.com/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](LICENSE).