agy-superpowers 5.2.2 → 5.2.4

package/template/agent/skills/rust-developer/references/rust-rules/type-phantom-marker.md

@@ -1,188 +0,0 @@
-# type-phantom-marker
-
-> Use `PhantomData` to express type relationships without runtime cost
-
-## Why It Matters
-
-Sometimes your type needs to be parameterized by a type that doesn't appear in any field—for variance, drop order, or semantic purposes. `PhantomData<T>` tells the compiler your type is "associated with" `T` without storing any `T` data. It has zero runtime cost.
-
-## Bad
-
-```rust
-// Type parameter unused - compiler error
-struct Handle<T> {
-    id: u64,
-    // Error: parameter `T` is never used
-}
-
-// Workaround with unnecessary storage
-struct Handle<T> {
-    id: u64,
-    _type: Option<T>,  // Wastes memory, requires T: Default
-}
-```
-
-## Good
-
-```rust
-use std::marker::PhantomData;
-
-struct Handle<T> {
-    id: u64,
-    _marker: PhantomData<T>,  // Zero-size, tells compiler about T
-}
-
-impl<T> Handle<T> {
-    fn new(id: u64) -> Self {
-        Handle {
-            id,
-            _marker: PhantomData,
-        }
-    }
-}
-
-// Different Handle types are incompatible
-struct User;
-struct Order;
-
-fn process_user(h: Handle<User>) { ... }
-
-let user_handle = Handle::<User>::new(1);
-let order_handle = Handle::<Order>::new(2);
-
-process_user(user_handle);   // OK
-process_user(order_handle);  // Error: expected Handle<User>, found Handle<Order>
-```
-
-## Expressing Ownership
-
-```rust
-use std::marker::PhantomData;
-
-// Owns T conceptually (like Box<T>)
-struct Container<T> {
-    ptr: *mut T,
-    _marker: PhantomData<T>,  // Acts like we own a T
-}
-
-// Drop will be called on T when Container drops
-impl<T> Drop for Container<T> {
-    fn drop(&mut self) {
-        unsafe {
-            std::ptr::drop_in_place(self.ptr);
-        }
-    }
-}
-```
-
-## Expressing Borrowing
-
-```rust
-use std::marker::PhantomData;
-
-// Borrows T for lifetime 'a
-struct Ref<'a, T> {
-    ptr: *const T,
-    _marker: PhantomData<&'a T>,  // Acts like &'a T
-}
-
-// Compiler tracks lifetime correctly
-impl<'a, T> Ref<'a, T> {
-    fn get(&self) -> &'a T {
-        unsafe { &*self.ptr }
-    }
-}
-```
-
-## Type-Level State Machine
-
-```rust
-use std::marker::PhantomData;
-
-// States as zero-size types
-struct Unlocked;
-struct Locked;
-
-struct Door<State> {
-    _state: PhantomData<State>,
-}
-
-impl Door<Unlocked> {
-    fn lock(self) -> Door<Locked> {
-        println!("Locking...");
-        Door { _state: PhantomData }
-    }
-    
-    fn open(&self) {
-        println!("Opening...");
-    }
-}
-
-impl Door<Locked> {
-    fn unlock(self) -> Door<Unlocked> {
-        println!("Unlocking...");
-        Door { _state: PhantomData }
-    }
-    
-    // Can't call open() on Locked door - method doesn't exist
-}
-
-fn example() {
-    let door: Door<Unlocked> = Door { _state: PhantomData };
-    door.open();           // OK
-    let locked = door.lock();
-    // locked.open();      // Error: no method `open` for Door<Locked>
-    let unlocked = locked.unlock();
-    unlocked.open();       // OK
-}
-```
-
-## Variance Control
-
-```rust
-use std::marker::PhantomData;
-
-// Covariant in T (PhantomData<T>)
-struct Producer<T> {
-    _marker: PhantomData<T>,  // Covariant
-}
-
-// Contravariant in T (PhantomData<fn(T)>)
-struct Consumer<T> {
-    _marker: PhantomData<fn(T)>,  // Contravariant
-}
-
-// Invariant in T (PhantomData<fn(T) -> T>)
-struct Both<T> {
-    _marker: PhantomData<fn(T) -> T>,  // Invariant
-}
-```
-
-## Common Uses
-
-```rust
-// 1. FFI handles with type safety
-struct FileHandle<T: FileType> {
-    fd: i32,
-    _marker: PhantomData<T>,
-}
-
-// 2. Generic iterators
-struct Iter<'a, T> {
-    ptr: *const T,
-    end: *const T,
-    _marker: PhantomData<&'a T>,
-}
-
-// 3. Allocator-aware types
-struct Vec<T, A: Allocator = Global> {
-    buf: RawVec<T, A>,
-    len: usize,
-}
-```
-
-## See Also
-
-- [api-typestate](./api-typestate.md) - State machine pattern
-- [api-newtype-safety](./api-newtype-safety.md) - Type-safe wrappers
-- [type-newtype-ids](./type-newtype-ids.md) - ID types

