agentleFS
xybrid-aixybrid-ai/xybrid/AGENTS.md

xybrid

AGENTS.md524 starsChanged 3 days agoApache-2.0View on GitHub

This is the canonical agent guide: xybrid's project decisions first, then a compressed index of the two upstream guides we follow. Where a project decision here disagrees with the upstream rule indexes below, the project decision wins. (CLAUDE.md holds only Claude-specific material and imports this file — new project decisions belong here, not there.) Fetch the upstream guides when you need detail on a specific rule: - Microsoft Pragmatic Rust (agent edition) — <https://microsoft.github.io/rust-guidelines/agents/all.txt> - rust-skills SKILL.md (leonardomso) — <https://github.com/leonardomso/rust-skills/blob/master/SKILL.md>…

  • Reads credentials
  • Deletes or force-pushes
  • Commits and pushes
  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository4 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

23 rules. About 0 are common, 3 are distinctive, and 20 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 20

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Before declaring a task done, run these locally — CI runs them again:

    line 21
  2. Very specific:

    Use bazelisk (reads .bazelversion).

    line 79
  3. Very specific:

    Every first-party Rust target (rust_library, rust_binary, rust_test, …) passes version = XYBRID_VERSION, loaded from …

    line 83
  4. Very specific:

    After editing bindings/flutter/rust, regenerate the Dart glue with flutter_rust_bridge_codegen generate (CLI version must match the pinned …

    line 114
  5. Very specific:

    Only the Kotlin AAR's arm64 slice (so Kotlin and React Native) uses //:llama_android_dl: ggml built with GGML_BACKEND_DL + …

    line 120
  6. Very specific:

    Anonymous reachability is not covered by our own CI: Every job here oras logins first, so a private package looks healthy internally and …

    line 227
  7. Very specific:

    Every SDK names itself in registry requests and telemetry (binding= in X-Xybrid-Client), and the first registration in a process wins.

    line 392
  8. Very specific:

    When adding a dep, match the surrounding crate's existing style — don't unilaterally migrate one crate to dep.workspace = true while the …

    line 428
  9. Very specific:

    Don't use Box<dyn Error> in public signatures.

    line 464
  10. Distinctive:

    No async-std, no smol.

    line 474
  11. Very specific:

    Use tokio::task::spawn_blocking for CPU-bound or sync I/O (model loading is the canonical example — see xybrid-sdk model loader).

    line 483
  12. Very specific:

    Don't hold Mutex / RwLock guards across .await (rust-skills async-no-lock-await, anti-lock-across-await).

    line 485
  13. Very specific:

    Run model-gated tests with just-recipes under mod integration-tests in the root justfile.

    line 537
  14. Very specific:

    Use std::sync::{Mutex, RwLock} — not parking_lot (not a dependency).

    line 556
  15. Very specific:

    Prefer borrows over Arc::clone when a borrow's lifetime is obviously short enough.

    line 561
  16. Very specific:

    run gh pr create for a release, or run just bump-version on a feature branch and open a PR from it — that bypasses the artifact builds, the …

    line 598
  17. Very specific:

    leave Package.swift's useLocalNatives = true in any committed state.

    line 602
  18. Very specific:

    Keep the submodule gitlink, LLAMA_CPP_COMMIT, and .github/llamacpp-version.json consistent.

    line 634
  19. Very specific:

    Concurrency groups: start with the file stem, never ${{ github.workflow }}, so a display name can change without changing the group.

    line 662
  20. Very specific:

    Regenerate the map: After touching any workflow, run python3 tools/scripts/gen_workflow_index.py.

    line 667
  21. Very specific:

    Workspace-level lints: Only bindings/flutter/rust has a [lints] table.

    line 730
  22. Distinctive:

    When you hit one of these, ask in the PR rather than guessing.

    line 742
  23. Very specific:

    Don't: anti-unwrap-abuse, anti-expect-lazy, anti-clone-excessive,

    line 928

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md — guidance for AI coding agents in xybrid

This is the canonical agent guide: xybrid's project decisions first, then a compressed index of the two upstream guides we follow. Where a project decision here disagrees with the upstream rule indexes below, the project decision wins. (CLAUDE.md holds only Claude-specific material and imports this file — new project decisions belong here, not there.)

Fetch the upstream guides when you need detail on a specific rule:


How to work in this repo

Before declaring a task done, run these locally — CI runs them again:

cargo fmt --all -- --check                              # CI: fmt
cargo clippy --workspace --all-targets -- -D warnings   # CI: clippy
cargo test  --workspace --features ort-download         # CI: test (matrix)

just fmt-check | lint | test | check are the equivalent recipes. just fmt (no -check) writes fixes — run before committing. Match CI's --features ort-download locally so feature-gated paths don't surprise you.

CI gates: two required checks protect master, CI Success (ci.yml) and Bazel graph + RBE targets (bazel.yml). ci.yml runs Repo checks (the workflow index, version sync and every tools/scripts/tests test, on every change), the three commands above (test on Linux only), the feature checks (check-*, clippy-llm, test-llm), api-contract, observability, the Web and Python SDKs, the binding drift job, the backend lanes (Candle, whisper.cpp, policy routing, llama.cpp) and the lanes it calls: the SDKs (build-android.yml, build-apple.yml, build-flutter.yml, build-react-native.yml, unity-editor.yml) and conformance (test-choice-conformance.yml, test-decision-conformance.yml). tools/scripts/ci_gate.py decides which jobs a change needs, and CI Success fails unless each job it requires, every lane included, passed or was skipped for that reason. .github/workflows/README.md maps every workflow.

Crate-wide lint opt-outs go in lib.rs at the crate root (see e.g. crates/xybrid-core/src/lib.rs). Don't sprinkle #[allow(...)] at call sites — push it to crate level or fix the lint. Never bypass hooks (--no-verify).

A workspace grows to tens of GB: target/, React Native Pods/ and Gradle builds, release checkouts in .context/, and a Bazel output base that lives outside the workspace. just clean (./clean.sh) lists what a rebuild recreates; add --all for merged .context worktrees and Bazel output bases, --apply to delete. Use it rather than a hand-rolled rm -rf.

Cleaning is per folder. Every folder that produces build output owns a clean.sh that sources tools/scripts/clean-lib.sh and names its outputs (clean_paths, plus clean_command for a tool like flutter clean); the root clean.sh runs every one git tracks, in parallel. A new folder that builds something gets a clean.sh too (commit it, or it never runs). Only list paths git ignores: the lib refuses anything else, and tools/scripts/tests/test_clean.py fails on it.

Building native bindings / cross-compiled artifacts

Native artifacts are built by Bazel, not xtask. Bazel brings its own hermetic toolchains (Rust, Android NDK, clang, Windows SDK), so these are the same targets the release ships from — do not hand-roll cargo ndk or raw cargo build --target <triple> to reproduce them:

bazel build -c opt //bindings/kotlin:xybrid_kotlin_aar        # Android AAR (jniLibs inside)
bazel build --config=ios //bindings/apple:XybridFFI           # Apple XCFramework (macOS host + Xcode)
bazel build --config=macos-metal //crates/xybrid-cli:xybrid   # CLI (see .bazelrc for other configs)
bazel build --config=windows-msvc //...                       # MSVC-ABI Windows, cross-built

Use bazelisk (reads .bazelversion). just bazel-build | bazel-analyze | bazel-test are the shortcuts; each forwards extra Bazel flags. Full setup, including the Windows MSVC EULA note, is in CONTRIBUTING.md.

Every first-party Rust target (rust_library, rust_binary, rust_test, …) passes version = XYBRID_VERSION, loaded from @xybrid_version//:version.bzl. That constant is read from Cargo.toml's [workspace.package] version by //bazel:cargo_version.bzl; without it rules_rust sets CARGO_PKG_VERSION to 0.0.0, which every shipped (Bazel-built) SDK would report. Add it to any new Rust target: bazel.yml's "Every Rust target stamps the workspace version" step (a bazel query for Rust targets still on the 0.0.0 default) fails otherwise.

xtask is not the native-binding entry point anymore. build-android, build-xcframework, build-uniffi, stage-react-native, setup-targets, build-all, and package were all removed once Bazel took over. What remains is Flutter, Unity staging, and dev-env chores:

cargo xtask build-flutter --platform <linux|macos|windows>  # Flutter native (deliberately cargo)
cargo xtask build-ffi --target <triple> --release           # xybrid-bolt cdylib (Unity native; Android via Bazel)
cargo xtask build-unity                                     # xybrid-bolt across Unity platforms (skips Android)
cargo xtask deploy-unity-native --lib <path> --target <triple>  # stage a Bazel-built lib into Unity
cargo xtask setup-test-env                                  # dev-env chore

Flutter native is cargo on purpose: flutter run inside the repo goes through cargokit → cargo, so the contributor path must match. build-ffi / build-unity build xybrid-bolt (the pre-bolt xybrid-ffi C ABI is retired); deploy-unity-native exists so a Bazel-built lib can be staged into bindings/unity/Runtime/Plugins/ with the right per-platform .meta. Unity Android natives are Bazel-only: //crates/xybrid-bolt:xybrid_bolt_cdylib links libc++ statically there and the Unity package ships no libc++_shared.so, while cargo-ndk links the shared runtime — so build-ffi --deploy-unity refuses Android and build-unity skips it.

After editing bindings/flutter/rust, regenerate the Dart glue with flutter_rust_bridge_codegen generate (CLI version must match the pinned flutter_rust_bridge in bindings/flutter/rust/Cargo.toml); flutter run then rebuilds the native lib via cargokit.

The arm64 AAR links llama.cpp dynamically; everything else statically. Only the Kotlin AAR's arm64 slice (so Kotlin and React Native) uses //:llama_android_dl: ggml built with GGML_BACKEND_DL + GGML_CPU_ALL_VARIANTS, so libxybrid_bolt.so needs libllama.so, libggml*.so and libmtmd.so, and one CPU backend per ISA level ships as a module that bindings/kotlin/bazel/jni/ggml_cpu_backend.cpp loads at startup (best first; ggml skips variants the CPU cannot run). It is selected by the //bazel/ggml:android_arm64_cpu_variants platform, which only the AAR builds for — the Flutter arm64 cdylib keeps the static //:llama, because its precompiled package carries a single .so. Any new target that picks a llama build must select on //bazel/ggml:cpu_variants_enabled too, or the AAR would link two ggml copies. The shipped variant list lives in bazel/ggml/android.bzl and must match the loader's (the build-android.yml gate fails otherwise). Two rules_foreign_cc traps are handled there: Android is configured as CMAKE_SYSTEM_NAME=Linux, so a CMake hook (bazel/ggml/android_system_name.cmake) makes ggml build its Android variant set, and CMAKE_PLATFORM_NO_VERSIONED_SONAME keeps sonames unversioned (an APK only carries lib*.so).

The same platform carries the Android 10 floor; nothing else does. //bazel/ggml:android_arm64_cpu_variants also carries //bazel/toolchains/android:api29, so the AAR's arm64 slice compiles and links with @androidndk_api29 (the pinned NDK at API 29), which is why the Kotlin and React Native SDKs require Android 10 (minSdk 29). Every other Bazel Android target (the AAR's armeabi-v7a / x86_64 slices, the Flutter precompiled libraries, the Unity plugin via --config=android-*) stays on @androidndk at API 28 and must not require Android 10. The API-29 toolchain wins only because MODULE.bazel registers it before @androidndk//:all, whose toolchains match any Android platform of their CPU; keep that order. ggml_cpu_backend.cpp refuses to compile below API 29, so a fallback to API 28 fails the build. CI also reads the API level each library was linked for from its .note.android.ident (tools/scripts/verify_android_api_level.py): build-android.yml requires 29 for the AAR's arm64 libraries and 28 for its other slices, and verify_unity_android_natives.py and release-prep's Flutter payload check require 28.

Speech ships only in the AAR's arm64 slice. The Kotlin AAR (so Kotlin and React Native) is the only standard binary built with --//:tts_zzz=true: its arm64-v8a libxybrid_bolt.so links the private zzz engine (Phonon, Kitten TTS 2) statically, and armeabi-v7a / x86_64 build without it through //bazel/zzz:android_without_slice. Every crate that forwards tts-zzz (xybrid-core's features and zzz-sys dep, xybrid-sdk, both xybrid-bolt libraries, integration-tests' tts_abort) uses the identical select {"//bazel/zzz:android_without_slice": [], "//:tts_zzz_enabled": [...], "//conditions:default": []}. A mismatch still compiles and misroutes speech at runtime; tools/scripts/tests/test_zzz_feature_wiring.py and bazel.yml's speech guard catch it. A new Android ABI either gets a pinned slice or joins that group, or every flag-on AAR build fails as incompatible. The flag is scope = "target" so build tools in the exec configuration never resolve the build host's slice; keep it. The engine's fourteen notices ride in the AAR at assets/xybrid/zzz/<path> (//bazel/zzz:notices.bzl) and are never committed. release-prep's Build Android job takes the engine secrets from the zzz-release environment and fails without them; zzz-engine stays master-only for test-zzz-engine.yml, trusted-zzz-sdk.yml and the test-zzz-android.yml proof lane. zzz-release's branch rule admits release/v* refs and GitHub checks only the run's ref, so any workflow on a release/v* branch can bind it: never bind it outside Build Android, and treat push access to release/v* as what guards the credentials (a repository ruleset should limit it to maintainers and the release automation). tools/scripts/verify_zzz_android.py gates the AAR, the xybrid-android-<tag>.zip and the Gradle-built AAR (speech in arm64-v8a only, the fourteen notices byte-exact, minSdk 29, no static TLS, libc imported from bionic) in release-prep, whose Verify Android Gradle packaging job replays the Gradle publish before the draft exists, and again in release-publish before Maven Central.

The engine is isolated at build time: only zzz_embed_* stays global. Its archive bundles its own runtime and defines memcpy, strlen, expf, __stack_chk_fail and other libc, libm and compiler-rt names globally, and the AAR takes the whole archive into libxybrid_bolt.so, where those copies used to satisfy xybrid's own references instead of bionic's. zzz-sys therefore links //bazel/zzz:android_engine (bazel/zzz/isolate.bzl), never @zzz_android//:zzz: the target toolchain's ld -r --unique prelinks the archive into one object (each input section kept apart, so --gc-sections still drops dead engine code; any ld -r warning fails), llvm-objcopy makes every definition but the C API local, and the action fails unless exactly that API (ZZZ_EMBED_API, kept equal to crates/zzz-sys/src/api.rs by test_zzz_isolation.py) is left global. A new engine function goes into both lists. The AAR gate's libc canary and the proof lane's compare-imports check the shipped library, and bazel/zzz/selftest proves the mechanism on a fake engine in bazel.yml. The other static slices and Cargo builds still link the archive as is (a follow-up; see crates/zzz-sys/README.md).

Prebuilt llama.cpp natives (the cargo fast path)

crates/llama-cpp-sys/build.rs does not always run cmake. It resolves the llama.cpp static archives in this order, falling through on any miss:

  1. XYBRID_NATIVES_PREBUILT_DIR/<target> — a slice staged by the caller. Our CI jobs pull with tools/scripts/natives-pull.sh and point at it.
  2. A slice named in crates/llama-cpp-sys/natives-manifest.txt, downloaded over plain HTTPS from ghcr.io/xybrid-ai/llama-natives and SHA-256 verified. Needs no oras, no env var, no cmake — this is what makes an external cargo build --features llm-llamacpp cheap.
  3. The cmake source build.

The manifest is GENERATED — .github/workflows/build-natives.yml publishes the slices, then its publish-manifest job regenerates the file via tools/scripts/natives-manifest.sh and opens a PR. Never hand-edit it.

Two traps:

  • The manifest goes stale on purpose. It pins plain hashes of wrapper.cpp, wrapper.h, build.rs, and the llama.cpp commit. Touch any of them and every row is ignored until CI republishes — that is the guard that stops a local edit from linking archives that predate it. A dropped fast path after editing build.rs is expected, not a bug.
  • Anonymous reachability is not covered by our own CI. Every job here oras logins first, so a private package looks healthy internally and 401s for everyone outside. tools/scripts/natives-verify-anon.sh is the check that catches it; it runs credential-free at the end of build-natives.

The publisher fingerprint (natives-fingerprint.sh) folds in the LOCAL cmake/cc/NDK versions. That is right for publisher/consumer cache parity and wrong for distribution, which is why the download path selects by target + feature set + ABI attributes from the manifest instead of recomputing it.

Liquid decision models (lfm3-d1/text/v1)

Decision models answer typed questions without generating text. A request is an EnvelopeKind::DecisionRequest on the ordinary run / run_async / run_with_options surface; there is no decision-specific run* method. The contract is docs/development/liquid-decision-protocol.md, and docs/development/decision-conformance.md says what is and is not qualified.

  • No build advertises the d1 registry capability. llamacpp-lfm3-d1-text-v1 is absent on purpose from xybrid_core::features and from the SDK's ARTIFACT_BACKENDS, so the registry serves no decision artifact while the reference comparison (P02 in the conformance record) is open. A test in each file fails if it is added. Loads that do not go through the registry are unaffected.
  • The chat path refuses decision artifacts that generate no text. A GGUF carries a decision marker when a metadata key is tokenizer.chat_template.systemone, starts with systemone. or contains .decision.. It stays a chat model only when its <architecture>.decision.type is one that also generates text (decision_type_generates_text: granite-switch, the one type the pinned llama.cpp's server_model_output_modalities serves as text too); xybrid answers no decisions with those. The SDK's header sniff (xybrid_core::execution::decision) is best effort; the authority is LlamaModel::load, which scans every key after loading and refuses. xybrid_llama keeps its own copy of the rules. Change both together: core tests compare them.
  • Decision conformance / Decision CPU conformance gates llama.cpp releases. ci.yml calls test-decision-conformance.yml on every change that is not docs-only, and tools/scripts/llamacpp_update.py waits on that check name. It collects a fresh upstream reference on the runner and compares bit for bit. Never loosen the comparison to make it pass.
  • The llama.cpp pin has copies the update automation does not rewrite: tools/conformance/decision/{check.py,oracle.py}, integration-tests/fixtures/decision/{integrity.json,oracle.json}, integration-tests/tests/decision_conformance.rs, and the commit named in crates/llama-cpp-sys/NOTICE. A llama.cpp update PR migrates them by hand, and rechecks decision_type_generates_text against upstream's list.
  • crates/llama-cpp-sys/NOTICE is the notice source. Byte-identical copies are committed for the Kotlin AAR (assets/xybrid/llama/NOTICE, gated by verify_zzz_android.py), Python and Unity; React Native, the web package, native slices and the CLI release assets copy it at build time. Edit the source, then the committed copies.
  • The wrapper compiles llama.cpp's Jinja closure (common/jinja/*.cpp, common/json.cpp, common/unicode.cpp). The list is in crates/llama-cpp-sys/build.rs and in //:llama_decision_jinja; keep them equal (tools/scripts/tests/test_decision_jinja_sources.py fails when they differ). Keep llama.cpp's src/ off the wrapper's include path: a second ggml.h breaks the iOS build.

Releases

Releases are cut by branch name, not by hand. Push a release/v<version> branch and .github/workflows/release-prep.yml does the rest (manifest-version check, artifact builds, Package.swift checksum patch, draft GitHub Release, and the Release v<version> PR to master). Don't gh pr create a release or run just bump-version on a feature branch and open a PR from it — that bypasses the pipeline and ships nothing. Never commit Package.swift useLocalNatives = true (local-dev only; breaks remote SPM — run bindings/apple/scripts/set-natives-mode.sh --set-remote). Full ritual + gotchas: § Releases below.


Section 0 — xybrid project decisions

These are the decisions xybrid has already made. They override the upstream rule indexes in Sections 1–2 wherever the two disagree.

What xybrid is (read this first)

xybrid is a local-first execution engine with a platform layer built on top. Both planes share one codebase, and the platform plane is additive — it extends the same runtime without replacing the offline path:

  1. Foundation — on-device execution engine. Model load/run/stream, pipelines, hardware acceleration. Zero-config, offline, no account required. This is the default path and most of the code today.
  2. Platform / control-plane layer (additive). Opt-in capabilities layered on the engine — the direction being actively built out. When a developer authenticates, these light up on top of the same local runtime:
    • Auth / API keys — crates/xybrid-core/src/cloud/config.rs (set_xybrid_api_key, XYBRID_API_KEY). Gates the cloud gateway. Default gateway: api.xybrid.dev. A key alone exports no telemetry (see the observability bullet).
    • Cloud routing — crates/xybrid-core/src/cloud/ + crates/xybrid-core/src/orchestrator/routing_engine.rs (local→cloud fallback under device stress).
    • Observability — OpenTelemetry (GenAI conventions, OTLP/HTTP) in the portable crates/xybrid-observability and bindings/observability-js (@xybrid/observability), which depend on OpenTelemetry only, never on xybrid crates; their shared contract is crates/xybrid-observability/CONTRACT.md. The SDK wires them in crates/xybrid-sdk/src/observability.rs. Export is off until configured explicitly (a Xybrid preset to ingest.xybrid.dev/v1/traces, or any OTLP endpoint or application-owned provider). xybrid-core stays free of observability types: it reports stages through crates/xybrid-core/src/tracing.rs. crates/xybrid-sdk/src/telemetry.rs is the in-process event stream only and never leaves the process.
    • Remote routing authority — crates/xybrid-core/src/orchestrator/authority/remote.rs (GET /v1/routing/advice; partial).
    • Control sync — crates/xybrid-core/src/control_sync.rs (policy / registry refresh; scaffolded, backend not yet wired).

The public README markets the foundation ("offline, no cloud, no API keys") because that's the zero-config default — the platform layer is what you add on top once you authenticate. When touching xybrid-sdk or xybrid-core, treat the platform plane as a first-class, additive surface, not an afterthought: new SDK entry points should consider whether they extend into it too.


Workspace layout

Cargo workspace, resolver = "2", edition 2021, MSRV not pinned. Members:

CrateRoleLayer
crates/xybrid-coreML execution + pipelines; additive platform plane (cloud routing, telemetry, control sync)core lib
crates/xybrid-sdkPublic Rust SDK; model load/run/stream + platform init (auth, observability)lib
crates/xybrid-observabilityPortable OpenTelemetry instrumentation and OTLP export; no xybrid dependencies (JS twin: bindings/observability-js)lib
crates/xybrid-clixybrid binarybin
crates/xybrid-ffi-facadeFFI-agnostic POD/Arc facade over the SDK (one canonical translation)FFI
crates/xybrid-boltBoltFFI bindings: Swift / Kotlin / Java / C# (Unity) / WASM + C header — the sole native binding crateFFI
bindings/flutter/rustflutter_rust_bridge wrapper for DartFFI
macrosproc-macros (xybrid-macros); syn/quote onlyproc
xtaskbuild / codegen automationtool
integration-testsend-to-end tests with real models & fixturestest

xybrid-uniffi was removed once iOS + Android migrated to xybrid-bolt; the FFI binding crates now route their SDK→foreign-language translation through xybrid-ffi-facade rather than each re-translating SDK types.

The Python SDK (bindings/python, not a workspace member) runs on boltffi's generated bindings as of 0.29: xybrid/_bolt/ is generator output (tools/scripts/gen_python_bolt.py, byte-compared in CI via --check), and it imports a compiled CPython bridge that dlopens the xybrid-bolt cdylib. Both binaries are staged by tools/scripts/build-python-bolt.sh and are build outputs, never committed — so wheels are per-interpreter (cp3XX) and the SDK requires Python >= 3.10.

Because the generated package is byte-compared, it carries no hand-written code. The Pythonic surface (envelope factories, result.text, model properties, typed exceptions) is attached to the generated classes at import by xybrid/_sugar.py and xybrid/_errors.py, guarded by tests/test_sdk.py. Add SDK ergonomics there, never in xybrid/_bolt/.

The React Native package (bindings/react-native, npm @xybrid/react-native, not a workspace member) is the one hand-bridged binding: a Codegen TurboModule over the Swift and Kotlin SDKs, so nothing reaches it for free. tests/parity.test.mjs fails when crates/xybrid-bolt gains an export, record field, enum variant or error variant that bindings/react-native/parity.json neither maps nor excludes. When you add bolt surface, wire it through React Native (spec, both shims, TS facade — see its README) or exclude it there with a reason; don't leave the test red. Its iOS core is not in the npm tarball: pod install downloads the release XCFramework and checks the SHA-256 that release-prep pins in its package.json.

Every SDK names itself in registry requests and telemetry (binding= in X-Xybrid-Client), and the first registration in a process wins. Flutter registers in its #[frb(init)] hook, Python on import, Unity from static constructors and React Native before every bridged call. Until an SDK registers, xybrid-bolt reports a fallback: swift on Apple platforms, kotlin on Android. A registration always replaces it, whenever it happens, so a new binding there reports theirs only until it registers. Add a new name to the facade's resolve_binding; a test fails until you do. The table is in docs/telemetry/registry.md.

The browser package (bindings/web, npm @xybrid/web) is a GGUF text-generation preview over the existing Rust/llama.cpp path. pnpm build invokes Bazel for CPU and experimental WebGPU WASM, then bundles the client and worker. pnpm pack:release checks the real npm archive in an isolated consumer; CI and release preparation run Chromium against its extracted contents. Release publication stages that same archive for npm approval. Setup is in bindings/web/RELEASING.md; installing the package never invokes native tools.

Dependency direction (do not reverse):

xybrid-cli  ──────────────────────► xybrid-sdk ─► xybrid-core
xybrid-bolt ──► xybrid-ffi-facade ─► xybrid-sdk ─► xybrid-core
flutter rust──► xybrid-ffi-facade ─► xybrid-sdk ─► xybrid-core
xtask ────────────────────────────► xybrid-core
integration-tests ────────────────► xybrid-core
xybrid-sdk, xybrid-cli ───────────► xybrid-observability (depends on no xybrid crate)

Workspace package metadata is inherited via [workspace.package] — member crates use version.workspace = true, edition.workspace = true, etc. Keep that pattern.

Workspace dependencies are not uniformly inherited today. The root [workspace.dependencies] block exists, but most member crates still pin versions per-crate (e.g. serde = "1.0", tokio = { version = "1.0", … }). When adding a dep, match the surrounding crate's existing style — don't unilaterally migrate one crate to dep.workspace = true while the rest stay version-pinned. Full proj-workspace-deps migration is a deliberate refactor, not a drive-by change.


Error handling

Rust-API library crates (xybrid-core, xybrid-sdk, xybrid-ffi-facade) use thiserror with a single canonical error enum and a Result alias per crate:

CrateError typeResult aliasDefined in
xybrid-coreXybridErrorXybridResultcrates/xybrid-core/src/error.rs
xybrid-sdkSdkErrorSdkResultcrates/xybrid-sdk/src/model.rs
xybrid-ffi-facadeErrorResultcrates/xybrid-ffi-facade/src/lib.rs (one canonical From<SdkError>; the FFI generator crates re-decorate it)

Sub-error enums (InferenceError, PipelineError, AdapterError, …) live next to the modules that raise them and convert into the canonical type via #[from] / impl From. Follow that pattern for new modules — don't invent parallel top-level error types.

Binaries (xybrid-cli, xtask) use anyhow with .context(...) at the boundaries where errors get printed.

SdkError implements a RetryableError trait (is_retryable, retry_after) — preserve those semantics when adding variants. As of today (crates/xybrid-sdk/src/model.rs) the retryable variants are NetworkError, RateLimited, Timeout, and Offline; everything else (including CircuitOpen, ConfigError, ModelNotFound, LoadError, InferenceError, IoError, CacheError, PipelineError, …) is explicitly non-retryable. Read the current is_retryable match arm before changing or extending it — don't infer the rule from the variant name.

Don't use Box<dyn Error> in public signatures. Don't .unwrap() outside tests, examples, and clearly-marked invariant checks (use .expect("...") with a message that explains the invariant — rust-skills err-expect-bugs-only).


Async runtime

Tokio, multi-threaded. Workspace pins: tokio = { version = "1.0", features = ["rt", "rt-multi-thread", "sync"] }. No async-std, no smol.

Public SDK APIs come in sync + async pairs: load / load_async, run / run_async, warmup / warmup_async, run_pipeline_async, etc. Sync variants block on the runtime internally. Match this convention when adding new SDK entry points — don't break the symmetry.

Inside async code:

  • Use tokio::task::spawn_blocking for CPU-bound or sync I/O (model loading is the canonical example — see xybrid-sdk model loader).
  • Don't hold Mutex / RwLock guards across .await (rust-skills async-no-lock-await, anti-lock-across-await).
  • Channels: tokio::sync::mpsc for streaming events; that's the established pattern for pipeline event streams (xybrid-sdk/src/lib.rs).

Tests that need a runtime use tokio::runtime::Runtime::new().unwrap().block_on(...) today. New async tests may use #[tokio::test] — both are accepted.


SDK run surface — capabilities are data, not entry points

The public run surface grows by axes, and axes multiply. The rule:

  • A new capability rides RunOptions, GenerationConfig, or Envelope — never a new run* method. Constrained decoding shipped this way (GenerationConfig.grammar — zero new entry points), and new capabilities (tool calling, etc.) must too (RunOptions-carried inputs, parsed outputs on InferenceResult).
  • A new entry point is justified only by a new IO shape — a different way results physically flow out: batch return, per-token callback, async Stream handle, TTS chunk sink. Each IO shape gets exactly one sync + one async form, nothing else.
  • Suffix chains are the anti-pattern. Names like run_streaming_with_context_options_preempt are capabilities leaking into the namespace. XybridModel currently carries 14 run* variants for this reason, while bolt's entire foreign surface needs exactly one (run(envelope, options)). The excess is consolidation backlog, not precedent — don't add variant #15.
  • Multi-step orchestration (agent loops, retries, tool-execution cycles) lives outside XybridModel — a free helper or the caller's own loop — and FFI bindings get turn-based primitives (parsed results + another run call), not cross-boundary callbacks.

Testing & mocking

  • Unit tests inline as #[cfg(test)] mod tests { use super::*; ... }.
  • Integration tests in each crate's tests/ directory.
  • End-to-end tests with real models in /integration-tests/. Fixtures live in integration-tests/fixtures/{input,models,pipelines}/. Tests that need a downloaded model gate themselves with fixtures::model_if_available() and skip cleanly if the model isn't present — follow that pattern, don't hard-fail on missing assets.
  • HTTP mocking: httpmock (already a dev-dep in xybrid-sdk). No mockall, mockito, or wiremock in this repo today — don't introduce another mocking library without discussion.
  • Benchmarks: criterion (dev-dep in xybrid-core).
  • No insta snapshots, no proptest. Don't add either casually — they bring CI cost and a learning curve.

Run model-gated tests with just-recipes under mod integration-tests in the root justfile.


Concurrency primitives — when to use what

The workspace is multi-threaded. Don't use Rc or RefCell — they aren't in use anywhere and they trap you in single-threaded contexts.

NeedUse
Pass data into a function for read-only use&T (or &[T], &str)
Share owned state across threads / async tasksArc<T>
Shared state, mostly reads, some writesArc<RwLock<T>> (std)
Shared state, exclusive access each timeArc<Mutex<T>> (std)
Cross-task message passingtokio::sync::mpsc
One-shot reply channeltokio::sync::oneshot

Use std::sync::{Mutex, RwLock} — not parking_lot (not a dependency). Public traits that cross task boundaries are bounded Send + Sync; this is established convention for backend / strategy / session traits in xybrid-core. Keep that bound on new traits in the same family.

Prefer borrows over Arc::clone when a borrow's lifetime is obviously short enough. Reach for Arc when you're crossing a spawn / spawn_blocking / channel boundary, or storing the value behind a trait object.


Releases — never hand-roll one (agents read this)

Releases are cut by branch name, not by hand. The entire pipeline keys off a release/v<version> branch. An agent's only correct action to start a release is to create and push that branch — everything else (artifact builds, checksum patch, draft GitHub Release, the release PR, the tag, and the crates.io / pub.dev / Maven Central publishes) is generated by CI. The ritual (.github/workflows/release-prep.yml → release-publish.yml):

git switch -c release/v<version> origin/master
just bump-version <version>     # syncs every manifest: Cargo, pubspec, Unity,
                                # Kotlin, Package.swift sdkVersion, Python
                                # pyproject, and the install-snippet pins in
                                # the READMEs and docs pages (install_pins.py)
./bindings/apple/scripts/set-natives-mode.sh --set-remote   # useLocalNatives=false
# fill the CHANGELOG entry for <version> (and bindings/flutter/CHANGELOG.md)
git commit -am "bump: <version>" && git push -u origin release/v<version>

Pushing release/v* triggers release-prep.yml, which:

  1. Parses the version from the branch name and fails unless it matches every package manifest (version-sync.sh --check must be green).
  2. Builds all artifacts, patches Package.swift's xybridFFIChecksum, and creates a draft GitHub Release.
  3. Opens the Release v<version> PR to master itself. On merge, release-publish.yml tags and publishes.

Do NOT:

  • run gh pr create for a release, or run just bump-version on a feature branch and open a PR from it — that bypasses the artifact builds, the checksum patch, and the draft release, producing a PR that looks like a release but ships nothing. The branch name (release/v*) is the trigger; a PR title is not.
  • leave Package.swift's useLocalNatives = true in any committed state. It is local-dev only and breaks remote SPM consumers (the local xcframework is not committed). Run bindings/apple/scripts/set-natives-mode.sh --set-remote before committing — remote (false) is the canonical committed state.

Install snippets in the READMEs and docs pages that name a release are pins in PINS (tools/scripts/install_pins.py). A new snippet shape, or a new page carrying one, gets an entry there or no bump rewrites it. CI's Repo checks job runs version-sync.sh --check and test_install_pins.py on every PR, docs-only ones included: a stale or dropped pin fails, and so does a known shape on an unlisted page or a package named with a version no pin owns. Pins follow prereleases too: an rc release PR merges to master, so until the final release the READMEs on master and docs.xybrid.dev say to install the rc.

just bump-version only rewrites the workspace version; it does not touch internal path-dep version = "..." pins (e.g. xybrid-sdk/xybrid-core in sibling Cargo.tomls). If those drift, lockfile regen fails under ^0.1.x — update them to match and re-run cargo update -w when bumping.

Native changes after the bump need a Flutter crate edit. cargokit names the Flutter precompiled release after a hash of bindings/flutter/rust alone, and release-prep reuses whatever that release already holds. If anything the library is built from (any Cargo.toml, workspace crates, vendor/ gitlinks, Bazel config) changes on a release branch after the bump, a master merge included, or you rebase or re-cut the branch after release-prep ran, change a line of bindings/flutter/rust/Cargo.toml too. The Verify release branch job runs tools/scripts/check_flutter_precompiled_inputs.py, which fails on the first case from history and on most of the second from the release's publication date.

llama.cpp stable updates (POC). llamacpp-update.yml checks official vX.Y.Z releases daily and opens one version-specific update PR at a time. Keep the submodule gitlink, LLAMA_CPP_COMMIT, and .github/llamacpp-version.json consistent. Release preparation waits for successful validation and a matching, complete generated native manifest, then pushes release/v<version> through the existing pipeline. Stable 0.x SDKs default to the next minor for classified patch or minor upstream updates; first tracked (bootstrap) updates, upstream major updates and SDKs >=1.0 require an explicit version. The release PR remains the publishing approval point. Release-branch version sync records the exact upstream commit being shipped. Setup, dry runs, and conformance-fixture migration are documented in docs/development/llamacpp-updates.md.


GitHub Actions workflows — names, files, keys

The map of every workflow is .github/workflows/README.md. Its inventory table is generated from the workflow files, and these rules keep it true:

  • Display name is "Group: Subject" (quoted). Group is one of CI, SDK, Artifacts, Release, Security, Maintenance, Community; GROUPS in tools/scripts/gen_workflow_index.py is the source of truth and says what each holds. A dispatch-only workflow ends its Subject with (manual). Docs that cite a display name change with it, so git grep the old name.
  • Purpose is the line directly above name:: # Purpose: <one sentence>, starting Manual: for a dispatch-only workflow. Keep it true when triggers change; a schedule edit can make "weekly" wrong.
  • Concurrency groups start with the file stem, never ${{ github.workflow }}, so a display name can change without changing the group. Use <file-stem>-${{ github.ref }}, key on the tag or issue number for event-driven workflows, or use the bare <file-stem> when every run must queue behind the last (llamacpp-update.yml, star-history.yml).
  • Regenerate the map. After touching any workflow, run python3 tools/scripts/gen_workflow_index.py. CI runs it with --check (job Repo checks) and fails on drift or a broken rule. A rebase can bring in master workflows written without these rules; fix them on your branch.
  • Rename workflow files rarely. GitHub ties run history and code-scanning configurations (CodeQL codeql.yml:analyze, Scorecard scorecard.yml:analysis) to the path, and release-publish.yml and the docs call gh workflow run <file>. Change name: instead.
  • Add CI by extending ci.yml, never with a new workflow file. gen_workflow_index.py --check fails on a file missing from its WORKFLOW_FILES, and on a pull_request / pull_request_target trigger outside PULL_REQUEST_FILES: only ci.yml and bazel.yml validate pull requests (the others listed scan, dry-run, publish or greet). A lane file declares workflow_call (plus workflow_dispatch, plus schedule for a nightly) and is called from ci.yml. A seconds-long check that needs no toolchain is a test under tools/scripts/tests/; a new cargo invocation is a step in the ci.yml job with the same runner and feature family; a new backend or real-model suite is one ci.yml job built from the shared actions in .github/actions/ (setup-rust, install-boltffi, fetch-model, free-disk-space), one LANE_PATHS row and OPTIONAL_JOBS entry in tools/scripts/ci_gate.py with its tooling-changes output and one CI Success needs entry (a lane that turns flaky goes to ADVISORY_JOBS while it is fixed); a new binding or platform is a lane file, the one new file this allows: its PR lists it in WORKFLOW_FILES. setup-rust, install-boltffi and fetch-model save their caches from master only. macOS runs 5 jobs at once for the whole organization, so add steps to an existing macOS job: the check also holds ci.yml and its lane files to MACOS_JOB_BUDGET macOS jobs, which a new one raises in the same PR with a reason. The full rules are in the workflow README, "Adding CI".
  • Job names are matched as checks; never rename them. CI Success (ci.yml) and Bazel graph + RBE targets (bazel.yml) gate master through branch protection. tools/scripts/llamacpp_update.py also waits on job names (REQUIRED_CHECKS, AUTOMATION_CHECKS) before it cuts a llama.cpp release. Edit a workflow's name: freely. A lane file's checks are named <caller job name> / <job name>, so the caller job's name: in ci.yml (Android, Choice conformance, ...) is part of those check names, two of which REQUIRED_CHECKS polls.

Things to leave alone unless explicitly asked

  • rustfmt.toml is intentionally empty (defaults). Don't add style overrides.
  • The #![allow(clippy::...)] lists at the top of xybrid-core/src/lib.rs and xybrid-sdk/src/lib.rs exist because the crates are still alpha (0.1.0-beta12). Fixing those lints crate-wide is fine; disabling individual call-sites with #[allow] is not — push it to crate-level if it's project-wide.
  • API contract checks (tools/scripts/api-contract-check.sh) run in CI as a soft warning. If you change a public SDK signature, run it locally.

Open questions (resolve before encoding as rules)

These are genuinely ambiguous in the current code — flag them to a maintainer rather than picking arbitrarily:

  1. MSRV. No rust-version is pinned in any Cargo.toml. Should the workspace pin one (e.g. matching what CI's dtolnay/rust-toolchain@stable resolves to today)?
  2. Async test style. runtime.block_on (current) vs #[tokio::test] (rust-skills test-tokio-async) — both work; no canonical choice yet.
  3. Workspace-level lints. Only bindings/flutter/rust has a [lints] table. The rust-skills lint-workspace-lints / lint-deny-correctness rules suggest configuring lints workspace-wide; alpha-stage allow-lists in each crate make that disruptive today. Worth revisiting post-1.0.
  4. Box<dyn Trait> vs impl Trait in public APIs. Trait-object style is used widely for backends (Arc<dyn LlmBackend> etc.) for plug-in replaceability. New code should follow that — but if a single-impl internal trait shows up, prefer impl Trait.
  5. Naming of streaming/event APIs. recv() (channel-style) vs an EventStream-newtype wrapper. Current code uses the channel idiom; an abstraction layer hasn't been decided.

When you hit one of these, ask in the PR rather than guessing.


Section 1 — Microsoft Pragmatic Rust (rule index)

Each ID below links to the upstream anchor on microsoft.github.io/rust-guidelines. The one-line summary is enough to decide whether to read the full rule. Bolded rules are the ones you'll consult most often in this repo.

License: MIT (Microsoft Corporation). Source: https://microsoft.github.io/rust-guidelines/agents/all.txt

AI-friendly design

  • M-DESIGN-FOR-AI — strong types, thorough docs/examples, testable APIs make agent work tractable.

Applications

  • M-APP-ERROR — apps may use anyhow/eyre; libraries must not (see M-ERRORS-CANONICAL-STRUCTS).
  • M-MIMALLOC-APPS — set mimalloc as global allocator in app binaries for free perf.

Documentation

  • M-CANONICAL-DOCS — public items: summary sentence + # Examples / Errors / Panics / Safety / Abort as applicable. No parameter tables.
  • M-DOC-INLINE — annotate pub use foo::Foo with #[doc(inline)] for own-crate re-exports (not std/third-party).
  • M-FIRST-DOC-SENTENCE — first sentence ≤15 words, one line.
  • M-MODULE-DOCS — every public module needs //! docs covering contents, when to use, examples, side effects.

FFI

  • M-ISOLATE-DLL-STATE — only portable (#[repr(C)], no statics/TypeId/non-portable refs) data crosses DLL boundaries. Critical for xybrid-bolt (the cdylib crossing DLL boundaries).

Performance

  • M-HOTPATH — identify hot paths early, bench with criterion, profile (Intel VTune / Superluminal). Enable debug = 1 in [profile.bench].
  • M-THROUGHPUT — items/cycle is the metric; batch, partition, avoid empty cycles and contention.
  • M-YIELD-POINTS — long CPU-bound async tasks must yield_now().await every ~10–100μs.

Safety

  • M-UNSAFE-IMPLIES-UB — unsafe is only for things where misuse causes UB. Don't use it to flag merely dangerous functions.
  • M-UNSAFE — needs a real reason (novel abstraction, perf, FFI). Document soundness, run Miri, follow unsafe-code guidelines.
  • M-UNSOUND — never acceptable. Safe code that can cause UB is a bug, no exceptions.

Universal

  • M-CONCISE-NAMES — drop weasel words (Service, Manager, Factory). BookingDispatcher > BookingService.
  • M-DOCUMENTED-MAGIC — magic numbers get a comment explaining why; prefer named constants.
  • M-LINT-OVERRIDE-EXPECT — submodule lint overrides use #[expect(..., reason = "...")], not #[allow].
  • M-LOG-STRUCTURED — structured events with named properties + message templates ({{property}} syntax). Follow OTel semantic conventions. Redact PII.
  • M-PANIC-IS-STOP — panic means stop the program. Not for upstream error signaling. Code must be panic-safe.
  • M-PANIC-ON-BUG — detected programming bugs panic; no Error variant for "this shouldn't happen".
  • M-PUBLIC-DEBUG — all public types implement Debug; redact sensitive data via custom impl + tested redaction.
  • M-PUBLIC-DISPLAY — types meant to be read by humans (errors, string wrappers) implement Display.
  • M-REGULAR-FN — free functions over associated functions, except for constructors and trait methods.
  • M-SMALLER-CRATES — split when in doubt; faster compiles, fewer cycles. Re-export via umbrella crate when useful.
  • M-STATIC-VERIFICATION — fmt, clippy (correctness, complexity, perf, style, suspicious, pedantic + select restriction), cargo-audit, cargo-hack, cargo-udeps, miri.
  • M-UPSTREAM-GUIDELINES — also follow Rust API Guidelines / Style Guide / Design Patterns. Watch C-CONV, C-GETTER, C-COMMON-TRAITS, C-CTOR, C-FEATURE.

Library / building

  • M-FEATURES-ADDITIVE — features only add; no no-std (use std feature); enabling any combo must compile.
  • M-OOBE — libraries cargo build on Tier-1 platforms with no extra tools/env. You own your dep tree's OOBE-ness.
  • M-SYS-CRATES — -sys crates: build via cc in build.rs, embed sources, optional tools, support static + libloading.

Library / interoperability

  • M-DONT-LEAK-TYPES — prefer std types in public APIs; leak third-party types only for substantial ecosystem benefit or behind a feature.
  • M-ESCAPE-HATCHES — native-handle wrappers expose unsafe fn from_native, to_native, into_native.
  • M-TYPES-SEND — public types and async futures should be Send for Tokio compatibility.

Library / resilience

  • M-AVOID-STATICS — static/thread-local items secretly duplicate across crate-version boundaries. Don't use them for correctness-relevant state.
  • M-MOCKABLE-SYSCALLS — I/O, clocks, entropy, anything non-deterministic is mockable via an internal enum dispatch + test-util feature.
  • M-NO-GLOB-REEXPORTS — pub use foo::{A, B, C}, not pub use foo::* (HAL platform-specific re-exports excepted).
  • M-STRONG-TYPES — PathBuf/Path for OS paths, not String/&str. Use the strongest std type early.
  • M-TEST-UTIL — testing/mocking functionality gated behind a test-util feature.

Library / UX

  • M-AVOID-WRAPPERS — don't expose Arc<Mutex<T>>, Box<T>, Rc<RefCell<T>> in public APIs; hide them behind clean signatures.
  • M-DI-HIERARCHY — concrete types > generics > dyn Trait. Don't translate IFoo interfaces from C# verbatim.
  • M-ERRORS-CANONICAL-STRUCTS — errors are structs with Backtrace + optional source; expose is_xxx() methods over public ErrorKind. See xybrid's per-crate error tables in § Error handling above.
  • M-ESSENTIAL-FN-INHERENT — core functionality is inherent; trait impls forward to inherent methods.
  • M-IMPL-ASREF — accept impl AsRef<str> / impl AsRef<Path> / impl AsRef<[u8]> for non-owning string/path/byte inputs.
  • M-IMPL-IO — sans-io: accept impl std::io::Read/Write (or futures::io::AsyncRead) for one-shot init I/O.
  • M-IMPL-RANGEBOUNDS — range params are Range<T> or impl RangeBounds<T>, not (low, high) tuples.
  • M-INIT-BUILDER — ≥4 init permutations → FooBuilder with Foo::builder() and chainable methods ending in .build(). Required params go to builder(deps: impl Into<FooDeps>).
  • M-INIT-CASCADED — types with 4+ params group parameters into helper types semantically.
  • M-SERVICES-CLONE — service types implement Clone via Arc<Inner> so dependents share a handle.
  • M-SIMPLE-ABSTRACTIONS — service-type generics don't nest visibly. Foo<Bar<FooBar>> in a user's field is a smell.

Section 2 — rust-skills (rule index)

179 rules across 14 categories. IDs are descriptive; consult github.com/leonardomso/rust-skills/blob/master/rules/<id>.md for examples. Priority order: apply CRITICAL before HIGH before MEDIUM before LOW.

License: MIT. Source: https://github.com/leonardomso/rust-skills

CRITICAL — Ownership (own-)

own-borrow-over-clone, own-slice-over-vec (&[T] not &Vec<T>, &str not &String), own-cow-conditional, own-arc-shared, own-rc-single-thread, own-refcell-interior, own-mutex-interior, own-rwlock-readers, own-copy-small, own-clone-explicit, own-move-large, own-lifetime-elision.

CRITICAL — Errors (err-)

err-thiserror-lib, err-anyhow-app, err-result-over-panic, err-context-chain, err-no-unwrap-prod, err-expect-bugs-only (only for programming errors, with a message describing the invariant), err-question-mark, err-from-impl (#[from]), err-source-chain (#[source]), err-lowercase-msg, err-doc-errors, err-custom-type (no Box<dyn Error> in public signatures).

CRITICAL — Memory (mem-)

mem-with-capacity, mem-smallvec, mem-arrayvec, mem-box-large-variant, mem-boxed-slice, mem-thinvec, mem-clone-from, mem-reuse-collections, mem-avoid-format, mem-write-over-format, mem-arena-allocator, mem-zero-copy, mem-compact-string, mem-smaller-integers, mem-assert-type-size.

HIGH — API design (api-)

api-builder-pattern, api-builder-must-use, api-newtype-safety, api-typestate, api-sealed-trait, api-extension-trait, api-parse-dont-validate, api-impl-into, api-impl-asref, api-must-use, api-non-exhaustive, api-from-not-into, api-default-impl, api-common-traits, api-serde-optional.

HIGH — Async (async-)

async-tokio-runtime, async-no-lock-await (never hold Mutex/RwLock guards across .await), async-spawn-blocking (CPU-bound or sync I/O — e.g. model loading), async-tokio-fs, async-cancellation-token, async-join-parallel, async-try-join, async-select-racing, async-bounded-channel, async-mpsc-queue, async-broadcast-pubsub, async-watch-latest, async-oneshot-response, async-joinset-structured, async-clone-before-await.

HIGH — Compiler optimization (opt-)

opt-inline-small, opt-inline-always-rare, opt-inline-never-cold, opt-cold-unlikely, opt-likely-hint, opt-lto-release, opt-codegen-units, opt-pgo-profile, opt-target-cpu, opt-bounds-check (iterators elide checks), opt-simd-portable, opt-cache-friendly (SoA layouts).

MEDIUM — Naming (name-)

Types/variants UpperCamelCase; functions/modules snake_case; consts SCREAMING_SNAKE_CASE; lifetimes short lowercase ('a, 'de, 'src); type params single uppercase. Conversion prefixes: as_ free, to_ expensive, into_ ownership-transfer. No get_ for simple getters. Booleans use is_/has_/can_. Iterators: iter/iter_mut/into_iter. Acronyms as words (Uuid, not UUID). No -rs crate suffix.

MEDIUM — Type safety (type-)

type-newtype-ids, type-newtype-validated, type-enum-states, type-option-nullable, type-result-fallible, type-phantom-marker, type-never-diverge, type-generic-bounds, type-no-stringly, type-repr-transparent.

MEDIUM — Testing (test-)

test-cfg-test-module, test-use-super, test-integration-dir, test-descriptive-names, test-arrange-act-assert, test-proptest-properties, test-mockall-mocking (note: xybrid uses httpmock, not mockall — see § Testing & mocking above), test-mock-traits, test-fixture-raii, test-tokio-async, test-should-panic, test-criterion-bench, test-doctest-examples.

MEDIUM — Documentation (doc-)

doc-all-public, doc-module-inner, doc-examples-section, doc-errors-section, doc-panics-section, doc-safety-section, doc-question-mark (use ? not .unwrap() in examples), doc-hidden-setup (# prefix for example setup), doc-intra-links, doc-link-types, doc-cargo-metadata.

MEDIUM — Performance patterns (perf-)

perf-iter-over-index, perf-iter-lazy, perf-collect-once, perf-entry-api, perf-drain-reuse, perf-extend-batch, perf-chain-avoid, perf-collect-into, perf-black-box-bench, perf-release-profile, perf-profile-first.

LOW — Project structure (proj-)

proj-lib-main-split, proj-mod-by-feature, proj-flat-small, proj-mod-rs-dir, proj-pub-crate-internal, proj-pub-super-parent, proj-pub-use-reexport, proj-prelude-module, proj-bin-dir, proj-workspace-large, proj-workspace-deps (xybrid is partially migrated — see § Workspace layout above, don't drive-by-convert).

LOW — Clippy / linting (lint-)

lint-deny-correctness, lint-warn-suspicious, lint-warn-style, lint-warn-complexity, lint-warn-perf, lint-pedantic-selective, lint-missing-docs, lint-unsafe-doc, lint-cargo-metadata, lint-rustfmt-check, lint-workspace-lints (open question — see § Open questions above).

REFERENCE — Anti-patterns (anti-)

Don't: anti-unwrap-abuse, anti-expect-lazy, anti-clone-excessive, anti-lock-across-await, anti-string-for-str, anti-vec-for-slice, anti-index-over-iter, anti-panic-expected, anti-empty-catch, anti-over-abstraction, anti-premature-optimize, anti-type-erasure (impl Trait over Box<dyn Trait> when possible), anti-format-hot-path, anti-collect-intermediate, anti-stringly-typed.


Recommended Cargo.toml release profile (from rust-skills)

[profile.release]
opt-level = 3
lto = "fat"
codegen-units = 1
panic = "abort"
strip = true

[profile.bench]
inherits = "release"
debug = true
strip = false

[profile.dev.package."*"]
opt-level = 3  # optimize deps in dev builds

Cross-check against xybrid's actual Cargo.toml before changing — some of these (notably panic = "abort") interact with the FFI boundary in ways the project may have decided against.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.