flowreg-agent-skills AGENTS.md

AGENTS.md — rules for agents working in flowreg-agent-skills

This repository ships scientific policy, not solvers. Read this before editing.

What this repository is

Skills encode how to decide: which FlowRegSuite workflow applies, what metadata must exist before running, how to pilot, which parameters to try and why, what counts as a valid result, and what must be recorded. Registration, warping, displacement estimation, file I/O and all numerics belong to pyflowreg / flowreg3D. Filesystem permissions, approvals and command execution belong to the agent host.

Hard rules

• Never reimplement FlowReg numerics here. No optical flow, no warping, no solvers.
• Every command, API, option key, enum value and output filename must be source-verified against the source revision recorded in capabilities.yaml. If it is not in that source, it does not go in a skill. tests/test_skill_commands.py and tests/test_forbidden_apis.py enforce this.
• capabilities.yaml is the single source of truth for runtime availability, versions, entry points and maturity. Do not restate that information anywhere else by hand.
• Generated files are never edited by hand. docs/capability-matrix.md, docs/runtime-compatibility.md, docs/benchmark-parameter-matrix.md and every skills/*/references/runtime-capability.md are produced by flowreg-agent-skills generate. They carry a generated-file header, and CI fails on drift.
• No MCP in 0.1. No .mcp.json, no MCP server, no MCP configuration. See docs/architecture.md. Adding one is an architecture change, not a patch.
• No absolute, personal or site-specific paths. No /home/<user>, /local, /share, /mnt/c/..., and no named hosts. Use placeholders such as <run-directory>.
• No hidden installation. Skills may inspect an environment and print explicit install instructions. They must never install or upgrade packages, mutate conda, or silently pick a different version.
• Never modify raw data. The documented default workflow always writes to a new run directory. No skill may overwrite, move or rename a source recording.
• Never advertise an unsupported capability as available. Status in capabilities.yaml is evidence-based. unavailable, planned, planning-only and experimental capabilities must not be given executable commands.
• Portability across hosts. Skills must work under both OpenAI Codex and Claude Code: reference bundled files by relative path only, never use ${CLAUDE_SKILL_DIR} (Claude-only), and keep each skill's directory name identical to its frontmatter name.
• Tests and evals are part of every skill change. A new routing boundary needs an eval case; a new claim about a runtime needs a source citation and a test.
• Benchmark parameters are pinned to full commit SHAs, never to a branch or a tag alone. catalogs/repositories.lock.json is the record. A tag can point somewhere other than the branch head — flow_registration's v1.0.0 is 24 commits behind main.
• Never execute MATLAB and never eval it. flowreg_agent_skills.matlab extracts statically and fails closed; an unresolved value is recorded with its raw text and a null value, never guessed.
• Preserve raw dimensional forms alongside effective ones. max_shift = 15 and [15, 15, 5] are different facts; recording only one loses information.
• Never mix benchmark profile classes. current-main, publication-era-code and paper-described are separate; a reproduction must name the one it used.
• Do not invent SNR-specific parameters. Where one sourced preset covers every noise condition, record that explicitly.
• Do not duplicate a runtime's implementation. Where pyflowreg provides the data, the solver or a helper, call its public interface; a second copy here is a second thing to keep correct.
• The wheel is self-contained for list, install, uninstall and doctor; development commands require a checkout and must fail with a clear message, not a traceback.
• Do not commit, tag or push unless explicitly asked.