pi-rust-skills 0.1.0

package/skills/rust-database/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: rust-database
+description: Builds and reviews Rust database code with SQLx, Diesel, migrations, transactions, pooling, query validation, test databases, schema drift checks, and async database error handling. Use for Rust persistence and data access work.
+license: MIT
+compatibility: Rust stable. Common tools include SQLx, Diesel, refinery, sea-query, PostgreSQL, SQLite, and MySQL.
+---
+
+# Rust Database
+
+Use this skill when implementing, testing, or reviewing Rust data access layers, migrations, and database-backed workflows.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Identify the database engine, migration tool, connection pool, schema ownership, and transaction boundaries.
+3. Keep SQL/data access behind a small module or repository boundary that is easy to test.
+4. Add tests for migrations, query behavior, transaction rollback, uniqueness/conflict handling, and missing-row behavior.
+5. Validate schema and query checks using the project's chosen tool.
+
+## Design rules
+
+- Prefer compile-time checked queries when SQLx offline data or live database validation is available.
+- Keep migrations forward-only unless the project already maintains down migrations.
+- Use transactions for multi-step invariants and make rollback behavior explicit.
+- Configure pool size, timeouts, and retry policy deliberately.
+- Map database errors into domain errors at the boundary.
+- Avoid leaking raw SQL errors to user-facing API responses.
+- Treat schema drift between migrations, generated types, and tests as a correctness bug.
+
+## Commands
+
+```bash
+cargo test --workspace --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+sqlx migrate run
+sqlx prepare --check
+diesel migration run
+```
+
+Use the commands that match the project. Do not require SQLx or Diesel if the project uses another migration path.
+
+## Testing
+
+- Use isolated test databases, transactions, schemas, or temporary SQLite files.
+- Seed only the records each test needs.
+- Test constraints and conflict cases, not only happy-path queries.
+- Keep tests deterministic and independent of production data.
+
+## Avoid
+
+- Do not build SQL by string concatenation with untrusted input.
+- Do not add global database state that makes tests order-dependent.
+- Do not hide failed migrations or query validation behind broad error handling.
+
+## Output expectations
+
+Report schema or query changes, migration behavior, transaction assumptions, validation commands, and required database setup.

package/skills/rust-debugging/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: rust-debugging
+description: Diagnoses Rust compiler errors, borrow checker issues, panics, failing tests, cargo build problems, feature resolution conflicts, runtime bugs, and platform-specific failures. Use when Rust code does not compile or behaves incorrectly.
+license: MIT
+compatibility: Rust stable toolchain with cargo recommended.
+---
+
+# Rust Debugging
+
+Use this skill when Rust code fails to compile, tests fail, a panic occurs, or behavior differs from expectations.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Capture the exact failing command and full error output.
+3. Identify the failure class:
+   - Compiler error.
+   - Borrow checker or lifetime issue.
+   - Trait bound or type inference issue.
+   - Cargo dependency, feature, or workspace issue.
+   - Test assertion failure.
+   - Runtime panic or logic bug.
+   - Proc macro, build script, generated code, or target-specific failure.
+4. Reduce the problem to the smallest relevant module, function, feature set, target, or test.
+5. Apply the narrowest fix that preserves intent.
+6. Re-run the original failing command and then the broader validation suite.
+
+## Useful commands
+
+```bash
+cargo check --all-targets --all-features
+cargo test --all-features -- --nocapture
+RUST_BACKTRACE=1 cargo test failing_test_name -- --nocapture
+cargo tree -e features
+cargo metadata --format-version 1
+cargo clean -p crate_name
+```
+
+For workspaces, prefer package-scoped commands while isolating the problem:
+
+```bash
+cargo check -p crate_name --all-targets --all-features
+cargo test -p crate_name test_name -- --nocapture
+cargo check --target target-triple
+```
+
+For macro-heavy or generated code:
+
+```bash
+cargo expand package_or_module
+```
+
+Use `cargo expand` only if installed or worth installing.
+
+Use `cargo bisect-rustc` only when a compiler regression is plausible and the issue cannot be explained by project changes.
+
+## Triage notes
+
+- For proc macro failures, inspect expanded code and the compile-fail test if one exists.
+- For `build.rs` failures, inspect environment variables, native toolchain assumptions, generated files, and rerun directives.
+- For feature conflicts, compare `cargo tree -e features` output for the failing and passing commands.
+- For target-specific failures, confirm `cfg` branches, target dependencies, linker settings, and installed targets.
+- Prefer a small reproducer in a temporary crate when dependency, compiler, or macro behavior is unclear.
+
+## Borrow checker strategy
+
+- First, shorten borrow scopes with blocks or temporary variables.
+- Split immutable reads from mutable writes.
+- Move computation before mutation when possible.
+- Prefer `Option::take`, `mem::take`, or `std::mem::replace` when moving out of fields.
+- Avoid reflexively adding `clone`; only clone when ownership is semantically required.
+- If lifetimes become complex, reconsider the data model and ownership boundaries.
+
+## Trait and generic errors
+
+- Find the first real error; later errors are often fallout.
+- Check whether a type parameter needs a bound like `Send`, `Sync`, `Clone`, `Debug`, `DeserializeOwned`, or a lifetime bound.
+- Prefer simple concrete types until generic reuse is justified.
+- For async trait issues, check whether the returned future must be `Send`.
+
+## Panics
+
+- Search for `unwrap`, `expect`, indexing, `panic!`, `todo!`, and `unreachable!`.
+- Add context-rich errors rather than silently defaulting.
+- For tests, assert the expected error rather than accepting any failure.
+
+## Avoid
+
+- Do not hide errors with broad defaults, extra clones, or relaxed trait bounds.
+- Do not weaken tests, lints, or feature coverage to make a failure disappear.
+- Do not rewrite unrelated working code while isolating the root cause.
+
+## Output expectations
+
+Provide:
+
+- Root cause.
+- Minimal code change.
+- Why the fix satisfies Rust's ownership/type rules.
+- Commands used to verify the fix.

