AI coding agents are getting much better at writing code.
But in real engineering work, the hard problems are often not just about whether the model can generate a patch.
The harder questions are:
- Did it read the right project baseline first?
- Did it understand the actual owner of the behavior?
- Did it verify the fix before claiming completion?
- Did it distinguish facts from assumptions?
- Did it preserve architecture boundaries?
- Did it leave enough evidence for a human or another agent to continue safely?
I built Aegis to work on that layer.
GitHub: https://github.com/GanyuanRan/Aegis
What is Aegis?
Aegis is an open-source method pack for AI coding agents.
It is not a new model.
It is not an IDE.
It is not a runtime core or an authoritative gate.
Instead, Aegis provides workflow discipline that can be installed into different AI coding hosts.
The current positioning is:
Aegis Method Pack: runtime-ready workflow discipline for AI coding agents.
That means Aegis focuses on the behaviors around the coding agent:
- how it starts a task
- how it reads project context
- how it plans
- how it debugs
- how it applies TDD
- how it verifies completion
- how it reports residual risk
- how it avoids pretending that a method-layer checklist is runtime authority
Why I built it
When working with AI coding agents, I kept seeing the same failure patterns.
The agent would often:
- skip the architecture baseline
- patch the consumer instead of the canonical owner
- add another fallback instead of retiring the old path
- pass one narrow test and claim the whole task was done
- forget to report architecture drift
- lose the user's requested language or output format
- treat logs or tool output as prompt payload instead of evidence
- confuse the target project with the installed method-pack support path
These issues are not solved only by writing better prompts.
They need repeatable workflow pressure.
What Aegis includes
Aegis currently includes workflow guidance for:
- baseline-first project context
- brainstorming and design clarification
- first-principles review
- writing implementation plans
- test-driven development
- systematic debugging
- long-task continuation
- verification before completion
- architecture alignment reporting
- ADR backfill checks
- cross-host method-pack installation guidance
The goal is not to make the agent more verbose.
The goal is to make the agent less likely to skip the boring steps that protect real projects.
Example: verification before completion
Aegis treats completion claims as something that must be backed by evidence.
Instead of saying:
Done, should work now.
Aegis pushes the agent toward a compact evidence shape:
Evidence Card:
- Command / Check:
- Exit Status:
- Covered:
- Not Covered:
- Residual Risk:
- Confidence:
For architecture-sensitive work, it also asks for an explicit architecture alignment result:
Architecture Alignment:
- Trigger:
- Scope:
- Baseline checked:
- Result: aligned | architecture drift | architecture defect
- Evidence:
- Residual architecture risk:
This is still advisory method-pack discipline.
It does not grant final authority.
It does not become a runtime GateDecision.
It simply makes skipped reasoning harder to hide.
Example: workspace helper boundaries
One recent fix in Aegis was about a subtle but important boundary.
A method-pack helper should belong to the installed Aegis method-pack path.
The target project should be passed separately:
python <aegis-workspace-helper> check --root <target-project-root>
That sounds small, but it prevents agents from assuming that every project repository must contain its own scripts/aegis-workspace.py.
This is the kind of problem Aegis tries to catch: not just whether a command exists, but whether the ownership model is correct.
What Aegis is not
Aegis deliberately does not claim to be a full runtime platform.
It does not own:
- authoritative runtime core decisions
- authoritative
GateDecision - authoritative
PolicySnapshot - final completion authority
That boundary matters.
A method pack can improve behavior, structure evidence, and make workflows more reliable.
But it should not pretend to be the final source of truth for a project.
The target project's rules, architecture baseline, ADRs, and human decisions still matter.
Who might find this useful?
Aegis may be useful if you:
- use AI coding agents on real codebases
- care about architecture drift
- want stronger verification before completion claims
- want repeatable debugging and TDD workflows
- work across multiple agent hosts
- want agents to preserve project-specific rules instead of inventing new owners
It is probably less useful if you only want a lightweight one-shot coding assistant for small isolated snippets.
Try it
The repo is here:
https://github.com/GanyuanRan/Aegis
The README includes host-specific install notes and verification commands.
A typical verification path includes:
python scripts/aegis-doctor.py --write-config --json
bash tests/e2e/layer1-fast-check.sh --host-profile none
The project is still evolving, and feedback is welcome.
I am especially interested in feedback on:
- whether the method-pack boundary is clear
- whether the install flow is understandable
- which AI coding workflows should be hardened next
- what failure modes people see most often in real agent-assisted development
Closing thought
AI coding agents are no longer just code generators.
They are becoming collaborators in planning, debugging, refactoring, verification, and handoff.
That means the surrounding workflow matters.
Aegis is my attempt to make that workflow more explicit, testable, and reusable.
Disclosure: I used AI assistance to draft and edit this post, then reviewed and adapted it before publishing.
Top comments (3)
v2.3.5 (2026-07-04)
TDD Default Mode
Changed Aegis TDD mode to default to off across aegis-doctor, host
bootstrap hooks, OpenCode integration, and public documentation.
Kept automatic TDD routing available as an explicit opt-in through
tdd-mode auto, AEGIS_TDD_MODE=auto, or direct query markers such as
TDD Route: strict, strict TDD, test-first, and
RED / GREEN / REFACTOR.
Preserved verification-before-completion in both off and auto modes so
turning off automatic TDD never weakens completion evidence.
Complexity Governance
Recalibrated 800+ line maintained artifacts as soft pressure signals rather
than automatic edit bans.
Added stronger pressure signals for 1200+ line maintained artifacts and files
in the largest 5-10% of a target project.
Added Pre-Edit Owner-Fit Decision to implementation workflows so overloaded
or mixed-purpose owners classify edit intent before non-trivial source edits.
Clarified that new-responsibility should not be added in place to an
over-budget or mixed-purpose owner by default.
Added Completion-Time Complexity Repair Decision so completion-time
complexity overruns are classified as govern-now, follow-up-required, or
not-complete before additional owner extraction or scope expansion.
Final Output Semantics
Updated the process baseline to treat Facts -> Inferences -> Conclusions as
an information-ordering principle instead of a fixed top-level response
template.
Renamed Final Output Contract to Final Output Semantic Slots / Attention Anchors and clarified that these anchors must not override workflow-owned
output structures such as findings-first code review, verification evidence
slots, repair/retirement closure, complexity closure, Aegis Visibility,
Execution Readiness View, or requested Trace Digest.
Updated the global user rules template shipped by Aegis with the same
anti-template guidance for future host configuration.
Regression Coverage
Expanded workflow-quality checks for default-off TDD mode, explicit TDD query
markers, pre-edit owner-fit decisions, completion-time complexity repair
decisions, and final-output semantic slots.
Updated the workflow-quality matrix and validator so owner-fit and
completion-time complexity decisions remain part of the expected workflow
contracts.
Updated activation-mode, TDD-policy, doctor, and workspace helper tests for
the default-off TDD configuration.
Verification
Fresh checks passed:
bash scripts/bump-version.sh 2.3.5,
bash scripts/bump-version.sh --check,
python tests/helpers/test_parse_codex_skills.py,
python -m pytest tests/helpers -q,
bash tests/e2e/workflow-quality-check.sh,
bash tests/e2e/tdd-policy-check.sh,
bash tests/e2e/activation-mode-check.sh,
bash tests/e2e/aegis-doctor-check.sh,
bash tests/e2e/context-budget-check.sh,
bash tests/e2e/boundary-compliance-check.sh, and
git diff --check.
Release Surface
Bumped declared package and host manifest versions from 2.3.4 to 2.3.5.
This release still ships Aegis Method Pack (runtime-ready). It does not add
authoritative GateDecision, PolicySnapshot, or completion authority.
Happy to answer questions about the method-pack boundary, host support, or the workflow checks. I am especially looking for feedback from people using coding agents on real codebases.
Some comments may only be visible to logged-in visitors. Sign in to view all comments.