How Grid works.
In depth.

What gets installed

Grid installs a single .grid/ directory at your project root. Everything is plain text — Markdown and Python scripts. Nothing executes during installation. No package manager, no daemon, no service.

.grid/
├── system/
│   ├── grid/
│   │   └── SKILL.md             # Session conductor — the bootstrap skill
│   ├── skill-index/
│   │   └── SKILL.md             # Registry of all discovered skills
│   └── maintain-skills/
│       └── SKILL.md             # Rules for keeping skill files accurate
│
├── programs/
│   ├── clu/
│   │   └── SKILL.md             # Session orchestrator and strategic planner
│   ├── tron/
│   │   └── SKILL.md             # Code quality, security, review standards
│   ├── ram/
│   │   ├── SKILL.md             # Issue management and workflow
│   │   └── scripts/             # Helper scripts for issue tracking
│   ├── recognizer/
│   │   ├── SKILL.md             # Skill discovery and knowledge graph builder
│   │   └── scripts/
│   │       └── scan-skills.py   # Walks .grid/ dirs, registers discovered skills
│   ├── dumont/
│   │   └── SKILL.md             # Git conventions and commit standards
│   ├── able/
│   │   ├── SKILL.md             # Session state and task tracking
│   │   └── scripts/
│   │       └── grid-state.py    # Session state, task tracking, skill registry
│   └── anon/
│       └── SKILL.md             # Registry access and program updates
│
└── isos/                        # Your project's knowledge — grows with the work
    └── .gitkeep

Your project's own skills live alongside your code — in .grid/ directories next to the modules they describe. The Recognizer discovers them automatically. The root isos/ directory holds cross-cutting architectural knowledge that doesn't belong to any single module.

Programs vs Isos

Programs come from the Grid registry — installed by Anon, updated from the registry, never project-specific. Isos are authored by your project and never touched by registry updates. This is a deliberate trust boundary: Grid can update itself without ever overwriting your knowledge.

Each program can have a user.md file alongside its SKILL.md — a project-local override for conventions, preferences, and exceptions. Registry updates replace SKILL.md but never touch user.md. After an update, the Grid can review whether the user.md content is still compatible with the updated skill — and help refactor it if needed. Your customizations are preserved and kept coherent.

Where knowledge lives

Skills emerge where the code is. Each module or layer of your project can have its own .grid/ directory — isos live there, co-located with what they describe. The Recognizer walks the full tree and builds the knowledge graph automatically.

your-project/
│
├── .grid/
│   ├── programs/              # Grid core (installed once)
│   └── isos/
│       ├── project/
│       │   └── SKILL.md       # Project overview — goals, stack, key decisions
│       ├── architecture/
│       │   └── SKILL.md       # Cross-cutting design principles and patterns
│       └── security/
│           └── SKILL.md       # Security model — JWT design, CSRF, permissions
│
├── api/
│   ├── .grid/
│   │   └── isos/
│   │       └── rest-layer/
│   │           └── SKILL.md   # REST conventions, endpoint patterns, versioning
│   └── src/
│
├── business/
│   ├── .grid/
│   │   └── isos/
│   │       └── business-layer/
│   │           └── SKILL.md   # Domain model, service boundaries, rules
│   └── src/
│
└── infra/
    ├── .grid/
    │   └── isos/
    │       └── infra/
    │           └── SKILL.md   # Build pipeline, Docker, deployment conventions
    └── ...

The Recognizer discovers all SKILL.md files across the tree and registers them in the skill index. When a session starts, the model loads only what's relevant — architecture loads the project and architecture isos, the REST layer loads its own. Context stays focused, not bloated.

On-demand loading via frontmatter

Every skill file starts with a YAML frontmatter block. The suggests field is the key — it tells the model under what circumstances to load this skill. The model reads the skill index (a lightweight registry of names, descriptions, and suggests) and pulls in skills on demand as the work evolves. Nothing is loaded speculatively.

---
name: rest-layer
description: Load when working on API endpoints, request handling,
             response formats, or versioning conventions.
