devflow-kit 1.0.0 → 1.2.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/test-driven-development/SKILL.md

@@ -0,0 +1,139 @@
+---
+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.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.ts"
+    - "**/*.tsx"
+    - "**/*.js"
+    - "**/*.jsx"
+    - "**/*.py"
+  exclude:
+    - "node_modules/**"
+    - "dist/**"
+    - "**/*.test.*"
+    - "**/*.spec.*"
+---
+
+# Test-Driven Development
+
+Enforce the RED-GREEN-REFACTOR cycle for all implementation work. Tests define the design. Code satisfies the tests. Refactoring improves the design without changing behavior.
+
+## Iron Law
+
+> **TESTS FIRST, ALWAYS**
+>
+> Write the failing test before the production code. No exceptions. If you catch
+> yourself writing production code without a failing test, stop immediately, delete
+> the production code, write the test, watch it fail, then write the minimum code
+> to make it pass. The test IS the specification.
+
+---
+
+## The Cycle
+
+### Step 1: RED — Write a Failing Test
+
+Write a test that describes the behavior you want. Run it. Watch it fail. The failure message IS your specification.
+
+```
+Describe what the code SHOULD do, not how it does it.
+One behavior per test. One assertion per test (ideally).
+Name tests as sentences: "returns error when email is invalid"
+```
+
+**Checkpoint:** The test MUST fail before proceeding. A test that passes immediately proves nothing.
+
+### Step 2: GREEN — Write Minimum Code to Pass
+
+Write the simplest production code that makes the failing test pass. No more, no less.
+
+```
+Hardcode first if that's simplest. Generalize when the next test forces it.
+Don't write code "you'll need later." Write code the test demands NOW.
+Don't optimize. Don't refactor. Don't clean up. Just pass the test.
+```
+
+**Checkpoint:** All tests pass. If any test fails, fix it before moving on.
+
+### Step 3: REFACTOR — Improve Without Changing Behavior
+
+Now clean up. Extract helpers, rename variables, simplify logic. Tests stay green throughout.
+
+```
+Run tests after every refactoring step.
+If a test breaks during refactor, undo immediately — you changed behavior.
+Apply DRY, extract patterns, improve readability.
+```
+
+**Checkpoint:** All tests still pass. Code is clean. Repeat from Step 1 for next behavior.
+
+---
+
+## Rationalization Prevention
+
+These are the excuses developers use to skip TDD. Recognize and reject them.
+
+| Excuse | Why It Feels Right | Why It's Wrong | Correct Action |
+|--------|-------------------|---------------|----------------|
+| "I'll write tests after" | Need to see the shape first | Tests ARE the shape — they define the interface before implementation exists | Write the test first |
+| "Too simple to test" | It's just a getter/setter | Getters break, defaults change, edge cases hide in "simple" code | Write it — takes 30 seconds |
+| "I'll refactor later" | Just get it working now | "Later" never comes; technical debt compounds silently | Refactor now in Step 3 |
+| "Test is too hard to write" | Setup is complex, mocking is painful | Hard-to-test code = bad design; the test is telling you the interface is wrong | Simplify the interface first |
+| "Need to see the whole picture" | Can't test what I haven't designed yet | TDD IS design; each test reveals the next piece of the interface | Let the test guide the design |
+| "Tests slow me down" | Faster to just write the code | Faster until the first regression; TDD is faster for anything > 50 lines | Trust the cycle |
+
+See `references/rationalization-prevention.md` for extended examples with code.
+
+---
+
+## Process Enforcement
+
+When implementing any feature under ambient BUILD/STANDARD:
+
+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
+3. **Run the test** — Confirm it fails (RED)
+4. **Write minimum code** — Just enough to pass (GREEN)
+5. **Refactor** — Clean up while tests stay green (REFACTOR)
+6. **Repeat** — Next behavior, next test, next cycle
+
+### File Organization
+
+- Test file lives next to production file: `user.ts` → `user.test.ts`
+- Follow project's existing test conventions (Jest, Vitest, pytest, etc.)
+- Import the module under test, not internal helpers
+
+### What to Test
+
+| Test | Don't Test |
+|------|-----------|
+| Public API behavior | Private implementation details |
+| Error conditions and edge cases | Framework internals |
+| Integration points (boundaries) | Third-party library correctness |
+| State transitions | Getter/setter plumbing (unless non-trivial) |
+
+---
+
+## When TDD Does Not Apply
+
+- **QUICK depth** — Ambient classified as QUICK (chat, exploration, trivial edits)
+- **Non-code tasks** — Documentation, configuration, CI changes
+- **Exploratory prototyping** — User explicitly says "just spike this" or "prototype"
+- **Existing test suite changes** — Modifying tests themselves (test-patterns skill applies instead)
+
+When skipping TDD, never rationalize. State clearly: "Skipping TDD because: [specific reason from list above]."
+
+---
+
+## Integration with Ambient Mode
+
+- **BUILD/STANDARD** → 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.

package/shared/skills/test-driven-development/references/rationalization-prevention.md

