lib

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

PRIME.md (2801B)

      1 # Radroots Core Libraries Beads Prime
      2 
      3 Read `AGENTS.md` first, then read `AGENT_INSTRUCTIONS.md`. `AGENTS.md` remains the authoritative concise contract for this repository.
      4 
      5 ## Workflow
      6 - When Beads is active, use it as the live execution state.
      7 - Keep active work scoped to the smallest coherent green checkpoint.
      8 - For larger efforts, keep only the next few follow-up issues concrete.
      9 - Every issue should have a clear scope, a definition of green, and one dominant verify lane.
     10 - Do not create markdown TODO trackers when Beads is active.
     11 - Do not use `bd edit`.
     12 
     13 ## Start Of Session
     14 - `bd ready --json`
     15 - `bd show <id>`
     16 - `bd update <id> --claim --json`
     17 - Trust cwd auto-filtering when working from a mapped crate or repo surface.
     18 - When working from an external parent repo or worktree, switch into this repo root before running Beads or Agent Mail commands.
     19 
     20 ## Environment Contract
     21 - Nix is the canonical environment contract for this workspace.
     22 - Prefer `nix develop` or `direnv allow` before targeted cargo work.
     23 - Prefer repo-owned Nix lanes over ad hoc raw commands for closeout validation.
     24 
     25 ## Planning Rules
     26 - Keep work small enough that one dominant verify lane can prove it green.
     27 - If a change needs unrelated lanes, split it into separate issues.
     28 - If new work is discovered, create it immediately and link it with `discovered-from:<parent-id>`.
     29 - Use stdin-based `bd create` or `bd update` forms when text contains backticks or quotes.
     30 
     31 ## Verify Lanes
     32 - repo-wide pure formatting, workflow linting, and Rust check/test validation
     33   - `nix flake check`
     34 - repo-aware SDK contract, export, and manifest validation
     35   - `nix run .#contract`
     36 - release workflow or publish-surface changes
     37   - `nix run .#release-preflight`
     38 - targeted crate iteration inside the Nix shell
     39   - `cargo check -p <crate>`
     40   - `cargo test -p <crate>`
     41 - targeted xtask iteration inside the Nix shell
     42   - `cargo run -q -p xtask -- sdk validate`
     43   - `cargo run -q -p xtask -- sdk release preflight`
     44 
     45 ## Closeout Guidance
     46 - any contract, export, conformance, release, flake, or multi-crate issue should close on a Nix lane, not on targeted cargo alone
     47 - crate-local issues may iterate with targeted cargo commands, but should still finish with the narrowest canonical Nix lane that proves the change green
     48 
     49 ## Coordination
     50 - If Agent Mail is active for the session, use the Beads issue id as the thread id.
     51 - Use the same Beads issue id as the reservation reason.
     52 - Reserve files before the first write when coordinating across agents.
     53 - Use build slots for long-running singleton resources when needed:
     54   - `rr-contract`
     55   - `rr-release-preflight`
     56   - `rr-wasm-builds`
     57 
     58 ## End Of Session
     59 - `bd close <id> --reason "..."`
     60 - if a Beads remote or shared state target is configured for the session, run `bd dolt push`