agy-superpowers 5.1.4 → 5.1.5

package/template/agent/skills/rust-developer/references/rust-rules/proj-flat-small.md

@@ -0,0 +1,133 @@
+# proj-flat-small
+
+> Keep small projects flat
+
+## Why It Matters
+
+Over-organizing small projects adds navigation overhead without benefit. A project with 5-10 files doesn't need nested directories. Start flat, add structure only when complexity demands it.
+
+## Bad
+
+```
+src/
+├── core/
+│   └── mod.rs           # Just re-exports
+├── domain/
+│   ├── mod.rs
+│   └── models/
+│       ├── mod.rs
+│       └── user.rs      # 50 lines
+├── infrastructure/
+│   ├── mod.rs
+│   └── database/
+│       ├── mod.rs
+│       └── connection.rs # 30 lines
+├── application/
+│   ├── mod.rs
+│   └── services/
+│       └── mod.rs       # Empty
+└── main.rs
+```
+
+## Good
+
+```
+src/
+├── main.rs
+├── lib.rs
+├── config.rs
+├── database.rs
+├── user.rs
+└── error.rs
+```
+
+## When to Add Structure
+
+| File Count | Structure |
+|------------|-----------|
+| < 10 files | Flat in `src/` |
+| 10-20 files | Group by feature |
+| 20+ files | Feature folders with submodules |
+
+## Progressive Structuring
+
+### Stage 1: Flat
+
+```
+src/
+├── main.rs
+├── config.rs
+├── user.rs
+└── database.rs
+```
+
+### Stage 2: Logical Groups
+
+```
+src/
+├── main.rs
+├── config.rs
+├── user.rs
+├── order.rs        # Getting bigger
+├── order_item.rs   # Related to order
+└── database.rs
+```
+
+### Stage 3: Feature Folders
+
+```
+src/
+├── main.rs
+├── config.rs
+├── user.rs
+├── order/          # Now complex enough
+│   ├── mod.rs
+│   ├── model.rs
+│   └── item.rs
+└── database.rs
+```
+
+## Signs You Need More Structure
+
+- Files exceed 300-500 lines
+- Related files are hard to identify
+- You're adding `_` prefixes for grouping (`user_model.rs`, `user_service.rs`)
+- New team members get lost
+- Same concepts repeated in file names
+
+## Signs of Over-Structure
+
+- Folders with 1-2 files
+- `mod.rs` files that only re-export
+- Deep nesting for simple concepts
+- More lines in module declarations than code
+
+## Example: CLI Tool
+
+```
+src/
+├── main.rs         # Argument parsing, entry point
+├── commands.rs     # CLI subcommands
+├── config.rs       # Configuration loading
+└── output.rs       # Formatting, printing
+```
+
+Not:
+
+```
+src/
+├── cli/
+│   └── commands/
+│       └── mod.rs
+├── config/
+│   └── mod.rs
+└── presentation/
+    └── output/
+        └── mod.rs
+```
+
+## See Also
+
+- [proj-mod-by-feature](./proj-mod-by-feature.md) - Feature organization
+- [proj-lib-main-split](./proj-lib-main-split.md) - Lib/main separation
+- [proj-mod-rs-dir](./proj-mod-rs-dir.md) - Multi-file modules

package/template/agent/skills/rust-developer/references/rust-rules/proj-lib-main-split.md

