Skip to content

Configuration

Aegis Spec stores all its configuration and analysis state inside the aegis/ folder at the project root. You can open and edit the files whenever you want.

The aegis/ folder structure

aegis/
├── config/
│   ├── state.json              ← analysis state between sessions
│   ├── config.toml             ← project configuration
│   ├── config.user.toml        ← your personal preferences (don't commit)
│   ├── manifest.yaml           ← installation metadata
│   └── files-manifest.json     ← SHA-256 hashes for safe updates
├── plan.md                     ← exploration plan (you can edit this)
├── version                     ← installed Aegis Spec version
├── runtime/
│   └── context/
│       ├── surface.json        ← data generated by Scout
│       └── modules.json        ← data generated by Archaeologist
├── specs/                      ← generated specs (sdd, adrs, openapi, …)
└── reports/                    ← generated reports (drift, gaps, …)

config.toml: project configuration

Created during installation. Defines settings shared with the team:

[project]
name = "my-project"
language = "en"

[agents]
installed = ["aegis", "scout", "archaeologist", "detective", "architect", "writer", "reviewer"]

[output]
folder = "aegis"

[engines]
active = ["claude-code"]

You can change the output folder if you prefer a different name than aegis.

config.user.toml: personal preferences

For preferences that are yours and shouldn't be committed:

[user]
name = "Your Name"
answer_mode = "chat"  # "chat" or "file"

Don't commit

Add config.user.toml to .gitignore. Each team member can have their own preferences without affecting others.

plan.md: exploration plan

Aegis Spec generates this file in the first session, after talking with you about the project. It lists the analysis tasks in order.

You can edit it directly: reorder tasks, remove modules you don't want to analyze, add notes. Aegis Spec will respect whatever is here when it resumes.

Answer mode (answer_mode)

Controls how the Reviewer raises validation questions for you:

Mode Behavior
chat (default) Questions appear in the chat, one by one. You answer in the conversation.
file The Reviewer generates a aegis/reports/questions.md file with all questions. You fill it in and notify when done.

The file mode is useful when there are many questions and you want to answer at your own pace, outside the session.

Documentation level (doc_level)

Defines the volume of artifacts each agent generates during the analysis. Not configured at install time: Aegis Spec asks at the start of the first analysis session, after the Scout maps the project, so you can decide with real information in hand.

Value When to use Artifacts generated
essencial Simple projects, scripts, prototypes (default) Code analysis, domain, architecture (C4 context), SDD specs
completo Medium projects, small teams Everything in essential + full C4 diagrams, ERD, ADRs, OpenAPI, user stories, traceability matrices
detalhado Enterprise systems, high criticality Everything in complete + per-function flowcharts, expanded ADRs, deployment diagram, mandatory cross-review

The choice is saved in aegis/config/state.json under the doc_level field. You can edit it manually at any time to adjust the level mid-analysis.