Aegis

<strong>Aegis Method Pack</strong>

Baseline-first, evidence-driven workflow discipline for AI coding agents.



<strong>English</strong>
·
<strong>中文</strong>
·
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:

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

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
• Advanced global rules template

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.

Host group	Current status	Start here
Codex, OpenCode	Fresh evidence exists for the current method-pack scope	Codex, OpenCode
Claude Code, CodeBuddy, DeepSeek-TUI, Trae, GitHub Copilot, Qoder, Kimi Code CLI, ZCode	Install guides exist; release-level fresh host smoke is still pending	Claude Code, CodeBuddy, DeepSeek-TUI, Trae, GitHub Copilot, Qoder, Kimi Code CLI, ZCode
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
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
Pi CLI, OpenClaw, Hermes Agent	Structural Agent Skills / SKILL.md skill-host adaptations; release-level fresh host smoke is still pending	Pi CLI, OpenClaw, Hermes Agent
Gemini CLI	Transitional compatibility surface while Antigravity support matures	Compatibility Matrix

Read the current host verdict before making support claims:

• Host compatibility matrix
• Known limitations

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:

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.

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.
• Code necessity before edits: before adding any source-code path, Aegis naturally states why a non-code path is insufficient, what the minimum change boundary is, and then enters code-change; non-trivial source edits use the fuller Change Necessity slot.
• Visible governance, on-demand trace: Aegis naturally exposes the risk it helped control at key governance points. When auditability is requested, it can output a Trace Digest summarizing execution trace, evidence chain, rule effects, skill stability, and verification chain without exposing raw internal reasoning.
• 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
• Workflow Quality Baseline
• Runtime-ready boundary
• Artifact schema 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

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.