# 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: ```text 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.