metadata:
  version: "1.0.0"
  suggests: "new endpoint | api design | request validation
             | response format | versioning | route"
  links:
    - skill: business-layer
      on: "creating or changing an endpoint — business layer defines
           the domain logic the endpoint exposes. Load to keep
           API contracts and domain model aligned."
---

The links field declares relationships between skills — the REST layer knows it should pull in the business layer when designing endpoints. The Recognizer builds a live dependency graph from these declarations. The model follows the graph, loading linked skills when they become relevant — without being explicitly told.

Skills are first-class development artifacts

This is one of Grid's strongest disciplines: skill updates go in the same commit as the code they reflect. A skill that lags behind code doesn't just become outdated — it actively misleads. The model will reason from stale knowledge as confidently as it reasons from accurate knowledge.

The maintain-skills system defines what makes a skill good and when it must change. Before any commit that touches a SKILL.md, Tron runs a quality checklist:

How skill detection works

At session start, the Recognizer walks every directory in the project looking for SKILL.md files. Each discovered skill is registered in Able's skill cache — a lightweight JSON index of paths, names, descriptions, and suggests text.

# Session start — scan and register all skills
python3 .grid/programs/recognizer/scripts/scan-skills.py \
  | python3 .grid/programs/able/scripts/grid-state.py skills --register-batch

# During a session — find skills relevant to the current area
python3 .grid/programs/able/scripts/grid-state.py skills --search "api endpoint"

# Mark a skill as loaded into context
python3 .grid/programs/able/scripts/grid-state.py skills --mark-loaded .grid/isos/rest-layer/SKILL.md

# See what is currently loaded
python3 .grid/programs/able/scripts/grid-state.py skills --loaded

State is stored in .grid/programs/able/assets/state/ — gitignored, session-local, never shared. Four domains, each owned by one program:

The trigger system

Tron doesn't rely on the model remembering to check before a commit. A trigger registry is seeded at init and persists in triggers.json. Before any consequential action — commit, close task, install skill, rewrite history — the model queries the trigger registry for the current phase. If a matching trigger exists, Tron's approval gate fires automatically.

# Check for triggers relevant to the current phase
python3 .grid/programs/able/scripts/grid-state.py triggers --phase commit
python3 .grid/programs/able/scripts/grid-state.py triggers --phase "closing a task"

This turns Grid's guardrails from advisory ("you should load Tron before commits") into structural ("a trigger fires before every commit, regardless of whether you thought of it"). The model cannot skip approval gates under time pressure or convenience — the trigger system ensures they're always consulted.

The live dependency mesh

Cross-links between skills aren't just metadata — they form a traversable graph. Each skill declares its outgoing links in frontmatter. Incoming links (which skills reference this one) are discovered by querying the mesh. Both directions are queryable without loading the skill bodies:

# Show outgoing and incoming links for a skill
python3 .grid/programs/able/scripts/grid-state.py skills --links rest-layer

This means the model can navigate the dependency graph on demand — discovering that changing the business layer might affect the REST layer, or that the security skill is referenced by both the authentication iso and the infra iso. The mesh grows as the project grows, without any manual maintenance beyond writing the links field when an iso is created.

Compaction recovery

AI clients periodically compress conversation history — a process called compaction. When it happens, the model silently loses track of which skills are loaded and what the active workflow step is. Grid is designed to survive this.

Clu owns compaction recovery. One command restores full session awareness:

# Recover after compaction — prints workflow, triggers, loaded skills, active tasks
python3 .grid/programs/able/scripts/grid-state.py recover

Staying current — Anon and the registry

Grid's programs are versioned and can be updated without touching your project's isos or user.md customizations. Anon is the registry manager — it fetches the live registry from GitHub, compares installed versions, and reports what's outdated or available to install.

# Fetch registry and compare against installed versions
# Shows: ✅ installed · ⬆️ outdated · ➕ available · ❓ unknown (user-created)
# → ask the model: "Check for Grid updates"

Anon never caches the registry between sessions — it fetches fresh on each status check. When updating a program, it replaces SKILL.md and any scripts, then re-runs the skill scanner to refresh the registry. user.md files are never touched. User-created isos are never touched.