Context Architecture

# Context Architecture: DAG-Based Progressive Disclosure

## Core Principle

**Agents should only read what they need.** Documents are organized as a directed acyclic graph (DAG) where index files act as hub nodes. An agent reads the index, identifies relevant edges, and follows only those to leaf documents. No agent ever loads the full tree.

---

## The 4-Tier Information Flow

```
refs/ (what IS)  -->  kits/ (what MUST BE)  -->  plans/ (HOW)  -->  impl/ (what WAS DONE)
     Tier 1                  Tier 2                     Tier 3              Tier 4
```

Each tier consumes the previous tier's output. Cross-references between tiers create the DAG edges that agents traverse.

---

## Directory Layout

```
context/
├── CLAUDE.md                              # Root entry node: describes all tiers + design layer
├── refs/                                  # Tier 1: Source material (read-only input)
│   ├── CLAUDE.md                          # "Source of truth. Organized by source. Read-only."
│   └── {source}/                          # Subdirs per source (e.g., prd/, api-spec/)
│       └── ...
├── kits/                            # Tier 2: WHAT to build
│   ├── CLAUDE.md                          # "Start at cavekit-overview.md. R-numbered reqs."
│   ├── cavekit-overview.md              # Index node (DAG hub)
│   ├── cavekit-{domain}.md              # Leaf — simple domain (single file)
│   └── {domain}/                          # Complex domain gets a subdirectory
│       ├── cavekit-{domain}.md          # Domain index (becomes hub node)
│       └── cavekit-{domain}-{sub}.md    # Sub-domain leaves
├── designs/                               # Cross-cutting: visual design system
│   ├── CLAUDE.md                          # "DESIGN.md at project root is canonical."
│   └── design-changelog.md               # Append-only change log
├── plans/                                 # Tier 3: HOW to build (task graphs)
│   ├── CLAUDE.md                          # "Start at plan-overview.md. Task dependency tiers."
│   ├── plan-overview.md                   # Index node
│   ├── build-site.md                      # Primary build site
│   ├── build-site-{feature}.md            # Feature-specific build sites
│   └── {domain}/                          # Complex plans get subdirectories
│       └── plan-{domain}-{area}.md
├── impl/                                  # Tier 4: What WAS DONE
│   ├── CLAUDE.md                          # "Start at impl-overview.md. Update after every session."
│   ├── impl-overview.md                   # Index node
│   ├── impl-{domain}.md                   # Per-domain tracking
│   ├── impl-review-findings.md            # Codex review findings ledger
│   ├── dead-ends.md                       # Failed approaches (shared across domains)
│   └── archive/                           # Compacted/archived tracking
```

> **Note:** `designs/` is a **cross-cutting constraint layer**, not a fifth tier. DESIGN.md (at project root) is read by agents at every Hunt phase — Draft reads it to constrain visual decisions, Architect references tokens in task descriptions, Build uses it for implementation, Inspect validates against it. It parallels how CLAUDE.md files provide conventions, but for visual design.

### Backward Compatibility: sites/ → plans/

Build sites previously lived in `context/sites/`. All Cavekit commands check b