# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project status

Greenfield Python 3.14 project. As of this writing the codebase is a stub: `main.py` prints a hello message, `pyproject.toml` declares no dependencies, and `README.md` is empty. There is no application architecture yet — design decisions are still open.

## BASIC RULES

### Rule 1 — Think Before Coding

State assumptions explicitly. If uncertain, ask rather than guess.
Push back when a simpler approach exists. Stop when confused.

### Rule 2 — Simplicity First

Minimum code that solves the problem. Nothing speculative.
No features beyond what was asked. No abstractions for single-use code.

### Rule 3 — Surgical Changes

Touch only what you must. Clean up only your own mess.
Don't "improve" adjacent code, comments, or formatting. Match existing style.

### Rule 4 — Goal-Driven Execution

Define success criteria. Loop until verified.
Don't follow steps. Define success and iterate independently.

### Rule 5 — Token budgets are not advisory

Per-task: 4,000 tokens. Per-session: 30,000 tokens.
If approaching budget, summarize and start fresh. Surface the breach.

### Rule 6 — Read before you write

Before adding code, read exports, immediate callers, shared utilities.
If unsure why code is structured a certain way, ask.

### Rule 7 — Checkpoint after every significant step

Summarize what was done, what's verified, what's left.
Don't continue from a state you can't describe back. Stop and restate.

### Rule 8 — Fail loud

"Completed" is wrong if anything was skipped silently.
"Tests pass" is wrong if any were skipped.
Default to surfacing uncertainty, not hiding it.

## Tooling

- Python version pinned by `.python-version` (3.14). Project metadata in `pyproject.toml`.
- `uv` is the package manager (presence of `pyproject.toml` + `.python-version` without `requirements.txt`/`Pipfile`).
  - Install/sync deps: `uv sync`
  - Add a dependency: `uv add <pkg>`
  - Run the entrypoint: `uv run python main.py`
- No test runner, linter, or build step is configured yet — set them up the first time they're needed rather than assuming a default.

## OpenWolf protocol (mandatory)

This project uses OpenWolf for cross-session context management. The full operating protocol is in `.wolf/OPENWOLF.md` and applies every turn:

- **Before reading any file:** check `.wolf/anatomy.md` — it has a description + token estimate for every tracked file. Prefer the description over a full read when sufficient.
- **Before generating code:** read `.wolf/cerebrum.md`, especially the `## Do-Not-Repeat` section.
- **Before fixing a bug:** check `.wolf/buglog.json` for known fixes; after fixing, append a new entry (error, root cause, fix, tags).
- **After significant actions:** append a one-line entry to `.wolf/memory.md`; update `.wolf/anatomy.md` when files are created/deleted/renamed.
- **Learn aggressively:** update `.wolf/cerebrum.md` whenever the user corrects you, expresses a preference, or you discover a non-obvious convention. The threshold is intentionally low.

`.wolf/reframe-frameworks.md` is the UI framework knowledge base — only read it when the user explicitly asks to pick or migrate a UI framework, and read only the sections needed.

## Design QC

When asked to evaluate UI/design: run `openwolf designqc` to capture screenshots into `.wolf/designqc-captures/`, then read those images. Each screenshot ≈ 2500 tokens — use `--routes` to limit scope on large apps.