devflow-kit 1.8.2 → 2.0.0

package/shared/skills/rust/references/patterns.md

@@ -1,210 +0,0 @@
-# Rust Extended Patterns
-
-Extended correct patterns for Rust. Reference from main SKILL.md.
-
-## Typestate Pattern
-
-Encode valid state transitions in the type system so invalid sequences don't compile.
-
-```rust
-// States are zero-sized types — no runtime cost
-struct Draft;
-struct Published;
-struct Archived;
-
-struct Article<State> {
-    title: String,
-    body: String,
-    _state: std::marker::PhantomData<State>,
-}
-
-impl Article<Draft> {
-    pub fn new(title: String, body: String) -> Self {
-        Article { title, body, _state: std::marker::PhantomData }
-    }
-
-    pub fn publish(self) -> Article<Published> {
-        Article { title: self.title, body: self.body, _state: std::marker::PhantomData }
-    }
-}
-
-impl Article<Published> {
-    pub fn archive(self) -> Article<Archived> {
-        Article { title: self.title, body: self.body, _state: std::marker::PhantomData }
-    }
-}
-
-// article.archive() on Draft won't compile — transition enforced at compile time
-```
-
----
-
-## Error Handling Hierarchy
-
-Layer errors from specific to general using `thiserror` for libraries and `anyhow` for applications.
-
-```rust
-// Library: precise, typed errors
-#[derive(thiserror::Error, Debug)]
-pub enum RepoError {
-    #[error("entity {entity} with id {id} not found")]
-    NotFound { entity: &'static str, id: String },
-    #[error("duplicate key: {0}")]
-    Duplicate(String),
-    #[error("connection failed")]
-    Connection(#[from] sqlx::Error),
-}
-
-// Application: ergonomic error propagation
-use anyhow::{Context, Result};
-
-fn run() -> Result<()> {
-    let config = load_config()
-        .context("failed to load configuration")?;
-    let db = connect_db(&config.database_url)
-        .context("failed to connect to database")?;
-    serve(db, config.port)
-        .context("server exited with error")
-}
-```
-
----
-
-## Trait Objects vs Generics
-
-### Use Generics for Performance (Monomorphization)
-
-```rust
-fn largest<T: PartialOrd>(list: &[T]) -> Option<&T> {
-    list.iter().reduce(|a, b| if a >= b { a } else { b })
-}
-```
-
-### Use Trait Objects for Heterogeneous Collections
-
-```rust
-trait Handler: Send + Sync {
-    fn handle(&self, request: &Request) -> Response;
-}
-
-struct Router {
-    routes: Vec<Box<dyn Handler>>, // Different concrete types in one Vec
-}
-```
-
-### Decision Guide
-
-| Criteria | Generics | Trait Objects |
-|----------|----------|--------------|
-| Known types at compile time | Yes | No |
-| Heterogeneous collection | No | Yes |
-| Performance-critical | Yes | Acceptable overhead |
-| Binary size concern | Increases | Minimal |
-
----
-
-## Smart Pointers
-
-### Box — Heap Allocation
-
-```rust
-// Recursive types require indirection
-enum List<T> {
-    Cons(T, Box<List<T>>),
-    Nil,
-}
-```
-
-### Rc/Arc — Shared Ownership
-
-```rust
-use std::sync::Arc;
-
-// Shared read-only config across threads
-let config = Arc::new(load_config()?);
-let config_clone = Arc::clone(&config);
-tokio::spawn(async move {
-    use_config(&config_clone).await;
-});
-```
-
-### When to Use Each
-
-| Pointer | Use Case |
-|---------|----------|
-| `Box<T>` | Single owner, heap allocation, recursive types |
-| `Rc<T>` | Multiple owners, single-threaded |
-| `Arc<T>` | Multiple owners, multi-threaded |
-| `Cow<'a, T>` | Clone-on-write, flexible borrowing |
-
----
-
-## From/Into Conversions
-
-```rust
-// Implement From for automatic Into
-impl From<CreateUserRequest> for User {
-    fn from(req: CreateUserRequest) -> Self {
-        User {
-            id: Uuid::new_v4(),
-            name: req.name,
-            email: req.email,
-            created_at: Utc::now(),
-        }
-    }
-}
-
-// Callers get Into for free
-fn save_user(user: impl Into<User>) -> Result<(), DbError> {
-    let user: User = user.into();
-    // ...
-    Ok(())
-}
-```
-
----
-
-## Derive and Trait Best Practices
-
-```rust
-// Derive the standard set for data types
-#[derive(Debug, Clone, PartialEq, Eq, Hash)]
-pub struct UserId(String);
-
-// Derive serde for serialization boundaries
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct ApiResponse<T> {
-    pub data: T,
-    pub metadata: Metadata,
-}
-```
-
-### Trait Implementation Order Convention
-
-1. Standard library traits (`Debug`, `Display`, `Clone`, `PartialEq`)
-2. Conversion traits (`From`, `Into`, `TryFrom`)
-3. Iterator traits (`Iterator`, `IntoIterator`)
-4. Serde traits (`Serialize`, `Deserialize`)
-5. Custom traits (domain-specific)
-
----
-
-## Module Organization
-
-```
-src/
-├── lib.rs          # Public API re-exports
-├── error.rs        # Crate-level error types
-├── domain/
-│   ├── mod.rs      # Domain re-exports
-│   ├── user.rs     # User entity and logic
-│   └── order.rs    # Order entity and logic
-├── repo/
-│   ├── mod.rs      # Repository trait definitions
-│   └── postgres.rs # Concrete implementation
-└── api/
-    ├── mod.rs      # Route registration
-    └── handlers.rs # HTTP handlers
-```
-
-Keep `lib.rs` thin — re-export only the public API. Internal modules use `pub(crate)`.

