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.
- CLAUDE.mdCLAUDE.md
- test-modelSkill
- xybrid-connectSkill
- xybrid-initSkill
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
- Distinctive: line 21
Before declaring a task done, run these locally — CI runs them again:
- Very specific: line 79
Use bazelisk (reads .bazelversion).
- Very specific: line 83
Every first-party Rust target (rust_library, rust_binary, rust_test, …) passes version = XYBRID_VERSION, loaded from …
- Very specific: line 114
After editing bindings/flutter/rust, regenerate the Dart glue with flutter_rust_bridge_codegen generate (CLI version must match the pinned …
- Very specific: line 120
Only the Kotlin AAR's arm64 slice (so Kotlin and React Native) uses //:llama_android_dl: ggml built with GGML_BACKEND_DL + …
- Very specific: line 227
Anonymous reachability is not covered by our own CI: Every job here oras logins first, so a private package looks healthy internally and …
- Very specific: line 392
Every SDK names itself in registry requests and telemetry (binding= in X-Xybrid-Client), and the first registration in a process wins.
- Very specific: line 428
When adding a dep, match the surrounding crate's existing style — don't unilaterally migrate one crate to dep.workspace = true while the …
- Very specific: line 464
Don't use Box<dyn Error> in public signatures.
- Distinctive: line 474
No async-std, no smol.
- Very specific: line 483
Use tokio::task::spawn_blocking for CPU-bound or sync I/O (model loading is the canonical example — see xybrid-sdk model loader).
- Very specific: line 485
Don't hold Mutex / RwLock guards across .await (rust-skills async-no-lock-await, anti-lock-across-await).
- Very specific: line 537
Run model-gated tests with just-recipes under mod integration-tests in the root justfile.
- Very specific: line 556
Use std::sync::{Mutex, RwLock} — not parking_lot (not a dependency).
- Very specific: line 561
Prefer borrows over Arc::clone when a borrow's lifetime is obviously short enough.
- Very specific: line 598
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 …
- Very specific: line 602
leave Package.swift's useLocalNatives = true in any committed state.
- Very specific: line 634
Keep the submodule gitlink, LLAMA_CPP_COMMIT, and .github/llamacpp-version.json consistent.
- Very specific: line 662
Concurrency groups: start with the file stem, never ${{ github.workflow }}, so a display name can change without changing the group.
- Very specific: line 667
Regenerate the map: After touching any workflow, run python3 tools/scripts/gen_workflow_index.py.
- Very specific: line 730
Workspace-level lints: Only bindings/flutter/rust has a [lints] table.
- Distinctive: line 742
When you hit one of these, ask in the PR rather than guessing.
- Very specific: line 928
Don't: anti-unwrap-abuse, anti-expect-lazy, anti-clone-excessive,
≈ “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.
Files
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:
- 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
(per-rule examples live at
rules/<rule-id>.mdin that repo)
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-builtUse 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 choreFlutter 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:
XYBRID_NATIVES_PREBUILT_DIR/<target>— a slice staged by the caller. Our CI jobs pull withtools/scripts/natives-pull.shand point at it.- A slice named in
crates/llama-cpp-sys/natives-manifest.txt, downloaded over plain HTTPS fromghcr.io/xybrid-ai/llama-nativesand SHA-256 verified. Needs no oras, no env var, no cmake — this is what makes an externalcargo build --features llm-llamacppcheap. - 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 editingbuild.rsis 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.shis the check that catches it; it runs credential-free at the end ofbuild-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-v1is absent on purpose fromxybrid_core::featuresand from the SDK'sARTIFACT_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 withsystemone.or contains.decision.. It stays a chat model only when its<architecture>.decision.typeis one that also generates text (decision_type_generates_text:granite-switch, the one type the pinned llama.cpp'sserver_model_output_modalitiesserves as text too); xybrid answers no decisions with those. The SDK's header sniff (xybrid_core::execution::decision) is best effort; the authority isLlamaModel::load, which scans every key after loading and refuses.xybrid_llamakeeps its own copy of the rules. Change both together: core tests compare them. Decision conformance / Decision CPU conformancegates llama.cpp releases.ci.ymlcallstest-decision-conformance.ymlon every change that is not docs-only, andtools/scripts/llamacpp_update.pywaits 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 incrates/llama-cpp-sys/NOTICE. A llama.cpp update PR migrates them by hand, and rechecksdecision_type_generates_textagainst upstream's list. crates/llama-cpp-sys/NOTICEis the notice source. Byte-identical copies are committed for the Kotlin AAR (assets/xybrid/llama/NOTICE, gated byverify_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 incrates/llama-cpp-sys/build.rsand in//:llama_decision_jinja; keep them equal (tools/scripts/tests/test_decision_jinja_sources.pyfails when they differ). Keep llama.cpp'ssrc/off the wrapper's include path: a secondggml.hbreaks 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:
- 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.
- 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-observabilityandbindings/observability-js(@xybrid/observability), which depend on OpenTelemetry only, never on xybrid crates; their shared contract iscrates/xybrid-observability/CONTRACT.md. The SDK wires them incrates/xybrid-sdk/src/observability.rs. Export is off until configured explicitly (a Xybrid preset toingest.xybrid.dev/v1/traces, or any OTLP endpoint or application-owned provider).xybrid-corestays free of observability types: it reports stages throughcrates/xybrid-core/src/tracing.rs.crates/xybrid-sdk/src/telemetry.rsis 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).
- Auth / API keys —
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:
| Crate | Role | Layer |
crates/xybrid-core | ML execution + pipelines; additive platform plane (cloud routing, telemetry, control sync) | core lib |
crates/xybrid-sdk | Public Rust SDK; model load/run/stream + platform init (auth, observability) | lib |
crates/xybrid-observability | Portable OpenTelemetry instrumentation and OTLP export; no xybrid dependencies (JS twin: bindings/observability-js) | lib |
crates/xybrid-cli | xybrid binary | bin |
crates/xybrid-ffi-facade | FFI-agnostic POD/Arc facade over the SDK (one canonical translation) | FFI |
crates/xybrid-bolt | BoltFFI bindings: Swift / Kotlin / Java / C# (Unity) / WASM + C header — the sole native binding crate | FFI |
bindings/flutter/rust | flutter_rust_bridge wrapper for Dart | FFI |
macros | proc-macros (xybrid-macros); syn/quote only | proc |
xtask | build / codegen automation | tool |
integration-tests | end-to-end tests with real models & fixtures | test |
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:
| Crate | Error type | Result alias | Defined in |
xybrid-core | XybridError | XybridResult | crates/xybrid-core/src/error.rs |
xybrid-sdk | SdkError | SdkResult | crates/xybrid-sdk/src/model.rs |
xybrid-ffi-facade | Error | Result | crates/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_blockingfor CPU-bound or sync I/O (model loading is the canonical example — seexybrid-sdkmodel loader). - Don't hold
Mutex/RwLockguards across.await(rust-skillsasync-no-lock-await,anti-lock-across-await). - Channels:
tokio::sync::mpscfor 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, orEnvelope— never a newrun*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 onInferenceResult). - 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
Streamhandle, 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_preemptare capabilities leaking into the namespace.XybridModelcurrently carries 14run*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 + anotherruncall), 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 inintegration-tests/fixtures/{input,models,pipelines}/. Tests that need a downloaded model gate themselves withfixtures::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 inxybrid-sdk). Nomockall,mockito, orwiremockin this repo today — don't introduce another mocking library without discussion. - Benchmarks:
criterion(dev-dep inxybrid-core). - No
instasnapshots, noproptest. 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.
| Need | Use |
| Pass data into a function for read-only use | &T (or &[T], &str) |
| Share owned state across threads / async tasks | Arc<T> |
| Shared state, mostly reads, some writes | Arc<RwLock<T>> (std) |
| Shared state, exclusive access each time | Arc<Mutex<T>> (std) |
| Cross-task message passing | tokio::sync::mpsc |
| One-shot reply channel | tokio::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:
- Parses the version from the branch name and fails unless it matches
every package manifest (
version-sync.sh --checkmust be green). - Builds all artifacts, patches
Package.swift'sxybridFFIChecksum, and creates a draft GitHub Release. - Opens the
Release v<version>PR to master itself. On merge,release-publish.ymltags and publishes.
Do NOT:
- run
gh pr createfor a release, or runjust bump-versionon 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'suseLocalNatives = truein any committed state. It is local-dev only and breaks remote SPM consumers (the local xcframework is not committed). Runbindings/apple/scripts/set-natives-mode.sh --set-remotebefore 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 ofCI,SDK,Artifacts,Release,Security,Maintenance,Community;GROUPSintools/scripts/gen_workflow_index.pyis 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, sogit grepthe old name. - Purpose is the line directly above
name::# Purpose: <one sentence>, startingManual: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(jobRepo 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, Scorecardscorecard.yml:analysis) to the path, andrelease-publish.ymland the docs callgh workflow run <file>. Changename:instead. - Add CI by extending
ci.yml, never with a new workflow file.gen_workflow_index.py --checkfails on a file missing from itsWORKFLOW_FILES, and on apull_request/pull_request_targettrigger outsidePULL_REQUEST_FILES: onlyci.ymlandbazel.ymlvalidate pull requests (the others listed scan, dry-run, publish or greet). A lane file declaresworkflow_call(plusworkflow_dispatch, plusschedulefor a nightly) and is called fromci.yml. A seconds-long check that needs no toolchain is a test undertools/scripts/tests/; a new cargo invocation is a step in theci.ymljob with the same runner and feature family; a new backend or real-model suite is oneci.ymljob built from the shared actions in.github/actions/(setup-rust,install-boltffi,fetch-model,free-disk-space), oneLANE_PATHSrow andOPTIONAL_JOBSentry intools/scripts/ci_gate.pywith itstooling-changesoutput and oneCI Successneedsentry (a lane that turns flaky goes toADVISORY_JOBSwhile it is fixed); a new binding or platform is a lane file, the one new file this allows: its PR lists it inWORKFLOW_FILES.setup-rust,install-boltffiandfetch-modelsave their caches frommasteronly. macOS runs 5 jobs at once for the whole organization, so add steps to an existing macOS job: the check also holdsci.ymland its lane files toMACOS_JOB_BUDGETmacOS 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) andBazel graph + RBE targets(bazel.yml) gatemasterthrough branch protection.tools/scripts/llamacpp_update.pyalso waits on job names (REQUIRED_CHECKS,AUTOMATION_CHECKS) before it cuts a llama.cpp release. Edit a workflow'sname:freely. A lane file's checks are named<caller job name> / <job name>, so the caller job'sname:inci.yml(Android,Choice conformance, ...) is part of those check names, two of whichREQUIRED_CHECKSpolls.
Things to leave alone unless explicitly asked
rustfmt.tomlis intentionally empty (defaults). Don't add style overrides.- The
#![allow(clippy::...)]lists at the top ofxybrid-core/src/lib.rsandxybrid-sdk/src/lib.rsexist 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:
- MSRV. No
rust-versionis pinned in anyCargo.toml. Should the workspace pin one (e.g. matching what CI'sdtolnay/rust-toolchain@stableresolves to today)? - Async test style.
runtime.block_on(current) vs#[tokio::test](rust-skillstest-tokio-async) — both work; no canonical choice yet. - Workspace-level lints. Only
bindings/flutter/rusthas a[lints]table. The rust-skillslint-workspace-lints/lint-deny-correctnessrules suggest configuring lints workspace-wide; alpha-stage allow-lists in each crate make that disruptive today. Worth revisiting post-1.0. Box<dyn Trait>vsimpl Traitin 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, preferimpl Trait.- Naming of streaming/event APIs.
recv()(channel-style) vs anEventStream-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 useanyhow/eyre; libraries must not (seeM-ERRORS-CANONICAL-STRUCTS).M-MIMALLOC-APPS— setmimallocas global allocator in app binaries for free perf.
Documentation
M-CANONICAL-DOCS— public items: summary sentence +# Examples / Errors / Panics / Safety / Abortas applicable. No parameter tables.M-DOC-INLINE— annotatepub use foo::Foowith#[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 forxybrid-bolt(the cdylib crossing DLL boundaries).
Performance
M-HOTPATH— identify hot paths early, bench with criterion, profile (Intel VTune / Superluminal). Enabledebug = 1in[profile.bench].M-THROUGHPUT— items/cycle is the metric; batch, partition, avoid empty cycles and contention.M-YIELD-POINTS— long CPU-bound async tasks mustyield_now().awaitevery ~10–100μs.
Safety
M-UNSAFE-IMPLIES-UB—unsafeis 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; noErrorvariant for "this shouldn't happen".M-PUBLIC-DEBUG— all public types implementDebug; redact sensitive data via custom impl + tested redaction.M-PUBLIC-DISPLAY— types meant to be read by humans (errors, string wrappers) implementDisplay.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+ selectrestriction), cargo-audit, cargo-hack, cargo-udeps, miri.M-UPSTREAM-GUIDELINES— also follow Rust API Guidelines / Style Guide / Design Patterns. WatchC-CONV,C-GETTER,C-COMMON-TRAITS,C-CTOR,C-FEATURE.
Library / building
M-FEATURES-ADDITIVE— features only add; nono-std(usestdfeature); enabling any combo must compile.M-OOBE— librariescargo buildon Tier-1 platforms with no extra tools/env. You own your dep tree's OOBE-ness.M-SYS-CRATES—-syscrates: build viaccinbuild.rs, embed sources, optional tools, support static +libloading.
Library / interoperability
M-DONT-LEAK-TYPES— preferstdtypes in public APIs; leak third-party types only for substantial ecosystem benefit or behind a feature.M-ESCAPE-HATCHES— native-handle wrappers exposeunsafe fn from_native,to_native,into_native.M-TYPES-SEND— public types and async futures should beSendfor 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-utilfeature.M-NO-GLOB-REEXPORTS—pub use foo::{A, B, C}, notpub use foo::*(HAL platform-specific re-exports excepted).M-STRONG-TYPES—PathBuf/Pathfor OS paths, notString/&str. Use the strongest std type early.M-TEST-UTIL— testing/mocking functionality gated behind atest-utilfeature.
Library / UX
M-AVOID-WRAPPERS— don't exposeArc<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 translateIFoointerfaces from C# verbatim.M-ERRORS-CANONICAL-STRUCTS— errors are structs withBacktrace+ optional source; exposeis_xxx()methods over publicErrorKind. 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— acceptimpl AsRef<str>/impl AsRef<Path>/impl AsRef<[u8]>for non-owning string/path/byte inputs.M-IMPL-IO— sans-io: acceptimpl std::io::Read/Write(orfutures::io::AsyncRead) for one-shot init I/O.M-IMPL-RANGEBOUNDS— range params areRange<T>orimpl RangeBounds<T>, not(low, high)tuples.M-INIT-BUILDER— ≥4 init permutations →FooBuilderwithFoo::builder()and chainable methods ending in.build(). Required params go tobuilder(deps: impl Into<FooDeps>).M-INIT-CASCADED— types with 4+ params group parameters into helper types semantically.M-SERVICES-CLONE— service types implementCloneviaArc<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 buildsCross-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.
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
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.

