epoch_forge/AGENTS.md

80 lines
3.8 KiB
Markdown

# 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 runs in CI with the tracked configuration and its documented line-
coverage floor. Do not restore `rust_autobadges`; Jenkins renders and publishes
the mutable badges from verified test and coverage results.
## 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.