package/shared/skills/rust/references/violations.md

@@ -1,191 +0,0 @@
-# Rust Violation Examples
-
-Extended violation patterns for Rust reviews. Reference from main SKILL.md.
-
-## Unwrap Abuse
-
-### Unwrap in Library Code
-
-```rust
-// VIOLATION: Panics on None — caller has no way to handle failure
-pub fn get_username(users: &HashMap<u64, String>, id: u64) -> &str {
-    users.get(&id).unwrap() // Panics if id not found
-}
-
-// VIOLATION: Unwrap on parse without context
-let port: u16 = std::env::var("PORT").unwrap().parse().unwrap();
-```
-
-### Expect Without Useful Message
-
-```rust
-// VIOLATION: Message doesn't help diagnose the problem
-let config = load_config().expect("failed");
-
-// CORRECT: Actionable message
-let config = load_config().expect("failed to load config from config.toml — does file exist?");
-```
-
----
-
-## Unnecessary Cloning
-
-### Clone to Satisfy Borrow Checker
-
-```rust
-// VIOLATION: Cloning to work around borrow issues
-fn process_items(items: &Vec<Item>) {
-    let cloned = items.clone(); // Entire Vec cloned
-    for item in &cloned {
-        println!("{}", item.name);
-    }
-}
-
-// CORRECT: Just borrow
-fn process_items(items: &[Item]) {
-    for item in items {
-        println!("{}", item.name);
-    }
-}
-```
-
-### Clone in Hot Loop
-
-```rust
-// VIOLATION: Allocating on every iteration
-for record in &records {
-    let key = record.id.clone(); // String allocation per iteration
-    map.insert(key, record);
-}
-
-// CORRECT: Borrow or use references
-for record in &records {
-    map.insert(&record.id, record);
-}
-```
-
----
-
-## Stringly-Typed APIs
-
-### String Where Enum Belongs
-
-```rust
-// VIOLATION: Any typo compiles and fails at runtime
-fn set_status(status: &str) {
-    match status {
-        "active" => { /* ... */ }
-        "inactive" => { /* ... */ }
-        _ => panic!("unknown status"), // Runtime failure
-    }
-}
-
-// CORRECT: Compiler enforces valid values
-enum Status { Active, Inactive }
-
-fn set_status(status: Status) {
-    match status {
-        Status::Active => { /* ... */ }
-        Status::Inactive => { /* ... */ }
-    } // Exhaustive — no default needed
-}
-```
-
----
-
-## Unsafe Without Justification
-
-### Bare Unsafe Block
-
-```rust
-// VIOLATION: No safety comment explaining invariants
-unsafe {
-    let ptr = data.as_ptr();
-    std::ptr::copy_nonoverlapping(ptr, dest, len);
-}
-
-// CORRECT: Document why this is safe
-// SAFETY: `data` is guaranteed to be valid for `len` bytes because
-// it was allocated by `Vec::with_capacity(len)` and filled by `read_exact`.
-// `dest` is a valid pointer from `alloc::alloc(layout)` with matching size.
-unsafe {
-    std::ptr::copy_nonoverlapping(data.as_ptr(), dest, len);
-}
-```
-
-### Unnecessary Unsafe
-
-```rust
-// VIOLATION: Using unsafe when safe alternative exists
-unsafe fn get_element(slice: &[u8], index: usize) -> u8 {
-    *slice.get_unchecked(index)
-}
-
-// CORRECT: Safe indexing with bounds check
-fn get_element(slice: &[u8], index: usize) -> Option<u8> {
-    slice.get(index).copied()
-}
-```
-
----
-
-## Ignoring Results
-
-### Discarding Write Errors
-
-```rust
-// VIOLATION: Write failure silently ignored
-let _ = file.write_all(data);
-let _ = file.flush();
-
-// CORRECT: Propagate errors
-file.write_all(data)?;
-file.flush()?;
-```
-
-### Ignoring Lock Poisoning
-
-```rust
-// VIOLATION: Silently ignoring poisoned mutex
-let guard = mutex.lock().unwrap_or_else(|e| e.into_inner());
-
-// CORRECT: Handle or propagate the poison
-let guard = mutex.lock().map_err(|_| AppError::LockPoisoned)?;
-```
-
----
-
-## Concurrency Violations
-
-### Shared Mutable State Without Synchronization
-
-```rust
-// VIOLATION: Data race potential — no synchronization
-static mut COUNTER: u64 = 0;
-
-fn increment() {
-    unsafe { COUNTER += 1; } // Undefined behavior under concurrency
-}
-
-// CORRECT: Use atomic or mutex
-use std::sync::atomic::{AtomicU64, Ordering};
-static COUNTER: AtomicU64 = AtomicU64::new(0);
-
-fn increment() {
-    COUNTER.fetch_add(1, Ordering::Relaxed);
-}
-```
-
-### Blocking in Async Context
-
-```rust
-// VIOLATION: Blocks the async runtime thread
-async fn read_file(path: &str) -> Result<String, io::Error> {
-    std::fs::read_to_string(path) // Blocking call in async fn
-}
-
-// CORRECT: Use async file I/O or spawn_blocking
-async fn read_file(path: &str) -> Result<String, io::Error> {
-    tokio::fs::read_to_string(path).await
-}
-```

