@dv.nghiem/flowdeck 0.1.0

package/src/skills/repo-memory-graph/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: repo-memory-graph
+description: Build and maintain a persistent graph of architecture, conventions, bug history, ownership patterns, and module relationships for this specific codebase.
+origin: FlowDeck
+---
+
+# Repo Memory Graph
+
+The Repo Memory Graph is FlowDeck's long-term knowledge store about this specific codebase. It persists in `.codebase/MEMORY.json` and grows over time.
+
+## What Gets Stored
+
+- **Modules**: files, their type (service/api/schema/config), owner, tags
+- **Dependencies**: which modules import or call which others
+- **Conventions**: patterns used in this repo (naming, error handling, auth flow)
+- **Bug history**: which modules have had recurring issues
+- **Ownership**: who owns what (from git blame, CODEOWNERS, or explicit annotation)
+
+## When to Update
+
+Update the graph:
+- After running `/map-codebase`
+- When onboarding a new module
+- When a bug fix reveals a recurring pattern (add to `bug_history`)
+- When a refactor changes module ownership
+
+## Usage with `repo-memory` tool
+
+```json
+// Write a node
+{ "action": "write_node", "node_id": "auth-service", "node": {
+    "type": "service", "path": "src/services/auth.ts",
+    "owner": "security-team", "tags": ["auth", "jwt"],
+    "dependencies": ["user-model", "token-store"],
+    "dependents": ["api-gateway", "session-handler"],
+    "bug_history": ["jwt-expiry-bug-2024-03"],
+    "conventions": ["always validate token before processing"]
+}}
+
+// Query by owner
+{ "action": "query", "query": { "owner": "security-team" } }
+```
+
+## How Agents Use This
+
+- **Impact Radar**: walks the dependency graph to find affected modules
+- **Blast Radius**: traverses dependents to map downstream risk
+- **Regression Prediction**: uses bug_history to weight risk categories
+- **Architectural Constraint Guard**: checks module boundaries before allowing edits

package/src/skills/rust-patterns/SKILL.md

