Rust Development

Runtime dispatch

Detect the runtime once, before the workflow:

• Claude Code (Agent, AskUserQuestion, and Skill tools available) → read runtime-claude.md.
• OMP (task and ask tools available, with skill://… readable through read) → read skill://rust-dev/runtime-omp.md.
• Any other tool surface → stop and report that this skill has no dispatch table for the runtime.

The selected file is a prompt asset, not a role declaration. Its implementation and review labels name the exact runtime subagent arguments. If a named agent is unavailable, stop before delegation: never substitute the generic task or general-purpose agent and never implement delegated work inline.

Workflow

For any non-trivial Rust change:

1. Discover project guidelines — Read CLAUDE.md, AGENTS.md (in repo root and .claude/, .cursor/, .codex/ subdirs), rustfmt.toml, clippy.toml, .clippy.toml, deny.toml, and [workspace.lints] / [lints] sections in Cargo.toml. These rules apply in addition to Core Rules below.

2. Implement — Delegate through the runtime dispatch table's implementation entry. It rediscovers guidelines, implements, then verifies its own work with cargo clippy --workspace --tests -- -D warnings and cargo test --workspace before reporting done.

3. Review — Delegate through the dispatch table's review entry after implementation completes. This is mandatory, not optional. Convert findings into TODOs: critical/warning → fix; suggestions → triage.

4. Fix issues one by one — Delegate each fix through the implementation entry. Do not batch unrelated fixes into one delegation.

5. Final build — Run cargo build --workspace directly.

Core Rules

1. Edition 2024: Always edition = "2024" in Cargo.toml
2. FAIL FAST: Every error MUST propagate with ? or return Err. Logging is NOT handling. See error-handling.md
3. Dependency versions: Use x.x format (e.g., serde = "1.0"). Find latest with python3 scripts/check_crate_version.py <crate>
4. Workspace architecture: Root Cargo.toml defines workspace only. Separate crates for lib/cli/client
5. Error types: thiserror (with backtrace) for libraries, anyhow for binaries/tests
6. CLI-first config: Never bypass CLI args. Use from_cli_args(), never Default that reads env
7. No env::set_var in tests: Pass config through function parameters
8. Async: Use tokio consistently
9. Visibility: Private (default) > pub(crate) > pub
10. No magic numbers: Use const or CLI args

Adding Dependencies

1. Run python3 scripts/check_crate_version.py <crate-name> to find latest version
2. Add to [workspace.dependencies] in root Cargo.toml with x.x format
3. Reference in member crates: serde = { workspace = true }

Common deps: thiserror = "2.0", anyhow = "1.0", tokio = { version = "1", features = ["full"] }, serde = { version = "1.0", features = ["derive"] }, clap = { version = "4.5", features = ["derive"] }

Creating New Projects

Use the template in assets/workspace-template/:

project/
├── Cargo.toml              # Workspace root, no code
├── project/                # Library crate (thiserror)
│   ├── Cargo.toml
│   └── src/lib.rs
└── project-cli/            # Binary crate (anyhow + clap)
    ├── Cargo.toml
    └── src/main.rs

Module Organization

Split modules when file exceeds ~500 lines or tests take 50%+ of file. See module-organization.md for patterns.

Error Handling

The most critical standard. See error-handling.md for full rules and examples.

Quick check: If you see if let Err or match ... Err without return Err or ?, it's a bug.

References

• error-handling.md — FAIL FAST rules, thiserror/anyhow patterns, error chain preservation
• module-organization.md — When/how to split modules, test extraction
• dependency-guide.md — Workspace deps, feature flags, common crates

Scripts

• scripts/check_crate_version.py — Query crates.io for latest dependency versions