package/shared/skills/search-first/SKILL.md

@@ -1,133 +0,0 @@
----
-name: search-first
-description: >-
-  This skill should be used when the user asks to "add a utility", "create a helper",
-  "implement parsing", "build a wrapper", or writes infrastructure/utility code that
-  may already exist as a well-maintained package. Enforces research before building.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
----
-
-# Search-First
-
-Research before building. Check if a battle-tested solution exists before writing custom utility code.
-
-## Iron Law
-
-> **RESEARCH BEFORE BUILDING**
->
-> Never write custom utility code without first checking if a battle-tested solution
-> exists. The best code is code you don't write. A maintained package with thousands
-> of users will always beat a hand-rolled utility in reliability, edge cases, and
-> long-term maintenance.
-
-## When This Skill Activates
-
-**Triggers** — creating or modifying code that:
-- Parses, formats, or validates data (dates, URLs, emails, UUIDs, etc.)
-- Implements common algorithms (sorting, diffing, hashing, encoding)
-- Wraps HTTP clients, retries, rate limiting, caching
-- Handles file system operations beyond basic read/write
-- Implements CLI argument parsing, logging, or configuration
-- Creates test utilities (mocking, fixtures, assertions)
-
-**Does NOT trigger** for:
-- Domain-specific business logic unique to this project
-- Glue code connecting existing components
-- Trivial operations (< 5 lines, single-use)
-- Code that intentionally avoids external dependencies (e.g., zero-dep libraries)
-
----
-
-## Research Process
-
-### Phase 1: Need Analysis
-
-Before searching, define what you actually need:
-
-```
-Need: {one-sentence description of the capability}
-Constraints: {runtime, bundle size, license, zero-dep requirement}
-Must-haves: {non-negotiable requirements}
-Nice-to-haves: {optional features}
-```
-
-### Phase 2: Search
-
-Delegate research to an Explore subagent to keep main session context clean.
-
-**Spawn an Explore agent** with this prompt template:
-
-```
-Task(subagent_type="Explore"):
-"Research existing solutions for: {need description}
-
-Search for:
-1. npm/PyPI/crates packages that solve this (check package.json/requirements.txt for ecosystem)
-2. Existing utilities in this codebase (grep for related function names)
-3. Framework built-ins that already handle this
-
-For each candidate, find:
-- Package name and weekly downloads (if applicable)
-- Last publish date and maintenance status
-- Bundle size / dependency count
-- API surface relevant to our need
-- License compatibility
-
-Return top 3 candidates with pros/cons, or confirm nothing suitable exists."
-```
-
-### Phase 3: Evaluate
-
-Score each candidate against evaluation criteria. See `references/evaluation-criteria.md` for the full matrix.
-
-Quick checklist:
-- [ ] Last published within 12 months
-- [ ] Weekly downloads > 1,000 (npm) or equivalent traction
-- [ ] No known vulnerabilities (check Snyk/npm audit)
-- [ ] API fits the use case without heavy wrapping
-- [ ] License compatible with project (MIT/Apache/BSD preferred)
-- [ ] Bundle size acceptable for the project context
-
-### Phase 4: Decide
-
-Choose one of four outcomes:
-
-| Decision | When | Action |
-|----------|------|--------|
-| **Adopt** | Exact match, well-maintained, good API | Install and use directly |
-| **Extend** | Partial match, needs thin wrapper | Install + write minimal adapter |
-| **Compose** | No single package fits, but 2-3 small ones combine well | Install multiple, write glue code |
-| **Build** | Nothing fits, or dependency cost exceeds value | Write custom, document why |
-
-**Document the decision** in a code comment at the usage site:
-
-```typescript
-// search-first: Adopted date-fns for date formatting (2M weekly downloads, 30KB)
-// search-first: Built custom — no package handles our specific wire format
-```
-
----
-
-## Anti-Patterns
-
-| Anti-Pattern | Correct Approach |
-|-------------|-----------------|
-| Adding a dependency for 5 lines of trivial code | Build — dependency overhead exceeds value |
-| Choosing the most popular package without checking fit | Evaluate API fit, not just popularity |
-| Wrapping a package so heavily it obscures the original | If wrapping > 50% of original API, reconsider |
-| Skipping research because "I know how to build this" | Research anyway — maintenance cost matters more than initial build |
-| Installing a massive framework for one utility function | Look for focused, single-purpose packages |
-
-## Scope Limiter
-
-This skill concerns **utility and infrastructure code** only:
-- Data transformation, validation, formatting
-- Network operations, retries, caching
-- CLI tooling, logging, configuration
-- Test utilities and helpers
-
-It does NOT apply to **domain-specific business logic** where:
-- The logic encodes unique business rules
-- No generic solution could exist
-- The code is inherently project-specific

