devflow-kit 1.1.0 → 1.3.0

package/plugins/devflow-rust/skills/rust/references/ownership.md

@@ -0,0 +1,242 @@
+# Rust Ownership Deep Dive
+
+Advanced ownership patterns, lifetime elision, interior mutability, and pinning.
+
+## Lifetime Elision Rules
+
+The compiler applies three rules to infer lifetimes. When they don't resolve, annotate manually.
+
+### Rule 1: Each Reference Parameter Gets Its Own Lifetime
+
+```rust
+// Compiler sees: fn first(s: &str) -> &str
+// Compiler infers: fn first<'a>(s: &'a str) -> &'a str
+fn first(s: &str) -> &str {
+    &s[..1]
+}
+```
+
+### Rule 2: Single Input Lifetime Applies to All Outputs
+
+```rust
+// One input reference — output borrows from it
+fn trim(s: &str) -> &str {
+    s.trim()
+}
+```
+
+### Rule 3: &self Lifetime Applies to All Outputs in Methods
+
+```rust
+impl Config {
+    // &self lifetime flows to return
+    fn database_url(&self) -> &str {
+        &self.db_url
+    }
+}
+```
+
+### When Elision Fails
+
+```rust
+// Two input lifetimes — compiler can't decide which output borrows from
+// Must annotate: output borrows from `a`, not `b`
+fn longest<'a>(a: &'a str, b: &str) -> &'a str {
+    if a.len() >= b.len() { a } else { a }
+}
+```
+
+---
+
+## Interior Mutability
+
+Mutate data behind a shared reference when ownership rules are too strict.
+
+### Cell — Copy Types Only
+
+```rust
+use std::cell::Cell;
+
+struct Counter {
+    count: Cell<u32>, // Mutate through &self
+}
+
+impl Counter {
+    fn increment(&self) {
+        self.count.set(self.count.get() + 1);
+    }
+}
+```
+
+### RefCell — Runtime Borrow Checking
+
+```rust
+use std::cell::RefCell;
+
+struct Cache {
+    data: RefCell<HashMap<String, String>>,
+}
+
+impl Cache {
+    fn get_or_insert(&self, key: &str, value: &str) -> String {
+        let mut data = self.data.borrow_mut(); // Panics if already borrowed
+        data.entry(key.to_string())
+            .or_insert_with(|| value.to_string())
+            .clone()
+    }
+}
+```
+
+### Mutex — Thread-Safe Interior Mutability
+
+```rust
+use std::sync::Mutex;
+
+struct SharedState {
+    data: Mutex<Vec<String>>,
+}
+
+impl SharedState {
+    fn push(&self, item: String) -> Result<(), AppError> {
+        let mut data = self.data.lock()
+            .map_err(|_| AppError::LockPoisoned)?;
+        data.push(item);
+        Ok(())
+    }
+}
+```
+
+### Decision Guide
+
+| Type | Thread-Safe | Cost | Use Case |
+|------|-------------|------|----------|
+| `Cell<T>` | No | Zero | Copy types, single-threaded |
+| `RefCell<T>` | No | Runtime borrow check | Non-Copy, single-threaded |
+| `Mutex<T>` | Yes | Lock overhead | Multi-threaded mutation |
+| `RwLock<T>` | Yes | Lock overhead | Multi-threaded, read-heavy |
+| `Atomic*` | Yes | Hardware atomic | Counters, flags |
+
+---
+
+## Cow — Clone on Write
+
+Defer cloning until mutation is actually needed.
+
+```rust
+use std::borrow::Cow;
+
+// Returns borrowed if no processing needed, owned if modified
+fn normalize_path(path: &str) -> Cow<'_, str> {
+    if path.contains("//") {
+        Cow::Owned(path.replace("//", "/"))
+    } else {
+        Cow::Borrowed(path)
+    }
+}
+
+// Function accepts both owned and borrowed transparently
+fn process(input: Cow<'_, str>) {
+    println!("{}", input); // No allocation if already borrowed
+}
+```
+
+### Cow in APIs
+
+```rust
+// Accept Cow for flexible ownership — caller decides allocation
+pub fn log_message(msg: Cow<'_, str>) {
+    eprintln!("[LOG] {}", msg);
+}
+
+// Caller with borrowed data — zero-copy
+log_message(Cow::Borrowed("static message"));
+
+// Caller with owned data — no extra clone
+log_message(Cow::Owned(format!("dynamic: {}", value)));
+```
+
+---
+
+## Pin for Async and Self-Referential Types
+
+### Why Pin Exists
+
+Self-referential structs break if moved in memory. `Pin` guarantees the value won't move.
+
+```rust
+use std::pin::Pin;
+use std::future::Future;
+
+// Async functions return self-referential futures
+// Pin ensures the future stays in place while polled
+fn fetch_data(url: &str) -> Pin<Box<dyn Future<Output = Result<Data, Error>> + '_>> {
+    Box::pin(async move {
+        let response = reqwest::get(url).await?;
+        let data = response.json::<Data>().await?;
+        Ok(data)
+    })
+}
+```
+
+### Pin in Practice
+
+```rust
+use tokio::pin;
+
+async fn process_stream(stream: impl Stream<Item = Data>) {
+    // pin! macro pins the stream to the stack
+    pin!(stream);
+
+    while let Some(item) = stream.next().await {
+        handle(item).await;
+    }
+}
+```
+
+### When You Need Pin
+
+| Scenario | Need Pin? |
+|----------|-----------|
+| Returning `async` blocks as trait objects | Yes |
+| Implementing `Future` manually | Yes |
+| Using `tokio::select!` on futures | Yes (automatically handled) |
+| Normal async/await | No (compiler handles it) |
+| Storing futures in collections | Yes (`Pin<Box<dyn Future>>`) |
+
+---
+
+## Ownership Transfer Patterns
+
+### Take Pattern — Move Out of Option
+
+```rust
+struct Connection {
+    session: Option<Session>,
+}
+
+impl Connection {
+    fn close(&mut self) -> Option<Session> {
+        self.session.take() // Moves out, leaves None
+    }
+}
+```
+
+### Swap Pattern — Replace In Place
+
+```rust
+use std::mem;
+
+fn rotate_buffer(current: &mut Vec<u8>, new_data: Vec<u8>) -> Vec<u8> {
+    mem::replace(current, new_data) // Returns old, installs new
+}
+```
+
+### Entry Pattern — Conditional Insertion
+
+```rust
+use std::collections::HashMap;
+
+fn get_or_create(map: &mut HashMap<String, Vec<Item>>, key: &str) -> &mut Vec<Item> {
+    map.entry(key.to_string()).or_insert_with(Vec::new)
+}
+```