@@ -0,0 +1,492 @@
+---
+name: rust-patterns
+description: Rust patterns covering ownership, lifetimes, error handling, traits, async/await with Tokio, smart pointers, and common pitfalls. Activate when writing or reviewing Rust code.
+origin: FlowDeck
+---
+
+# Rust Patterns Skill
+
+Safe, idiomatic Rust for production systems. Covers the ownership model, trait system, and async patterns.
+
+## When to Activate
+
+Activate when:
+- Writing new Rust crates or services
+- Reviewing Rust code for safety and idiom
+- Fighting the borrow checker and looking for solutions
+- Designing async services with Tokio
+- Choosing between smart pointer types
+
+## Ownership and Borrowing — Mental Model
+
+Every value has exactly one owner. When the owner goes out of scope, the value is dropped. References borrow a value without taking ownership.
+
+### The Three Rules
+
+1. Each value has exactly one owner.
+2. There can be any number of shared (`&T`) references, OR exactly one exclusive (`&mut T`) reference — never both at the same time.
+3. References must not outlive the value they point to.
+
+```rust
+fn main() {
+    let s1 = String::from("hello");
+    let s2 = s1;          // ownership moved to s2
+    // println!("{s1}");  // compile error: s1 moved
+
+    let s3 = String::from("world");
+    let r1 = &s3;         // shared borrow
+    let r2 = &s3;         // another shared borrow — fine
+    println!("{r1} {r2}");
+
+    let mut s4 = String::from("mutable");
+    let r3 = &mut s4;     // exclusive borrow
+    r3.push_str("!");
+    // let r4 = &s4;      // compile error: s4 already mutably borrowed
+}
+```
+
+### Clone When You Need a Copy
+
+```rust
+// clone() is explicit and potentially expensive — use it knowingly
+let original = vec![1, 2, 3];
+let copy = original.clone();
+// both are usable
+
+// For cheap copies, implement Copy (stack-allocated types)
+#[derive(Clone, Copy)]
+struct Point { x: f64, y: f64 }
+
+let p1 = Point { x: 1.0, y: 2.0 };
+let p2 = p1;  // copied, not moved — p1 still valid
+```
+
+## Lifetime Annotations
+
+The compiler infers lifetimes in most cases via elision rules. Annotate when the compiler cannot determine the relationship.
+
+### When Annotations Are Required
+
+```rust
+// Return value borrows from one of the arguments — annotate the relationship
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+
+// Struct holding a reference must declare its lifetime
+struct Excerpt<'a> {
+    text: &'a str,
+}
+
+impl<'a> Excerpt<'a> {
+    fn content(&self) -> &str {
+        self.text  // lifetime elided — same as self's lifetime
+    }
+}
+```
+
+### Elision Rules (No Annotation Needed)
+
+```rust
+// Rule 1: each input reference gets its own lifetime
+fn first_word(s: &str) -> &str { ... }
+// expanded: fn first_word<'a>(s: &'a str) -> &'a str
+
+// Rule 2: if there's exactly one input lifetime, it applies to all outputs
+fn trim(s: &str) -> &str { s.trim() }
+```
+
+### 'static — Only When Truly Static
+
+```rust
+// String literals have 'static lifetime
+let s: &'static str = "I live for the entire program";
+
+// Avoid &'static in generic bounds unless you truly need it — it rules out
+// borrowed data entirely and forces owned types or leaked memory
+```
+
+## Error Handling
+
+### Result<T, E> and the ? Operator
+
+```rust
+use std::fs;
+use std::io;
+
+fn read_config(path: &str) -> Result<String, io::Error> {
+    let content = fs::read_to_string(path)?;  // ? returns early on Err
+    Ok(content.trim().to_owned())
+}
+
+// Chaining with map_err to convert error types
+fn parse_port(s: &str) -> Result<u16, String> {
+    s.parse::<u16>()
+     .map_err(|e| format!("invalid port {s:?}: {e}"))
+}
+```
+
+### thiserror — Library Error Types
+
+```rust
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum StoreError {
+    #[error("record {id} not found")]
+    NotFound { id: u64 },
+
+    #[error("database error")]
+    Database(#[from] sqlx::Error),
+
+    #[error("serialization failed: {0}")]
+    Serialize(#[from] serde_json::Error),
+}
+
+// Callers can pattern-match on variants
+match store.get(id).await {
+    Err(StoreError::NotFound { id }) => respond_404(id),
+    Err(e) => respond_500(e),
+    Ok(record) => respond_200(record),
+}
+```
+
+### anyhow — Application Error Handling
+
+```rust
+use anyhow::{Context, Result};
+
+// anyhow::Result<T> = Result<T, anyhow::Error>
+async fn run() -> Result<()> {
+    let config = load_config("app.toml")
+        .context("failed to load application config")?;
+
+    let db = connect(&config.database_url).await
+        .context("database connection failed")?;
+
+    serve(db, config.port).await
+}
+
+// context() attaches a message; with_context() is lazy (use for expensive messages)
+let data = fetch(url).await
+    .with_context(|| format!("fetch failed for url: {url}"))?;
+```
+
+## Trait System
+
+### impl Trait — Static Dispatch
+
+```rust
+// Return an opaque type — compiler monomorphises at call site
+fn make_greeting(name: &str) -> impl Display {
+    format!("Hello, {name}!")
+}
+
+// Accept any type implementing a trait — zero-cost abstraction
+fn print_all(items: &[impl Display]) {
+    for item in items {
+        println!("{item}");
+    }
+}
+```
+
+### dyn Trait — Dynamic Dispatch
+
+```rust
+// Trait objects — runtime dispatch, heap-allocated
+fn make_handler(kind: &str) -> Box<dyn Handler> {
+    match kind {
+        "log"   => Box::new(LogHandler::new()),
+        "audit" => Box::new(AuditHandler::new()),
+        _       => Box::new(NoopHandler),
+    }
+}
+
+// Object safety rules: no generic methods, no Self return types
+// Use dyn Trait only when you need heterogeneous collections or
+// when the concrete type isn't known until runtime
+```
+
+### Where Clauses for Readability
+
+```rust
+// Inline bounds get crowded
+fn process<T: Debug + Clone + Send + 'static>(item: T) { ... }
+
+// Where clause is cleaner
+fn process<T>(item: T)
+where
+    T: Debug + Clone + Send + 'static,
+{
+    ...
+}
+```
+
+### Blanket Implementations
+
+```rust
+// Implement a trait for all types that satisfy a constraint
+impl<T: Display> MyPrint for T {
+    fn print(&self) { println!("{self}"); }
+}
+```
+
+## Iterators
+
+Iterators are lazy — no work until consumed. Chain adapters freely; the compiler fuses them.
+
+```rust
+let result: Vec<String> = (1..=10)
+    .filter(|n| n % 2 == 0)
+    .map(|n| n * n)
+    .take(3)
+    .map(|n| format!("n={n}"))
+    .collect();
+// ["n=4", "n=16", "n=36"]
+
+// fold — general reduction
+let product: u64 = (1..=10).fold(1, |acc, n| acc * n);
+
+// chain — concatenate iterators
+let combined: Vec<i32> = vec![1, 2].into_iter()
+    .chain(vec![3, 4].into_iter())
+    .collect();
+
+// Custom iterator
+struct Counter { count: u32, max: u32 }
+
+impl Iterator for Counter {
+    type Item = u32;
+    fn next(&mut self) -> Option<u32> {
+        if self.count < self.max {
+            self.count += 1;
+            Some(self.count)
+        } else {
+            None
+        }
+    }
+}
+```
+
+## Async/Await with Tokio
+
+### Spawning Tasks
+
+```rust
+use tokio::task;
+
+#[tokio::main]
+async fn main() {
+    let handle: task::JoinHandle<u64> = tokio::spawn(async {
+        compute_heavy_thing().await
+    });
+
+    let result = handle.await.expect("task panicked");
+}
+```
+
+### select! — Racing Futures
+
+```rust
+use tokio::select;
+use tokio::time::{sleep, Duration};
+
+async fn with_timeout<T>(fut: impl Future<Output = T>, ms: u64) -> Option<T> {
+    select! {
+        result = fut => Some(result),
+        _ = sleep(Duration::from_millis(ms)) => None,
+    }
+}
+```
+
+### Channels
+
+```rust
+use tokio::sync::{mpsc, oneshot};
+
+// mpsc — multiple producers, single consumer
+let (tx, mut rx) = mpsc::channel::<String>(32);  // bounded, backpressure
+
+tokio::spawn(async move {
+    while let Some(msg) = rx.recv().await {
+        process(msg).await;
+    }
+});
+
+tx.send("hello".to_owned()).await.unwrap();
+
+// oneshot — single response (request/reply pattern)
+let (resp_tx, resp_rx) = oneshot::channel::<Result<User, StoreError>>();
+
+tokio::spawn(async move {
+    let user = db.find_user(id).await;
+    let _ = resp_tx.send(user);
+});
+
+let user = resp_rx.await.expect("worker dropped");
+```
+
+## Smart Pointers
+
+| Type | Ownership | Thread-safe | Interior mutability |
+|------|-----------|-------------|---------------------|
+| `Box<T>` | owned, heap | yes (if T: Send) | no |
+| `Rc<T>` | shared, heap | ❌ no | no |
+| `Arc<T>` | shared, heap | ✅ yes | no |
+| `RefCell<T>` | owned | ❌ no | ✅ runtime borrow |
+| `Mutex<T>` | owned | ✅ yes | ✅ locked |
+| `RwLock<T>` | owned | ✅ yes | ✅ locked |
+
+```rust
+// Box — when you need heap allocation or unsized types
+let large: Box<[u8; 1_000_000]> = Box::new([0; 1_000_000]);
+
+// Arc — shared ownership across threads
+let shared = Arc::new(Config::load());
+let clone = Arc::clone(&shared);
+tokio::spawn(async move { use_config(clone).await });
+
+// Arc<Mutex<T>> — shared mutable state across threads
+let counter = Arc::new(Mutex::new(0u64));
+let c = Arc::clone(&counter);
+tokio::spawn(async move {
+    *c.lock().await += 1;
+});
+
+// Rc<RefCell<T>> — shared mutable state in single-threaded contexts
+let node = Rc::new(RefCell::new(Node::new()));
+node.borrow_mut().value = 42;
+```
+
+## Enums and Pattern Matching
+
+```rust
+#[derive(Debug)]
+enum Command {
+    Quit,
+    Move { x: i32, y: i32 },
+    Write(String),
+    ChangeColor(u8, u8, u8),
+}
+
+fn execute(cmd: Command) {
+    match cmd {
+        Command::Quit => println!("quit"),
+        Command::Move { x, y } => println!("move to ({x},{y})"),
+        Command::Write(msg) => println!("write: {msg}"),
+        Command::ChangeColor(r, g, b) => println!("color: #{r:02x}{g:02x}{b:02x}"),
+    }
+}
+
+// if let — when only one variant matters
+if let Some(value) = map.get("key") {
+    println!("found: {value}");
+}
+
+// while let — consume until variant changes
+let mut stack = vec![1, 2, 3];
+while let Some(top) = stack.pop() {
+    println!("{top}");
+}
+```
+
+## Cargo Workspace and Features
+
+### Workspace
+
+```toml
+# Cargo.toml at root
+[workspace]
+members = ["crates/core", "crates/api", "crates/cli"]
+resolver = "2"
+
+[workspace.dependencies]
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+```
+
+### Conditional Compilation with Features
+
+```toml
+# crates/core/Cargo.toml
+[features]
+default = []
+metrics = ["dep:prometheus"]
+tracing = ["dep:tracing-subscriber"]
+
+[dependencies]
+prometheus = { version = "0.13", optional = true }
+```
+
+```rust
+#[cfg(feature = "metrics")]
+fn record_metric(name: &str, value: f64) {
+    prometheus::counter!(name).inc_by(value);
+}
+
+#[cfg(not(feature = "metrics"))]
+fn record_metric(_name: &str, _value: f64) {}
+```
+
+## Common Pitfalls
+
+### Fighting the Borrow Checker — Solutions
+
+```rust
+// Problem: returning a reference to something inside a match
+// Solution: clone or restructure to return owned data
+
+// Problem: two mutable references to different fields of a struct
+struct Grid { rows: Vec<Vec<i32>>, count: usize }
+impl Grid {
+    fn swap_and_count(&mut self, r1: usize, r2: usize) {
+        // borrow checker rejects: &mut self.rows and &mut self.count at once
+        // Solution: split borrows by borrowing fields directly
+        let (rows, count) = (&mut self.rows, &mut self.count);
+        rows.swap(r1, r2);
+        *count += 1;
+    }
+}
+
+// Problem: value moved in loop
+// Solution: borrow or clone before the loop, or use indices
+for item in &items {          // borrow — items still usable after loop
+    process(item);
+}
+for item in items.iter() {   // same as above, explicit
+    process(item);
+}
+```
+
+### String vs &str vs &[u8]
+
+```rust
+// &str — borrowed string slice — use in function parameters when you don't need ownership
+fn greet(name: &str) -> String { format!("Hello, {name}!") }
+
+// String — owned, heap-allocated, growable — return types, struct fields
+struct User { name: String }
+
+// &[u8] — raw bytes — use for binary data or when encoding is uncertain
+fn checksum(data: &[u8]) -> u32 { ... }
+
+// Vec<u8> — owned bytes — when you need to mutate or own binary data
+```
+
+### Copy vs Clone
+
+```rust
+// Copy types are silently duplicated on assignment (all stack data: i32, bool, char, &T, arrays of Copy)
+let x: i32 = 5;
+let y = x;  // x is still valid — i32 implements Copy
+
+// Clone is explicit — use when the duplication is intentional and potentially expensive
+#[derive(Clone)]  // opt in
+struct Config { /* ... */ }
+
+let c1 = Config::load();
+let c2 = c1.clone();  // explicit, reader knows a copy was made
+
+// Do not implement Copy for types with heap data — it creates shallow copies
+// that would double-free. The compiler prevents this for types with Drop.
+```

