mev-beta/AGENTS.md

Agent Handoff Guide

This guide keeps multi-agent work on the MEV Bot repository (/home/administrator/projects/mev-beta) aligned. Always follow the shared practices here first, then layer any agent-specific instructions (for example, .qwen/QWEN.md or CLAUDE.md).

Repository Context

• Primary language Go 1.22+ with auxiliary scripts in Bash/Node; binaries land in bin/
• Core service: arbitrage-focused MEV bot targeting Arbitrum (see PROJECT_SPECIFICATION.md for architecture)
• Tests span unit, property, fuzz, math audit, integration, and profitability simulations
• CI defined under .github/workflows/, harness/, and .drone.yml; local equivalents exist in scripts/ and Makefile

Operating Principles (All Agents)

• Keep go test ./... and make build green before handing off; document exceptions directly in the checklist
• Maintain determinism: prefer reproducible scripts, pinned vectors, and declarative configs
• Never commit secrets from keystore/, env/, or generated artifacts; redact sample values when documenting
• Update related docs (README, AGENTS.md, docs/5_development, docs/6_operations) when workflows or expectations change
• Preserve or increase test coverage; extend existing suites rather than creating redundant harnesses
• Record blockers (sandbox limits, missing fixtures, approvals) in the checklist with next steps

Agent Roles & Overlays

• Codex (default) – infrastructure, orchestration, release engineering, cross-package fixes; see this file plus the harness README
• Qwen – numerical correctness and performance; follow .qwen/QWEN.md for math tooling and audit flow
• Claude – developer-experience alignment, documentation, and CI scaffolding; see CLAUDE.md
• Add new agents by checking in <NAME>.md at the repo root and linking it here; mirror the conventions above

Workflow & Handoff Expectations

1. Review this guide, outstanding checklist items, and recent agent notes before starting work.
2. Log progress with status markers ([ ], [~], [x]) plus initials/date (YYYY-MM-DD) when updating any item.
3. When a task spans multiple agents, leave actionable pointers: commands run, logs produced, files touched, follow-up owners.
4. Attach artifacts (reports, coverage, simulation outputs) under reports/ or the designated directory and reference the path.
5. Prefer deterministic scripts (e.g., ./scripts/run_audit_suite.sh, .qwen/scripts/math-test.sh) over ad-hoc commands.
6. Document blockers or required approvals inline; include whether retries are needed post-approval.
7. During release phases, ensure Drone/Harness pipeline invocations are captured with run IDs and artifact paths.

Shared Checklists

Phase 4 – Profitability & Monitoring

• Profitability simulation harness (tools/simulation) with default vectors – Qwen 2024-10-05
• Prometheus profitability metrics wired (pkg/metrics/metrics.go) – Qwen 2024-10-05
• Docs updated (docs/5_development/TESTING_BENCHMARKING.md, docs/6_operations/DEPLOYMENT_GUIDE.md) – Qwen 2024-10-05

Phase 5 – Agent Validation & Release

• Provide keystore + secrets for smoke start (MEV_BOT_KEYSTORE_PATH, env vars) – Codex 2025-10-05 (env/smoke.env, directories scaffolded)
• [~] Run full regression (go test ./..., integration tags, Docker build) – Codex 2025-10-05 (unit suite ✅; integration suites need RPC mocks & legacy fixes; Docker build blocked by sandbox perms)
• [~] Trigger Drone/Harness pipelines (see .drone.yml, harness/pipelines/staging.yaml) and attach artifacts; GitHub workflows now manual-only backups – Codex 2025-10-05 (Drone test-suite/security-suite/integration-opt-in triggered via local bin/drone; lint & gosec blocked by toolchain mismatches, logs in reports/ci/; Harness CLI built locally but staging run blocked by missing Harness API credentials/permissions)
• Confirm Prometheus alerts configured (error rate, profit factor) – Codex 2025-10-05 (monitoring/alerts.yml, pkg/metrics/metrics.go export)
• Final release summary in docs/8_reports/ – Codex 2025-10-05 (docs/8_reports/2024-10-05_final_release_summary.md)

Outstanding Follow-ups

• Decide on secrets management strategy (Vault / SSM / local .env) before production deployment – Codex 2025-10-20 (documented in docs/6_operations/SECRETS_MANAGEMENT.md; Vault for prod, SSM for CI/staging, templated .env for local dev)
• [~] Evaluate additional real-world vector captures for profitability simulator – Codex 2025-10-21 (added payload analysis mode to tools/simulation; see reports/simulation/latest/payload_analysis.{json,md}; follow-up: enrich captures with block numbers, gas, and realized profit for vector ingestion)
• Repair integration test harness (update arbitrage config structs, import paths, and RPC fixtures) before release gating – Codex 2025-10-20 (added deterministic legacy security harness and moved fork-dependent suites behind legacy,forked; go test -tags='integration legacy' ./... now completes without RPC dependencies)

Code Audit Plan

• Work through docs/8_reports/subsystem_audit_checklist.md module by module
• Log findings/issues per package (open PRs/issues) and update status table

Add new items as work emerges; remove or archive completed entries once signed off.

Reference Commands

• go test ./... – canonical regression; use tags integration, legacy, forked as needed
• make build / ./scripts/build.sh – produce binaries for bin/
• ./scripts/run_audit_suite.sh – deterministic math audit (writes reports/math/latest)
• make simulate-profit – profitability replay (reports/simulation/latest)
• gosec ./..., golangci-lint run – security & lint gates

Supporting Docs & Directories

• PROJECT_SPECIFICATION.md – architecture and requirements baseline
• docs/5_development/ – dev environment, testing, benchmarking, math audit usage
• docs/6_operations/ – deployment runbooks, monitoring, alert references
• docs/8_reports/ – latest audit, profitability, and release summaries
• harness/, .drone.yml, .github/workflows/ – CI/CD definitions
• @prompts/continuous-dev.md – full iterative development contract