agy-superpowers 5.2.2 → 5.2.3

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

@@ -1,142 +0,0 @@
-# proj-bin-dir
-
-> Put multiple binaries in src/bin/
-
-## Why It Matters
-
-When a crate produces multiple binaries, placing them in `src/bin/` keeps the project organized. Each file becomes a separate binary target automatically, without manual `Cargo.toml` configuration.
-
-## Bad
-
-```
-my-project/
-├── Cargo.toml        # Complex [[bin]] sections for each binary
-├── src/
-│   ├── main.rs       # Which binary is this?
-│   ├── server.rs     # Is this a module or binary?
-│   ├── cli.rs        # Unclear
-│   └── lib.rs
-```
-
-```toml
-# Cargo.toml - verbose and error-prone
-[[bin]]
-name = "server"
-path = "src/server.rs"
-
-[[bin]]
-name = "cli"
-path = "src/cli.rs"
-```
-
-## Good
-
-```
-my-project/
-├── Cargo.toml        # Clean, no [[bin]] needed
-├── src/
-│   ├── lib.rs        # Shared library code
-│   └── bin/
-│       ├── server.rs # Binary: my-project-server (or just server)
-│       └── cli.rs    # Binary: my-project-cli (or just cli)
-```
-
-Each file in `src/bin/` automatically becomes a binary named after the file.
-
-## Running Binaries
-
-```bash
-# Run specific binary
-cargo run --bin server
-cargo run --bin cli
-
-# Build specific binary
-cargo build --bin server
-
-# Build all binaries
-cargo build --bins
-```
-
-## Pattern: Binary with Multiple Files
-
-For complex binaries, use directories:
-
-```
-src/
-├── lib.rs
-└── bin/
-    ├── server/
-    │   ├── main.rs      # Entry point
-    │   ├── config.rs    # Server-specific module
-    │   └── handlers.rs
-    └── cli/
-        ├── main.rs
-        └── commands.rs
-```
-
-## Pattern: Shared Library Code
-
-```rust
-// src/lib.rs - Shared code
-pub mod config;
-pub mod database;
-pub mod models;
-
-// src/bin/server.rs - Server binary
-use my_project::{config, database, models};
-
-fn main() {
-    let config = config::load();
-    let db = database::connect(&config);
-    // ...
-}
-
-// src/bin/cli.rs - CLI binary
-use my_project::{config, models};
-
-fn main() {
-    let config = config::load();
-    // CLI logic using shared code
-}
-```
-
-## Binary Naming
-
-| File Path | Binary Name |
-|-----------|-------------|
-| `src/main.rs` | `my-project` (crate name) |
-| `src/bin/server.rs` | `server` |
-| `src/bin/my-cli.rs` | `my-cli` |
-| `src/bin/server/main.rs` | `server` |
-
-## Explicit Configuration
-
-When you need custom settings:
-
-```toml
-[[bin]]
-name = "my-server"
-path = "src/bin/server.rs"
-required-features = ["server"]
-
-[[bin]]
-name = "my-cli"
-path = "src/bin/cli.rs"
-```
-
-## Pattern: Default Binary
-
-```toml
-# src/main.rs is the default binary
-# Additional binaries in src/bin/
-
-[package]
-name = "my-tool"
-default-run = "my-tool"  # Or specify another
-```
-
-## See Also
-
-- [proj-lib-main-split](./proj-lib-main-split.md) - Keep main.rs minimal
-- [proj-workspace-large](./proj-workspace-large.md) - Workspace for larger projects
-- [proj-flat-small](./proj-flat-small.md) - Simple project structure

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