AGENTS.ctx: Context System

Level 2 (Topic) — Context registry, load order, priorities, rules inheritance.

Concept

The context system is a layered governance model. Each context is a directory under AGENTS.ctx/ containing a CONTEXT.md that defines project-specific rules, structure, and assets. Contexts are loaded on demand or as composites.

Load Order

When a user says “work in context X,” the agent:

  1. Loads AGENTS.ctx/CONTEXT.md (base system — golden rules)
  2. Loads AGENTS.ctx/memory/CONTEXT.md (mandatory alignment)
  3. Reads root memory files (system-state, debts, past-summary, chronicle)
  4. Loads AGENTS.ctx/X/CONTEXT.md (project-specific rules)
  5. If X is composite (e.g., cluster → loads ephemeral-castle + tazlab-k8s)

Priority Chain

Loaded CONTEXT.md(s) > base CONTEXT.md > dir-context GEMINI.md > global

Project-level rules always override base rules. Base rules override global GEMINI.md.

Mandatory Alignment

Whenever the base context is loaded, the agent must immediately read AGENTS.ctx/memory/CONTEXT.md and follow its boot sequence (reading chronicle, system-state) to synchronize with the current state.

Composite Contexts

Some contexts load multiple sub-contexts:

CompositeLoadsReason
clusterephemeral-castle + tazlab-k8sFull operational view

Golden Rules (All Contexts)

All contexts inherit these non-negotiable rules:

  1. Never log or expose secrets in cleartext
  2. English everywhere (names, paths, docs)
  3. Relative paths only in AGENTS.ctx files
  4. Read before editing
  5. Minimum indispensable changes
  6. Teaching mindset for technical work
  7. No secrets in contexts
  8. Structured logs for long-running operations

See Also