@xgent-ai/skills 0.7.4 → 0.7.6

package/skills/rust/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: rust
 description: Use when writing, reviewing, refactoring, testing or debugging Rust code. Covers ownership, errors, performance and Tokio async patterns.
+when_to_use: 'Requests like "why does the borrow checker reject this", "should this be Arc or a reference", or "write this Tokio task".'
 license: MIT
 compatibility: Rust 1.70+ (1.75+ for async fn in traits), Cargo
 allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read Write Edit Glob Grep
@@ -8,87 +9,78 @@ allowed-tools: Bash(cargo:*) Bash(rustc:*) Bash(rustfmt:*) Bash(clippy:*) Read W
 
 # Rust Best Practices
 
-Apply these guidelines when writing or reviewing Rust code. 
-
-## Best Practices Reference
-
-Before reviewing, familiarize yourself with the relevant chapters. Read ALL relevant chapters in the same turn in parallel. Reference these files when providing feedback:
-
-- [Chapter 1 - Coding Styles and Idioms](references/chapter_01.md): Borrowing vs cloning, Copy trait, Option/Result handling, iterators, import ordering, when to extract a function (duplication vs. wrong abstraction)
-- [Chapter 2 - Clippy and Linting](references/chapter_02.md): Clippy configuration, important lints, workspace lint setup
-- [Chapter 3 - Performance Mindset](references/chapter_03.md): Profiling, avoiding redundant clones, stack vs heap, zero-cost abstractions
-- [Chapter 4 - Error Handling](references/chapter_04.md): Result vs panic, thiserror vs anyhow, error hierarchies
-- [Chapter 5 - Automated Testing](references/chapter_05.md): Test naming, one assertion per test, snapshot testing
-- [Chapter 6 - Generics and Dispatch](references/chapter_06.md): Static vs dynamic dispatch, trait objects, dyn compatibility
-- [Chapter 7 - Type State Pattern](references/chapter_07.md): Compile-time state safety, when to use it
-- [Chapter 8 - Comments vs Documentation](references/chapter_08.md): When to comment, `SAFETY:`/`CONTEXT:` prefixes, TODOs as issues, doc comments, rustdoc
-- [Chapter 9 - Understanding Pointers](references/chapter_09.md): Thread safety, Send/Sync, pointer types
-- [Chapter 10 - Async Patterns with Tokio](references/chapter_10.md): Execution model, JoinSet, channels, streams, async traits, graceful shutdown, async debugging
-
-## Quick Reference
-
-### Borrowing & Ownership
-- Prefer `&T` over `.clone()` unless ownership transfer is required
-- Use `&str` over `String`, `&[T]` over `Vec<T>` in function parameters
-- Small `Copy` types (≤24 bytes) can be passed by value
-- Use `Cow<'_, T>` when ownership is ambiguous
-
-### Error Handling
-- Return `Result<T, E>` for fallible operations; avoid `panic!` in production
-- Never use `unwrap()`/`expect()` outside tests
-- Use `thiserror` for library errors, `anyhow` for binaries only
-- Prefer `?` operator over match chains for error propagation
-
-### Performance
-- Always benchmark with `--release` flag
-- Run `cargo clippy -- -D clippy::perf` for performance hints
-- Avoid cloning in loops; use `.iter()` instead of `.into_iter()` for Copy types
-- Prefer iterators over manual loops; avoid intermediate `.collect()` calls
-
-### Linting
-Run regularly: `cargo clippy --all-targets --all-features --locked -- -D warnings`
-
-Key lints to watch:
-- `redundant_clone` - unnecessary cloning
-- `large_enum_variant` - oversized variants (consider boxing)
-- `needless_collect` - premature collection
-
-Use `#[expect(clippy::lint)]` over `#[allow(...)]` with justification comment.
-
-### Testing
-- Name tests descriptively: `process_should_return_error_when_input_empty()`
-- One assertion per test when possible
-- Use doc tests (`///`) for public API examples
-- Consider `cargo insta` for snapshot testing generated output
-
-### Generics & Dispatch
-- Prefer generics (static dispatch) for performance-critical code
-- Use `dyn Trait` only when heterogeneous collections are needed
-- Box at API boundaries, not internally
-
-### Type State Pattern
-Encode valid states in the type system to catch invalid operations at compile time:
-```rust
-struct Connection<State> { /* ... */ _state: PhantomData<State> }
-struct Disconnected;
-struct Connected;
-
-impl Connection<Connected> {
-    fn send(&self, data: &[u8]) { /* only connected can send */ }
-}
-```
-
-### Async (Tokio)
-- Never block an async thread: no `std::thread::sleep`, blocking I/O or heavy CPU work in `async fn` - use `spawn_blocking`
-- Never hold a lock across `.await`; `std::sync::Mutex` is cheaper unless the guard must cross one
-- Bound concurrency with `buffer_unordered`/`Semaphore`; use `JoinSet` to own and abort task groups
-- Prefer channels over shared state - `mpsc` (work queue), `broadcast` (fan-out), `oneshot` (reply), `watch` (latest value)
-- Put a timeout on every outbound call; handle shutdown via `CancellationToken`
-- `async fn` in traits (1.75+) for static dispatch; `#[async_trait]` only when you need `dyn Trait`
-- Instrument with `tracing`: `#[instrument]` on async fns, `.instrument(span)` on spawned tasks
-
-### Documentation
-- `//` comments explain *why* (safety, workarounds, design rationale)
-- `///` doc comments explain *what* and *how* for public APIs
-- Every `TODO` needs a linked issue: `// TODO(#42): ...`
-- Enable `#![deny(missing_docs)]` for libraries
+Apply these guidelines when writing, reviewing, refactoring, testing or debugging Rust code.
+
+## Working Approach
+
+- Read the affected code, tests, `Cargo.toml`, toolchain pin and CI commands first.
+  Respect the project's edition, MSRV, feature combinations and conventions.
+- If the affected crate uses Bevy, read [Bevy practices](references/bevy.md) before
+  applying generic borrowing, import or lint advice to system functions.
+- Keep application code direct: concrete types, simple control flow and no speculative
+  traits or builders. Libraries with external callers need deliberate public contracts.
+- Model the domain with Rust's ownership, enums, traits and `Result`; do not translate
+  inheritance or exception patterns mechanically from another language.
+- During refactoring, preserve public signatures, error variants, output ordering and
+  behavior unless changing them is in scope. Explain necessary contract changes; do not
+  rename getters or replace existing parameters merely to satisfy a style preference.
+- Read-only reviews produce findings, not edits. Stay within the requested change;
+  installing tools, upgrading dependencies or publishing is not implied by this skill.
+
+## References by Task
+
+Read the relevant references before making decisions. Each topic owns its detailed rules
+and examples; follow cross-links only when the task crosses that boundary.
+
+| Task | Reference |
+|---|---|
+| Borrow-checker friction, iterators, imports or function extraction | [Coding idioms](references/coding-idioms.md) |
+| Clippy warnings, suppressions or workspace lint configuration | [Clippy and linting](references/clippy-and-linting.md) |
+| Profiling, allocations, cloning or hot paths | [Performance](references/performance.md) |
+| Fallible operations, library error types or resource cleanup | [Error handling](references/error-handling.md) |
+| Regression, property, integration or snapshot tests; controllable I/O | [Testing](references/testing.md) |
+| Closure bounds, trait contracts, static dispatch or trait objects | [Generics and dispatch](references/generics-and-dispatch.md) |
+| Compile-time state transitions | [Type state](references/type-state.md) |
+| Comments, public docs or executable examples | [Documentation](references/documentation.md) |
+| Lifetimes, smart pointers, interior mutability or shared ownership | [Pointers and ownership](references/pointers-and-ownership.md) |
+| Tokio tasks, channels, cancellation or async shared state | [Async with Tokio](references/async-tokio.md) |
+| Public types, constructors, standard traits or API evolution | [API design](references/api-design.md) |
+| Unsafe blocks, raw pointers, native handles or foreign interfaces | [Unsafe and FFI](references/unsafe-and-ffi.md) |
+| Cargo manifests, dependencies, features, MSRV or no_std | [Crates and dependencies](references/crates-and-dependencies.md) |
+| Declarative/procedural macros, generated APIs or expansion diagnostics | [Macros](references/macros.md) |
+| Queued actions, configurable algorithms, AST traversal or tree transformation | [Behavioral patterns](references/behavioral-patterns.md) |
+| Bevy systems, queries, scheduling, deferred changes or ECS tests | [Bevy](references/bevy.md) |
+
+## Core Rules
+
+- Make ownership intentional: borrow to read, move to consume, and share only when the
+  design needs multiple owners. Resolve borrow scopes before adding deep copies.
+- Use types to express domain invariants and keep public contracts deliberate. Prefer
+  concrete code; introduce traits, builders, macros or type states for an actual need.
+- Return `Result` for fallible operations and `Option` for normal absence. Never use
+  `unwrap()`/`expect()` outside tests. Use `thiserror` for library errors and `anyhow`
+  for binaries; preserve causes and add useful context. Do not use panics or
+  `catch_unwind` as ordinary error handling. Keep `Drop` non-panicking.
+- Measure performance in release builds before changing ownership, allocation, dispatch
+  or synchronization. Keep loops when they express control flow more clearly.
+- Keep blocking I/O and heavy CPU work off async workers. End synchronous lock guards
+  before `.await`; choose async synchronization only when the operation requires it.
+  Bound concurrency, handle cancellation and give outbound calls timeouts.
+- Keep unsafe code behind a small sound boundary, document each unsafe operation's
+  invariants, and document caller obligations in `# Safety` for every `unsafe fn`.
+- Keep formatting and lint policy compatible with the project and MSRV. Use narrow,
+  justified suppressions; enforce warnings-as-errors through CI rather than blanket
+  `#![deny(warnings)]` in source.
+- Test observable behavior, including failures and boundaries. Reproduce bugs before
+  fixing them; use unit, integration and doc tests for their respective contracts.
+- Use `//` for rationale and `///`/`//!` for API usage and contracts. Link TODOs to issues,
+  document errors/panics/safety where relevant, and enforce library documentation with
+  `#![deny(missing_docs)]`. Keep fallible doc examples executable with `?`.
+
+## Verification Before Handoff
+
+Use the project's commands and supported feature/target matrix. For code changes, run
+format checks, Clippy and relevant tests; include doc tests and `cargo doc --no-deps`
+for public API/doc changes. Check new syntax and dependencies against the MSRV. Unsafe,
+FFI or performance changes also need applicable Miri, platform tests or release benchmarks.
+Report what actually ran and any limitations; do not claim unrun checks passed.

