# buildsomethingai/aegis-framework architecture

> Architecture diagram of the GitHub repository buildsomethingai/aegis-framework, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/buildsomethingai/aegis-framework
- Repository: https://github.com/buildsomethingai/aegis-framework

## Overview

Aegis is a documentation- and configuration-driven framework for collaborative AI-assisted project management. The documented workflow is for people and AI to plan work, manage tasks, preserve project context, and track and validate state. The tree exposes command catalogs, operation definitions, memory files, and task-state directories, but no source excerpts show runtime call paths; relationships below therefore reflect documented capabilities and named responsibilities, not inferred implementation wiring.

Main entry points: [`.context/tasks`](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/tasks) (Task management), [`.context/plan`](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/plan) (AI planning), [`.context/memory/session`](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/session) (Session state), [`COMMANDS.md`](https://github.com/buildsomethingai/aegis-framework/blob/main/COMMANDS.md) (Command catalog)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["Commands and guidance"]
  node_command_catalog["Command catalog<br/>[COMMANDS.md]"]
  node_command_data["Command definitions<br/>[COMMANDS.json]"]
  node_operation_guides["Operation guides<br/>[operations]"]
  node_project_guidance["Framework guidance<br/>[AI_INSTRUCTIONS.md]"]
end

subgraph group_work["Planning and tasks"]
  node_planning["AI planning<br/>[plan]"]
  node_task_lifecycle["Task management<br/>[tasks]"]
  node_task_states[("Task state directories<br/>[active]")]
end

subgraph group_continuity["Memory and state"]
  node_memory_core[("Core memory<br/>[core]")]
  node_project_context[("Project context<br/>[context]")]
  node_session_state[("Session state<br/>[session]")]
  node_state_tracking["State tracking guidance<br/>[STATE_TRACKING.md]"]
end

subgraph group_assurance["Validation and templates"]
  node_validation["Validation rules<br/>[validation.yaml]"]
  node_templates["Work templates<br/>[templates]"]
  node_task_guidance["Task guidance<br/>[README.md]"]
end

node_human(("Human collaborator"))
node_ai(("AI collaborator"))

node_human -->|"uses commands"| node_command_catalog
node_ai -->|"assists planning"| node_planning
node_planning -->|"breaks down work"| node_task_lifecycle
node_human -->|"manages tasks"| node_task_lifecycle
node_task_lifecycle -->|"tracks progress"| node_task_states
node_ai -->|"maintains context"| node_memory_core
node_human -->|"shares context"| node_project_context
node_session_state -->|"records state"| node_state_tracking
node_task_lifecycle -->|"checks consistency"| node_validation
node_task_lifecycle -->|"uses templates"| node_templates
node_ai -->|"follows procedures"| node_operation_guides
node_human -->|"consults guidance"| node_project_guidance

click node_command_catalog "https://github.com/buildsomethingai/aegis-framework/blob/main/COMMANDS.md"
click node_command_data "https://github.com/buildsomethingai/aegis-framework/blob/main/COMMANDS.json"
click node_operation_guides "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/ai/operations"
click node_project_guidance "https://github.com/buildsomethingai/aegis-framework/blob/main/.context/AI_INSTRUCTIONS.md"
click node_planning "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/plan"
click node_task_lifecycle "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/tasks"
click node_task_states "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/tasks/active"
click node_memory_core "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/core"
click node_project_context "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/project/context"
click node_session_state "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/session"
click node_state_tracking "https://github.com/buildsomethingai/aegis-framework/blob/main/.context/memory/STATE_TRACKING.md"
click node_validation "https://github.com/buildsomethingai/aegis-framework/blob/main/.context/ai/operations/validation.yaml"
click node_templates "https://github.com/buildsomethingai/aegis-framework/tree/main/.context/templates"
click node_task_guidance "https://github.com/buildsomethingai/aegis-framework/blob/main/.context/tasks/README.md"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_command_catalog,node_command_data,node_operation_guides,node_project_guidance toneBlue
class node_planning,node_task_lifecycle,node_task_states toneAmber
class node_memory_core,node_project_context,node_session_state,node_state_tracking toneMint
class node_validation,node_templates,node_task_guidance toneRose
class node_human,node_ai toneIndigo
```

## Components

### Commands and guidance

- [Command catalog](https://github.com/buildsomethingai/aegis-framework/blob/main/COMMANDS.md): `COMMANDS.md`
- [Command definitions](https://github.com/buildsomethingai/aegis-framework/blob/main/COMMANDS.json): `COMMANDS.json`
- [Operation guides](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/ai/operations): `.context/ai/operations`
- [Framework guidance](https://github.com/buildsomethingai/aegis-framework/blob/main/.context/AI_INSTRUCTIONS.md): `.context/AI_INSTRUCTIONS.md`

### Planning and tasks

- [AI planning](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/plan): `.context/plan`
- [Task management](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/tasks): `.context/tasks`
- [Task state directories](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/tasks/active): `.context/tasks/active`

### Memory and state

- [Core memory](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/core): `.context/memory/core`
- [Project context](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/project/context): `.context/memory/project/context`
- [Session state](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/memory/session): `.context/memory/session`
- [State tracking guidance](https://github.com/buildsomethingai/aegis-framework/blob/main/.context/memory/STATE_TRACKING.md): `.context/memory/STATE_TRACKING.md`

### Validation and templates

- [Validation rules](https://github.com/buildsomethingai/aegis-framework/blob/main/.context/ai/operations/validation.yaml): `.context/ai/operations/validation.yaml`
- [Work templates](https://github.com/buildsomethingai/aegis-framework/tree/main/.context/templates): `.context/templates`
- [Task guidance](https://github.com/buildsomethingai/aegis-framework/blob/main/.context/tasks/README.md): `.context/tasks/README.md`

### Other components

- **Human collaborator**
- **AI collaborator**

## Connections

- Human collaborator → Command catalog: uses commands
- AI collaborator → AI planning: assists planning
- AI planning → Task management: breaks down work
- Human collaborator → Task management: manages tasks
- Task management → Task state directories: tracks progress
- AI collaborator → Core memory: maintains context
- Human collaborator → Project context: shares context
- Session state → State tracking guidance: records state
- Task management → Validation rules: checks consistency
- Task management → Work templates: uses templates
- AI collaborator → Operation guides: follows procedures
- Human collaborator → Framework guidance: consults guidance