package/plugins/devflow-rust/skills/rust/references/patterns.md

@@ -0,0 +1,210 @@
+# 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/plugins/devflow-rust/skills/rust/references/violations.md

@@ -0,0 +1,191 @@
+# 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/plugins/devflow-self-review/.claude-plugin/plugin.json

@@ -1,7 +1,14 @@
 {
   "name": "devflow-self-review",
   "description": "Self-review workflow: Simplifier + Scrutinizer for code quality",
-  "version": "1.1.0",
-  "agents": ["simplifier", "scrutinizer", "validator"],
-  "skills": ["self-review", "core-patterns"]
+  "version": "1.3.0",
+  "agents": [
+    "simplifier",
+    "scrutinizer",
+    "validator"
+  ],
+  "skills": [
+    "self-review",
+    "core-patterns"
+  ]
 }

package/plugins/devflow-self-review/skills/self-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: self-review
-description: Self-review framework evaluating implementation quality against 9 pillars (correctness, completeness, security, performance, maintainability, testing, documentation, error handling, simplicity). Fixes P0/P1 issues immediately rather than reporting them. Used by the Scrutinizer agent as a quality gate.
+description: This skill should be used when evaluating implementation quality before submission, checking correctness, security, and simplicity.
 user-invocable: false
 allowed-tools: Read, Grep, Glob, Edit, Write, Bash
 ---

package/plugins/devflow-specify/.claude-plugin/plugin.json

@@ -5,11 +5,22 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.1.0",
+  "version": "1.3.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",
-  "keywords": ["specification", "requirements", "planning", "issues", "github"],
-  "agents": ["skimmer", "synthesizer"],
-  "skills": ["agent-teams"]
+  "keywords": [
+    "specification",
+    "requirements",
+    "planning",
+    "issues",
+    "github"
+  ],
+  "agents": [
+    "skimmer",
+    "synthesizer"
+  ],
+  "skills": [
+    "agent-teams"
+  ]
 }