package/skills/rust/references/api-design.md

@@ -0,0 +1,97 @@
+# Public API Design
+
+Read when adding or reviewing public types, constructors, traits or signatures. Apply
+these choices to new APIs; changing an existing API requires a compatibility decision.
+Application-local code should stay concrete unless reuse or a real boundary needs more.
+
+## Names and signatures
+
+- Follow std naming: `UpperCamelCase` types/traits/variants, `snake_case` functions and
+  modules, `SCREAMING_SNAKE_CASE` constants. Treat acronyms as words (`Uuid`, `HttpClient`)
+  and prefer specific domain names over vague suffixes or redundant module prefixes.
+  Name errors by the failed operation, such as `ParseAddrError`.
+- Use a method for receiver behavior; otherwise choose a free or associated function
+  by domain meaning. Keep analogous parameter ordering consistent, normally with
+  closures last. Essential operations should be discoverable without obscure trait imports.
+- Getters normally omit `get_`: use `field`, `field_mut`, `set_field`, `take_field` or
+  `replace_field` as appropriate. Pair `len` with `is_empty`; do not add unchecked access
+  just to complete a pair. Closure accessors must define borrowing/reentrancy behavior.
+- Return values in tuples or structs instead of out-parameters unless an in-place API
+  or reusable caller buffer justifies them. Return useful work already computed, such
+  as an insertion index or replaced value, when it saves callers repeating the operation.
+
+## Domain types and construction
+
+- Use newtypes to distinguish IDs and units. A type alias does not prevent mixing them.
+  Keep invariant-bearing fields private and validate through `TryFrom`, `FromStr` or a
+  fallible constructor; an infallible `From` must not accept invalid raw values.
+  A newtype also permits local trait implementations around a foreign type. Forward
+  only meaningful traits; use `repr(transparent)` when layout equivalence is contractual.
+- Use enums for mutually exclusive modes or states, `Option` for normal absence, and
+  named fields for compound data. Replace ambiguous boolean choices in new APIs with
+  named modes; a clear boolean setter need not become an enum. Independent flags may
+  use a bitflag type; a single choice remains an enum.
+- Prefer `Path`/`PathBuf` for paths and `Duration` for elapsed time. Do not weaken a
+  useful domain type merely to expose a primitive at a boundary.
+- Prefer `new`, domain verbs such as `open`/`connect`, and conventional conversion names:
+  `as_` borrows cheaply, `to_` performs conversion work, `into_` consumes the receiver.
+  Use `as_mut_slice`, not `as_slice_mut`; place conversions on the more specific type.
+- Make `new()` and `Default` agree when both represent the same default construction.
+  Do not add `Default` to a type that has no meaningful default or requires external I/O.
+- Introduce a builder when related options or cross-field validation justify it.
+  Validate the complete configuration at `build`; setters may reject individual invalid
+  values. Consuming setters move inputs; borrowing setters support staging and reuse.
+  Prefer defaults and struct-update syntax for simple options, and do not introduce a
+  builder just because a private function has several arguments.
+
+## Ownership and standard traits
+
+- Follow the [ownership choices](coding-idioms.md#11-borrowing-over-cloning) for inputs.
+  Generalize with `AsRef<Path>`, `IntoIterator` or `RangeBounds` when callers benefit;
+  weigh inference, compile-time and code-size costs. Returning an iterator avoids forced
+  allocation; return an owned collection when callers need its ownership/indexing.
+- Generic `Read`/`Write` parameters may be taken by value: callers can pass `&mut reader`
+  to retain ownership. Document consumption and buffering; accept caller-provided I/O
+  using the project's synchronous or async traits.
+- Keep smart-pointer and interior-mutability details private unless ownership or sharing
+  is itself the contract. `Box<dyn Trait>` and shared handles are legitimate boundaries;
+  do not mechanically remove them from existing signatures.
+- Implement applicable `Debug`, `Clone`, `Copy`, equality, ordering, `Hash` and `Default`.
+  Give even empty values recognizable `Debug` output. Redact secrets in diagnostic and
+  user formatting; test sensitive formatting. Do not derive `Clone` for a unique resource
+  or `Copy` for a large value just because its fields allow it.
+- If ordering ignores fields, equality must agree and hashing must hash equal values
+  identically. Derive together only when field-wise semantics are correct. Test these
+  laws when implementations are custom; do not blindly derive equality beside custom
+  order or force a partial order into `Ord` when the domain has no total order.
+- Implement `From`/`TryFrom`, not `Into`/`TryInto` directly. Use `FromStr` for parsing,
+  `Display` for user-facing text, and `FromIterator`/`Extend` for collection construction.
+  Do not hide a lossy conversion in `From` or an unchecked `as` cast. Use operator traits
+  for natural domain operations, and numeric formatting traits only when meaningful.
+- Expose useful owned, borrowed and mutable iteration, with conventional iterator names
+  such as `Iter`, `Keys`, `IntoIter`. Keep `size_hint` truthful; implement
+  `DoubleEndedIterator`/`ExactSizeIterator` only when their contracts hold.
+- Use `#[must_use]` when ignoring a result, lazy value or pure transformation is likely
+  a bug. Optional Serde integration must validate invariants on deserialization rather
+  than bypassing construction through an indiscriminate derive.
+- Put trait bounds on the implementations that need them unless the type's definition
+  itself requires a bound. Use `Deref` for smart-pointer behavior, not fake inheritance.
+
+## Visibility and evolution
+
+- Start private; widen to `pub(crate)` or `pub(super)` before committing to `pub`.
+  Keep representation details out of the public contract.
+- Consider `#[non_exhaustive]` for new extensible public enums/structs and sealing for
+  traits downstream must not implement. Retrofitting either can break existing users.
+- Treat exposed dependency types as part of the API. If callers need to name one,
+  provide an intentional public path and account for its version compatibility. Make
+  the canonical path clear while preserving alternate paths needed by existing users.
+- Treat public `const fn` capability as a compatibility commitment. Hide unstable
+  implementations behind wrappers or `impl Trait` while retaining promised traits.
+- Preserve public signatures, derives, error variants and observable output during a
+  behavior-preserving refactor. Report required before/after changes and their migration
+  impact instead of quietly applying style rules to an established contract.
+
+For dispatch tradeoffs read [Generics and dispatch](generics-and-dispatch.md); for
+compile-time transitions read [Type state](type-state.md). Error contracts are covered
+in [Error handling](error-handling.md).

package/skills/rust/references/{chapter_10.md → async-tokio.md}

@@ -1,6 +1,6 @@
-# Chapter 10 - Async Patterns with Tokio
+# Async Patterns with Tokio
 
-> Not part of the original Apollo handbook. Added to cover async Rust, which the other chapters only touch in passing (see [Chapter 4](chapter_04.md) for error traits across `.await`, and [Chapter 9](chapter_09.md) for `Send`/`Sync`).
+> Not part of the original Apollo handbook. Added to cover async Rust, which the other chapters only touch in passing (see [Error Handling](error-handling.md) for error traits across `.await`, and [Pointers and Ownership](pointers-and-ownership.md) for `Send`/`Sync`).
 
 Async Rust is not a separate language, but it does change which idioms are correct. Ownership, borrowing and error handling rules from the previous chapters still apply - what is new is that your code can be *suspended* at every `.await`, and everything held across that point must survive the suspension.
 
@@ -8,6 +8,9 @@ Async Rust is not a separate language, but it does change which idioms are corre
 
 A `Future` is **lazy**: nothing runs until something polls it. That is why an un-awaited future is a bug, not a background task.
 
+Prefer readable `async fn` declarations. Explicit returned futures remain useful for
+precise trait bounds or setup that must run before polling; document that timing distinction.
+
 ```
 Future (lazy) → poll() → Ready(value) | Pending
                 ↑           ↓
@@ -28,6 +31,12 @@ The practical consequences, each expanded later in this chapter:
 * **State held across `.await` must be `Send`** when the future is spawned on a multi-threaded runtime.
 * **Cancellation is silent.** Dropping a future stops it wherever it was suspended, so cleanup belongs in `Drop`, not after the `.await` - see [10.6](#106-graceful-shutdown).
 
+Check `Send`/`Sync` on public types and returned futures when crossing threads is part
+of their contract; local executors and thread-local APIs can intentionally be `!Send`.
+Prefer caller-owned runtime/I/O resources in libraries and document any Tokio dependency.
+Keep related shared-state invariants under one lock, shorten guard lifetimes, and avoid
+calling arbitrary user callbacks while holding a lock.
+
 ## 10.2 Project Setup
 
 ```toml
@@ -151,31 +160,32 @@ async fn mpsc_example() {
 }
 
 // broadcast: every live receiver gets every message; slow ones get Lagged
-async fn broadcast_example() {
+async fn broadcast_example() -> Result<(), broadcast::error::SendError<String>> {
     let (tx, _) = broadcast::channel::<String>(100);
 
     let mut rx1 = tx.subscribe();
     let mut rx2 = tx.subscribe();
 
-    tx.send("Event".to_string()).unwrap();
+    tx.send("Event".to_string())?;
 
     let _ = rx1.recv().await;
     let _ = rx2.recv().await;
+    Ok(())
 }
 
 // oneshot: a single value, consumed by awaiting the receiver
-async fn oneshot_example() -> String {
+async fn oneshot_example() -> Result<String, oneshot::error::RecvError> {
     let (tx, rx) = oneshot::channel::<String>();
 
     tokio::spawn(async move {
         let _ = tx.send("Result".to_string());
     });
 
-    rx.await.expect("sender dropped without sending")
+    rx.await
 }
 
 // watch: receivers see only the latest value, never a backlog
-async fn watch_example() {
+async fn watch_example() -> Result<(), watch::error::SendError<String>> {
     let (tx, mut rx) = watch::channel("initial".to_string());
 
     tokio::spawn(async move {
@@ -184,7 +194,8 @@ async fn watch_example() {
         }
     });
 
-    tx.send("updated".to_string()).unwrap();
+    tx.send("updated".to_string())?;
+    Ok(())
 }
 ```
 
@@ -192,7 +203,7 @@ async fn watch_example() {
 
 ## 10.5 Async Error Handling
 
-The rules from [Chapter 4](chapter_04.md) hold: `thiserror` for libraries, `anyhow` for binaries, `?` over match chains. Async adds one requirement - errors that cross a spawn or an `.await` boundary generally need `Send + Sync + 'static`.
+The rules from [Error Handling](error-handling.md) hold: `thiserror` for libraries, `anyhow` for binaries, `?` over match chains. Async adds one requirement - errors that cross a spawn or an `.await` boundary generally need `Send + Sync + 'static`.
 
 ```rust
 use anyhow::{Context, Result};
@@ -332,7 +343,7 @@ The catch is that such a trait is **not dyn-compatible** and its returned future
 | `Send` bound for spawning | `fn get(..) -> impl Future<Output = ..> + Send` |
 | `dyn Repository` / heterogeneous storage | `#[async_trait]` (boxes each future) |
 
-This follows the rule from [Chapter 6](chapter_06.md): static where you can, dynamic where you must. `#[async_trait]` is not deprecated - it is the tool for the `dyn` case, at the cost of one `Box` allocation per call.
+This follows the rule from [Generics and Dispatch](generics-and-dispatch.md): static where you can, dynamic where you must. `#[async_trait]` is not deprecated - it is the tool for the `dyn` case, at the cost of one `Box` allocation per call.
 
 ```rust
 use async_trait::async_trait;
@@ -420,7 +431,7 @@ async fn merge_streams() {
 }
 ```
 
-> The same advice as [Chapter 1](chapter_01.md) applies: avoid an intermediate `.collect()` when the next stage can consume the stream directly.
+> The same advice as [Coding Idioms](coding-idioms.md) applies: avoid an intermediate `.collect()` when the next stage can consume the stream directly.
 
 ## 10.9 Shared State and Resource Limits
 
@@ -466,11 +477,13 @@ impl Pool {
         }
     }
 
-    async fn acquire(&self) -> PooledConnection<'_> {
-        // The permit guarantees a connection is available
-        let permit = self.semaphore.acquire().await.expect("semaphore never closed");
-        let conn = self.connections.lock().unwrap().pop().expect("permit implies a free conn");
-        PooledConnection { pool: self, conn: Some(conn), _permit: permit }
+    async fn acquire(&self) -> anyhow::Result<PooledConnection<'_>> {
+        let permit = self.semaphore.acquire().await?;
+        let conn = self.connections.lock()
+            .map_err(|_| anyhow::anyhow!("connection pool lock poisoned"))?
+            .pop()
+            .ok_or_else(|| anyhow::anyhow!("connection pool has no free connection"))?;
+        Ok(PooledConnection { pool: self, conn: Some(conn), _permit: permit })
     }
 }
 
@@ -483,7 +496,13 @@ struct PooledConnection<'a> {
 impl Drop for PooledConnection<'_> {
     fn drop(&mut self) {
         if let Some(conn) = self.conn.take() {
-            self.pool.connections.lock().unwrap().push(conn);
+            match self.pool.connections.lock() {
+                Ok(mut connections) => connections.push(conn),
+                Err(_) => {
+                    self.pool.semaphore.close();
+                    tracing::error!("connection pool lock poisoned; closing pool");
+                }
+            }
         }
     }
 }
