agents.md

Project Agents Guide (Template, v1)

A concise, reusable guide for human and AI contributors. Customize the bracketed fields for each project.

Project: [PROJECT_NAME]
Primary language: Rust (stable)
UI layer: [CHOOSE ONE: Leptos/React/etc.] (single framework)
API layer: [Axum/Actix/etc.]
Build/bundle: [Trunk/cargo-leptos/—]
Target platform: Fedora (dnf/rpm)

---

0) Scope & Baseline

• Rust stable only. No nightly/unstable features.
• One UI stack. Do not mix frameworks; follow the project’s chosen UI layer.
• API is thin. Routes/serde/auth live in API crate; business logic lives in library crates.
• Workspace layout:
  • web/ = UI only (views, state, API calls).
  • api/ = HTTP only (routes, mapping, errors).
  • libs/* = domain logic (models, traits, persistence, orchestration).

---

1) Architecture Principles

1. Separation of concerns: UI ↔ API ↔ Libs boundary is enforced.
2. Small, composable crates: New domain areas → new lib crate.
3. Security & least privilege: Rootless by default; no elevation on dev hosts.
4. Reproducibility: Builds succeed on clean Fedora hosts with stable Rust.

---

2) Dependencies

• Use latest stable releases from crates.io. No pre-releases, no git refs (unless critical fix, documented in .docs/deps-exceptions.md).
• Prefer caret SemVer ranges ("0.x") over exact pins; avoid wildcards.
• Keep features minimal; prefer rustls when applicable.
• Validate:
  • cargo update -p <dep> + cargo check at workspace root
  • cargo tree -d has no conflicts
  • UI bundling (e.g., trunk build) succeeds if applicable

---

3) Platform & Packaging

• Fedora-first: documentation/scripts target dnf/rpm. Do not add apt/Debian/Ubuntu instructions.
• Containers: Rootless Podman only; rpm-based base images; Quadlet for systemd integration.
• Avoid curl | bash installers; prefer packaged approaches (official repos or COPR when justified).

---

4) Comments & Rationale

• Functional comments only (what/how, invariants, safety).
• No design essays in code. Long-form rationale goes to .docs/<topic>.md (gitignored) and is summarized in the PR.

---

5) Privilege & Debugging

• No sudo or elevation attempts by agents or scripts on developer workstations.
• Provide rootless alternatives; fail fast with instructions when a privileged step is operator-only (CI/ops).

---

6) Clarification Policy

• Ask for clarification when requirements are incomplete/ambiguous/contradictory. Propose options and a default.
• If partially blocked, implement the minimal, reversible path and mark TODOs.

---

7) Build Quality

• Must compile on stable at workspace root:
  • cargo build --workspace --all-targets --release
  • UI bundle (if present) builds cleanly (e.g., cd web && trunk build --release).
• Prefer zero warnings. Scope any #[allow(...)] narrowly with a one-line reason.
• Clippy/fmt recommended: cargo clippy -- -D warnings, cargo fmt --all --check.
• Tests pass (cargo test --workspace -q) when present.

---

8) PR Checklist

• Implementation in libs, not hard-coded into UI/API.
• Latest stable dependencies; minimal features.
• Builds cleanly (workspace + UI bundle).
• Rootless Podman (no Docker); no Debian/Ubuntu instructions.
• No sudo usage in dev flows.
• Comments are concise & functional; long rationale in .docs/.
• Clarifications sought where guidance was incomplete.