Skip to content

Keeper

The agent that prevents new code from becoming legacy.

What it does

The Keeper closes the feedback loop between Aegis Spec-generated specs and the day-to-day code changes a developer makes. It runs in two modes — one before a change (read-only briefing) and one after (updates specs, changelog, and the drift dashboard).

Why it exists

Aegis Spec generates specs from existing legacy code. But once those specs exist, code keeps changing. Without a guardian, specs drift out of sync within weeks and become as useless as the absent documentation Aegis Spec was meant to replace.

The Keeper is that guardian. It treats specs as active sources of truth, not snapshots.

Two modes

before <description-or-files>

Read-only briefing. Use this before you start a change.

/aegis-keeper before lib/auth/login.js
/aegis-keeper before "vou adicionar rate limiting no login"

The agent: 1. Reads aegis/traceability/code-spec-matrix.md to find which specs cover the affected files 2. Reads only those specs (token-aware — does not scan everything) 3. Surfaces the contracts, invariants, and business rules the change must respect 4. Asks if your planned change still respects them 5. Writes nothing — purely informative

after

Default mode if there are uncommitted changes or queued hook events. Use this after you finish a change.

/aegis-keeper after
/aegis-keeper            # also defaults to after when there's a queue

The agent: 1. Collects modified files from git diff HEAD and (if hooks installed) aegis/runtime/queue/keeper-queue.jsonl 2. Maps files to impacted specs via code-spec-matrix.md 3. Asks 3 short questions: Why the change, any breaking impact, extra context 4. Updates each impacted spec in-place, reclassifies confidence (🟢/🟡/🔴) per the rules in references/drift-rules.md 5. Appends an entry to <output_folder>/changelog/YYYY-MM-DD.md 6. Updates <output_folder>/reports/drift.md (the dashboard) 7. Cleans the processed entries from the queue

Outputs

File When
aegis/changelog/YYYY-MM-DD.md Mode after, always
aegis/specs/sdd/[component].md Mode after, updated in-place if impacted
aegis/traceability/code-spec-matrix.md Mode after, when files added/deleted
aegis/reports/drift.md Mode after, always (the dashboard)
aegis/config/state.json Mode after, checkpoint

Mode before writes nothing.

Drift detection rules (summary)

The Keeper classifies code changes into 5 categories — each with a different update strategy. Full rules in references/drift-rules.md.

Category What it is Action
Trivial Refactor, rename, optimization without contract change Update spec, keep confidence
Incremental New function / branch / validation Add new section to spec
Structural Signature, return type, status code changed Update spec + breaking change note
Semantic Code violates a business rule from domain.md Pause and ask — bug or intentional?
Deletion Code removed Mark spec section as ~~deprecated~~, do not delete history

Confidence reclassification

After processing a change, the Keeper may upgrade or downgrade confidence on existing spec statements:

  • 🟢 → 🟢: change confirms what the spec said
  • 🟢 → 🟡: change made the previously-confirmed claim only partially true
  • 🟡 → 🟢: change provides direct evidence for what was inferred
  • ✕ → 🔴: change introduces a gap (e.g. references env var or feature flag not visible)

Manual vs automated trigger

You can run the Keeper manually via /aegis-keeper at any time — works on every supported engine without any setup.

For automatic invocation when files are edited, install hooks via npx aegis-spec add-hooks. Hooks queue change events to aegis/runtime/queue/keeper-queue.jsonl and pre-fill stub entries in the changelog. The next time you run /aegis-keeper after, the agent enriches them with the 3 questions and updates specs.

When NOT to run

  • Without aegis/: run /aegis first to bootstrap
  • Without code-spec-matrix.md: run /aegis-architect or /aegis-writer first
  • Without code changes (queue empty + git diff clean): nothing to do

Integration with the rest of the team

The Keeper complements but does not replace the other agents:

  • Reviewer validates specs initially and finds internal contradictions — the Keeper keeps them up to date afterwards
  • Archaeologist does deep one-shot analysis — the Keeper does small, frequent, incremental updates
  • Architect synthesizes diagrams — the Keeper flags when an architectural change should trigger a re-run

If the Keeper detects a change that affects more than 5 specs at once, or touches entry points / DI containers / database schemas, it suggests escalating to Reviewer / Architect / Data Master.