package/skills/rust-embedded-no-std/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: rust-embedded-no-std
+description: Builds and reviews Rust embedded and no_std projects with target triples, HALs, panic handlers, alloc constraints, probe/debug workflows, cross-compilation, hardware abstraction, and host-side tests. Use for firmware, microcontrollers, and constrained Rust targets.
+license: MIT
+compatibility: Rust stable or nightly depending on target. Embedded work may require target toolchains, probe-rs, cargo-embed, and hardware access.
+---
+
+# Rust Embedded No Std
+
+Use this skill when working on firmware, `no_std` crates, hardware abstraction layers, or constrained Rust targets.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, `.cargo/config.toml`, and `rust_project_context` output when available.
+2. Identify the target triple, board, HAL, runtime, panic strategy, allocator policy, and hardware access requirements.
+3. Separate platform-neutral logic from hardware-specific code so host-side tests can cover core behavior.
+4. Validate host tests first, then target builds, then hardware or simulator checks when available.
+5. Document any hardware-only validation that could not be run locally.
+
+## Design rules
+
+- Use `#![no_std]` only where required; keep shared crates `std`-optional when useful.
+- Gate `alloc` usage explicitly and avoid hidden heap requirements.
+- Keep interrupt handlers, DMA ownership, and peripheral access rules precise.
+- Prefer HAL traits for portability when the abstraction does not hide critical hardware behavior.
+- Choose panic handlers and logging/defmt strategy intentionally.
+- Keep unsafe code small and document register, pointer, and concurrency invariants.
+
+## Commands
+
+```bash
+cargo test --workspace --all-features
+cargo build --target target-triple
+cargo check -p crate_name --target target-triple --no-default-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Use `probe-rs`, `cargo embed`, `cargo flash`, or board-specific tools only when the project already uses them or hardware validation is requested.
+
+## Testing
+
+- Put pure logic in host-testable crates or modules.
+- Use feature flags to separate host tests from firmware builds.
+- For register-level or unsafe code, add compile checks and narrow unit tests around safe wrappers.
+- Record board, probe, firmware profile, and target triple for hardware runs.
+
+## Avoid
+
+- Do not introduce `std`, heap allocation, or blocking behavior into constrained code accidentally.
+- Do not assume hardware access is available in CI.
+- Do not weaken target builds because host tests pass.
+
+## Output expectations
+
+Report target assumptions, feature gates, hardware validation status, commands run, and any safety invariants.

package/skills/rust-ffi/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: rust-ffi
+description: Implements and reviews Rust FFI with C ABI, repr(C), raw pointers, ownership transfer, bindgen, cbindgen, unsafe boundaries, dynamic libraries, and cross-language tests. Use when Rust interoperates with C, C++, or other native languages.
+license: MIT
+compatibility: Requires careful unsafe review. C toolchain may be required depending on target.
+---
+
+# Rust FFI
+
+Use this skill when Rust crosses a native language boundary through C ABI, dynamic libraries, generated bindings, or embedded Rust.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Define ownership and lifetime contracts before writing code.
+3. Keep unsafe code at the boundary and expose safe Rust internally.
+4. Use `repr(C)` only for types that cross the ABI boundary.
+5. Validate nullability, allocation ownership, string encoding, alignment, unwinding, and thread-safety.
+6. Add cross-language smoke tests or examples when possible.
+
+## Exporting Rust to C
+
+```rust
+#[repr(C)]
+pub struct MyResult {
+    pub code: i32,
+}
+
+#[unsafe(no_mangle)]
+pub extern "C" fn my_library_do_work(input: *const std::ffi::c_char) -> MyResult {
+    if input.is_null() {
+        return MyResult { code: -1 };
+    }
+
+    let input = unsafe { std::ffi::CStr::from_ptr(input) };
+    match input.to_str() {
+        Ok(value) => {
+            let _ = value;
+            MyResult { code: 0 }
+        }
+        Err(_) => MyResult { code: -2 },
+    }
+}
+```
+
+Every unsafe block needs a safety comment explaining why pointers, aliasing, initialization, and lifetimes are valid.
+
+Prevent Rust panics from crossing FFI boundaries. Convert failures into explicit status codes or error handles, and use `catch_unwind` only when the boundary can safely recover.
+
+## Cargo setup
+
+For a dynamic/static library:
+
+```toml
+[lib]
+crate-type = ["cdylib", "staticlib", "rlib"]
+```
+
+For generating headers:
+
+```bash
+cbindgen --config cbindgen.toml --crate crate_name --output include/crate_name.h
+```
+
+For consuming C headers:
+
+```bash
+bindgen wrapper.h -o src/bindings.rs
+```
+
+## Safety checklist
+
+- Who allocates memory?
+- Who frees memory?
+- Is there a paired free function for every Rust allocation handed to foreign code?
+- Can null pointers be passed?
+- Are buffers length-delimited?
+- Are strings UTF-8, UTF-16, or platform-native?
+- Are callbacks called synchronously or asynchronously?
+- Can foreign code call from multiple threads?
+- Is unwinding across FFI prevented?
+- How is ABI versioning or symbol compatibility managed?
+- Are generated headers checked into the repo or generated in release builds?
+
+## Validation
+
+```bash
+cargo test --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+For FFI code, also run platform-specific build commands and any C/C++ integration test harness available.
+Use sanitizers or valgrind-style tooling when the project already supports them or memory ownership is risky.
+
+## Output expectations
+
+Document ABI contracts, safety invariants, ownership rules, and test evidence. Treat missing safety comments as review findings.
+
+## Avoid
+
+- Do not expose Rust-owned memory without an explicit free path.
+- Do not let panics unwind into foreign callers.
+- Do not change ABI layout without versioning or release notes.

