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

English · 中文 · Workflow Guide · 工作流程说明

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.

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

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.

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

cd <aegis-method-pack-root>
python scripts/aegis-doctor.py tdd-mode off

Details live in docs/current/AEGIS_TDD_MODE.md.

Aegis keeps a multi-host, plugin-installable distribution goal.

Read the current host verdict before making support claims:

• Host compatibility matrix
• Known limitations

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.

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

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

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.

MIT License. See LICENSE.