@@ -0,0 +1,111 @@
+# TDD Rationalization Prevention — Extended Examples
+
+Detailed code examples showing how each rationalization leads to worse outcomes.
+
+## "I'll write tests after"
+
+### What happens:
+
+```typescript
+// Developer writes production code first
+function calculateDiscount(price: number, tier: string): number {
+  if (tier === 'gold') return price * 0.8;
+  if (tier === 'silver') return price * 0.9;
+  return price;
+}
+
+// Then "writes tests after" — but only for the happy path they remember
+test('gold tier gets 20% off', () => {
+  expect(calculateDiscount(100, 'gold')).toBe(80);
+});
+// Missing: negative prices, unknown tiers, zero prices, NaN handling
+```
+
+### What TDD would have caught:
+
+```typescript
+// Test first — forces you to think about the contract
+test('returns error for negative price', () => {
+  expect(calculateDiscount(-100, 'gold')).toEqual({ ok: false, error: 'NEGATIVE_PRICE' });
+});
+// Now the interface includes error handling from the start
+```
+
+## "Too simple to test"
+
+### What happens:
+
+```typescript
+// "It's just a config getter, no test needed"
+function getMaxRetries(): number {
+  return parseInt(process.env.MAX_RETRIES || '3');
+}
+// 6 months later: someone sets MAX_RETRIES="three" and prod crashes with NaN retries
+```
+
+### What TDD would have caught:
+
+```typescript
+test('returns default when env var is not a number', () => {
+  process.env.MAX_RETRIES = 'three';
+  expect(getMaxRetries()).toBe(3); // Forces validation logic
+});
+```
+
+## "Test is too hard to write"
+
+### What happens:
+
+```typescript
+// "I can't test this easily because it needs database + email + filesystem"
+async function processOrder(orderId: string) {
+  const db = new Database();
+  const order = await db.find(orderId);
+  await sendEmail(order.customerEmail, 'Your order is processing');
+  await fs.writeFile(`/invoices/${orderId}.pdf`, generateInvoice(order));
+  await db.update(orderId, { status: 'processing' });
+}
+// Result: untestable monolith, test would need real DB + email + filesystem
+```
+
+### What TDD forces:
+
+```typescript
+// Hard-to-test = bad design. TDD forces dependency injection:
+async function processOrder(
+  orderId: string,
+  deps: { db: OrderRepository; emailer: Emailer; invoices: InvoiceStore }
+): Promise<Result<void, OrderError>> {
+  // Now trivially testable with mocks
+}
+```
+
+## "I'll refactor later"
+
+### What happens:
+
+```typescript
+// Sprint 1: "just get it working"
+function handleRequest(req: any) {
+  if (req.type === 'create') { /* 50 lines */ }
+  else if (req.type === 'update') { /* 50 lines */ }
+  else if (req.type === 'delete') { /* 30 lines */ }
+  // Sprint 2-10: more conditions added, function grows to 500 lines
+  // "Refactor later" never comes because nobody wants to touch it
+}
+```
+
+### What TDD enforces:
+
+Step 3 (REFACTOR) happens every cycle. The function never grows beyond what's clean because you clean it every 5-10 minutes.
+
+## "Tests slow me down"
+
+### The math:
+
+| Approach | Time to write | Time to first bug | Time to fix bug | Total (1 month) |
+|----------|:---:|:---:|:---:|:---:|
+| No TDD | 2h | 4h | 3h (no repro test) | 9h+ |
+| TDD | 3h | Caught in test | 15min (test pinpoints) | 3h 15min |
+
+TDD is slower for the first 30 minutes. It's faster for everything after that.

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/managed-settings.json

@@ -5,6 +5,15 @@
       "Bash(rm -rf ~*)",
       "Bash(rm -rf .*)",
       "Bash(* rm -rf /*)",
+      "Bash(rm -r /*)",
+      "Bash(rm -r ~*)",
+      "Bash(rm -r .*)",
+      "Bash(rm -fr /*)",
+      "Bash(rm -fr ~*)",
+      "Bash(rm -fr .*)",
+      "Bash(rm -f /*)",
+      "Bash(rm -f ~*)",
+      "Bash(rm -f .*)",
       "Bash(dd if=*)",
       "Bash(dd*of=/dev/*)",
       "Bash(mkfs*)",
@@ -85,12 +94,17 @@
       "Bash(crontab*)",
       "Bash(rm /var/log*)",
       "Bash(rm -rf /var/log*)",
+      "Bash(rm -r /var/log*)",
+      "Bash(rm -f /var/log*)",
+      "Bash(rm -fr /var/log*)",
       "Bash(> /var/log*)",
       "Bash(truncate /var/log*)",
       "Bash(history -c*)",
       "Bash(history -w*)",
       "Bash(rm ~/.bash_history*)",
+      "Bash(rm -f ~/.bash_history*)",
       "Bash(rm ~/.zsh_history*)",
+      "Bash(rm -f ~/.zsh_history*)",
       "Bash(unset HISTFILE*)",
       "Bash(curl 169.254.169.254*)",
       "Bash(wget 169.254.169.254*)",