From 8e03af130727aef597b904e6156b3320398190d1 Mon Sep 17 00:00:00 2001 From: hermes Date: Thu, 8 Oct 2026 11:33:12 +0200 Subject: [PATCH] docs: add AGENTS.md working rules for coding agents Orientation file so agents do not have to re-derive project conventions from the 300-line readme every session: environment paths, the honest red/green state per crate, test-data rules (fixtures in, raw samples out), git boundaries (feature branches freely, main only on approval), and a definition of done demanding executed verification over inspection. Points at readme.md sections rather than duplicating them. --- AGENTS.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..0e161e9 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,63 @@ +# AGENTS.md — working rules for coding agents on RustyRPN + +readme.md is the single source of truth for design decisions and roadmap. +Read at minimum these sections before starting work: + +- §Workflow — the TDD loop you are expected to follow +- §General guidelines for AI — hard prohibitions +- §Data formats — input formats, edge cases, and where test fixtures live +- §Roadmap and status of functionality — what is green, red, or unstarted + +## Environment + +- Rust stable (edition 2024, MSRV 1.85) via rustup; on this machine the + shims are at `/opt/homebrew/opt/rustup/bin` (in PATH via ~/.zprofile). +- All cargo commands run from `Application/`: + `cargo test`, `cargo fmt --check`, `cargo clippy`. +- Workspace members: `src/core` (rpn-core, domain logic), + `src/cli` (rpn-cli, binary `rpnc`). `src/server` and `src/web` are + planned but not scaffolded yet. + +## Current state (verify against readme.md roadmap; update both when it changes) + +- core/config: implemented, tests green. +- core/db: tests committed and RED (they reference functions that do not + exist yet — the crate does not compile its test target). The first task + is the minimal implementation to turn them green. Do not weaken or + rewrite these tests to make them pass; they encode agreed behaviour. +- cli: `fn main() {}`. Command surface specified in Documentation/cli.md. +- feature/epsilon-parser: branch exists, zero commits. Needs workflow + step 2 (spec + test checklist agreed with the maintainer) before any + failing test is written. + +## Test data + +- Real samples: `Application/data/test_input/` — gitignored, never + committed, never embed their values in test files or fixtures output. +- Committed sanitized fixtures: `Application/data/fixtures/` + (epsilon / tsdrms / subfranchise). Parser tests should use these. + Regenerate with `python3 Application/scripts/sanitize_samples.py`; + after any change to fixtures run + `python3 Application/scripts/check_fixture_leaks.py` and require exit 0. +- `Documentation/schema.sql` is the v1 domain schema; it is also the + embedded migration (test-asserted in core/db). + +## Git rules + +- Work on a named feature branch; commit per passing test (workflow step + 5.3). Commit messages are the project's code documentation: format + `area: imperative summary`, body explaining *why*. +- Never commit or push to `main` without the maintainer's explicit + approval. Never rewrite history. +- Never commit: config files (except config.template.toml), anything under + data/ except data/fixtures/, secrets, real customer data. + +## Definition of done for a task + +1. `cargo test` green (all crates), `cargo fmt --check` and + `cargo clippy` clean for files you touched. +2. Every checklist item from the task's spec verified — by a test or by + a command you actually ran, not by inspection alone. +3. readme.md roadmap updated in the same branch. +4. A short summary for the maintainer: what changed, what is still red, + suggested next step.