package/skills/rust-performance/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: rust-performance
+description: Profiles and optimizes Rust code for CPU, memory, allocations, binary size, async throughput, dependency bloat, and algorithmic complexity. Use when Rust code is slow, allocates too much, or needs performance review.
+license: MIT
+compatibility: Rust stable. Optional tools include criterion, cargo-flamegraph, heaptrack, samply, perf, dhat, and cargo-bloat.
+---
+
+# Rust Performance
+
+Use this skill when the user asks to speed up Rust code, reduce allocations, shrink binary size, or explain performance tradeoffs.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Define the performance goal, workload, baseline command, and acceptable tradeoffs.
+3. Measure before changing code.
+4. Look for algorithmic improvements before micro-optimizations.
+5. Make one change at a time and compare results.
+6. Preserve readability unless the measured gain justifies complexity.
+
+## Measurement commands
+
+```bash
+cargo test --release
+cargo bench
+cargo build --release
+cargo test -p crate_name --release
+```
+
+Optional tools when installed:
+
+```bash
+cargo flamegraph --bench bench_name
+cargo bloat --release --crates
+heaptrack target/release/binary_name
+```
+
+Use `criterion` for stable benchmarks:
+
+```toml
+[dev-dependencies]
+criterion = "0.5"
+
+[[bench]]
+name = "throughput"
+harness = false
+```
+
+Record results in a compact form:
+
+```text
+workload: parse 10 MB fixture
+baseline: 125 ms median, 12.4 MB allocated
+change: reuse parse buffer
+after: 88 ms median, 4.1 MB allocated
+tradeoff: parser state is now explicit
+```
+
+## Common Rust performance checks
+
+- Avoid unnecessary `String` allocation; prefer `&str` where ownership is not needed.
+- Avoid repeated allocation inside loops; reuse buffers.
+- Prefer iterator clarity, but verify generated performance when hot.
+- Use `HashMap::with_capacity` when size is known.
+- Avoid cloning large structures; clone IDs or handles instead.
+- Use `Cow` only when it simplifies a real borrowed-or-owned API.
+- Check `Debug` or formatting in hot paths.
+- Avoid holding async locks in hot loops.
+
+## Binary size
+
+```toml
+[profile.release]
+lto = true
+codegen-units = 1
+strip = true
+panic = "abort"
+```
+
+Review dependencies and features before adding size-focused profile settings.
+
+Measure before and after with `cargo bloat --release --crates`, `twiggy`, or artifact size checks when available.
+
+## Async throughput
+
+- Look for blocking calls on executor workers.
+- Add bounded queues for backpressure.
+- Batch small operations when safe.
+- Avoid unbounded task spawning.
+- Use `tracing` to find slow spans.
+- Measure throughput, tail latency, queue depth, and cancellation behavior under realistic concurrency.
+
+## Output expectations
+
+Provide baseline measurement, change made, new measurement, tradeoffs, and commands used. If no measurement is possible, clearly label recommendations as hypotheses.
+
+## Avoid
+
+- Do not optimize without a baseline unless clearly labeled as a hypothesis.
+- Do not trade away correctness, cancellation, or public API clarity for unmeasured gains.
+- Do not add profile settings before checking dependency and feature bloat.

