hep-workflow: Instructions file for Claude Code

hep-workflow

Read by all AI agents working in this repo. Claude Code loads CLAUDE.md; Codex and other tooling load AGENTS.md. The two files are kept byte-identical by tests/contract/test_top_level_docs_byte_identical.py.

Project

A skill-based agent workflow for high-energy physics phenomenology — model proposal → symbolic calculation (Package-X / Mathematica) → numerical scans → publication-grade exclusion plots.

The repo ships skill definitions and validation tooling, not a runtime application. Most edits change schemas, skill prompts, helper scripts, or fixtures, and the test/validator layer is the contract surface.

Common commands

Setup (one-time):

python3 -m venv .venv && source .venv/bin/activate
python3 -m pip install -r requirements-dev.txt

The three validation layers — all must be green before any commit lands:

python3 scripts/validate_examples.py
python3 scripts/validate_workspace_projects.py
python3 -m pytest -q

When a skill tree or vendored shared helper changes, run the read-only mirror precondition before those three layers:

python3 scripts/sync_skill_mirrors.py --check

Run a single test or one layer:

python3 -m pytest -q tests/contract
python3 -m pytest -q tests/integration/test_minimal_scan.py

End-to-end suite (requires wolframscript; gated):

python3 -m pytest -q tests/e2e --run-e2e

Project-level contracts (load-bearing)

These rules apply project-wide. Full text in docs/contracts/. The summaries here are pointers, not duplicates — never copy contract bodies into this file.

Contract	One-line rule	Full text
Mirror invariants	.claude/skills/ ↔ .agents/skills/ byte-identical; orchestrator .md ↔ .toml content-equivalent; CLAUDE.md ↔ AGENTS.md byte-identical	docs/contracts/mirror-invariants.md
Canonical name rule	New canonical identifiers match ^[A-Za-z_][A-Za-z0-9_]*$ and are not Python hard keywords; workflow IDs follow their own patterns	docs/contracts/canonical-name-convention.md
Content-addressed dependencies	New calculation, scan, and reproduction outputs bind exact declared input/code bytes; legacy evidence cannot support new scientific claims	docs/contracts/content-addressed-dependencies.md
Three-validator discipline	validate_examples + validate_workspace_projects + pytest -q must stay green on main	docs/contracts/three-validator-discipline.md
Manifest history actions	New action requires synchronized update across schema + skills + orchestrator + tests	docs/contracts/manifest-history-actions.md
Transactional publication	Multi-path writers publish one coherent generation through lock + journal + CAS; interrupted state fails closed	docs/contracts/transactional-state-publication.md
Numerics manifest ownership	Manifest v2 owns files and dependency snapshots per analysis; aggregates are deterministic projections	docs/contracts/numerics-manifest-ownership.md
Skill / agent / script division	Mechanical → script; generation → skill; coordination → agent	docs/contracts/skill-agent-division.md
Honest reproduction principle	Calculations independently derived; disagreement reported as-is; never adjust tolerance to mask	docs/contracts/honest-reproduction-principle.md
Reproduction readiness	Per-target prerequisites are derived read-only from typed current evidence; formula targets do not consume model/calculation/scan state	docs/contracts/reproduction-readiness.md
Strict JSON trust boundaries	Duplicate keys, non-standard/non-finite numbers, overflow, and invalid UTF-8 fail before side effects	docs/contracts/strict-json.md