package/src/skills/security-scan/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: security-scan
+description: Pre-commit security scan covering secrets, injection, auth, CVE dependencies. Returns PASS/FAIL verdict with severity-ranked findings and specific remediations.
+origin: FlowDeck
+---
+
+# Security Scan Skill
+
+Catches security issues before they reach production. Returns a severity-ranked report with specific remediations.
+
+## When to Activate
+
+Activate:
+- Before merging any PR that touches auth, data access, or API routes
+- Before every production deployment
+- When adding new dependencies
+- When changing environment variable handling
+
+## Core Principles
+
+- Security takes priority over convenience
+- Every finding includes a specific remediation
+- CRITICAL or HIGH = must fix before merge
+- No exceptions without documented risk acceptance
+
+## Workflow
+
+1. Check for hardcoded secrets (grep patterns)
+2. Check for injection vulnerabilities (SQL, command, template)
+3. Verify auth middleware on protected routes
+4. Check input validation at API boundaries
+5. Run `npm audit --audit-level=moderate`
+6. Review sensitive data in logs
+7. Produce verdict
+
+## OWASP Top 10 Quick Reference
+
+| ID | Name | Check For |
+|----|------|-----------|
+| A01 | Broken Access Control | Missing auth checks, IDOR, privilege escalation |
+| A02 | Cryptographic Failures | HTTP for sensitive data, MD5/SHA1 for passwords |
+| A03 | Injection | SQL/NoSQL/cmd/template injection via string concat |
+| A04 | Insecure Design | Missing rate limiting, no lockout after failed logins |
+| A05 | Security Misconfiguration | Debug mode in prod, default credentials, verbose errors |
+| A06 | Vulnerable Components | CVEs in dependencies (run npm audit) |
+| A07 | Auth Failures | Missing middleware, weak JWT, no session invalidation |
+| A08 | Integrity Failures | Missing input validation, unsafe deserialization |
+| A09 | Logging Failures | Passwords/tokens in logs, insufficient logging |
+| A10 | SSRF | User-controlled URLs fetched by server without validation |
+
+## Scan Commands
+
+```bash
+# Dependency vulnerabilities
+npm audit --audit-level=moderate
+
+# Hardcoded secrets (grep patterns)
+grep -r "password\s*=\s*['\"]" src/ --include="*.ts"
+grep -r "api_key\s*=\s*['\"]" src/ --include="*.ts"
+grep -r "secret\s*=\s*['\"]" src/ --include="*.ts"
+
+# SQL string concatenation
+grep -r "query\`.*\${" src/ --include="*.ts"
+grep -rn "query.*+.*req\." src/ --include="*.ts"
+```
+
+## Output Format
+
+```markdown
+## Security Scan Report
+
+### 🔴 Critical
+| # | File | Line | Issue | Remediation |
+|---|------|------|-------|-------------|
+
+### 🟠 High
+| # | File | Line | Issue | Remediation |
+|---|------|------|-------|-------------|
+
+### 🟡 Medium
+| # | File | Line | Issue | Remediation |
+|---|------|------|-------|-------------|
+
+### Dependencies
+- npm audit: 0 critical, 0 high, 2 moderate (tracked)
+
+### Verdict: PASS ✅ | FAIL ❌ | PASS_WITH_NOTES ⚠️
+
+FAIL if any Critical or High findings.
+PASS_WITH_NOTES if only Medium or Low findings.
+```

