devflow-kit 1.1.0 → 1.3.0

package/shared/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/shared/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/shared/skills/security-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: security-patterns
-description: Security vulnerability analysis patterns for code review. Detects injection flaws, authentication bypasses, insecure cryptography, hardcoded secrets, and missing input sanitization. Loaded by Reviewer agent when focus=security.
+description: This skill should be used when reviewing code for injection flaws, auth bypasses, or hardcoded secrets.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 ---

package/shared/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/shared/skills/test-driven-development/SKILL.md

@@ -1,9 +1,6 @@
 ---
 name: test-driven-development
-description: >-
-  Enforce RED-GREEN-REFACTOR cycle during implementation. Write failing tests before
-  production code. Distinct from test-patterns (which reviews test quality) — this
-  skill enforces the TDD workflow during code generation.
+description: This skill should be used when implementing new features, fixing bugs, or writing new code. Enforces RED-GREEN-REFACTOR.
 user-invocable: false
 allowed-tools: Read, Grep, Glob
 activation:
@@ -94,7 +91,7 @@ See `references/rationalization-prevention.md` for extended examples with code.
 
 ## Process Enforcement
 
-When implementing any feature under ambient BUILD/STANDARD:
+When implementing any feature under ambient BUILD/GUIDED:
 
 1. **Identify the first behavior** — What is the simplest thing this feature must do?
 2. **Write the test** — Describe that behavior as a failing test
@@ -133,7 +130,7 @@ When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [spe
 
 ## Integration with Ambient Mode
 
-- **BUILD/STANDARD** → TDD enforced. Every new function/method gets test-first treatment.
+- **BUILD/GUIDED** → TDD enforced. Every new function/method gets test-first treatment.
 - **BUILD/QUICK** → TDD skipped (trivial single-file edit).
-- **BUILD/ESCALATE** → TDD mentioned in nudge toward `/implement`.
-- **DEBUG/STANDARD** → TDD applies to the fix: write a test that reproduces the bug first, then fix.
+- **BUILD/ELEVATE** → TDD mentioned in nudge toward `/implement`.
+- **DEBUG/GUIDED** → TDD applies to the fix: write a test that reproduces the bug first, then fix.

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

@@ -137,7 +137,7 @@ const isUndefined = (value: unknown): value is undefined =>
 const isNullish = (value: unknown): value is null | undefined =>
   value === null || value === undefined;
 
-const isFunction = (value: unknown): value is Function =>
+const isFunction = (value: unknown): value is (...args: unknown[]) => unknown =>
   typeof value === 'function';
 
 const isObject = (value: unknown): value is object =>
@@ -760,7 +760,7 @@ function debounce<T extends (...args: any[]) => any>(
   fn: T,
   delayMs: number
 ): (...args: Parameters<T>) => void {
-  let timeoutId: NodeJS.Timeout | null = null;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
 
   return (...args: Parameters<T>) => {
     if (timeoutId) clearTimeout(timeoutId);
@@ -774,7 +774,7 @@ function throttle<T extends (...args: any[]) => any>(
   limitMs: number
 ): (...args: Parameters<T>) => void {
   let lastRun = 0;
-  let timeoutId: NodeJS.Timeout | null = null;
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
 
   return (...args: Parameters<T>) => {
     const now = Date.now();

package/src/templates/settings.json

@@ -9,7 +9,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${DEVFLOW_DIR}/scripts/hooks/stop-update-memory.sh",
+            "command": "${DEVFLOW_DIR}/scripts/hooks/run-hook stop-update-memory",
             "timeout": 10
           }
         ]
@@ -20,7 +20,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${DEVFLOW_DIR}/scripts/hooks/session-start-memory.sh",
+            "command": "${DEVFLOW_DIR}/scripts/hooks/run-hook session-start-memory",
             "timeout": 10
           }
         ]
@@ -31,7 +31,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${DEVFLOW_DIR}/scripts/hooks/pre-compact-memory.sh",
+            "command": "${DEVFLOW_DIR}/scripts/hooks/run-hook pre-compact-memory",
             "timeout": 10
           }
         ]