claude-delegate-local-mcp CLAUDE.md

CLAUDE.md

Traps and invariants for anyone — human or agent — editing this repository. Terse on purpose: it assumes you can read code, and it exists to stop mistakes that are cheap to make and expensive to find.

Not a summary of docs/ARCHITECTURE.md. That explains how the system works and why. This lists what will bite you.

Commands

python scripts/docs_gate.py --mode pre-commit   # structural checks, by hand
python scripts/install_hooks.py                 # installs the commit-msg hook
python scripts/docs_gate.py --owner <path>      # which document owns this file
python scripts/gen_config_docs.py               # after touching config.py
python scripts/gen_agents_docs.py               # after touching .claude/agents/
python scripts/gen_tools_docs.py                # after touching tools.py
.venv/Scripts/python.exe -m pytest -q           # Windows; parallel, `-n 0` for serial
wsl -d Ubuntu-24.04 -e bash -lc '...'           # anything needing bwrap or ext4

Documentation ownership

Every file under src/, scripts/ and .github/ has exactly one owning document, or is explicitly declared unowned. Changing the code means updating its owning document in the same commit. The gate blocks otherwise.

Do not memorise the mapping and do not copy it here — scripts/docs_ownership.toml is the only copy, and a second one is the drift this whole scheme exists to prevent. Ask instead:

python scripts/docs_gate.py --owner src/claude_delegate_local/paths.py
→ docs/AGENTS.md

Rules a machine cannot check, so they land here:

• A fact belongs to exactly one document, and to exactly one plane. Project plane is the repo root (where are we, why did we choose this). Product plane is docs/ (how does it work). If you find yourself explaining a config default in prose, stop — link.
• docs/TROUBLESHOOTING.md owns zero facts. It is a symptom index. It links to whichever document owns the answer and never restates it. Restating a default inside a symptom explanation is exactly how the project this descends from ended up documenting one setting three different ways.
• Generated documents are never hand-edited. docs/CONFIGURATION.md and docs/TOOLS.md are rendered from code. Edit the source, run the generator.
• Blocked by the gate and genuinely right anyway? Add a trailer: Docs-Gate-Skip: owning-doc -- pure rename, no behaviour change. It is echoed in every run and audited, so it is visible rather than quiet. Two skips on one document in ninety days is a signal that something is wrong with the document, not with the rule.