Context Loss

AI agents operate with limited context windows. Without documentation, the agent reads code, guesses the design intent, and may violate unstated constraints. Example: "Don't make the WebSocket upgrade async" (learned by breaking it repeatedly). With ACE, the agent reads the gotcha first.

Design Drift

Codebases evolve, but the reasoning behind decisions lives only in tribal knowledge. "Routes go in /routes/, not in router.ts" is an invisible convention. "This was split from X because of Y" is lost to git history. "Cookie name is hardcoded": changing this breaks existing sessions.

Wasted Tokens

Every mistake an agent makes costs tokens to fix. Identified waste: reading to understand, debugging preventable gotchas, re-asking for context. Tokens spent on docs are always less than tokens wasted on mistakes.

YAML frontmatter

• file: filename this ACE describes (required)
• created: creation date YYYY-MM-DD (required)
• lastModified: last significant modification (required)
• consumers: files that import this file (optional)
• produces: what this file outputs/exports (optional)
• deprecated: boolean flag (optional)

Body sections

• Purpose: single paragraph, role and intent
• Key Functions: exports with signatures and descriptions
• Dependencies: import list with purposes
• Gotchas: tribal knowledge and traps to avoid
• API Contracts: TypeScript interfaces / data shapes
• Change History: dated entries with WHY and Impact

Token limit

5,000 tokens (~3,750 words, ~20 KB). Agents process this reliably without losing focus. The limit forces clarity. You cannot document bloated code. Split it first.

Change history format

YYYY-MM-DD — Brief title / Why: the reason / Impact: what this means for consumers

Real example

---
file: console-websocket.ts
created: 2025-01-15
lastModified: 2026-04-15
consumers:
  - src/main.ts
produces:
  - ConsoleWebSocketHandler
---

# Purpose
Handles WebSocket upgrades and bidirectional message routing for the
AI console. Bridges the HTTP server (konui) to the bridge relay
client, enabling in-browser AI sessions without a persistent connection.

# Architecture
handleUpgrade(req, conn)
  └── authenticate session token
  └── upgrade HTTP → WebSocket
  └── attach message handlers
      ├── inbound:  browser msg  → bridge relay
      └── outbound: bridge relay → browser

# Gotchas
- Do not make handleUpgrade async. The HTTP upgrade must happen
  synchronously or the connection drops before upgrade completes.
- Never write to stdout inside WebSocket handlers. gvmcp reads
  stdio for MCP protocol — any stdout output corrupts JSON-RPC.
- Session tokens expire after 15 min of inactivity. Re-auth on
  reconnect. Do not cache stale tokens across WebSocket restarts.

# Change History
2026-04-15 — Add session affinity header
  Why: bridge relay must route reconnects to same node
  Impact: clients must send X-Session-Affinity on reconnect

2026-01-20 — Split from router.ts
  Why: WebSocket lifecycle too complex to inline in request handler
  Impact: import ConsoleWebSocketHandler from this file

YAML frontmatter

• folder: folder name (required)
• type: service, module, library, or config (required)
• entryPoint: main file if runnable (optional)
• port: port number if service (optional)

Body sections

• Purpose: module's role in the overall architecture
• Design Intent: patterns used, what belongs here, what does not
• Key Components: files and their roles
• Dependency Graph: ASCII architecture diagrams
• Gotchas: module-level warnings
• Workflows: multi-step procedures
• Change History: architectural decisions with reasoning

Folder ACEs sit at the root of each module. Agents read the folder ACE before any file ACE in that module.

• ACE-First: Every file has a design document. For new code, write the .ace first, then implement. For existing code, always read the .ace before reading the code. Not optional.
• Locality of Documentation: Documentation lives next to the code it describes. Not buried in /docs. Not scattered across wikis. Right there.
• Change History with "Why": The ACE file tracks significant changes. Not what changed (git does that). Why it changed.
• Token Efficiency: ACE files are optimised for agent consumption. Max 5,000 tokens. Structured sections. No prose padding.
• Procedural Knowledge: ACE captures not just what code does, but how to perform multi-step operations. Workflows, sequences, gotchas.
• Agent Authorship: The agent writes and maintains .ace files. Humans prompt and review. The agent creates structured docs with purpose, functions, dependencies, and gotchas.

Creating new code

• Write the .ace file first
• Implement the code
• Verify code matches the design in the .ace
• Commit both files together

Modifying existing code

• Read the .ace file
• Read the code
• Update the .ace file
• Update the code
• Commit both together

When to update the ACE

Do update: new or removed exports, new dependencies, discovered gotchas, breaking changes, bug fixes with insight.

Do not update: internal refactors, typo fixes, adding comments.

• Kernel Rules: compiled into every agent's context via the gvContext asset pipeline. Cannot be disabled.
• Turn-Context Reinforcement: per-turn macros injected into every turn's context. Rules sharp at turn 1, still sharp at turn 15.
• Post-Turn Validation: analyses which code files were edited and whether the corresponding ACE was read first.
• Git Pre-Commit Hooks: blocks commits that modify code without updating the corresponding ACE file.
• Drift Detection: tracks compliance metrics per session and alerts on degradation.

Compliance targets

• ACE read rate: > 95%
• ACE update rate: > 80%
• New file ACE rate: 100%
• Stale ACE files: < 5%

Plus 83 folder.ace files providing module-level architecture documentation. Total: 927.