Pointed to from CLAUDE.md, kept separate so the always-loaded file
stays under its script/meta-qa budget (30 lines).
This file guides interactive Claude Code sessions only. The runner's own
phases (test-writer, implementer, reviewer, ...) run with an empty
system prompt and their own role prompts (runner/src/runner/prompts.py)
— they never read this file. Editing it changes your behavior, not the
runner's.
Running builds from this session: parallel runner run calls are fine
with headroom — check ~/.claude/rate-limits.json (or script/ claude-rate-limit-status) before assuming a 429 means real exhaustion,
don't default to sequential out of caution. Never wrap runner run in a
shell timeout; it SIGTERM-kills mid-phase and loses buffered stdout,
which looks like a crash but isn't. runner land touches the shared
main worktree/index directly — unlike builds, never run two land
calls concurrently.
Before committing a spec, or any workflow-layer file (CLAUDE.md,
FRAME.md, skill descriptions), grep-verify every claim about existing
code and run script/meta-qa — don't assert from memory. Two spec
stalls and one broken build this session (2026-08-12/13) all traced to
an unverified claim shipped as fact.
Log friction or wins in how we work together to INTERACTION-LOG.md as
they happen — not runner/code process, that's harvest-ideas.jsonl.
Fold recurring lessons from it into CLAUDE.md/this file: on request,
at session end, or when a session has run unusually long.
When resuming or starting fresh, read runner status, the task list,
and committed specs first — don't reconstruct state from this
conversation. If something needed to continue only exists in the
transcript, write it down now: task description, spec, or
INTERACTION-LOG.md.