agy-superpowers 5.2.2 → 5.2.4

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

@@ -1,133 +0,0 @@
-# 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

@@ -1,148 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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

@@ -1,155 +0,0 @@
-# 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