package/shared/skills/search-first/references/evaluation-criteria.md

@@ -1,101 +0,0 @@
-# Search-First — Evaluation Criteria
-
-Detailed package evaluation criteria and decision matrix for the 4-outcome model.
-
-## Evaluation Matrix
-
-Score each candidate on these axes (1-5 scale):
-
-| Criterion | Weight | 1 (Poor) | 3 (Acceptable) | 5 (Excellent) |
-|-----------|--------|-----------|-----------------|----------------|
-| **Maintenance** | High | No commits in 2+ years | Active, yearly releases | Regular releases, responsive maintainer |
-| **Adoption** | Medium | < 100 weekly downloads | 1K-10K weekly downloads | > 100K weekly downloads |
-| **API Fit** | High | Needs heavy wrapping | Partial fit, thin adapter needed | Direct use, clean API |
-| **Bundle Size** | Medium | > 500KB | 50-500KB | < 50KB |
-| **Security** | High | Known vulnerabilities | No known issues, few dependencies | Audited, zero/minimal dependencies |
-| **License** | Required | GPL/AGPL (restrictive) | LGPL (conditional) | MIT/Apache/BSD (permissive) |
-
-**Minimum thresholds**: License must be compatible. Security must be ≥ 3. All others are trade-offs.
-
-## Decision Matrix
-
-### Adopt (score ≥ 20/25, API Fit ≥ 4)
-
-The package directly solves the problem with minimal integration code.
-
-**Example**: Using `zod` for schema validation — exact fit, massive adoption, tiny bundle.
-
-```
-✅ Adopt: zod v3.22
-- Maintenance: 5 (monthly releases)
-- Adoption: 5 (4M weekly downloads)
-- API Fit: 5 (direct use for all validation)
-- Bundle Size: 4 (57KB)
-- Security: 5 (zero dependencies)
-- Total: 24/25
-```
-
-### Extend (score ≥ 15/25, API Fit ≥ 2)
-
-The package handles 60-80% of the need. Write a thin adapter for the rest.
-
-**Example**: Using `got` for HTTP but wrapping it with project-specific retry and auth logic.
-
-```
-✅ Extend: got v14
-- Maintenance: 4 (active)
-- Adoption: 5 (8M weekly downloads)
-- API Fit: 3 (need custom retry wrapper)
-- Bundle Size: 3 (150KB)
-- Security: 4 (minimal deps)
-- Total: 19/25
-Adapter: ~30 lines wrapping retry + auth headers
-```
-
-### Compose (no single package fits, but small packages combine)
-
-Two or three focused packages together solve the problem better than one large framework.
-
-**Example**: `ms` (time parsing) + `p-retry` (retry logic) + `quick-lru` (caching) instead of a monolithic HTTP client framework.
-
-**Rules for Compose**:
-- Maximum 3 packages in a composition
-- Each package must be focused (single responsibility)
-- Total combined bundle < what a monolithic alternative would cost
-- Glue code should be < 50 lines
-
-### Build (nothing fits, or dependency cost > value)
-
-Write custom code when:
-- No package scores ≥ 15/25
-- The code is < 50 lines and trivial
-- Zero-dependency constraint is explicit
-- The domain is too specific for generic packages
-
-**Required**: Document why Build was chosen:
-
-```typescript
-// search-first: Built custom — our wire format uses non-standard
-// ISO-8601 extensions that no date library handles correctly.
-// Evaluated: date-fns (no custom format support), luxon (500KB overhead),
-// dayjs (close but missing timezone edge case).
-```
-
-## Ecosystem-Specific Hints
-
-### Node.js / TypeScript
-- Check npm: `https://www.npmjs.com/package/{name}`
-- Bundle size: `https://bundlephobia.com/package/{name}`
-- Check if Node.js built-ins handle it (`node:crypto`, `node:url`, `node:path`)
-
-### Python
-- Check PyPI: `https://pypi.org/project/{name}`
-- Check if stdlib handles it (`urllib`, `json`, `pathlib`, `dataclasses`)
-
-### Rust
-- Check crates.io: `https://crates.io/crates/{name}`
-- Check if std handles it
-
-### Go
-- Check pkg.go.dev
-- Go standard library is extensive — check stdlib first