package/template/agent/skills/rust-developer/references/rust-rules/type-repr-transparent.md

@@ -1,143 +0,0 @@
-# type-repr-transparent
-
-> Use `#[repr(transparent)]` for newtypes in FFI contexts
-
-## Why It Matters
-
-`#[repr(transparent)]` guarantees a newtype has the same memory layout as its inner type. This is essential for FFI where you need type safety in Rust but must match C ABI layouts. Without it, the compiler may add padding or change layout.
-
-## Bad
-
-```rust
-// No layout guarantee - might not match inner type in FFI
-struct Handle(u64);
-
-// Passing to C code might fail
-extern "C" {
-    fn process_handle(h: Handle);  // May not work correctly
-}
-
-// Wrapping C type without layout guarantee
-struct SafePointer(*mut c_void);
-```
-
-## Good
-
-```rust
-// Guaranteed same layout as inner type
-#[repr(transparent)]
-struct Handle(u64);
-
-// Safe for FFI
-extern "C" {
-    fn process_handle(h: Handle);  // Works - same layout as u64
-}
-
-// FFI pointer wrapper
-#[repr(transparent)]
-struct SafePointer(*mut c_void);
-
-impl SafePointer {
-    // Safe Rust API around raw pointer
-    pub fn new(ptr: *mut c_void) -> Option<Self> {
-        if ptr.is_null() {
-            None
-        } else {
-            Some(SafePointer(ptr))
-        }
-    }
-}
-```
-
-## What repr(transparent) Guarantees
-
-```rust
-use std::mem::{size_of, align_of};
-
-#[repr(transparent)]
-struct Meters(f64);
-
-// Same size
-assert_eq!(size_of::<Meters>(), size_of::<f64>());
-
-// Same alignment
-assert_eq!(align_of::<Meters>(), align_of::<f64>());
-
-// Same ABI - can pass where f64 expected
-extern "C" fn measure(distance: Meters) { ... }
-```
-
-## With PhantomData
-
-```rust
-use std::marker::PhantomData;
-
-// PhantomData is zero-sized, doesn't affect layout
-#[repr(transparent)]
-struct TypedHandle<T> {
-    raw: u64,
-    _marker: PhantomData<T>,  // Zero-sized, ignored for layout
-}
-
-// Still same layout as u64
-assert_eq!(size_of::<TypedHandle<String>>(), size_of::<u64>());
-```
-
-## NonZero Wrappers
-
-```rust
-use std::num::NonZeroU64;
-
-#[repr(transparent)]
-struct NonZeroHandle(NonZeroU64);
-
-// Inherits null-pointer optimization
-assert_eq!(size_of::<Option<NonZeroHandle>>(), size_of::<u64>());
-```
-
-## FFI Pattern
-
-```rust
-mod ffi {
-    use std::os::raw::c_int;
-    
-    #[repr(transparent)]
-    pub struct FileDescriptor(c_int);
-    
-    extern "C" {
-        pub fn open(path: *const i8, flags: c_int) -> FileDescriptor;
-        pub fn close(fd: FileDescriptor) -> c_int;
-        pub fn read(fd: FileDescriptor, buf: *mut u8, len: usize) -> isize;
-    }
-}
-
-// Safe wrapper
-pub struct File {
-    fd: ffi::FileDescriptor,
-}
-
-impl File {
-    pub fn open(path: &str) -> std::io::Result<Self> {
-        let c_path = std::ffi::CString::new(path)?;
-        let fd = unsafe { ffi::open(c_path.as_ptr(), 0) };
-        // ... error handling
-        Ok(File { fd })
-    }
-}
-```
-
-## When to Use
-
-| Scenario | Use `#[repr(transparent)]`? |
-|----------|----------------------------|
-| FFI newtype wrappers | Yes |
-| Type-safe handles | Yes |
-| NonZero optimization | Yes |
-| Pure Rust newtypes | Optional (doesn't hurt) |
-| Multi-field structs | N/A (only for single-field) |
-
-## See Also
-
-- [type-newtype-ids](./type-newtype-ids.md) - Newtype pattern
-- [type-phantom-marker](./type-phantom-marker.md) - PhantomData usage
-- [api-newtype-safety](./api-newtype-safety.md) - Type-safe newtypes

package/template/agent/skills/rust-developer/references/rust-rules/type-result-fallible.md

@@ -1,131 +0,0 @@
-# type-result-fallible
-
-> Use `Result<T, E>` for operations that can fail
-
-## Why It Matters
-
-`Result<T, E>` makes failure explicit in the type system. Callers must acknowledge and handle potential errors—they can't accidentally ignore failures. The `?` operator makes error propagation ergonomic while maintaining explicit error handling.
-
-## Bad
-
-```rust
-// Returning Option loses error context
-fn read_config(path: &str) -> Option<Config> {
-    let content = std::fs::read_to_string(path).ok()?;  // Why did it fail?
-    toml::from_str(&content).ok()  // Parse error lost
-}
-
-// Panicking on errors
-fn read_config(path: &str) -> Config {
-    let content = std::fs::read_to_string(path).unwrap();  // Crashes
-    toml::from_str(&content).unwrap()  // Crashes
-}
-
-// Sentinel values
-fn divide(a: i32, b: i32) -> i32 {
-    if b == 0 { return -1; }  // Magic value, easy to miss
-    a / b
-}
-```
-
-## Good
-
-```rust
-// Result with clear error type
-fn read_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)
-        .map_err(ConfigError::IoError)?;
-    toml::from_str(&content)
-        .map_err(ConfigError::ParseError)
-}
-
-fn divide(a: i32, b: i32) -> Result<i32, DivisionError> {
-    if b == 0 {
-        return Err(DivisionError::DivideByZero);
-    }
-    Ok(a / b)
-}
-
-// Caller must handle
-match divide(10, 0) {
-    Ok(result) => println!("Result: {}", result),
-    Err(e) => println!("Error: {}", e),
-}
-```
-
-## The ? Operator
-
-```rust
-fn process_file(path: &str) -> Result<ProcessedData, Error> {
-    let content = std::fs::read_to_string(path)?;  // Propagates Err
-    let parsed: RawData = serde_json::from_str(&content)?;
-    let validated = validate(parsed)?;
-    let processed = transform(validated)?;
-    Ok(processed)
-}
-
-// Equivalent to:
-fn process_file(path: &str) -> Result<ProcessedData, Error> {
-    let content = match std::fs::read_to_string(path) {
-        Ok(c) => c,
-        Err(e) => return Err(e.into()),
-    };
-    // ... etc
-}
-```
-
-## Result Combinators
-
-```rust
-let result: Result<i32, Error> = Ok(42);
-
-// map: transform success value
-let doubled = result.map(|n| n * 2);  // Ok(84)
-
-// map_err: transform error
-let with_context = result.map_err(|e| format!("Failed: {}", e));
-
-// and_then: chain fallible operations
-let processed = result.and_then(|n| {
-    if n > 0 { Ok(n * 2) } else { Err(Error::Negative) }
-});
-
-// unwrap_or: provide default on error
-let value = result.unwrap_or(0);
-
-// ok(): convert to Option, discarding error
-let maybe_value: Option<i32> = result.ok();
-```
-
-## Defining Error Types
-
-```rust
-use thiserror::Error;
-
-#[derive(Error, Debug)]
-pub enum ConfigError {
-    #[error("failed to read file: {0}")]
-    Io(#[from] std::io::Error),
-    
-    #[error("failed to parse config: {0}")]
-    Parse(#[from] toml::de::Error),
-    
-    #[error("missing required field: {0}")]
-    MissingField(String),
-}
-
-fn load_config(path: &str) -> Result<Config, ConfigError> {
-    let content = std::fs::read_to_string(path)?;  // Io error
-    let config: Config = toml::from_str(&content)?;  // Parse error
-    if config.name.is_empty() {
-        return Err(ConfigError::MissingField("name".into()));
-    }
-    Ok(config)
-}
-```
-
-## See Also
-
-- [err-thiserror-lib](./err-thiserror-lib.md) - Defining error types
-- [err-question-mark](./err-question-mark.md) - Using ? operator
-- [type-option-nullable](./type-option-nullable.md) - Option vs Result

package/template/agent/skills/saas-architect/SKILL.md

@@ -1,139 +0,0 @@
----
-name: saas-architect
-description: Use when designing multi-tenant SaaS architecture, tenant isolation, data models, or making core infrastructure decisions for a SaaS product
----
-
-# SaaS Architect Lens
-
-> **Philosophy:** Multi-tenancy is not a feature — it's a fundamental architectural constraint.
-> Every design decision must answer: "Is this tenant-safe?"
-
----
-
-## Core Instincts
-
-- **Tenant isolation first** — data leaking between tenants is an existential business risk
-- **Design for the tenant, not the user** — every entity in the data model has a `tenant_id`
-- **Shared infrastructure, isolated data** — the sweet spot for indie hackers
-- **Plan the upgrade path** — schema-per-tenant → RLS → shared schema: picking wrong is expensive to change
-- **Hard-delete rarely; soft-delete by default** — audit trails matter in B2B
-
----
-
-## Tenancy Isolation Models
-
-| Model | Isolation | Cost | Complexity | Best for |
-|-------|-----------|------|------------|----------|
-| **Separate database per tenant** | ✅ Strongest | 💰 Highest | High | Enterprise, regulated industries |
-| **Schema per tenant** (PostgreSQL) | ✅ Strong | 💰 Medium | Medium | Mid-market SaaS |
-| **Row-level security (RLS)** | ✅ Good | 💰 Low | Medium | Indie hacker / SMB SaaS |
-| **Application-level filtering** | ⚠️ Weakest | 💰 Lowest | Low | Prototype only — never production |
-
-**Recommended for indie hackers:** Row-Level Security (RLS) on PostgreSQL (Supabase, Neon). Strong isolation at low cost.
-
----
-
-## Tenant Data Model Pattern
-
-```sql
--- Every table must have tenant_id
-CREATE TABLE projects (
-  id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-  tenant_id   UUID NOT NULL REFERENCES tenants(id) ON DELETE CASCADE,
-  name        TEXT NOT NULL,
-  created_at  TIMESTAMPTZ DEFAULT now(),
-  deleted_at  TIMESTAMPTZ  -- soft delete
-);
-
--- RLS: tenant can only see their own rows
-ALTER TABLE projects ENABLE ROW LEVEL SECURITY;
-CREATE POLICY tenant_isolation ON projects
-  USING (tenant_id = current_setting('app.tenant_id')::UUID);
-
--- Index tenant_id on EVERY tenant-scoped table
-CREATE INDEX ON projects(tenant_id);
-```
-
----
-
-## Tenant Routing Patterns
-
-```
-Option 1: Subdomain routing
-  acme.myapp.com → tenant lookup by subdomain → set tenant_id context
-
-Option 2: Path routing
-  myapp.com/acme → extract slug from path → set tenant_id context
-
-Option 3: Custom domain
-  app.acme.com → CNAME → myapp.com → DNS lookup → set tenant_id context
-
-Recommended for indie hackers: Start with subdomain routing; add custom domains when users ask.
-```
-
----
-
-## ❌ Anti-Patterns to Avoid
-
-| ❌ NEVER DO | Why | ✅ DO INSTEAD |
-|------------|-----|--------------|
-| Application-level tenant filtering only | One missing WHERE clause = data breach | RLS at DB level = defense in depth |
-| Tenant ID in JWT payload, enforced only in app | Bypassed by direct DB access | DB-level enforcement (RLS or schema) |
-| Hard-delete tenant data immediately | Chargebacks, disputes, legal holds | Soft-delete + 30-day retention before purge |
-| No tenant_id index | Full table scan at scale | `CREATE INDEX ON every_table(tenant_id)` |
-| Single shared sequence for IDs | Enumerable IDs expose tenant data volume | UUIDs (v4 or v7) always |
-| Storing cross-tenant references | Breaks isolation, schema nightmare | Denormalize data within tenant boundary |
-
----
-
-## Tenant Lifecycle Management
-
-```
-Sign up → Create tenant record → Create owner user → Provision trial subscription
-         ↓
-      Active → Upgrade → Downgrade → Cancel → Grace period (30 days) → Purge
-```
-
-**Required tenant states:** `trialing`, `active`, `past_due`, `canceled`, `suspended`
-
----
-
-## Questions You Always Ask
-
-**When adding a new model:**
-- Does every record in this table belong to a tenant? → Add `tenant_id`
-- Is there an index on `tenant_id`?
-- Does the RLS policy cover this table?
-- What happens when the tenant is deleted/canceled?
-
-**When reviewing a query:**
-- Is `tenant_id` in the WHERE clause? (Even with RLS, explicit filtering = clarity)
-- Could this query return data from another tenant?
-
----
-
-## Red Flags
-
-**Must fix:**
-- [ ] Tables with user data but no `tenant_id`
-- [ ] Application-level tenant filtering without DB-level enforcement
-- [ ] No index on `tenant_id` columns
-- [ ] Hard-delete on tenant cancellation (no retention period)
-
-**Should fix:**
-- [ ] No soft-delete strategy for tenant-scoped records
-- [ ] Cross-tenant foreign key references
-- [ ] Tenant ID stored as integer (enumerable — use UUID)
-
----
-
-## Who to Pair With
-- `backend-developer` — for query patterns and migration execution
-- `auth-and-identity` — for tenant-scoped authentication
-- `security-engineer` — for data isolation audit
-- `devops-engineer` — for per-tenant resource provisioning
-
----
-
-## Tools
-Supabase (RLS built-in) · Neon (branching per tenant possible) · PlanetScale (separate DBs) · Drizzle ORM / Prisma (schema management) · Zod (runtime tenant_id validation)