lib

Core libraries for Radroots
git clone https://radroots.dev/git/lib.git
Log | Files | Refs | README | LICENSE

AGENTS.md (4780B)

      1 # Radroots Core Libraries - Agent Specification
      2 
      3 See [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.
      4 
      5 This file exists for compatibility with tools that look for AGENTS.md.
      6 
      7 ## 1. Scope and hierarchy
      8 
      9 - This file applies to the full repository.
     10 - Keep this file concise and durable.
     11 - Put detailed procedures, examples, and extended guidance in `AGENT_INSTRUCTIONS.md`.
     12 - If a closer directory-level `AGENTS.md` is added later, it overrides this file for that subtree.
     13 
     14 ## 2. Repository operating model
     15 
     16 - This is a public open-source library workspace; optimize for durable library design, portability, determinism, and explicit contracts.
     17 - Keep release and validation automation forge-agnostic; repo-owned xtask commands, Nix apps, tags, and contract metadata are canonical, while committed provider-specific workflow automation is not.
     18 - Prefer clean target-state changes over compatibility scaffolding unless compatibility is explicitly required.
     19 - Stay within the requested scope and the smallest coherent file set.
     20 - Do not fold unrelated cleanup, speculative refactors, or roadmap work into the same change.
     21 - Do not create hidden task trackers in markdown checklists, source comments, or stray notes.
     22 - Keep commits and handoff language standalone and open-source-readable; do not reference internal monorepo paths, internal mapping rationale, or private repository context.
     23 
     24 ## 3. Preflight before edits
     25 
     26 Before editing code:
     27 
     28 - Read this file, `AGENT_INSTRUCTIONS.md`, and `README`.
     29 - When touching Nix behavior, read `flake.nix` and the active Nix implementation files under `build/nix/`.
     30 - Enter the canonical environment with `nix develop` or `direnv allow` before targeted cargo work.
     31 - Discover commands from checked-in repo surfaces; do not invent ad hoc workflows.
     32 - Read the current implementation and nearby tests before designing a change.
     33 - Inspect `git status --short` before broad edits or refactors.
     34 - Fail early when the task is blocked by missing prerequisites, contaminated scope, or unresolved public contract questions.
     35 
     36 ## 4. Canonical command surface
     37 
     38 - `nix flake check`
     39 - `nix run .#contract`
     40 - `nix run .#release-preflight`
     41 - targeted `cargo check -p <crate>` and `cargo test -p <crate>` only inside the Nix shell
     42 - targeted `cargo xtask contract ...`, `cargo xtask coverage ...`, `cargo xtask release ...`, or `cargo xtask hygiene ...` only when narrowing a repo-owned workflow
     43 - if Beads is active, read `.beads/PRIME.md`
     44 
     45 ## 5. Rust engineering rules
     46 
     47 - Use Rust `1.92.0`, edition `2024`, and workspace dependency versions from the root `Cargo.toml`.
     48 - Preserve intended `no_std` portability; gate `std`, wasm, and runtime-specific behavior explicitly.
     49 - Keep core logic functional and composable: prefer pure transformations, explicit state, and narrow side-effect boundaries.
     50 - Prefer enums, newtypes, and typed domain models over stringly APIs, boolean mode switches, or loosely typed maps.
     51 - Avoid hidden panics in library code; reserve `unwrap` and `expect` for tests, build tooling, or proven internal invariants.
     52 - Prefer typed public error surfaces; do not expose opaque convenience errors as stable library contracts.
     53 - Avoid `unsafe` unless it is strictly necessary and documented by invariants close to the code.
     54 - Borrow first, clone late, and allocate intentionally.
     55 - Keep `lib.rs` thin as a module manifest and public re-export surface.
     56 - Treat generated bindings and generated type artifacts as generated; do not hand-edit them.
     57 - Add or update deterministic tests for new behavior, invariants, parsing, conversions, feature gates, and cross-target behavior where relevant.
     58 
     59 ## 6. Contract and release discipline
     60 
     61 - `contracts/` and `tools/xtask` are authoritative for core-library contracts, conformance, coverage, hygiene, and release-candidate governance.
     62 - Behavior changes that affect public surfaces must update the relevant contract metadata, conformance vectors, export rules, or validation flows in the same change.
     63 - Keep pure flake checks and repo-aware command apps aligned with the documented Nix command map.
     64 
     65 ## 7. Commit directives
     66 
     67 - Format commits as `<scope>: <imperative summary>`.
     68 - Use lowercase scopes that match the crate or subsystem being changed.
     69 - Leave a blank line after the summary when writing a multi-line commit.
     70 - Use `- ` bullets for notable changes, validations, or compatibility notes when a body is needed.
     71 - Split unrelated changes into separate commits.
     72 
     73 ## 8. Definition of done
     74 
     75 - The requested change is implemented.
     76 - Affected code, tests, docs, and contract surfaces are updated together.
     77 - Relevant canonical validation ran, or a concrete blocker is reported.
     78 - The handoff states what changed, what validations ran, and any follow-up risks or assumptions.