agent-workflow-kit-cli 1.3.2 → 1.3.4

package/templates/rust/rules/memory-concurrency.md

@@ -0,0 +1,47 @@
+# Memory Management & Concurrency in Rust
+
+This document details conventions for lifetimes, smart pointer usage, and async Tokio runtime operations.
+
+---
+
+## ⏳ Lifetime Annotations ('a)
+- When a struct or function references a borrowing context, annotate lifetimes explicitly to guarantee spatial memory safety:
+```rust
+pub struct TokenValidator<'a> {
+    pub secret_key: &'a str,
+}
+```
+- Avoid bypassing the borrow checker with unnecessary `.clone()` calls or `'static` lifetime modifiers if the scope can be expressed with valid lifetime relationships.
+
+---
+
+## 🧠 Smart Pointer Matrix
+Select the correct smart pointer types according to the allocation scope:
+
+| Smart Pointer | Environment | Memory Allocation Characteristics | Application Use Case |
+| :--- | :--- | :--- | :--- |
+| **`Box<T>`** | Single / Multi-thread | Allocates large types on the Heap | Flattens recursive data structures (Sized types) |
+| **`Rc<T>`** | Single-thread Only | Reference count without thread safety | Shares immutable data across a single-threaded runtime |
+| **`Arc<T>`** | Multi-thread | Thread-safe Reference Count (Atomic) | Shares immutable resources across thread pools (e.g., Web Server) |
+| **`RefCell<T>`** | Single-thread Only | Interior Mutability (Checked at Runtime) | Mutates fields inside an immutable single-threaded struct |
+| **`Mutex<T>`** | Multi-thread | Thread safety via OS or runtime lock | Protects mutable resources shared across multiple threads |
+
+---
+
+## 🚦 Async Runtime (Tokio) CPU vs I/O Bound Tasks
+Blocking the executor threads in an async environment will starve the thread pool, degrading throughput.
+- **I/O Bound Tasks:** (DB Queries, Async file read/write, HTTP calls). Use standard `async/await` syntax.
+- **CPU Bound Tasks:** (Password hashing, image processing, complex computations). Never run these directly in the async thread pool. Use `tokio::task::spawn_blocking`:
+```rust
+let hashed_password = tokio::task::spawn_blocking(move || {
+    bcrypt::hash(password, bcrypt::DEFAULT_COST)
+})
+.await
+.unwrap()?;
+```
+
+---
+
+## 🔒 Send + Sync Traits & MutexGuard Safety
+- Shared items sent across task boundaries (`tokio::spawn`) must implement `Send` and `Sync`.
+- **MutexGuard across Await:** Never hold a non-thread-safe guard (like `std::sync::MutexGuard`) across `.await` points. Doing so will lead to compilation errors or runtime deadlocks. If a lock must span an await point, use `tokio::sync::Mutex`.

package/templates/rust/rules/project-layout.md

@@ -0,0 +1,49 @@
+# Rust Crate Layout & Modular Architecture
+
+This document defines module structures, visibility scopes, Cargo Workspace configurations, and dependency injection in Rust.
+
+---
+
+## 🏗️ Modules & Crate Separation
+- **Separating Binary & Library:**
+  - `src/main.rs`: Entrypoint of the binary application. Responsible only for parsing arguments, reading configuration, and starting the runtime.
+  - `src/lib.rs`: Holds 100% of the core business logic, enabling testability and decoupling.
+- **Visibility Scope Control:** Do not expose symbols using `pub` indiscriminately. Prefer `pub(crate)` to limit access to within the same crate, maintaining strict encapsulation.
+
+---
+
+## 📦 Cargo Workspaces (Multi-Crate Monorepos)
+For large monorepo systems, split the project into a Cargo Workspace containing isolated crates to enable parallel compilation:
+```toml
+# Cargo.toml at the root directory
+[workspace]
+members = [
+    "crates/api-gateway",
+    "crates/user-domain",
+    "crates/core-engine",
+    "crates/shared-utils"
+]
+```
+
+---
+
+## 💉 Trait-Based Dependency Injection (DI)
+Due to Rust's strict lifetimes and borrow checker, decouple dependencies by implementing **Traits** combined with thread-safe smart pointers: `Arc<dyn Trait + Send + Sync>`.
+```rust
+use std::sync::Arc;
+
+pub trait UserRepository: Send + Sync {
+    fn find_by_id(&self, id: i64) -> Result<User, AppError>;
+}
+
+pub struct UserService {
+    // Thread-safe pointer to dynamic trait implementation
+    repo: Arc<dyn UserRepository>,
+}
+
+impl UserService {
+    pub fn new(repo: Arc<dyn UserRepository>) -> Self {
+        Self { repo }
+    }
+}
+```

