# AGENTS.md > AI Coding Agent Guide for wepppy ## Authorship **This document and all AGENTS.md documents are maintained by GitHub Copilot / Codex which retain full authorship rights for all AGENTS.md content revisions. Agents can author AGENTS.md document when and where they see fit.** ## Purpose - This is the global, high-signal onboarding map for agent work in this repository. - Keep root guidance concise; place deep subsystem details in nested `AGENTS.md` files and docs. - Prefer progressive disclosure: read only the docs needed for the task at hand. ## Instruction Discovery - Instruction precedence is nearest-to-workdir: global defaults -> repo root -> nested directories. - When a nested `AGENTS.md` exists for files you are editing, treat it as the primary local playbook. - Use root `AGENTS.md` for repository-wide invariants and routing only. ## Core Directives - `??` in prompt means provide critical analysis only; do not implement code. - Ask for human clarification when requirements or debug context are ambiguous. - Keep docs terse: Codex loads context in bulk and does not compress verbose guidance. - Do not add fallback wrappers that silently mask missing required dependencies. - Prefer explicit failures over hidden recovery paths for easier debugging. - Do not create or switch to a new git branch unless the user explicitly asks for it. ## Agent Feedback Loop - Treat avoidable friction as diagnostic signal about the codebase, docs, tooling, or task framing. - Surface unprompted feedback when it would materially improve developer ergonomics, architectural clarity, or shared docs, tooling, and agent-facing interfaces. - Distinguish clearly between: - confirmed defects/blockers - local painpoints or ambiguity - speculative improvement ideas - Keep unsolicited feedback concise and actionable: name the friction, why it mattered, and the smallest improvement that would reduce recurrence. - Do not invent speculative redesigns; prefer substrate improvements tied to concrete task experience. ## Exception Handling (Required) - Do not introduce bare `except:` or broad `except Exception` handlers in production paths unless the block is a deliberate boundary. - Prefer narrow, expected exception types and preserve canonical error contracts when translating errors. - Never swallow exceptions silently; log with context and either re-raise or return an explicit, contract-compliant error response. - If a broad catch is unavoidable (for example, boundary cleanup/telemetry), document why in a short comment and keep the protected block minimal. ## ExecPlans (Required) - For complex features, significant refactors, or multi-hour work, execute against an active ExecPlan. - Standard location for active ExecPlans is `docs/work-packages/*/prompts/active/`. - Ad hoc ExecPlans may live under `docs/mini-work-packages/*.md` when explicitly designated by the user. - Current ad hoc active ExecPlan: `none`. - Current work-package active ExecPlan: `docs/work-packages/20260403_roads_map_drilldown/prompts/active/roads_map_drilldown_execplan.md` - Before authoring or revising an ExecPlan, read `docs/prompt_templates/codex_exec_plans.md`. - Active plans are living documents: keep `Progress`, `Surprises & Discoveries`, `Decision Log`, and `Outcomes & Retrospective` current. - When asked to run a plan end-to-end, proceed milestone by milestone without pausing for extra confirmation unless blocked by an external dependency. - If multiple active ExecPlans exist, explicitly identify which plan you are executing before edits. - If the active plan is under `docs/work-packages/*/prompts/active/`, update both the active ExecPlan and `docs/work-packages/*/tracker.md` before handoff. ## Change Scope Discipline (Required) - Do not add speculative abstractions for unsupported or hypothetical cases. - Match existing data and API contracts first; call out contract changes before implementation. - Prefer the smallest fix that resolves the confirmed failing path. - State assumptions explicitly in change notes before broadening behavior. - Add regression coverage for the exact failure mode. ## Dependency and Performance Discipline (Required) - Before recommending or integrating a new external dependency, run the precedent check and evaluation gates in `docs/standards/dependency-evaluation-standard.md`. - For geospatial/raster/hydrology/climate/model execution paths, treat `weppcloud-wbt`, `wepppyo3`, `oxidized-rasterstats`, and `peridot` as the performance baseline. - Do not propose pure-Python replacements for those paths without benchmark and parity evidence on WEPPpy-representative workloads. - Treat marketing claims and institutional endorsements as hypotheses; route unproven proposals to a scoped evaluation work package before integration. - Preserve "Own the Stack": prefer extending owned components over adding external dependencies that duplicate existing capability. ## Repository Contracts - Canonical RQ response and error payload contract: `docs/schemas/rq-response-contract.md`. - Canonical CSRF contract for browser/session boundaries: `docs/schemas/weppcloud-csrf-contract.md`. - Canonical WEPP output scope contract (baseline vs roads): `docs/schemas/output-scope-contract.md`. - Update `wepppy/rq/job-dependencies-catalog.md` whenever enqueue sites or dependency edges change in: - `wepppy/rq/*.py` - `wepppy/microservices/rq_engine/*` - rq-initiated route handlers - Run `wctl check-rq-graph` after queue wiring edits; if drift is reported, regenerate with `python tools/check_rq_dependency_graph.py --write`. - After queue wiring changes, manually validate against live job trees via `wepppy/rq/job_info.py` or the job dashboard. ## Environment Baseline - Assume Linux host with Docker, Docker Compose, and `wctl` installed. - Local virtualenv baseline: `/workdir/wepppy/.venv` is built from the same `requirements-uv.txt` used by `wepppy`. - Compose source of truth: `docker/docker-compose.dev.yml`. - Use `wctl` wrappers for tests, container exec, and local orchestration. - Canonical run root is `/wc1/runs/`; check it first when debugging run data. ## Validation Entry Points - Iteration loop: `wctl run-pytest tests/` - Pre-handoff sanity: `wctl run-pytest tests --maxfail=1` - Frontend changes: `wctl run-npm lint` and `wctl run-npm test` - Stub/API surface changes: `wctl run-stubtest ` and `wctl check-test-stubs` - RQ queue wiring changes: `wctl check-rq-graph` - Dead-code refactor gate: `.venv/bin/vulture` (configured in `pyproject.toml`, whitelist in `wepppy/vulture_whitelist.py`) - Code quality observability (non-blocking): `python3 tools/code_quality_observability.py --base-ref origin/master` - Broad exception inventory/enforcement: `python3 tools/check_broad_exceptions.py --enforce-changed --base-ref origin/master` - Docs changes: `wctl doc-lint --path `; preview spelling normalization with `diff -u <(uk2us )` - Root onboarding size gate: `tools/check_agents_size.sh AGENTS.md` ## Code Quality Observability (Observe-Only) - Treat complexity/LOC bands as triage telemetry, not merge blockers. - Prefer changed-file deltas first; use hotspot tables to plan opportunistic cleanup. - When a touched file worsens materially, capture a brief rationale or follow-up note in review artifacts. ## Documentation Map - Architecture overview: `ARCHITECTURE.md` - Human-facing project overview: `readme.md` - Active initiative board: `PROJECT_TRACKER.md` - Full work package process: `docs/work-packages/README.md` - Mini packages: `docs/mini-work-packages/` - Prompt/template catalog: `docs/prompt_templates/AGENTS.md` - NoDb facade/collaborator implementation standard: `docs/standards/nodb-facade-collaborator-pattern.md` - Vulture dead-code gate standard: `docs/standards/vulture-dead-code-gate-standard.md` - Docker/local secret conventions: `docker/secrets/README.md` ## Subsystem Maps (Nearest AGENTS Wins) - NoDb controllers and module contracts: `wepppy/nodb/AGENTS.md` - WEPPcloud app/routes/controllers: `wepppy/weppcloud/AGENTS.md` - Controller JS specifics: `wepppy/weppcloud/controllers_js/AGENTS.md` - GL dashboard specifics: `wepppy/weppcloud/static/js/gl-dashboard/AGENTS.md` - WEPP report templates: `wepppy/weppcloud/templates/reports/wepp/AGENTS.md` - Playwright smoke tests and agent auth accounts: `wepppy/weppcloud/static-src/tests/smoke/AGENTS.md` - RQ engine microservice: `wepppy/microservices/rq_engine/AGENTS.md` - Test fixtures, stubs, markers, isolation: `tests/AGENTS.md` - Docker stack conventions: `docker/AGENTS.md` - WCTL and tooling wrappers: `wctl/AGENTS.md` - Status/preflight/cao services: `services/status2/AGENTS.md`, `services/preflight2/AGENTS.md`, `services/cao/AGENTS.md` ## Security Guardrails - Never commit secrets or tokens. Keep secrets in gitignored files and runtime env. - Preserve run-scoped access expectations and auth checks when editing endpoints. - Do not weaken validation, locking, or serialization safeguards in NoDb/RQ flows. ## Root Exclusions - Do not place long tutorials in this file (NoDb internals, frontend migration guides, route catalogs, or markdown tooling manuals). - Do not duplicate subsystem instructions already maintained in nested `AGENTS.md` files. - Do not embed prompt templates in root onboarding text; keep templates under `docs/prompt_templates/`. - Move growing sections to canonical docs and leave a short pointer here. ## If Blocked - Check the nearest subsystem `AGENTS.md`, then module README and tests. - Reuse existing patterns from adjacent code before introducing new abstractions. - Ask a human when requirements are unclear or an external dependency blocks progress. - When work is possible but unnecessarily difficult, note the friction and recommend the smallest doc/tooling/interface improvement in handoff for human review. ## Root Size Policy - Keep this file within roughly 100-160 lines. - If a section grows beyond quick onboarding value, move detail to a canonical doc and leave a pointer. - Prefer stable links over copied prose when updating this file. - Re-check line count after major edits to avoid onboarding bloat.