@@ -0,0 +1,148 @@
+# proj-lib-main-split
+
+> Keep `main.rs` minimal, logic in `lib.rs`
+
+## Why It Matters
+
+Putting your logic in `lib.rs` makes it testable, reusable, and keeps `main.rs` as a thin entry point. Integration tests can only access your library crate, not binary code in `main.rs`.
+
+## Bad
+
+```rust
+// src/main.rs - everything here
+fn main() {
+    let args = parse_args();
+    let config = load_config(&args.config_path).unwrap();
+    let db = connect_database(&config.db_url).unwrap();
+    
+    // Hundreds of lines of application logic...
+    // All untestable from integration tests!
+}
+
+fn parse_args() -> Args { /* ... */ }
+fn load_config(path: &str) -> Result<Config, Error> { /* ... */ }
+fn connect_database(url: &str) -> Result<Db, Error> { /* ... */ }
+// ... more functions that can't be tested
+```
+
+## Good
+
+```rust
+// src/main.rs - thin entry point
+use my_app::{run, Config};
+
+fn main() -> anyhow::Result<()> {
+    let config = Config::from_env()?;
+    run(config)
+}
+
+// src/lib.rs - all the logic
+pub mod config;
+pub mod database;
+pub mod handlers;
+
+pub use config::Config;
+
+pub fn run(config: Config) -> anyhow::Result<()> {
+    let db = database::connect(&config.db_url)?;
+    let app = handlers::build_app(db);
+    app.run()
+}
+```
+
+## With CLI Arguments
+
+```rust
+// src/main.rs
+use clap::Parser;
+use my_app::{run, Args};
+
+fn main() -> anyhow::Result<()> {
+    let args = Args::parse();
+    run(args)
+}
+
+// src/lib.rs
+use clap::Parser;
+
+#[derive(Parser, Debug)]
+#[command(name = "myapp", version, about)]
+pub struct Args {
+    #[arg(short, long)]
+    pub config: PathBuf,
+    
+    #[arg(short, long, default_value = "info")]
+    pub log_level: String,
+}
+
+pub fn run(args: Args) -> anyhow::Result<()> {
+    // All application logic here - testable!
+}
+```
+
+## Project Structure
+
+```
+my_app/
+├── Cargo.toml
+├── src/
+│   ├── main.rs       # Entry point only
+│   ├── lib.rs        # Library root, re-exports
+│   ├── config.rs     # Configuration
+│   ├── database.rs   # Database connection
+│   └── handlers/     # Request handlers
+│       ├── mod.rs
+│       └── users.rs
+└── tests/
+    └── integration.rs  # Can access lib.rs!
+```
+
+## Testing Benefits
+
+```rust
+// tests/integration.rs - can test everything!
+use my_app::{Config, run, database};
+
+#[test]
+fn test_database_connection() {
+    let config = Config::test_config();
+    let db = database::connect(&config.db_url).unwrap();
+    assert!(db.is_connected());
+}
+
+#[test]
+fn test_full_workflow() {
+    let config = Config::test_config();
+    // Test the actual run function
+    assert!(my_app::run(config).is_ok());
+}
+```
+
+## Multiple Binaries
+
+```rust
+// src/lib.rs - shared code
+pub mod core;
+pub mod utils;
+
+// src/bin/server.rs
+use my_app::core::Server;
+
+fn main() -> anyhow::Result<()> {
+    Server::new()?.run()
+}
+
+// src/bin/cli.rs
+use my_app::core::Client;
+
+fn main() -> anyhow::Result<()> {
+    let client = Client::new()?;
+    client.execute_command()
+}
+```
+
+## See Also
+
+- [proj-bin-dir](proj-bin-dir.md) - Put multiple binaries in src/bin/
+- [proj-mod-by-feature](proj-mod-by-feature.md) - Organize modules by feature
+- [test-integration-dir](test-integration-dir.md) - Integration tests in tests/

package/template/agent/skills/rust-developer/references/rust-rules/proj-mod-by-feature.md

