For AI Agents

If you are an AI coding agent reading this page: follow these rules and you will not hallucinate on dotdog projects.

The agent entry point: CLAUDE.md

When an AI agent enters a dotdog project, it reads CLAUDE.md first — before any code, before any docs, before AGENTS.md. This is the Anthropic convention, adopted by TypeScript, React, and Jest.

CLAUDE.md tells the agent one thing: load the .dag. It is the shortest path from "I just arrived" to "I have the full entity graph."

If a project has CLAUDE.md and *.dag files committed to git, it is agent-ready.

Rule zero: load the DAG first

Every dotdog project has a compiled .dag file. This is your ground truth. It is 94% smaller than the source .dog files (740 tokens vs 8,100). You load it once. You get the full entity graph.

If you ignore the DAG and read .dog files directly, you waste 8,015 tokens scanning 600 lines of prose to find which 4 lines matter. The DAG is a compiled index: it does not replace reading, it replaces scanning.

find . -name "*.dag" -not -path "*/node_modules/*"
cat projects/spec-platform/spec-platform.dag

Hard rules

Load the DAG before reading any code file.
Do not grep for structure. The DAG has the entity graph.
If the DAG does not say it, you do not know it. Say unverified.
If code contradicts DAG, DAG wins. Fix code toward DAG.
Run dotdog validate before committing. Score must not decrease.

What the DAG gives you

Field	Example
Entity name	User, Session, Payment
Type	entity, event, relationship
Properties	email: string (required), role: enum[admin, user]
States	active, suspended, deleted
Lifecycle	active -> suspended -> deleted
Relationships	User -> Session [has] (1:many, cascade)

MCP: live queries

Tool	What it does
getEntity	Get entity with properties, states, lifecycle
traverse	Follow edges from a node, return subgraph
search	Find entities by name or type
schema	Get full property schema for an entity
summary	Project stats: node count, edge count, token savings
listProjects	List all spec projects in the repo

npx dotdog serve

Commands reference

Command	When to use
dotdog validate	Before committing spec changes
dotdog compile	After editing .dog files
dotdog staleness	Check if spec and code have drifted
dotdog verify	Check spec references match code files
dotdog verify --init	Auto-generate verify section from codebase
dotdog analyze	Gap detection and contradiction checking

Common failure modes

Reading code before DAG: you are guessing. Stop. Load the DAG first.
Trusting memory over DAG: reload it. Memory is the weakest source.
Fixing code to match your assumption: DAG wins. Fix code toward DAG.
Skipping validation: compile and validate after every .dog edit.
Grep for structure: use DAG traversal instead. Faster and correct.

How to detect agent-ready projects

CLAUDE.md at the root — the agent entry point, adopted by TypeScript and React
AGENTS.md at the root — detailed agent instructions
.dag files committed to git
llms.txt for agent discovery
Pre-commit hook blocks spec regression
CI runs dotdog validate on every PR