commit 2f960e1053ef0e0354d4575b9cd14bfdbe7739d0
parent b282947cc09853534f4b2e6243f9b51cbe1ccd34
Author: triesap <tyson@radroots.org>
Date: Mon, 27 Jul 2026 07:10:34 +0000
docs: add repository agent instructions
- Anchor public SDK work to the release-v1 specification.
- Record SDK and facade ownership and architecture constraints.
- Add the contributor workflow and deviation process.
- Guard publication and other irreversible repository actions.
Diffstat:
3 files changed, 159 insertions(+), 19 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
@@ -1,19 +1,93 @@
-# radroots_sdk - code directives
-
-- this repo owns the Radroots `sdk` workspace, including Rust SDK APIs, generated language bindings, FFI layers, WebAssembly surfaces, package metadata, and SDK validation flows
-- own generated SDK artifacts through their source generators, schemas, templates, and public contracts, not by hand-editing generated output
-- do not make this repo responsible for downstream app repos, private layout, platform deployment, publication policy outside this repo's public contract, or compatibility packages unless explicitly represented here
-- work spec-first for public SDK behavior; do not invent packages, bindings, exports, compatibility layers, or publishing behavior
-- prefer the smallest coherent change that fully addresses the request; do not mix unrelated cleanup, speculative refactors, compatibility scaffolding, or roadmap work into the same change
-- inspect the relevant implementation, tests, manifests, specs, package metadata, and docs before changing behavior
-- do not depend on private repositories, unpublished artifacts, local machine layouts, absolute paths, or internal monorepo context
-- keep generated bindings reproducible from checked-in source contracts
-- preserve root imports, package boundaries, and public API shapes unless the task explicitly changes the SDK contract
-- when behavior changes affect generated outputs, update the source contract and regenerate through repo-owned tooling rather than hand-editing artifacts
-- prefer explicit typed models, deterministic behavior, narrow side effects, and direct service boundaries over stringly or implicit behavior
-- avoid hidden production panics; use typed errors for expected failure modes
-- avoid `unsafe` unless it is strictly necessary, locally justified, and documented with nearby invariants
-- do not expose secrets, private keys, credentials, tokens, invite codes, private identifiers, sensitive user data, or sensitive event content in code, logs, tests, fixtures, docs, or examples
-- use checked-in, repo-owned validation first; prefer narrow contract tests plus repo-wide validation for generated-code or package-surface changes
-- if validation cannot run, report exactly what was skipped and why; never claim validation passed unless it actually ran
-- keep commits focused and reviewable, using `<scope>: <imperative summary>` unless a repo convention overrides it
+# Radroots SDK agent specification
+
+This file applies to the full standalone SDK repository. Read
+`CONTRIBUTING.md` for the contributor workflow. A closer `AGENTS.md`
+overrides this file for its subtree.
+
+## Source of intent
+
+- Read `docs/specs/README.md` and
+ `docs/specs/radroots_crates_release_v1.md` before changing a public
+ package, dependency, feature, binding, or release control.
+- The Markdown specification is normative. Its TOML catalog is the executable
+ package and dependency representation; the CSV and DOT files are review
+ aids.
+- Current source and tests are implementation evidence. They do not silently
+ override `radroots.crates.release.v1`.
+- Record any evidence-based plan deviation in
+ `docs/implementation/DEVIATIONS.md` before proceeding.
+
+## Repository operating model
+
+- This repository owns the Radroots SDK workspace, including Rust SDK APIs,
+ generated language bindings, FFI layers, WebAssembly surfaces, package
+ metadata, and SDK validation flows.
+- It owns `radroots-sdk` and the ordinary-user `radroots` facade. The 17
+ lower release-v1 packages remain owned by the standalone
+ `radrootslabs/lib` repository.
+- Do not make this repository responsible for downstream apps, private
+ layouts, deployment policy, or compatibility packages unless represented by
+ a public contract here.
+- Keep commits and handoff language standalone and open-source-readable. Do
+ not reference private checkout structure or internal coordination context.
+- Prefer the smallest coherent target-state change. Do not mix unrelated
+ cleanup, speculative abstraction, compatibility scaffolding, or roadmap work.
+
+## Preflight and engineering rules
+
+- Inspect the relevant specs, manifests, implementation, tests, package
+ metadata, generators, and generated outputs before editing.
+- Inspect `git status --short` and preserve unrelated work.
+- Use checked-in repository commands and the narrowest validation that proves
+ the change; never claim a check passed unless it ran successfully.
+- Work spec-first. Do not invent packages, bindings, exports, compatibility
+ layers, or publishing behavior.
+- Prefer explicit typed models, deterministic behavior, narrow side effects,
+ and direct service boundaries over stringly or implicit behavior.
+- Avoid hidden production panics. Use typed errors for expected failures.
+- Avoid `unsafe` unless strictly necessary and document the local invariants.
+- Do not expose secrets, private keys, credentials, tokens, private
+ identifiers, sensitive user data, or sensitive event content in code, logs,
+ tests, fixtures, docs, or examples.
+
+## Architecture and generation rules
+
+- `radroots-sdk` is the advanced front door. It owns host-neutral client
+ semantics, not global runtimes, hidden workers, logging installation, UI
+ state, Studio databases, or process lifecycle.
+- `radroots` is a curated ordinary-user facade. It has no public `sdk`
+ namespace and does not wildcard-reexport `radroots-sdk`.
+- Cross-repository dependencies on the lower package family use registry
+ versions in release candidates, never production sibling paths or Git
+ overrides.
+- No public package has a dependency on a private or unpublished Radroots
+ package, including dev, build, optional, and target-specific edges.
+- Own generated artifacts through checked-in schemas, generators, templates,
+ and public contracts. Do not hand-edit generated output.
+- Generated bindings remain reproducible and do not mechanically dictate the
+ native Rust module layout.
+- During migration, every package remains non-publishable until its
+ package-realistic release gates pass and publication is explicitly
+ authorized.
+
+## Commits, deviations, and irreversible actions
+
+- Format commits as `<scope>: <lower-case imperative summary>`.
+- Keep commits focused and reviewable. Use a blank line before a multi-line
+ body and `- ` bullets for notable changes and validation.
+- If repository evidence proves a planned step obsolete or unsafe, record the
+ evidence, affected specification anchor, disposition, and validation in
+ `docs/implementation/DEVIATIONS.md`. A normative change also requires an
+ approved decision record.
+- Do not publish crates or packages, create release tags, change registry
+ ownership, merge or rename repositories, merge pull requests, rotate
+ credentials, or mutate trusted-publisher configuration without explicit
+ authorization.
+
+## Definition of done
+
+- The requested change is complete at the correct package boundary.
+- Affected code, tests, contracts, generators, outputs, and docs agree.
+- Relevant repository-owned validation passed or an exact blocker is reported.
+- The final review records files changed, checks run, residual risks, and
+ whether the next step is safe.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,44 @@
+# Contributing
+
+Radroots SDK changes are contract-driven and independently reviewable. Before
+editing, read these files in order:
+
+1. `AGENTS.md`
+2. `docs/specs/README.md`
+3. `docs/specs/radroots_crates_release_v1.md` for crate-surface work
+4. the affected manifests, implementation, contracts, generators, and tests
+
+The release-v1 architecture identifier is `radroots.crates.release.v1`. This
+repository owns `radroots-sdk` and the ordinary-user `radroots` facade; the
+standalone core-library repository owns the other 17 public packages.
+
+## Workflow
+
+1. Inspect repository status and the current source authority.
+2. Make one coherent, commit-sized change.
+3. Update public contracts, tests, generators, checked-in outputs, and docs
+ with the implementation they govern.
+4. Run the narrowest repository-owned checks that prove the change, followed
+ by the broader workspace or package lane required by its scope.
+5. Review the staged diff for API leakage, private dependencies, generated
+ drift, secrets, hidden side effects, and unrelated changes.
+
+Use `cargo xtask check` for the repository-wide Rust and generated-package
+lane where applicable. Run targeted format, check, test, Clippy, contract, and
+generated-freshness commands while iterating.
+
+## Commits and deviations
+
+Use this commit form:
+
+```text
+<scope>: <lower-case imperative summary>
+```
+
+Keep commits focused and keep public commit language independent of any
+private checkout. Do not publish, tag, merge, or change registry ownership
+without explicit authorization.
+
+When current evidence proves a planned step obsolete or unsafe, follow
+`docs/implementation/DEVIATIONS.md`. Record the evidence and affected spec
+anchor before changing the plan; do not silently redefine the architecture.
diff --git a/docs/implementation/DEVIATIONS.md b/docs/implementation/DEVIATIONS.md
@@ -0,0 +1,22 @@
+# Implementation deviations
+
+This ledger records evidence-based deviations from
+`radroots.crates.release.v1` implementation planning. It does not authorize a
+change to the normative package architecture.
+
+No deviations are currently recorded.
+
+## Required record
+
+Every deviation entry must include:
+
+- a stable identifier and date;
+- the affected plan step and normative specification anchor;
+- current repository evidence proving the planned action obsolete or unsafe;
+- the smallest safe disposition and any temporary compatibility boundary;
+- validation performed and unresolved risk;
+- the approving decision record when normative architecture changes.
+
+Do not silently skip, merge, reorder, or broaden implementation steps. Keep
+the repository at a known-good checkpoint and obtain approval for any
+normative change before proceeding.
