Overview

Understand the problem this architecture solves, how it works, and the design decisions behind it.

---

Start Here

• What It Does For You

  ---

  The complete capability map — 20 capabilities across startup, work, and shutdown. See what each one prevents and which level enables it.

Concepts

• The Problem

  ---

  Why unmanaged AI agent sessions fail: context waste, rule drift, and startup chaos. The case for structural enforcement over written instructions.

• Architecture

  ---

  The 5-hook engine (SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, Stop), manifest/sentinel state management, and how tiers work together.

Implementation

• Implementation Levels

  ---

  Four progressive levels from voluntary compliance (Level 1) to full structural enforcement with stop-hook cleanup (Level 4). Start simple, add enforcement as needed.

• Data Store & Platforms

  ---

  YAML files vs SQLite vs PostgreSQL — when to use each. Platform adaptation guides for Claude Code, Cursor, Windsurf, Aider, and custom agents.

Insights

• Lessons Learned

  ---

  Eleven hard-won insights from building this system: documenting is not doing, exit codes lie, gate don't nag, more reasoning = worse faithfulness, and more.

• Slide Deck

  ---

  10-slide visual companion covering the problem, 5-hook engine, tiering strategy, and all 4 levels. Use alongside these pages or share with your team.