hermes
8e03af1307
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.
2.9 KiB
2.9 KiB
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, binaryrpnc).src/serverandsrc/webare 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 withpython3 Application/scripts/sanitize_samples.py; after any change to fixtures runpython3 Application/scripts/check_fixture_leaks.pyand require exit 0. Documentation/schema.sqlis 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
mainwithout 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
cargo testgreen (all crates),cargo fmt --checkandcargo clippyclean for files you touched.- Every checklist item from the task's spec verified — by a test or by a command you actually ran, not by inspection alone.
- readme.md roadmap updated in the same branch.
- A short summary for the maintainer: what changed, what is still red, suggested next step.