package/skills/rust-proc-macro/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: rust-proc-macro
+description: Builds and reviews Rust procedural macros with syn, quote, derive macros, attribute macros, diagnostics, span hygiene, generated code review, trybuild compile-fail tests, and cargo expand. Use for proc macro implementation and debugging.
+license: MIT
+compatibility: Rust stable with proc-macro crates. Common tools include syn, quote, proc-macro2, trybuild, and cargo-expand.
+---
+
+# Rust Proc Macro
+
+Use this skill when implementing, testing, debugging, or reviewing Rust procedural macros.
+
+## Workflow
+
+1. Inspect `Cargo.toml`, workspace shape, feature flags, target crates, and `rust_project_context` output when available.
+2. Identify the macro kind: derive, attribute, or function-like macro.
+3. Define accepted input syntax, generated API, diagnostics, and compatibility expectations.
+4. Inspect expanded output for representative examples.
+5. Add runtime tests for generated behavior and compile-fail tests for invalid input.
+
+## Design rules
+
+- Keep parsing strict enough to produce useful diagnostics and permissive enough for valid Rust syntax.
+- Prefer `syn` parsing types over token-string manipulation.
+- Use spans from user input for errors so diagnostics point to the right code.
+- Keep generated code simple, hygienic, and independent of local imports.
+- Reference external crates with absolute paths or documented crate-name configuration.
+- Avoid generating hidden panics for user input errors; emit compile errors instead.
+
+## Commands
+
+```bash
+cargo test --workspace --all-features
+cargo test -p macro_crate
+cargo expand -p example_crate
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+Use `cargo expand` when installed or when generated code needs inspection.
+
+## Testing
+
+- Use `trybuild` for compile-pass and compile-fail diagnostics.
+- Keep test fixtures small and named after the behavior they prove.
+- Add tests for generics, lifetimes, visibility, attributes, where clauses, and path hygiene.
+- Review stderr snapshots before accepting diagnostic changes.
+
+## Avoid
+
+- Do not parse Rust by splitting strings.
+- Do not rely on caller imports unless that is part of the documented contract.
+- Do not change generated public API without semver review.
+
+## Output expectations
+
+Report macro inputs, generated behavior, diagnostics changed, expansion checks, and tests run.

package/skills/rust-project-bootstrap/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: rust-project-bootstrap
+description: Creates new Rust crates or workspaces, chooses binary/library layouts, configures Cargo.toml, rustfmt, clippy, CI, tests, examples, feature flags, and initial project structure. Use when starting or restructuring a Rust project.
+license: MIT
+compatibility: Rust stable toolchain with cargo, rustfmt, and clippy recommended.
+---
+
+# Rust Project Bootstrap
+
+Use this skill when the task is to create a new Rust project, convert a single crate into a workspace, add a new crate, or make an existing project feel production-ready.
+
+## Workflow
+
+1. Inspect the target directory first. If it already has `Cargo.toml`, inspect workspace shape, feature flags, target crates, and `rust_project_context` output when available; preserve intent.
+2. Choose the smallest fitting project shape:
+   - CLI app: `src/main.rs`, `src/cli.rs`, integration tests in `tests/`.
+   - Library crate: `src/lib.rs`, examples in `examples/`, docs on public APIs.
+   - Workspace: root `Cargo.toml` with `[workspace]`, one crate per responsibility under `crates/`.
+3. Add a clean baseline:
+   - `.gitignore` with `target/`.
+   - `rust-toolchain.toml` if the user wants pinned Rust.
+   - `rustfmt.toml` only for intentional formatting choices.
+   - `.cargo/config.toml` only when needed for aliases, target config, or lint consistency.
+   - GitHub Actions CI if the project has or should have a public repo.
+4. Create a validation path before writing much code: `cargo fmt --check`, `cargo clippy --all-targets --all-features -- -D warnings`, and `cargo test --all-features`.
+5. Prefer standard crates only until the project requirements justify dependencies.
+
+## Cargo defaults
+
+Derive edition, resolver, and MSRV from the user's policy or the existing project. For new modern projects, prefer:
+
+```toml
+[package]
+edition = "2024"
+rust-version = "1.85"
+license = "MIT OR Apache-2.0"
+
+[dependencies]
+```
+
+When compatibility matters, use edition 2021 unless the user asks for latest Rust patterns.
+
+For applications, commit `Cargo.lock`. For libraries, follow the repository's existing policy; include it only when the workspace or project wants reproducible development checks.
+
+Design feature flags before adding optional dependencies:
+
+- Keep default features small and unsurprising.
+- Name features after capabilities, not dependency crate names, unless exposing the dependency is the intent.
+- Avoid mutually exclusive features unless the target platform requires them.
+
+## Workspace layout
+
+Use this shape for multi-crate projects:
+
+```text
+project/
+├── Cargo.toml
+├── README.md
+├── crates/
+│   ├── app/
+│   │   ├── Cargo.toml
+│   │   └── src/main.rs
+│   └── core/
+│       ├── Cargo.toml
+│       └── src/lib.rs
+├── tests/
+└── .github/workflows/ci.yml
+```
+
+Use crate names that match responsibility, such as `core`, `cli`, `server`, or `bindings`. Avoid vague member names like `common` unless the shared boundary is clear.
+
+## Baseline docs
+
+- Add README content with purpose, install/run instructions, minimal example, validation commands, and license.
+- Add license files or metadata matching the selected license expression.
+- Add public API docs for library crates and `--help` coverage for CLI crates.
+
+Root manifest:
+
+```toml
+[workspace]
+members = ["crates/*"]
+resolver = "3"
+
+[workspace.package]
+edition = "2024"
+license = "MIT OR Apache-2.0"
+rust-version = "1.85"
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+pedantic = { level = "warn", priority = -1 }
+```
+
+Each member can opt in with:
+
+```toml
+[lints]
+workspace = true
+```
+
+## Validation
+
+After generating files, run:
+
+```bash
+cargo fmt
+cargo check --workspace --all-targets --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --all-features
+```
+
+If a command fails, fix the project rather than weakening linting. If a lint is intentionally noisy, document why before allowing it.
+
+## Avoid
+
+- Do not pin a Rust version, add CI, or introduce workspace complexity unless it matches the project goals.
+- Do not add dependencies before the first real requirement needs them.
+- Do not create public APIs before the crate boundary is clear.
+
+## Output expectations
+
+When done, summarize:
+
+- Project shape chosen and why.
+- Important files created or changed.
+- Commands run and results.
+- Next implementation tickets for the agent.