@@ -0,0 +1,130 @@
+# proj-mod-by-feature
+
+> Organize modules by feature, not type
+
+## Why It Matters
+
+Feature-based organization keeps related code together, making navigation intuitive and changes localized. Type-based organization (all handlers in one folder, all models in another) scatters related code across the codebase, making features harder to understand and modify.
+
+## Bad
+
+```
+src/
+├── controllers/
+│   ├── user_controller.rs
+│   ├── order_controller.rs
+│   └── product_controller.rs
+├── models/
+│   ├── user.rs
+│   ├── order.rs
+│   └── product.rs
+├── services/
+│   ├── user_service.rs
+│   ├── order_service.rs
+│   └── product_service.rs
+└── repositories/
+    ├── user_repository.rs
+    ├── order_repository.rs
+    └── product_repository.rs
+```
+
+## Good
+
+```
+src/
+├── user/
+│   ├── mod.rs           # Re-exports public items
+│   ├── model.rs         # User struct, types
+│   ├── repository.rs    # Database operations
+│   ├── service.rs       # Business logic
+│   └── handler.rs       # HTTP handlers
+├── order/
+│   ├── mod.rs
+│   ├── model.rs
+│   ├── repository.rs
+│   ├── service.rs
+│   └── handler.rs
+├── product/
+│   ├── mod.rs
+│   ├── model.rs
+│   ├── repository.rs
+│   └── handler.rs
+└── lib.rs
+```
+
+## Benefits
+
+| Aspect | Type-Based | Feature-Based |
+|--------|------------|---------------|
+| Finding code | Search across folders | One folder per feature |
+| Adding feature | Touch 4+ folders | Create one folder |
+| Understanding feature | Jump between folders | Everything in one place |
+| Deleting feature | Hunt through codebase | Delete one folder |
+| Code ownership | Unclear | Clear feature owners |
+
+## Module Structure
+
+```rust
+// src/user/mod.rs
+mod model;
+mod repository;
+mod service;
+mod handler;
+
+// Re-export public API
+pub use model::{User, UserId, CreateUserRequest};
+pub use handler::router;
+pub(crate) use service::UserService;
+```
+
+## Shared Code
+
+```
+src/
+├── user/
+├── order/
+├── shared/              # Cross-cutting concerns
+│   ├── mod.rs
+│   ├── database.rs      # Connection pool
+│   ├── error.rs         # Common error types
+│   └── middleware.rs    # Auth, logging
+└── lib.rs
+```
+
+## When to Flatten
+
+Small modules don't need deep nesting:
+
+```
+src/
+├── user/
+│   ├── mod.rs           # Contains User struct + simple functions
+│   └── repository.rs    # Only if complex enough
+├── config.rs            # Simple enough for single file
+└── lib.rs
+```
+
+## Hybrid Approach
+
+For larger features, nest further by concern:
+
+```
+src/
+├── billing/
+│   ├── mod.rs
+│   ├── invoice/
+│   │   ├── mod.rs
+│   │   ├── model.rs
+│   │   └── service.rs
+│   ├── payment/
+│   │   ├── mod.rs
+│   │   ├── model.rs
+│   │   └── processor.rs
+│   └── shared.rs
+```
+
+## See Also
+
+- [proj-flat-small](./proj-flat-small.md) - Keep small projects flat
+- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Clean public API
+- [proj-lib-main-split](./proj-lib-main-split.md) - Lib/main separation

package/template/agent/skills/rust-developer/references/rust-rules/proj-mod-rs-dir.md

@@ -0,0 +1,120 @@
+# proj-mod-rs-dir
+
+> Use mod.rs for multi-file modules
+
+## Why It Matters
+
+Rust offers two styles for multi-file modules. The `mod.rs` style is clearer for larger modules and aligns with how most Rust projects are structured. Choose one style consistently.
+
+## Two Styles
+
+### Style 1: mod.rs (Recommended for larger modules)
+
+```
+src/
+├── user/
+│   ├── mod.rs          # Module root
+│   ├── model.rs
+│   └── repository.rs
+└── lib.rs
+```
+
+```rust
+// src/lib.rs
+mod user;  // Looks for user/mod.rs or user.rs
+
+// src/user/mod.rs
+mod model;
+mod repository;
+pub use model::User;
+```
+
+### Style 2: Adjacent file (Recommended for smaller modules)
+
+```
+src/
+├── user.rs             # Module root
+├── user/
+│   ├── model.rs
+│   └── repository.rs
+└── lib.rs
+```
+
+```rust
+// src/lib.rs
+mod user;  // Looks for user.rs, then user/ for submodules
+
+// src/user.rs
+mod model;
+mod repository;
+pub use model::User;
+```
+
+## When to Use Each
+
+| Scenario | Recommendation |
+|----------|----------------|
+| Simple module (1-3 submodules) | Adjacent file (`user.rs` + `user/`) |
+| Complex module (4+ submodules) | `mod.rs` style (`user/mod.rs`) |
+| Deep nesting | `mod.rs` at each level |
+| Library with public modules | Consistent style throughout |
+
+## mod.rs Benefits
+
+- Clear that `user/` is a module directory
+- All module code inside the folder
+- Easier to move/rename entire modules
+- Common in large codebases (tokio, serde)
+
+## Adjacent File Benefits
+
+- Module declaration outside directory
+- Can see module's interface without entering folder
+- Matches Rust 2018+ default lint preference
+- Good for small modules with few submodules
+
+## Example: Complex Module
+
+```
+src/
+├── database/
+│   ├── mod.rs          # Main module, re-exports
+│   ├── connection.rs   # Connection pool
+│   ├── migrations.rs   # Schema migrations
+│   ├── queries/        # Sub-module for queries
+│   │   ├── mod.rs
+│   │   ├── user.rs
+│   │   └── order.rs
+│   └── error.rs
+└── lib.rs
+```
+
+```rust
+// src/database/mod.rs
+mod connection;
+mod migrations;
+mod queries;
+mod error;
+
+pub use connection::Pool;
+pub use error::DatabaseError;
+pub use queries::{UserQueries, OrderQueries};
+```
+
+## Consistency Rule
+
+Pick one style for your project and stick with it:
+
+```rust
+// Cargo.toml or clippy.toml
+[lints.clippy]
+mod_module_files = "warn"  # Enforces mod.rs style
+# OR
+self_named_module_files = "warn"  # Enforces adjacent style
+```
+
+## See Also
+
+- [proj-flat-small](./proj-flat-small.md) - Keep small projects flat
+- [proj-mod-by-feature](./proj-mod-by-feature.md) - Feature organization
+- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Re-export patterns

