WEPPcloud
UserSummary Docs

← Back to usersum index

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.
  • Do not create or switch to a new git branch unless the user explicitly asks for it.
  • Always ignore wepppy/weppcloud/routes/usersum/generated/docs_index.json when it is dirty unless explicitly asked to modify 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, and 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 ExecPlans: Project Config Builder locale expansion at docs/work-packages/20260827_project_config_builder_locale_expansion/prompts/active/project_config_builder_locale_expansion_execplan.md; Project Config run UI authority at docs/work-packages/20260827_project_config_run_ui_authority/prompts/active/project_config_run_ui_authority_execplan.md; WEPPcloudR execution backend refactor at docs/work-packages/20260821_weppcloudr_execution_backend_refactor/prompts/active/weppcloudr_execution_backend_refactor_execplan.md; Pure UI controller testing at docs/work-packages/20260716_pure_ui_contract_standardization_c/prompts/active/pure_ui_contract_standardization_execplan.md; run-statistics ledger at docs/work-packages/20260505_run_statistics_ledger/prompts/active/run_statistics_ledger_execplan.md; SSURGO study at docs/work-packages/20260721_ssurgo_intelligent_fallback_study/prompts/active/ssurgo_intelligent_fallback_empirical_study_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.
  • For Pure UI and UI-coupled WEPPcloud/NoDb/RQ behavior, follow docs/standards/contract-first-change-standard.md; other subsystems retain current canonical specifications named by their nearest AGENTS.
  • Update affected user, operator, and developer documentation in the same final change set for every production change; contract-first sequencing is an additional requirement, not a replacement.
  • Prefer the smallest fix that resolves the confirmed failing path; for mechanical refactors, preserve code structure (scope/indent/order) and change only the intended tokens.
  • For incident-driven hardening and mitigation-retirement work, follow docs/standards/hardening-lifecycle-standard.md.
  • State assumptions explicitly in change notes before broadening behavior.
  • Do not rely on model memory or chat history as the only requirements source; closed work packages are immutable history, never living governance, so promote durable rules outside docs/work-packages/ and amend the promotion later.
  • When user conversation establishes or changes behavior/UX/data contracts, update the authoritative spec/work-package doc in the same change.
  • Capture both normative contract and concise rationale (why this choice, what alternatives were rejected) for conversation-derived decisions.
  • In handoff notes, cite the exact file/section where the decision was documented.
  • For a user-requested literal config-value edit, change only the requested value and required provenance docs; do not add, rewrite, or delete tests merely to assert the literal, and validate only by direct readback or an existing parser/schema check unless the user explicitly requests tests or executable logic changed.
  • For project data/schema mutations (run-scoped CSV/parquet/NoDb contracts), write a brief compatibility and regression plan before editing.
  • Default to additive/backward-compatible evolution; do not rename or remove user-visible keys/columns without explicit operator approval.
  • For data/schema mutations, validate downstream propagation to generated run artifacts (for example wepp/runs/*) in addition to regression tests.
  • Any change that modifies parameterization defaults, formulas, thresholds, unit conversions, or fallback heuristics must include an ADR per docs/standards/parameterization-adr-standard.md before merge (or within one business day for urgent incident fixes).

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/error contract: docs/schemas/rq-response-contract.md; WEPPcloudR render execution: docs/schemas/weppcloudr-render-execution-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.
  • Canonical NoDb persistence/concurrency contract: docs/schemas/nodb-persistence-concurrency-contract.md.
  • Canonical geospatial metadata and artifact README authoring guide: wepppy/nodb/mods/features_export/specification.md#11-manifest-and-warning-contract.
  • 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

  • Local virtualenv baseline: /workdir/wepppy/.venv is built from the same requirements-uv.txt used by wepppy.
  • Compose source of truth is 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.
  • Deployment boundary: wepp.cloud (wepp1/wepp2/wepp3) uses Docker Compose via the installed wctl preset and scripts/deploy-production.sh; openwepp.org uses Kubernetes and may use registry-published images.
  • Before proposing or executing deployment/rollback mechanics, inspect the canonical deploy entry point and nearest docs; never invent parallel image, registry, or Compose workflows.

Validation Entry Points

  • Iteration loop: wctl run-pytest tests/<path or module>
  • Pre-handoff sanity for substantive code changes: wctl run-pytest tests --maxfail=1; never use this for literal-only config edits unless the user explicitly requests it.
  • Frontend changes: wctl run-npm lint and wctl run-npm test
  • Stub/API surface changes: wctl run-stubtest <module> 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 <file>; preview spelling normalization with diff -u <file> <(uk2us <file>)
  • 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
  • Work package process: docs/work-packages/README.md; mini packages: docs/mini-work-packages/
  • Prompt/template catalog: docs/prompt_templates/AGENTS.md
  • Hardening lifecycle standard (including callus softening): docs/standards/hardening-lifecycle-standard.md
  • Parameterization ADR requirement: docs/standards/parameterization-adr-standard.md
  • RQ scoped NoDb mutation cache-guard standard: docs/standards/rq-scoped-nodb-mutation-cache-guard-standard.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
  • WBT release cutover reference (includes canonical weppcloud-wbt runbook link): docs/dev-notes/weppcloud-wbt-release-cutover.md
  • Docker/local secrets: docker/secrets/README.md; WEPPcloud web startup/minimum secret contract: docs/infrastructure/weppcloud-web-runtime-contract.md

Subsystem Maps (Nearest AGENTS Wins)

  • WEPP binary vendoring and observability debugging: wepp_runner/AGENTS.md
  • 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.
  • Do not ship changes across process, container, host-mount, permission, or execution boundaries until the existing user-facing workflow passes end-to-end under production-equivalent identities, groups, mounts, umask, configuration, and orchestration; unit tests alone are insufficient. Deployment preflights must exercise the real workflow and block rollout when parity evidence is missing or fails.
  • Security-sensitive work packages require a dedicated security review artifact per docs/work-packages/README.md (see "Security Review Gate").

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; re-check line count after major edits.