# ~/.codex/AGENTS.md

## Swarm Agent Execution Protocol

### Purpose
Execute complex work through coordinated multi-agent swarms with explicit ownership, verifiable outcomes, and reproducible artifacts.

All swarm executions must follow:
define -> decompose -> assign -> execute -> verify -> integrate -> record.

Unverified work is treated as incomplete.

---

## 0. Default Stack

Unless explicitly overridden:

- Python 3.12 or newer
- `uv` for dependency and environment management (preferred)
- Project-local environment: `.venv`
- `rg` for codebase search and discovery
- `jq` for JSON parsing and transformation

Use parallel execution when it increases throughput without reducing correctness or reproducibility.

---

## 1. Swarm Task Definition

Before execution, define:

- Inputs and required context
- Outputs and artifact paths
- Success criteria and verification gates
- Constraints and risks
- Required interfaces between agents

If scope is ambiguous, stop and resolve before assignment.

---

## 2. Swarm Plan and Ownership

Break work into independent units with minimal coupling.

For each unit, assign:

- Owner agent
- Deliverable
- Verification method
- Dependencies
- Deadline/order

No unit may have shared ownership. One owner per unit.

---

## 3. Execution Rules for Worker Agents

Every worker must:

- Stay inside assigned scope
- Log assumptions and decisions
- Produce objective evidence (tests, outputs, metrics, traces)
- Run local verification before handoff
- Report blockers immediately

Workers must not silently change interfaces owned by other agents.

---

## 4. Integration Rules for Coordinator Agents

Coordinators must:

- Validate each unit against its gate
- Reject unverifiable or partial work
- Resolve merge/interface conflicts explicitly
- Re-run end-to-end verification after integration
- Record deltas versus baseline

If integrated behavior regresses, rollback that unit and reassign.

---

## 5. Verification Gates

Define gates before execution:

- Correctness: exact match, invariants, or bounded tolerances
- Stability: repeat runs where variability exists (>=3 runs)
- Performance: baseline vs final comparisons when relevant
- Reproducibility: commands and artifacts must be rerunnable

Any gate failure blocks completion.

---

## 6. Iteration Discipline

For each iteration:

1. Apply one scoped change per unit
2. Verify unit-level gates
3. Integrate
4. Verify system-level gates
5. Record outcomes and side effects

Stop when success criteria are met and further changes are low value or high risk.

---

## 7. Final Swarm Record

Deliver:

- Baseline vs final summary
- Evidence per unit
- Verification results
- Integration notes
- Remaining risks and recommended next steps
- Final table of runs and outcomes

---

## Hard Rules

- No implicit assumptions
- No unverifiable claims
- No correctness regressions
- No irreproducible outputs
- No unowned tasks in the swarm plan

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 -->
