Aegis — Summary

Aegis is an AI-powered project management framework delivered as a .context/ folder drop-in that gives any AI assistant a shared understanding of project state, tasks, decisions, and sessions through structured markdown files and a /aegis command vocabulary.

Problem it solves: AI coding assistants lose context between sessions, lack a consistent way to track task state transitions, and have no shared memory of architectural decisions; Aegis imposes a .context/ directory convention with YAML-driven operation patterns (plan.yaml, task.yaml, etc.) so the agent always knows the project's current position.

Distinctive trait: All /aegis commands are interpreted by the AI, not executed in a terminal — they are protocol-level instructions that tell the AI how to update structured markdown files, enforcing a strict checklist before claiming any command complete.

Target audience: Individual developers and small teams using any AI assistant who want a consistent project state machine (planned → active → hold → completed) with human-readable audit trails stored in .context/sessions/ and .context/decisions/.

Production-readiness: Alpha-quality (60 GitHub stars), maintained by BuildSomethingAI, MIT licensed, last pushed May 2025.

Differs from seeds: Closest to agent-os (Archetype 4 — markdown-scaffold, zero-binary primitives); Aegis adds YAML operation specs in .context/ai/operations/ that define each command's validation, execution, and output steps more rigorously than agent-os's standards/ folder, but both rely entirely on the AI reading files rather than a CLI enforcing behavior.

Aegis — Overview

Origin

BuildSomethingAI, a startup building AI-assisted development tooling, released Aegis as an open-source framework (MIT). It ships as a single GitHub repo whose payload is entirely a .context/ folder and a COMMANDS.md reference. There is no separate SDK, CLI package, or IDE extension.

Philosophy

Aegis is built on a collaborative philosophy where humans and AI work together with a shared understanding of principles and practices. The README states documentation is dual-purpose: it guides Aegis's behavior while serving as a human reference. The framework's core bet is that transparent operation — documenting not just what to do, but why — yields more reliable AI behavior than opaque instructions.

Manifesto-style quotes (verbatim from AI_INSTRUCTIONS.md)

"CRITICAL: These rules must be followed for all command operations"

"/aegis commands are NEVER executed directly in the terminal — These commands are interpreted by the AI assistant, not the shell"

"If a step fails, retry with more specific instructions. If a file update fails, check permissions and retry. If validation fails, fix the issues before proceeding. Never skip steps in the command implementation."

"Common Failure Points: Incomplete command implementation, Missing decision records, Missing self-improvement updates, Outdated timestamps, Inconsistent state files"

Design Choices

• YAML operation files in .context/ai/operations/ describe each command's steps declaratively — the AI reads these as operational contracts
• Tasks move between filesystem folders (planned/, active/, hold/, completed/) using mv, never cp — the file's location IS its state
• Self-improvement records are first-class artifacts; the agent is expected to learn and write reflections into the memory system
• All commands have mandatory checklists with [ ] boxes the agent must mentally complete before claiming success

Aegis — Architecture

Distribution

Standalone GitHub repo. No npm package, no pip package, no CLI binary. Install = clone/copy the .context/ folder into your project.

Install

# Clone or download, then copy .context/ into your project root
cp -r aegis-framework/.context /path/to/your-project/

Directory Tree

.context/
├── AI_INSTRUCTIONS.md           # Master instruction set for the AI
├── README.md                    # Human quick reference
├── ai/
│   └── operations/              # YAML command specs
│       ├── context.yaml
│       ├── help.yaml
│       ├── plan.yaml
│       ├── reconcile.yaml
│       ├── save.yaml
│       ├── session_triggers.yaml
│       ├── start.yaml
│       ├── status.yaml
│       ├── task.yaml
│       ├── task_creation.yaml
│       ├── task_transition.yaml
│       └── validation.yaml
├── memory/
│   ├── core/                    # Framework-level memory
│   ├── project/                 # Project context & decisions
│   └── session/                 # Active session state
├── templates/
│   ├── tasks/TEMPLATE.md
│   ├── sessions/TEMPLATE.md
│   └── decisions/TEMPLATE.md
├── tasks/
│   ├── planned/
│   ├── active/
│   ├── hold/
│   └── completed/
├── sessions/                    # Session logs
├── decisions/                   # Architectural decisions
└── plan/
    └── planning_document.md

Also ships COMMANDS.md and COMMANDS.json at root as human quick-reference cards.

Required Runtime

None. Pure markdown + YAML files. Any AI assistant that can read files works.

Target AI Tools

Any (Claude Code, Cursor, ChatGPT, Copilot). Cross-tool portability is high by design — the entire framework is passive markdown.

Config Files

• .context/AI_INSTRUCTIONS.md — primary agent instructions
• .context/ai/operations/*.yaml — per-command operation specs
• COMMANDS.md — human+AI reference

Aegis — Components

Commands (AI-interpreted slash commands — 8 total)

All commands use the /aegis prefix and are interpreted by the AI, not executed in a shell.

Operation Specs (YAML files in .context/ai/operations/)

Templates

Memory System

Scripts / Hooks

None — no programmatic hooks or scripts. All behavior is AI-interpreted.

Aegis — Uniqueness

Differs from Seeds

Aegis is most similar to agent-os (Archetype 4 — markdown scaffold). Both drop structured markdown files into a project and rely on the AI to read them; neither ships a CLI, MCP server, or hooks. Aegis's distinguishing delta is its YAML operation specification layer in .context/ai/operations/: each command is defined as a declarative YAML contract with validation steps, execution steps, and output requirements — something agent-os lacks entirely. Aegis also treats self-improvement records as first-class artifacts (the AI is instructed to write lessons-learned after every save), whereas agent-os is purely passive context. Compared to BMAD-METHOD, Aegis has no persona model and no skills system; it is simpler and more PM-focused than BMAD's persona-driven approach. Compared to superpowers, Aegis has no autonomous activation (no hooks), no TDD enforcement, and no git workflow automation — it is purely a project state tracking layer.

Positioning

Aegis positions itself as a "collaborative framework" — a shared protocol between human and AI for maintaining project state. It is not a coding agent harness, it is a PM/state-management overlay that any AI can use without being Claude Code-specific.

Distinctive Opinion

The YAML operation specs in .context/ai/operations/ are Aegis's most opinionated feature: by separating command definition (the YAML) from command instructions (AI_INSTRUCTIONS.md), Aegis creates a dual-layer specification that lets you modify command behavior without rewriting the master instruction file.

Observable Failure Modes

1. Token overhead: Loading all .context/ files at session start can consume significant context; mitigated by /aegis context (quick refresh) vs /aegis start (full load)
2. AI discipline dependency: The entire framework relies on the AI following the checklists faithfully; a non-compliant AI or truncated context window will silently skip steps
3. No enforcement: Since there are no hooks or tests, there is no way to verify the AI actually completed all checklist items — it self-reports
4. Timestamp staleness: The instructions warn repeatedly about "always use current year" — a symptom that AI models sometimes write stale timestamps