package/src/skills/self-healing-policies/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: self-healing-policies
+description: Update internal editing rules automatically after repeated failures, making the plugin more reliable over time inside the same repo.
+origin: FlowDeck
+---
+
+# Self-Healing Prompt Policies
+
+FlowDeck can learn from its own mistakes. When the same type of failure recurs, a new policy is added to `.codebase/POLICIES.json` to prevent it from happening again.
+
+## How Policies Work
+
+A policy is a trigger → rule pair:
+- **trigger**: the pattern that precedes the mistake (e.g., "editing auth middleware")
+- **rule**: what the agent must do/avoid when the trigger matches (e.g., "always run auth integration tests before committing")
+
+## Policy Lifecycle
+
+1. **Detection**: A failure is recorded in FAILURES.json with recurrence_count ≥ 2
+2. **Proposal**: The agent proposes a new policy to prevent the recurrence
+3. **Review**: Human reviews and approves/rejects via `/policy-update`
+4. **Active**: Policy is marked active=true and checked before relevant edits
+5. **Violation tracking**: Every time a policy is nearly violated, record it
+6. **Pruning**: Policies with 0 violations in 90 days are candidates for deactivation
+
+## Policy Sources
+
+| Source | Meaning |
+|--------|---------|
+| manual | Added by a human directly |
+| learned | Proposed by the agent after failure pattern detected |
+
+## Workflow
+
+### Adding a Learned Policy
+
+After recording a recurrent failure:
+1. Check if recurrence_count ≥ 2 for any failure entry
+2. If yes, propose a policy:
+   ```json
+   { "action": "add", "policy": {
+       "id": "no-auth-edit-without-tests",
+       "name": "Auth edits require test run",
+       "trigger": "editing files matching src/auth/ or src/middleware/",
+       "rule": "Always run auth test suite before committing. If no auth tests exist, create at least one regression test.",
+       "source": "learned",
+       "failure_count": 3
+   }}
+   ```
+3. Notify the human for approval
+
+### Checking Policies Before Edit
+
+Before editing a file:
+1. Query active policies: `{ "action": "query", "query": { "active_only": true } }`
+2. Check if any policy trigger matches the current file path or change type
+3. If match: apply the rule before proceeding
+
+### Updating Policies After New Failure
+
+```json
+{ "action": "record_violation", "policy_id": "no-auth-edit-without-tests" }
+```
+
+## Manual Policy Management
+
+```
+/policy-update {"action": "add", "policy": {...}}   — add new policy
+/policy-update {"action": "toggle", "policy_id": "X", "active": false}  — disable
+```
+
+## Guidance
+
+- Policies should be specific ("when editing X, always Y") not vague ("be careful")
+- Every learned policy must reference the failure ID that triggered it
+- Review all policies quarterly — disable ones that have never fired