package/template/agent/skills/rust-developer/references/rust-rules/proj-prelude-module.md

@@ -0,0 +1,155 @@
+# proj-prelude-module
+
+> Create prelude module for common imports
+
+## Why It Matters
+
+A `prelude` module collects the most commonly used types and traits for glob import. Users write `use my_crate::prelude::*` instead of many individual imports. This follows the pattern established by `std::prelude`.
+
+## Bad
+
+```rust
+// Users must import everything individually
+use my_crate::Client;
+use my_crate::Config;
+use my_crate::Error;
+use my_crate::Request;
+use my_crate::Response;
+use my_crate::traits::Handler;
+use my_crate::traits::Middleware;
+use my_crate::types::Method;
+```
+
+## Good
+
+```rust
+// src/lib.rs
+pub mod prelude {
+    pub use crate::{
+        Client,
+        Config,
+        Error,
+        Request,
+        Response,
+    };
+    pub use crate::traits::{Handler, Middleware};
+    pub use crate::types::Method;
+}
+
+// Users write:
+use my_crate::prelude::*;
+```
+
+## What to Include
+
+| Include | Don't Include |
+|---------|---------------|
+| Core types users always need | Rarely-used types |
+| Common traits | Implementation details |
+| Error types | Internal helpers |
+| Extension traits | Feature-gated items (usually) |
+| Type aliases | Everything |
+
+## Example: Web Framework Prelude
+
+```rust
+pub mod prelude {
+    // Core request/response
+    pub use crate::{Request, Response, Body};
+    
+    // Error handling
+    pub use crate::Error;
+    
+    // Common traits
+    pub use crate::traits::{FromRequest, IntoResponse};
+    
+    // Routing
+    pub use crate::Router;
+    
+    // HTTP types
+    pub use crate::http::{Method, StatusCode};
+}
+```
+
+## Example: Database Library Prelude
+
+```rust
+pub mod prelude {
+    // Connection and pool
+    pub use crate::{Connection, Pool};
+    
+    // Query building
+    pub use crate::query::{Query, Select, Insert, Update, Delete};
+    
+    // Traits for custom types
+    pub use crate::traits::{FromRow, ToSql};
+    
+    // Error type
+    pub use crate::Error;
+}
+```
+
+## Pattern: Tiered Preludes
+
+```rust
+// Minimal prelude
+pub mod prelude {
+    pub use crate::{Client, Config, Error};
+}
+
+// Full prelude for power users
+pub mod full_prelude {
+    pub use crate::prelude::*;
+    pub use crate::advanced::*;
+    pub use crate::extensions::*;
+}
+```
+
+## Pattern: Feature-Gated Prelude Items
+
+```rust
+pub mod prelude {
+    pub use crate::{Client, Error};
+    
+    #[cfg(feature = "async")]
+    pub use crate::async_client::AsyncClient;
+    
+    #[cfg(feature = "serde")]
+    pub use crate::serde::{Serialize, Deserialize};
+}
+```
+
+## Guidelines
+
+1. **Be conservative** - Only include truly common items
+2. **Avoid conflicts** - Don't include names that might clash (e.g., `Error`)
+3. **Document it** - List what's included in module docs
+4. **Stay stable** - Removing items is breaking change
+
+## Documenting the Prelude
+
+```rust
+//! Common imports for convenient glob importing.
+//!
+//! # Usage
+//!
+//! ```
+//! use my_crate::prelude::*;
+//! ```
+//!
+//! # Contents
+//!
+//! This prelude re-exports:
+//! - [`Client`] - The main API client
+//! - [`Config`] - Client configuration
+//! - [`Error`] - Error type
+pub mod prelude {
+    // ...
+}
+```
+
+## See Also
+
+- [proj-pub-use-reexport](./proj-pub-use-reexport.md) - Re-export patterns
+- [api-extension-trait](./api-extension-trait.md) - Extension traits
+- [doc-module-inner](./doc-module-inner.md) - Module documentation