by GanyuanRan
Make AI coding agents architecture-aware: baseline-first, evidence-verified, drift-checked, and safe across long tasks.
# Add to your Claude Code skills
git clone https://github.com/GanyuanRan/AegisGuides for using ai agents skills like Aegis.
中文版本：README.zh-CN.md
If you are using an AI coding agent, you can ask it to install Aegis for you:
Please read the installation instructions in https://github.com/GanyuanRan/Aegis carefully, identify the correct path for my AI coding host, install Aegis globally, restart or reload the host if needed, and verify that Aegis is fully available, including skill discovery and project workspace support.
If Aegis is already installed, you can ask your AI coding agent to update it for you:
Please update my installed Aegis to the latest main branch version from https://github.com/GanyuanRan/Aegis, using the correct update path for my current AI coding host, then restart or reload the host if needed and verify that Aegis is fully available, including skill discovery and project workspace support.
For smoother host-level behavior, copy the whole block below into your AI coding tool's global user rules. It improves Aegis routing and skill triggering without duplicating the full workflows:
# Aegis Lite Global Rules
If Aegis is installed:
- At the start of each turn, check whether the task matches an installed Aegis
skill. If it matches, load and follow that skill.
- Simple, local, low-risk tasks may use a fast path. Do not expand the full
governance workflow just because Aegis exists.
- Complex, diagnostic, architecture, refactor, contract, cross-module, shared
module, compatibility, or long-running tasks should use the relevant Aegis
workflow by default.
- Before implementation, identify the goal, scope, impact surface, and
verification method. Read project baseline or authority docs when relevant.
- Before claiming completion, provide fresh verification evidence. If
verification is blocked, state the blocker and residual risk.
- Aegis is a method layer, not a final authority system. Do not claim final
gate decisions or completion authority.
- The user's current instruction and the target project's rules take priority
over Aegis guidance.
For stricter teams or governance-heavy projects, you can instead start from the full advanced templates and merge only the parts you need:
Aegis defaults to automatic mode. To switch to manual mode, edit:
~/.config/aegis/config.toml
Windows:
%USERPROFILE%\.config\aegis\config.toml
If the file does not exist, create it manually. Add:
activation_mode = "explicit"
To return to automatic mode, set activation_mode = "auto" or delete the file.
Then restart the host. In explicit mode, supported bootstrap hooks stop
injecting Aegis automatically, while direct skill calls such as
aegis:using-aegis remain available. Host caveats are documented in
docs/current/AEGIS_ACTIVATION_MODE.md.
Aegis is an Architecture-Driven Development (ADD) method pack for AI coding agents.
It builds on the original superpowers methodology and adds evidence-driven governance, TLREF execution flow, and dual-track repair/retirement rules.
In Aegis, ADD means the agent should understand the project's baseline, architecture boundaries, owners, impact surface, compatibility constraints, and verification path before making substantial changes.
Current release shape:
Aegis Method Pack (runtime-ready)
This repository is not the full Aegis Platform. It does not provide authoritative runtime-core decisions, authoritative GateDecision, or completion authority.
AI coding agents are strong at local execution, but long or risky software work often fails for process reasons:
Aegis addresses those problems at the method-pack layer. It makes the agent frame the task, read the relevant baseline, keep evidence close to claims, track repair and retirement together, and maintain resumable checkpoints for long work.
Installing Aegis gives an AI coding tool a stricter development discipline without requiring a new runtime platform:
Aegis keeps the useful parts of superpowers:
Aegis adds a stricter governance spine:
Aegis currently owns:
Aegis does not currently own:
Host AdaptersRuntime CoreGateDecisionFor the current authority map, read:
Aegis keeps the multi-host plugin-installable goal.
Current host-facing status:
| Host | Current status |
| --- | --- |
| Codex | Representative smoke path verified; Git Bash naive smoke still has known observation items |
| OpenCode | Base suite and integration closeout have passed in the current method-pack scope |
| Claude Code | Plugin skeleton and install guide exist; release-level fresh host smoke is still pending |
| CodeBuddy | Plugin skeleton and native SKILL.md manual install guide exist; release-level fresh host smoke is still pending |
| DeepSeek-TUI | Native SKILL.md discovery supports manual Aegis skill install; release-level fresh host smoke is still pending |
| Trae | Native SKILL.md discovery supports manual Aegis skill install; release-level fresh host smoke is still pending |
Other hosts remain product targets, but are not yet current release-level verdicts.
Read:
Aegis can be installed through each host's native discovery or plugin path. A public marketplace listing is not required for the paths below.
After installation and host restart, Aegis skills are discovered automatically. For normal use, users can ask for development work naturally; the agent should select the relevant Aegis method when the task matches a skill. Explicit skill commands are still available when you want to force, test, or debug a workflow.
macOS / Linux:
git clone https://github.com/GanyuanRan/Aegis.git ~/.codex/aegis
mkdir -p ~/.agents/skills
ln -s ~/.codex/aegis/skills ~/.agents/skills/aegis
Windows PowerShell:
git clone https://github.com/GanyuanRan/Aegis.git "$env:USERPROFILE\.codex\aegis"
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
cmd /c mklink /J "$env:USERPROFILE\.agents\skills\aegis" "$env:USERPROFILE\.codex\aegis\skills"
Optional Codex config for subagent-heavy skills:
No comments yet. Be the first to share your thoughts!