Compile AGENTS docs from modular assets and make guidance concrete

[willccbb]

Motivation

• Split monolithic AGENTS generation into modular source files so outputs can be tailored for repository maintainers and end-user lab workspaces and avoid repo-local generator references in portable assets.
• Replace vague, generic guidance with concrete Verifiers-specific instructions that map directly to documented workflows and the repo's single-golden-path philosophy.
• Ensure setup consumers receive the portable lab variants of AGENTS/CLAUDE so prime lab/vf-setup users get editable, provenance-agnostic copies.

Description

• Added a compiler-style generator at scripts/sync.py that composes AGENTS.md/CLAUDE.md and environments/AGENTS.md from modular sources under assets/agents/ and writes lab variants to assets/lab/.
• Added modular source docs: assets/agents/common_best_practices.md, repo_development_best_practices.md, end_user_best_practices.md, and compilation_design.md and regenerated compiled outputs AGENTS.md, CLAUDE.md, environments/AGENTS.md, and lab copies under assets/lab/.
• Removed the old scripts/sync_agents_md.py and updated .pre-commit-config.yaml to call the new scripts/sync.py and broadened the hook's watched files to include assets/agents/*.md and scripts/sync.py.
• Updated verifiers/scripts/setup.py to download end-user docs from assets/lab/... instead of repo-root files, and simplified CLAUDE.md headers to reflect generated provenance.
• Rewrote AGENTS content to be explicit and actionable (e.g. require load_environment(...) -> vf.Environment, prime env install, prime eval run, vf.ensure_keys(...), and prefer a single clear path for repo-internal workflows).

Testing

• Ran python scripts/sync.py to generate outputs and observed updated files on first run and "up to date" on the second run, confirming generation and idempotency (succeeded).
• Ran uv run ruff check --fix scripts/sync.py to validate formatting/linting for the new script (succeeded: "All checks passed!").
• Re-ran python scripts/sync.py as an idempotency check and confirmed no further edits (succeeded).
• Searched generated outputs with rg -n "backward-compatible|ToolEnv|StatefulToolEnv|ensure_keys|prime env init|prime eval run" assets/agents AGENTS.md assets/lab/AGENTS.md to verify the intended content appears in the right places (succeeded).

---

Codex Task

---

Note

Low Risk
Primarily documentation/generation tooling changes; the only behavioral impact is which AGENTS/CLAUDE markdown files verifiers/scripts/setup.py downloads into workspaces.

Overview
Introduces a new generator (scripts/sync.py) that compiles repo and lab/workspace variants of AGENTS.md, CLAUDE.md, and environments/AGENTS.md from modular markdown sources under assets/agents/, writing portable copies to assets/lab/.

Replaces the previous sync_agents_md.py flow, updates the pre-commit hook to run the new compiler and watch the modular sources, and adjusts verifiers/scripts/setup.py to download the lab variants (assets/lab/...) instead of the repo-root files. Compiled root AGENTS.md/CLAUDE.md content is rewritten to be shorter, repo-scoped, and explicitly marked as generated.

^{Written by Cursor Bugbot for commit 53ab183. This will update automatically on new commits. Configure here.}