@@ -491,6 +510,11 @@ impl Drop for PooledConnection<'_> {
 
 > Spawning from `Drop` to run async cleanup does not work here: `tokio::spawn` requires `'static`, and `self.pool` is a borrow. Either make the cleanup synchronous as above, or hold an `Arc<Pool>` instead of a reference.
 
+This application-level example uses `anyhow`; a library pool exposes a typed error.
+Keep the free-list critical section short. On poisoning, discard the returned connection
+and close the semaphore instead of panicking during `Drop` or reusing unchecked state.
+Connections requiring slow or fallible shutdown need an explicit cleanup operation.
+
 CPU-bound or blocking work must leave the async threads:
 
 ```rust
@@ -550,5 +574,5 @@ tokio-console
 * **Don't hold a lock across `.await`** - narrow the critical section or clone the value out first.
 * **Don't use `tokio::sync::Mutex` by default** - `std::sync::Mutex` is cheaper unless the guard crosses an `.await`.
 * **Don't ignore `JoinError`** - it is how a panicked task reports itself.
-* **Don't forget `Send`** on futures you spawn, or on errors that cross task boundaries ([Chapter 9](chapter_09.md)).
+* **Don't forget `Send`** on futures you spawn, or on errors that cross task boundaries ([Pointers and Ownership](pointers-and-ownership.md)).
 * **Don't create a future you never await** - it does nothing at all.

package/skills/rust/references/behavioral-patterns.md

@@ -0,0 +1,49 @@
+# Actions, Algorithms and Tree Traversal
+
+Read when actions need queuing/replay, callers select an algorithm, or heterogeneous
+trees need traversal/transformation. Start with direct code; use a pattern only for an
+actual requirement, not to introduce a framework around a single operation.
+
+## Queue, replay or undo actions: Command
+
+Use an enum or closure for simple actions. A command trait can serve multiple operations
+that share an execution contract. Choose storage and dispatch according to ownership
+and runtime selection; a function pointer is still an indirect call.
+
+Define ordering, failure and rollback behavior. Store the data needed for undo rather
+than assuming a command makes multiple external effects transactional. Test partial
+failure, replay and rollback when those capabilities are promised.
+
+## Select an algorithm: Strategy
+
+A closure often suffices for one configurable operation; use a trait when the contract
+has richer behavior. Choose closure bounds and static/dynamic dispatch through
+[generics and dispatch](generics-and-dispatch.md). Do not add a strategy layer when a
+plain branch already expresses the choice. Test each algorithm against the shared contract.
+
+## Inspect heterogeneous nodes: Visitor
+
+Separate `visit_*` hooks from shared traversal for structures such as an AST. Specify
+traversal order, whether hooks recurse by default, early exits and error propagation.
+Verify coverage of relevant node kinds. Use ordinary iteration for homogeneous data.
+
+## Transform a tree: Fold
+
+Default recursive `fold_*` methods can rebuild a tree while overrides transform selected
+nodes. Define ownership, failure propagation and preservation of untouched nodes; test
+those properties. This structural transformation differs from `Iterator::fold`.
+
+## Evaluate a language: Interpreter
+
+Introduce an interpreter only for a real recurring language with a grammar and an error
+contract. Ordinary configuration does not need a DSL. For compile-time Rust-like syntax,
+consider [macros](macros.md). Conversion/variant concepts such as Iso or Prism may help
+reasoning, but `match`, field access and normal conversions usually suffice without an
+optics abstraction.
+
+## Related construction and resource scenarios
+
+Use [API design](api-design.md) for newtypes and builders,
+[type state](type-state.md) for compile-time protocols, and
+[error handling](error-handling.md#cleanup-and-panic-boundaries) for RAII and fallible
+teardown. These topics own their rules; do not duplicate them in a pattern layer.

package/skills/rust/references/bevy.md

@@ -0,0 +1,95 @@
+# Bevy — framework-specific Rust practices
+
+Adapted from `local/rust-best-practices/references/bevy.md`. Read only when the affected
+crate uses `bevy`/`bevy_ecs`, or the requested code is explicitly a Bevy system/plugin.
+Check the versions in `Cargo.toml` and `Cargo.lock`, then consult matching
+[API docs](https://docs.rs/bevy/0.20.0/bevy/) and
+[migration guides](https://bevy.org/learn/migration-guides/). The local digest targets
+0.20; do not migrate a project or assume its API names match that version.
+
+This is guidance, not a claim that the project's systems or every example have been
+executed. Framework exceptions below apply to Bevy APIs; general error, safety and scope
+rules still apply to helpers and application logic.
+
+## Keep Bevy's conventions
+
+- **System parameters by value:** Bevy constructs `Res`, `ResMut`, `Query`, `Single`,
+  `Commands`, `Local` and message-reader/writer parameters. Do not convert them to
+  `&Res` or `&Query` to satisfy ordinary borrowing advice. Helpers should accept the
+  narrow domain data they need rather than an entire query.
+- **Framework prelude:** `use bevy::prelude::*` is an intentional Bevy convention.
+  Do not remove it merely for being a glob or create a project prelude as a consequence.
+- **Plain-data components/resources:** public fields are reasonable for passive ECS
+  data. Protect coupled invariants where necessary; avoid getters, builders or panicking
+  constructors that add no useful contract. Apply gameplay caps at the mutation boundary.
+- **Query complexity:** multiple system parameters and complex query types can be normal.
+  Use a named alias or reusable `SystemParam` when it clarifies a shared concept, not
+  merely to satisfy `too_many_arguments` or `type_complexity`.
+- **Lint adaptation:** inspect the project's existing configuration and toolchain. A
+  justified system-specific or crate-scoped exception may be appropriate for
+  `needless_pass_by_value`, `type_complexity`, `too_many_arguments` or
+  `elided_lifetimes_in_paths`. Do not disable these globally for unrelated crates or
+  install an external lint preset. Keep the Rust 1.81 `expect` boundary in mind.
+
+## Correctness checks
+
+### Conflicting access
+
+Queries that might access the same component mutably can be rejected at runtime during
+system initialization. `With<Player>` and `With<Enemy>` do not prove disjointness because
+an entity can carry both markers. Use domain-correct `Without` filters for genuinely
+disjoint sets, or a `ParamSet` when overlapping accesses must happen sequentially.
+Check resource borrow conflicts too. Do not change gameplay membership just to silence
+the diagnostic; exercise the combined system/plugin in a test.
+
+### Deferred commands and system ordering
+
+`Commands` queue structural changes. A consumer must run after both the producer and
+the relevant deferred buffer application. Explicit ordering (`chain`, `before`, `after`
+or system sets) communicates dependencies; a tuple of systems alone does not promise order.
+Bevy 0.20 inserts `ApplyDeferred` along appropriate dependency edges by default, but
+custom schedule settings can change this. Verify the schedule actually used by the project.
+See [ApplyDeferred](https://docs.rs/bevy/0.20.0/bevy/ecs/schedule/struct.ApplyDeferred.html).
+
+Check same-frame assumptions for resources, components, messages, spawns and despawns.
+For example, checking whether a wave is empty before queued spawns become visible can
+start a duplicate wave. Order the entire observation/update sequence deliberately.
+
+### Cardinality, system errors and vanished entities
+
+Handle failed entity lookup and single-entity cardinality explicitly; a dead player or
+second camera should not turn a recoverable situation into an unwrap panic. Depending
+on the locked version and semantics, use a fallible query with `let Ok(...) = ... else`
+or an appropriate system parameter. In Bevy 0.20, `Single` validation skips a system
+when exactly-one cardinality is not met; use it only when skipping is intended.
+See [Single](https://docs.rs/bevy/0.20.0/bevy/ecs/system/struct.Single.html).
+
+Returning `Result` from a system does not alone establish graceful recovery: inspect
+the configured error handler and its default behavior. Select logging, skipping or
+escalation intentionally; do not globally silence all system errors to fix one case.
+
+Queued commands can encounter entities despawned earlier in the frame. Avoid duplicate
+despawn logic, or use the locked version's fallible/tolerant entity-command APIs such
+as `try_insert`/`try_despawn` where their semantics fit. Verify command-application errors.
+
+### Messages and event APIs
+
+Each reader maintains its own cursor; an active reader does not reread already consumed
+messages. A reader scheduled before its writer may observe data on a later update.
+Order them when same-frame handling is required and test retention when readers are
+disabled for multiple updates. Use the project's actual message/event API names and
+observer signatures; they vary between Bevy versions.
+
+## Testing systems
+
+- Use a headless `App` with only the required resources and plugins; do not pull in
+  rendering/window plugins for a pure gameplay test.
+- Control time explicitly using the chosen time resource or update strategy. Avoid
+  wall-clock sleeps, and check that a time plugin is not overwriting manually advanced time.
+- Test zero, one and multiple matching entities; overlapping markers; disappearing
+  entities; duplicate commands; message ordering; and bounds such as health caps when relevant.
+- Test deferred changes at the point the consumer observes them, not just command enqueueing.
+- Add a smoke test for the whole affected plugin and run at least two updates. Isolated
+  system tests can miss query conflicts, missing resources and cross-system ordering.
+- Record the Bevy version and which headless/native scenarios actually ran. Compile
+  success alone does not establish that systems initialize and execute correctly.