package/templates/rust/rules/rust-style.md

@@ -0,0 +1,26 @@
+# Idiomatic Rust Style & Optimization
+
+This document outlines standard conventions for writing idiomatic Rust code, optimizing borrowing, and complying with Clippy.
+
+---
+
+## 🦀 Idiomatic Rust Conventions
+- **Pattern Matching:** Leverage Pattern Matching (`match`, `if let`, `let-else`) instead of deep nested `if/else` checks to handle control flow safely.
+- **Naming Conventions:**
+  - `snake_case` for functions, methods, variables, and modules.
+  - `PascalCase` for Structs, Enums, Traits, and Unions.
+  - `SCREAMING_SNAKE_CASE` for constants and statics.
+
+---
+
+## 🧠 Borrowing & Cloning Optimizations
+AI models often overuse `.clone()` to satisfy the Rust Borrow Checker, which degrades performance and negates Rust's zero-cost abstraction benefits.
+- **Minimize Cloning:** Use `.clone()` or `.to_string()` on Heap-allocated objects (e.g., `String`, `Vec`) only when you absolutely need independent ownership.
+- **Leverage References:** Pass read references `&T` or write references `&mut T`. For strings, prefer `&str` over `String` parameter types.
+- **Exclusive Write Access:** Restrict code to have only one active mutable reference `&mut T` in a given scope, with no concurrent immutable reference `&T`.
+
+---
+
+## 🛠️ Clippy Specifications
+- Code generated by the AI Agent must strictly follow all optimizations suggested by Clippy.
+- Run validation checks: `cargo clippy -- -D warnings` and guarantee **Zero Warnings** before submitting pull requests.

package/templates/rust/skills/rust-db/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: rust-db
+description: Scaffold a database repository layer in Rust using SQLx, Diesel, or SeaORM
+---
+
+Follow this process to add database models, tables, and access methods in Rust.
+
+Inputs:
+- modelName: Name of the struct (e.g., `User`)
+- tableName: Database table name (e.g., `users`)
+- databaseLibrary: DB access style: SQLx, Diesel, or SeaORM
+
+Steps:
+1. Declare the database entity struct, applying appropriate serialization/deserialization attributes (e.g., `#[derive(Debug, Serialize, Deserialize, sqlx::FromRow)]`).
+2. Define the repository trait or struct handling asynchronous database connection execution.
+3. If using SQLx, write queries using async query macros to ensure compile-time SQL validation:
+   ```rust
+   let user = sqlx::query_as!<User, _>(
+       "SELECT id, email, created_at FROM users WHERE id = $1", id
+   )
+   .fetch_one(&self.pool)
+   .await?;
+   ```
+4. If using Diesel or SQLx migrations, add a migration script under the `/migrations` directory.
+5. Setup connection pooling parameters and pass database pool references using constructor dependency injection.
+6. Verify query compilation and formatting:
+   - `cargo clippy --all-targets -- -D warnings`

package/templates/rust/skills/rust-feature/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: rust-feature
+description: Scaffold a Rust module, including structs, traits, implementations, and unit/integration tests
+---
+
+Follow this process to generate a new Rust feature or sub-module.
+
+Inputs:
+- moduleName: Name of the module/file (e.g., `billing`)
+- traitName: Name of the trait interface if any (e.g., `BillingService`)
+- functionality: Summary of the business requirements and structs
+
+Steps:
+1. Create a file under `src/` named `<moduleName>.rs` (e.g., `src/billing.rs`), or a subdirectory containing `mod.rs`.
+2. Register the module in `lib.rs` or `main.rs` using `pub mod <moduleName>;`.
+3. Declare traits, structs, and custom error types (using `thiserror` for domain-specific errors) in the new module.
+4. Implement functionality for the structs, mapping options and results safely (no `unwrap` or `expect` allowed in production).
+5. Write inline unit tests inside a nested `tests` module decorated with `#[cfg(test)]`:
+   ```rust
+   #[cfg(test)]
+   mod tests {
+       use super::*;
+
+       #[test]
+       fn test_feature_logic() {
+           // Arrange, Act, Assert
+       }
+   }
+   ```
+6. Add integration tests inside `/tests` if this feature integrates multiple modules or dependencies.
+7. Verify compilation and warnings:
+   - `cargo check`
+   - `cargo test`
+   - `cargo clippy --all-targets -- -D warnings`