towerwatch-ops-agent: Instructions file for Claude Code

CLAUDE.md

Budget: 115 lines / ~1,600 tokens (limit: 150 lines, per spec-ai-native-repo-layer.md). Measured 2026-07-26. Deep context lives in docs/ and loads on demand — this file stays a map, never a manual. Re-measure when you edit it.

Agent-facing guide. The user-facing README is imported below and is the source of truth for the project story, the three-phase map, and the toolchain — read it first, then come back here for the agent-only notes.

@README.md

---

Repo state — read before reasoning about code

Implementation is partial — check the tree before assuming. The server, config, domain, and telemetry layers exist, and query_metrics is the only tool built of the seven in docs/design/. Do not reference, import, or assume the existence of any tool, module, function, or eval you have not confirmed on disk: the remaining six tools and the eval suite are still contract-only.

fixtures/stub/ is a stub, not the corpus. Two hand-authored windows proving the format and the code path. Any number read from it is illustrative, never evidence.

RATIONALE.md records choices that read as defects. Append-only, one dated entry per deliberate decision a reviewer would otherwise flag. Check it before reporting a finding, and add an entry when a refuted finding would recur.

What does exist is the contract layer. When asked to build, work from docs/design/ (the locked tool contracts) and docs/adr/ (the decisions behind them) — not from memory of "what the code probably does," and not from the Phase 1 spec's candidate tool table, which docs/design/ supersedes.

docs/specs/ is frozen. Never edit a spec to reflect something learned later: the README's "requirements defined upfront" claim depends on them being unmodified, and a reader must be able to tell requirement from backfill. Learnings land in docs/design/ (contract) or docs/adr/ (decision), which already win on conflict.