AGENTS.md

1# Repository instructions
2 
3This repository contains the `mathmodel-skill` product. When working inside this repository, act as a maintainer: do not start the ten-stage contest workflow merely because modeling-related files are present.
4 
5## Sources of truth
6 
7- `SKILL.md` defines runtime behavior and trigger boundaries.
8- `references/stage_00_kickoff.md` through `references/stage_09_review.md` contain stage details and must be loaded lazily at runtime.
9- `competitions/<competition>/` contains competition-specific rules, heuristics, overlays, and paper structures.
10- `templates/shared/decision_log.json` is the canonical persistent-state template.
11- `.codex-plugin/plugin.json`, `agents/openai.yaml`, and `skills/mathmodel-skill/SKILL.md` are packaging metadata or thin discovery shims. Do not duplicate the workflow into them.
12 
13## Maintenance rules
14 
15- Preserve the trigger boundary: this skill is for CUMCM, MCM/ICM, and Diangong Cup contest work, not generic data analysis or ordinary paper review.
16- Treat official contest rules as time-sensitive. Keep a verification date and primary source in `competitions/<competition>/current_rules.md`; official current-year material always overrides repository guidance.
17- Treat empirical distributions and `winning_patterns.md` as observations or maintainer heuristics, never official thresholds or award predictors.
18- Keep user artifacts relative to the user's working directory (`state/`, `results/`, `figures/`, `paper_workspace/`, `paper_output/`). Resolve repository resources relative to the installed skill root.
19- Keep `SKILL.md` concise and dispatch stage-specific detail into `references/`.
20- Do not add runtime claims about awards, token savings, or elapsed time without a reproducible benchmark.
21- When changing behavior, update the README, tests, plugin version, state schema, and relevant competition docs together.
22- Do not vendor or reintroduce templates, examples, papers, or binary assets without a clear redistribution license. Keep runtime dependencies and external-source boundaries accurate in `THIRD_PARTY_NOTICES.md`.
23 
24## Verification
25 
26Run the checks proportionate to the change. Before a release, run all of them:
27 
28```bash
29python -m compileall -q scripts templates/shared/code_starter
30python -m unittest discover -s tests -p 'test_*.py' -v
31python scripts/doctor.py --competition cumcm --skip-tools
32python scripts/doctor.py --competition mcm --skip-tools
33python scripts/doctor.py --competition diangong --skip-tools
34git diff --check
35```
36 
37Maintainers with the Codex skill/plugin creator tooling installed should also run its current `quick_validate.py` and `validate_plugin.py` entrypoints. Do not hard-code a machine-specific installation path into contributor commands.
38 
39Runtime evaluation prompts should explicitly invoke `$mathmodel-skill`. Negative-trigger tests should confirm that generic model-selection and non-competition writing requests do not invoke it.
40