DocsConcepts
How it works
What a session reads when it starts, in which order, and how the blueprint keeps a long feature from filling the context window. How one session hands over to the next is in the Session continuity guide.
Context loading order
Every tool loads AGENTS.md from the project root as its instructions. Claude Code loads it through the @AGENTS.md line in CLAUDE.md (a symlink works too); Amp, Cursor CLI, Grok Build, Pi, Hermes, Codex and Antigravity read AGENTS.md directly. From there a session reads, in this order:
AGENTS.md: how work is done here and why, where things are, the skills to use, when to decide and when to askdocs/: the Session Continuity notes and what is in flightcontext/ STATUS.md docs/: the stack and the commands, read before writing codecontext/ CONVENTIONS.md docs/: execution state for resuming work in progress (wave progress, finished tasks)context/ STATE.md docs/andcontext/ GOALS.md DECISIONS.md: what the project is for and what is lockedBACKLOG.md: what is waitingdocs/andsolutions/ docs/: searched before planninglearnings/ blueprint.local.md: which helpers run for this stack- Skills: picked from their descriptions as the work calls for them, or named by you
- Helper prompts: run by the skills that use them, in a helper or inline
In Claude Code and Codex the session-start hook also points the session at STATUS.md; elsewhere AGENTS.md says to read it first.
Context window management
Large features can fill a session’s context. The blueprint has several layers against that:
| Layer | Mechanism | What it does |
|---|---|---|
| Prevention | Helper isolation | Where the tool has subagents, each helper works in a fresh context and the main session sees only its output |
| Detection | context-monitor.js (PostToolUse hook, Claude Code and Codex) |
Warns at 150 tool calls, escalates at 200, and flags eight or more reads in a row without progress |
| Fresh context per iteration | The ship runner | Starts a new headless session per iteration in any tool; state persists through git, the plan file and state.json |
| Session guard | ship-loop.sh (Stop hook, Claude Code and Codex) |
Keeps an interactive ship run from stopping while state.json says running; stands down under the runner |
| Circuit breakers | ab-autonomous-loop |
Stops after three iterations with no progress or five identical errors, notices rising difficulty and churn on the same files, and writes a reflection before every retry |
The runner and the Stop hook solve different problems. The hook catches an interactive session that quits early (same session, growing context). The runner handles a context that is full: a fresh session per iteration with the state on disk, in every tool, with or without hooks.