# ~/.codex/AGENTS.md

## Universal Agent Execution Rules

### Purpose
Execute the assigned task **correctly, reproducibly, and verifiably**.

Agents must follow a complete loop:  
define → measure → act → verify → record → iterate.

Results without evidence are invalid.
---

## 0. Software Stack (Mandatory)

All agent execution must assume and use the following stack unless explicitly overridden:

- **Python 3.12, or 3.13 or 3.14t (preferred)**
- **uv** for environment and dependency management (preferred), or micromamba if uv is unavailable.
- Always activate and use the project-local virtual environment: **`.venv`**
- Use **multi-threading** when it provides measurable performance benefit
- Use **multi-processing** only if it can be shown to improve performance without compromising correctness or reproducibility

---

## 1. Task Definition (First, Always)

- Explicitly state:
  - Inputs
  - Outputs
  - Success criteria
  - Constraints and assumptions
- If anything is ambiguous, make it explicit before proceeding.

---

## 2. Baseline State

- Capture the initial state of the task:
  - Outputs, behavior, metrics, or artifacts
- If results can vary, run **≥3 times**
- Record execution context:
  - Environment, tools, versions
  - Hardware if relevant
- Store baseline artifacts in a versioned location  
  `outputs/baseline/<timestamp>/`

---

## 3. Evidence Collection

- Gather objective evidence relevant to the task:
  - Measurements, logs, traces, observations
- Identify limitations, failures, inefficiencies, or risks
- Do not propose actions without supporting evidence.

---

## 4. Verification Gates (Define Before Acting)

- Define how correctness is checked:
  - Exact match, tolerance, invariants, or rules
- Specify acceptable variability and tolerances
- Prefer automated checks

Any change that fails a gate is rejected.

---

## 5. Action Strategy (Justified)

Apply changes incrementally, prioritized as:
1. Remove unnecessary steps or assumptions
2. Simplify logic, structure, or workflow
3. Improve data or control flow
4. Add parallelism or acceleration only if needed
5. Change tools or platforms only with proven benefit

Each action must state its justification.

---

## 6. Iteration Discipline

For each iteration:
- Apply one scoped change
- Re-run verification
- Compare against baseline
- Record deltas and side effects

Stop when:
- Success criteria are met
- Further gains are marginal
- Correctness is at risk

---

## 7. Final Record

Deliver:
- Baseline vs final comparison
- Evidence supporting decisions
- Verification results
- Reproducible steps or artifacts
- Clear recommendation or conclusion

---

## Hard Rules

- No assumptions left implicit
- No unverifiable claims
- No correctness regressions
- No irreproducible outcomes

If it cannot be verified, it does not exist.

<!-- FAST-TOOLS PROMPT v1 | codex-mastery | watermark:do-not-alter -->

## CRITICAL: Use ripgrep, not grep

NEVER use grep for project-wide searches (slow, ignores .gitignore). ALWAYS use rg.

- `rg "pattern"` — search content
- `rg --files | rg "name"` — find files
- `rg -t python "def"` — language filters

## File finding

- Prefer `fd` (or `fdfind` on Debian/Ubuntu). Respects .gitignore.

## JSON

- Use `jq` for parsing and transformations.

## Install Guidance

- macOS: `brew install ripgrep fd jq`
- Debian/Ubuntu: `sudo apt update && sudo apt install -y ripgrep fd-find jq` (alias `fd=fdfind`)

## Agent Instructions

- Replace commands: grep→rg, find→rg --files/fd, ls -R→rg --files, cat|grep→rg pattern file
- Cap reads at 250 lines; prefer `rg -n -A 3 -B 3` for context
- Use `jq` for JSON instead of regex

<!-- END FAST-TOOLS PROMPT v1 | codex-mastery -->
