epoch_forge/AGENTS.md

3.8 KiB

Epoch Forge contributor guide

Epoch Forge is a CLI-first, local world-state manager. Its primary product qualities are, in order: safety and reversibility, ease of use, compatibility with existing repositories, and pleasant terminal output. Do not add a GUI, web service, or TUI unless a task explicitly changes that scope.

Product vocabulary

  • A repository is a directory initialised by efo init.
  • An epoch is an immutable-in-spirit snapshot of world state. Commands may edit the checked-out epoch, but every destructive workflow must have a clear recovery path.
  • An entity is a typed game object such as a character, town, event, blocker, calamity, or (eventually) organisation.
  • An identifier may be a human-readable name or the stable @UUID form.
  • The CLI is efo; lib_efo owns the domain and persistence logic while bin_efo owns argument parsing and presentation.

Engineering rules

  1. Preserve persisted data compatibility. If a format change is unavoidable, add a version/migration plan and fixtures before changing it.
  2. Mutating commands must either complete fully or leave the prior on-disk state usable. Prefer write-to-temporary-then-rename where practical.
  3. Destructive commands require an explicit, documented recovery path. Model vocabulary after Git where it helps: status, log, diff, switch, restore, and later stage/commit.
  4. Errors must say what failed, identify the relevant object/path, and suggest the next useful command when one exists. Do not panic for user input or repository corruption.
  5. efo --help and every subcommand's --help are user documentation. Include meaningful summaries, argument value hints, and examples where Clap allows.
  6. Human output should be compact, aligned, Unicode-aware, and colour only when appropriate for the terminal. Machine-readable output must remain plain and stable. Never require a Nerd Font to understand essential output.
  7. Keep domain operations in lib_efo; CLI handlers should parse, invoke, and render. Avoid unsafe, unchecked unwrap, and hidden working-directory mutations.
  8. Custom organisation/entity fields are a planned compatibility direction. Avoid closed designs that prevent adding schema-less metadata later.

Quality gates

Run before each implementation commit:

cargo fmt --all -- --check
cargo test --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings

Add tests at the lowest useful layer and CLI integration tests for observable workflows. Tests that touch a repository must use a temporary directory and must not depend on execution order. Snapshot tests are appropriate for stable human output; assertions on structured data are preferred for persistence.

Tarpaulin and rust_autobadges are release-time tools. Do not run them in CI or for routine commits. Refresh their badges only for a significant release.

Documentation and commits

  • Keep the README short: purpose, honest capability summary, quick start, safety model, and links into docs/.
  • Keep commands, repository format, architecture, and roadmap in focused, cross-linked files under docs/.
  • Update documentation in the same commit as user-visible behavior.
  • Maintain AGENTS-TASKS.md: mark completed items, add discoveries, and record decisions that affect later work.
  • Commit small coherent changes regularly. Use conventional subjects such as docs:, test:, fix:, feat:, and refactor:. Never mix an unrelated cleanup with a behavior change.

Definition of done

A task is done when behavior is implemented, failure modes are covered, the full quality gates pass, CLI help and relevant docs agree with reality, and the change is committed with AGENTS-TASKS.md updated.