@stacksjs/defaults 0.70.206 → 0.70.208

package/ai/skills/stacks-path/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: stacks-path
+description: Use when working with file paths in Stacks — 100+ framework-aware path builder functions for every directory in the project (actions, app, config, database, models, routes, storage, etc.), plus Node.js path utilities (join, resolve, basename, dirname, etc.). Covers @stacksjs/path.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Path
+
+100+ path builder functions for every framework directory.
+
+## Key Path
+- Core package: `storage/framework/core/path/src/`
+
+## Node.js Path Re-exports
+`basename`, `delimiter`, `dirname`, `extname`, `isAbsolute`, `join`, `normalize`, `parse`, `relative`, `resolve`, `sep`, `toNamespacedPath`
+
+## Framework Path Builders
+
+All accept an optional relative path suffix and return absolute paths.
+
+### Application Paths
+```typescript
+appPath('Models')                  // ~/app/Models
+userActionsPath()                  // ~/app/Actions
+userComponentsPath()               // ~/app/Components
+userViewsPath()                    // ~/app/Views
+userFunctionsPath()                // ~/app/Functions
+userJobsPath()                     // ~/app/Jobs
+userControllersPath()              // ~/app/Controllers
+userListenersPath()                // ~/app/Listeners
+userMiddlewarePath()               // ~/app/Middleware
+userModelsPath()                   // ~/app/Models
+userNotificationsPath()            // ~/app/Notifications
+userDatabasePath()                 // ~/database
+userMigrationsPath()               // ~/database/migrations
+userEventsPath()                   // ~/app/Events.ts
+```
+
+### Framework Paths
+```typescript
+actionsPath()                      // ~/storage/framework/core/actions
+buddyPath()                        // ~/storage/framework/core/buddy
+runtimePath()                      // ~/storage/framework/core/buddy
+buildPath()                        // ~/storage/framework/core/build
+cachePath()                        // ~/storage/framework/cache
+cloudPath()                        // ~/cloud
+frameworkCloudPath()               // ~/storage/framework/cloud
+libsPath()                         // ~/storage/framework/libs
+```
+
+### Package Paths (one per core package)
+```typescript
+aiPath()         analyticsPath()    aliasPath()
+arraysPath()     authPath()         browserPath()
+cliPath()        chatPath()         collectionsPath()
+configPath()     databasePath()     datetimePath()
+dnsPath()        docsPath()         emailPath()
+enumsPath()      envPath()          errorHandlingPath()
+eventsPath()     fakerPath()        gitPath()
+healthPath()     httpPath()         i18nPath()
+lintPath()       loggingPath()      notificationsPath()
+objectsPath()    ormPath()          pathPath()
+paymentsPath()   pluginsPath()      pushPath()
+queuePath()      realtimePath()     routerPath()
+schedulerPath()  searchEnginePath() securityPath()
+serverPath()     shellPath()        slugPath()
+smsPath()        socialsPath()      storagePath()
+stringsPath()    testingPath()      tinkerPath()
+tunnelPath()     typesPath()        uiPath()
+utilsPath()      validationPath()   whoisPath()
+```
+
+### Resource Paths
+```typescript
+assetsPath()                       // ~/resources/assets
+resourcesPath()                    // ~/resources
+publicPath()                       // ~/public
+localesPath()                      // ~/locales
+routesPath()                       // ~/routes
+```
+
+### Build & Output Paths
+```typescript
+buildEnginePath()
+libsEntriesPath()
+frameworkPath()                    // ~/storage/framework
+corePath()                         // ~/storage/framework/core
+defaultsPath()                     // ~/storage/framework/defaults
+defaultsAppPath()
+defaultsResourcesPath()
+```
+
+### Relative Path Variants
+Most paths have `relative*` variants:
+```typescript
+relativeActionsPath()
+relativeAppPath()
+```
+
+## Path with Suffix
+
+```typescript
+appPath('Models/User.ts')           // ~/app/Models/User.ts
+databasePath('migrations')          // ~/storage/framework/core/database/migrations
+configPath('app.ts')                // ~/config/app.ts
+```
+
+## Gotchas
+- Always use `@stacksjs/path` instead of Node's `path` for framework paths
+- All paths resolve to absolute paths by default
+- Most functions accept an optional relative path suffix
+- `relative*` variants return paths relative to project root
+- `user*Path()` functions point to application-level directories (app/)
+- `built*Path()` functions point to compiled output directories
+- Path is a dependency of almost every framework package
+- Some paths accept `options` with `relative` flag

package/ai/skills/stacks-payments/SKILL.md

@@ -0,0 +1,373 @@
+---
+name: stacks-payments
+description: Use when implementing payment processing in Stacks — Stripe charges, subscriptions, checkout sessions, customer management, payment methods, invoices, coupons, promo codes, products, prices, webhooks, or the Payment facade. Covers @stacksjs/payments and config/payment.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Stacks Payments
+
+Full Stripe integration via the Payment facade. Uses Stripe API version `2026-01-28.clover`. The Stripe SDK is initialized from `services.stripe.secretKey` (sourced from `config/payment.ts`).
+
+## Key Paths
+- Core package: `storage/framework/core/payments/src/`
+- Payment facade: `storage/framework/core/payments/src/payment.ts`
+- Stripe driver: `storage/framework/core/payments/src/drivers/stripe.ts`
+- Billable modules: `storage/framework/core/payments/src/billable/`
+- Configuration: `config/payment.ts`
+- SaaS config: `config/saas.ts`
+- Default billing functions: `storage/framework/defaults/functions/billing/payments.ts`
+
+## Package Exports
+- `Payment` (default) -- facade object with all payment methods
+- All individual functions (`charge`, `subscribe`, `checkout`, etc.)
+- All billable modules (`manageCharge`, `manageCustomer`, `manageSubscription`, etc.)
+- `stripe` -- raw Stripe SDK instance
+- `Stripe` -- re-exported Stripe types namespace
+
+## Payment Facade
+
+The `Payment` object aggregates all payment operations. Every method is also available as a standalone export.
+
+### Charges
+
+```typescript
+import { Payment } from '@stacksjs/payments'
+
+// Create and confirm a charge (creates PaymentIntent with confirm: true)
+const intent = await Payment.charge(user, 2999, 'pm_xxx', { currency: 'usd' })
+
+// Create PaymentIntent without confirming (for client-side confirmation)
+const intent = await Payment.createPayment(user, 2999, { currency: 'usd' })
+
+// Refund -- partial
+const refund = await Payment.refund('pi_xxx', 1000)
+
+// Refund -- full (omit amount)
+const refund = await Payment.refund('pi_xxx')
+```
+
+`charge()` sets `confirmation_method: 'automatic'`, `confirm: true`, attaches the payment method, and delegates to `createPayment()`. If the user has a `stripe_id`, it is set as the customer on the PaymentIntent. Default currency is `'usd'`.
+
+The `manageCharge` module also exposes `findPayment(id)` which retrieves a PaymentIntent by ID, returning `null` on failure.
+
+### Checkout Sessions
+
+```typescript
+// One-time payment checkout
+const session = await Payment.checkout(user, [
+  { price: 'price_xxx', quantity: 1 }
+], { success_url: '/success', cancel_url: '/cancel' })
+
+// Subscription checkout
+const subSession = await Payment.subscriptionCheckout(user, 'price_xxx', {
+  success_url: '/success', cancel_url: '/cancel'
+})
+```
+
+Both methods require the user to have a `stripe_id` (throws if missing). `checkout()` sets `mode: 'payment'`, `subscriptionCheckout()` sets `mode: 'subscription'`.
+
+### Subscriptions
+
+```typescript
+// Create -- uses lookup_key to resolve the Stripe Price
+const sub = await Payment.subscribe(user, 'premium-monthly')
+
+// Cancel at period end (prorate: true)
+const cancelled = await Payment.cancelSubscription('sub_xxx')
+
+// Cancel immediately (invoice_now: true, prorate: false)
+const cancelled = await Payment.cancelSubscription('sub_xxx', true)
+
+// Check active subscription
+const hasActive = await Payment.hasActiveSubscription(user, 'default')
+
+// Change plan -- swaps the subscription item's price
+const changed = await Payment.changeSubscription(user, 'enterprise-monthly')
+```
+
+`subscribe()` calls `managePrice.retrieveByLookupKey(lookupKey)` to find the price, then creates the subscription with `payment_behavior: 'allow_incomplete'` and `expand: ['latest_invoice.payment_intent']`. It stores the subscription in the `subscriptions` database table.
+
+`isValid()` returns `true` if the subscription status is `'active'` or `'trialing'`. `isIncomplete()` checks for `'incomplete'` status.
+
+`cancel()` calls `stripe.subscriptions.cancel()` and updates `provider_status` to `'canceled'` in the database.
+
+`update()` retrieves the active subscription via `user.activeSubscription()`, finds the new price by lookup key, updates the subscription item, and stores the updated price in the database.
+
+### Customers
+
+```typescript
+// Get existing or create new Stripe customer
+const customer = await Payment.getOrCreateCustomer(user, { name: 'John' })
+
+// Update customer details in Stripe
+const updated = await Payment.updateCustomer(user, { name: 'Jane' })
+
+// Delete from Stripe and clear stripe_id on user model
+const deleted = await Payment.deleteCustomer(user)
+```
+
+`createOrGetStripeUser()` checks `user.stripe_id` first. If the user has one, it retrieves the customer from Stripe. If the customer was deleted (404 or `deleted: true`), it creates a new one. On creation, it auto-fills `name` and `email` from the user model and calls `user.update({ stripe_id: customer.id })`.
+
+Additional methods on `manageCustomer`:
+- `stripeId(user)` -- returns `user.stripe_id`
+- `hasStripeId(user)` -- boolean check
+- `createStripeCustomer(user, options)` -- throws if user already has a stripe_id
+- `createOrUpdateStripeUser(user, options)` -- creates or updates
+- `retrieveStripeUser(user)` -- returns customer or undefined
+- `syncStripeCustomerDetails(user, options)` -- updates Stripe with user's name, email, address, locales, metadata
+
+### Payment Methods
+
+```typescript
+// Add a payment method to the customer
+const pm = await Payment.addPaymentMethod(user, 'pm_xxx')
+
+// Set as default (by Stripe payment method ID string)
+const customer = await Payment.setDefaultPaymentMethod(user, 'pm_xxx')
+
+// Remove a payment method (by database record ID number)
+const removed = await Payment.removePaymentMethod(user, paymentMethodDbId)
+
+// Create a setup intent for collecting payment methods
+const intent = await Payment.createSetupIntent(user, { payment_method_types: ['card'] })
+```
+
+`addPaymentMethod()` accepts a string (Stripe PM ID) or Stripe.PaymentMethod object. It attaches the PM to the customer if not already attached, then stores it in the `payment_methods` table with `type`, `last_four`, `brand`, `exp_year`, `exp_month`, `user_id`, `provider_id`.
+
+`setUserDefaultPayment()` accepts a Stripe PM ID string, clears existing `is_default` flags, sets the new default in the database, and updates `invoice_settings.default_payment_method` on the Stripe customer.
+
+`setDefaultPaymentMethod()` accepts a database record ID number.
+
+Additional methods on `managePaymentMethod`:
+- `updatePaymentMethod(user, pmId, params)` -- updates PM in Stripe
+- `listPaymentMethods(user)` -- queries `payment_methods` table by `user_id`
+- `retrievePaymentMethod(user, pmId)` -- by database ID
+- `retrieveDefaultPaymentMethod(user)` -- finds where `is_default: true`
+
+### Invoices
+
+```typescript
+const invoices = await Payment.getInvoices(user)  // lists with expanded payment_intent.payment_method
+const invoice = await Payment.createInvoice('cus_xxx', { description: 'Custom invoice' })
+const paid = await Payment.payInvoice('inv_xxx')
+```
+
+`getInvoices()` requires the user to have a `stripe_id` and expands `data.payment_intent.payment_method`.
+
+### Products & Prices
+
+```typescript
+// Create a product with its price
+const { product, price } = await Payment.createProduct('Pro Plan', 2999, {
+  currency: 'usd', interval: 'month', description: 'Pro features'
+})
+
+// Get a price by Stripe lookup_key
+const price = await Payment.getPrice('premium-monthly')
+
+// List active products
+const products = await Payment.listProducts({ limit: 10 })
+```
+
+`createProduct()` creates the Stripe product, then creates a price linked to it. If `interval` is provided, the price gets `recurring: { interval }`.
+
+Additional methods on `manageProduct`:
+- `create(params)`, `retrieve(productId)`, `update(productId, params)`
+- `archive(productId)` -- sets `active: false`
+- `search(query, params)` -- Stripe product search
+- `list(params)` -- defaults to `active: true`
+
+Additional methods on `managePriceExtended`:
+- `create(params)`, `retrieve(priceId)`, `update(priceId, params)`
+- `list(params)` -- defaults to `active: true`
+- `listByProduct(productId, params)` -- prices for a specific product
+- `search(query, params)` -- Stripe price search
+- `archive(priceId)` -- sets `active: false`
+
+### Coupons & Promo Codes
+
+```typescript
+const coupon = await Payment.createCoupon({
+  percentOff: 20, duration: 'once', name: 'Holiday Sale', maxRedemptions: 100
+})
+
+// Or amount-based: { amountOff: 500, currency: 'usd', duration: 'forever' }
+
+const promo = await Payment.createPromoCode('coupon_xxx', 'SAVE20')
+const valid = await Payment.validatePromoCode('SAVE20')  // returns PromotionCode | null
+```
+
+`createCoupon()` supports `percentOff`, `amountOff`, `currency`, `duration` ('forever' | 'once' | 'repeating'), `durationInMonths`, `name`, `maxRedemptions`.
+
+Additional methods on `manageCoupon`:
+- `retrieve(couponId)`, `update(couponId, params)`, `delete(couponId)`, `list(params)`
+- `createPromotionCode(params)` -- wraps `stripe.promotionCodes.create()`
+- `retrievePromotionCode(code)` -- lists active promotion codes matching the code string
+
+### Transactions
+
+```typescript
+import { manageTransaction } from '@stacksjs/payments'
+
+const tx = await manageTransaction.store(user, productId, {
+  brand: 'visa', provider_id: 'pi_xxx', description: 'Purchase', type: 'one-time'
+})
+const txList = await manageTransaction.list(user)
+```
+
+Transactions are stored in the `payment_transactions` table with `name` (from product), `amount` (from product `unit_price`), `brand`, `type`, `provider_id`, `user_id`.
+
+### Webhooks
+
+```typescript
+import { Payment } from '@stacksjs/payments'
+
+// Register handlers
+Payment.onPaymentIntent({
+  succeeded: async (event) => { /* ... */ },
+  failed: async (event) => { /* ... */ },
+  created: async (event) => { /* ... */ },
+  canceled: async (event) => { /* ... */ },
+})
+
+Payment.onSubscription({
+  created: async (event) => { /* ... */ },
+  updated: async (event) => { /* ... */ },
+  deleted: async (event) => { /* ... */ },
+  trialWillEnd: async (event) => { /* ... */ },
+})
+
+Payment.onInvoice({
+  paid: async (event) => { /* ... */ },
+  paymentFailed: async (event) => { /* ... */ },
+  created: async (event) => { /* ... */ },
+  finalized: async (event) => { /* ... */ },
+})
+
+Payment.onCheckout({
+  completed: async (event) => { /* ... */ },
+  expired: async (event) => { /* ... */ },
+})
+
+Payment.onCharge({
+  succeeded: async (event) => { /* ... */ },
+  failed: async (event) => { /* ... */ },
+  refunded: async (event) => { /* ... */ },
+  disputed: async (event) => { /* ... */ },
+})
+
+// Process incoming webhook request
+const result = await Payment.processWebhook(rawPayload, signatureHeader, {
+  secret: 'whsec_xxx', tolerance: 300
+})
+// Returns: { success: boolean, eventType?: string, error?: string }
+
+// Low-level: register any event type
+Payment.webhook.onWebhookEvent('payment_method.attached', handler)
+Payment.webhook.registerWebhookHandlers({ 'payment_intent.succeeded': handler })
+
+// Event data extractors
+import { getPaymentIntent, getSubscription, getInvoice, getCheckoutSession, getCharge, getCustomer } from '@stacksjs/payments'
+```
+
+Supported webhook event types: `payment_intent.succeeded`, `payment_intent.payment_failed`, `payment_intent.created`, `payment_intent.canceled`, `customer.subscription.created/updated/deleted`, `customer.subscription.trial_will_end`, `customer.created/updated/deleted`, `invoice.paid/payment_failed/finalized/created`, `checkout.session.completed/expired`, `charge.succeeded/failed/refunded`, `charge.dispute.created/closed`, `payment_method.attached/detached`, `setup_intent.succeeded/setup_failed`, plus any string.
+
+### Setup Products from SaaS Config
+
+```typescript
+import { createStripeProduct } from '@stacksjs/payments'
+
+const result = await createStripeProduct()
+// Creates Stripe products and prices from config/saas.ts plans
+```
+
+This iterates `saas.plans`, creates a Stripe product per plan, then creates prices for each pricing option using `lookup_key` from the `key` field.
+
+### Utility Functions
+
+```typescript
+Payment.formatAmount(2999, 'usd')   // '$29.99' (uses Intl.NumberFormat)
+Payment.toCents(29.99)               // 2999
+Payment.toDollars(2999)              // 29.99
+```
+
+### Client-Side Billing (useBillable)
+
+The `storage/framework/defaults/functions/billing/payments.ts` file provides a `useBillable()` composable for frontend billing UI:
+
+```typescript
+const { loadCardForm, loadPaymentForm, handleAddPaymentMethod, handlePayment } = useBillable()
+
+await loadCardForm(clientSecret)      // loads Stripe Card Element
+await loadPaymentForm(clientSecret)   // loads Stripe Payment Element
+await handleAddPaymentMethod(clientSecret, elements)  // confirms card setup
+await handlePayment(elements)         // confirms payment
+```
+
+## config/payment.ts
+
+```typescript
+{
+  driver: 'stripe',
+  stripe: {
+    publishableKey: env.STRIPE_PUBLISHABLE_KEY || '',
+    secretKey: env.STRIPE_SECRET_KEY || '',
+  },
+} satisfies PaymentConfig
+```
+
+## config/saas.ts
+
+Plans use `productName`, `description`, `metadata`, and a `pricing` array where each entry has `key` (lookup_key), `price` (in cents), `interval` (optional: 'month' | 'year'), `currency`:
+
+```typescript
+{
+  plans: [
+    {
+      productName: 'Stacks Hobby',
+      description: 'All the Stacks features.',
+      pricing: [
+        { key: 'stacks_hobby_early_monthly', price: 1900, interval: 'month', currency: 'usd' },
+        { key: 'stacks_hobby_yearly', price: 37900, interval: 'year', currency: 'usd' },
+      ],
+      metadata: { createdBy: 'admin', version: '1.0.0' },
+    },
+    // ... more plans
+  ],
+  webhook: { endpoint: 'your-webhook-endpoint', secret: 'your-webhook-secret' },
+  currencies: ['usd'],
+  coupons: [],
+  products: [
+    { name: 'Stacks Hobby', description: '...', images: ['image-url'] },
+  ],
+} satisfies SaasConfig
+```
+
+## Database Tables Used
+- `subscriptions` -- columns: `user_id`, `type`, `unit_price`, `provider_id`, `provider_status`, `provider_price_id`, `quantity`, `trial_ends_at`, `ends_at`, `provider_type`, `last_used_at`
+- `payment_methods` -- columns: `id`, `type`, `last_four`, `brand`, `exp_year`, `exp_month`, `user_id`, `provider_id`, `is_default`
+- `payment_products` -- columns: `id`, `name`, `unit_price`
+- `payment_transactions` -- columns: `id`, `name`, `description`, `amount`, `brand`, `type`, `provider_id`, `user_id`
+
+## User Model Requirements
+The `UserModel` must have:
+- `id`, `name`, `email`, `stripe_id` fields
+- `hasStripeId()` method -- returns boolean
+- `update(data)` method -- for persisting `stripe_id`
+- `activeSubscription()` method -- for subscription updates
+
+## Gotchas
+- Stripe API keys MUST be in `.env` as `STRIPE_SECRET_KEY` and `STRIPE_PUBLISHABLE_KEY` -- never hardcode them in config files
+- The Stripe SDK is initialized eagerly -- if `STRIPE_SECRET_KEY` is missing, the module throws on import
+- All amounts are in cents -- use `toCents()` and `toDollars()` for conversion
+- `charge()` creates AND confirms the PaymentIntent in one step
+- `subscribe()` resolves the price via `lookup_key`, not a direct Stripe price ID
+- `removePaymentMethod()` takes a database record ID (number), not a Stripe PM ID (string)
+- `setDefaultPaymentMethod` has two variants: one takes a Stripe PM ID string (`setUserDefaultPayment`), the other takes a database ID number
+- `getOrCreateCustomer()` handles deleted Stripe customers by recreating them
+- Subscription status checks query the local database, not Stripe directly
+- `list()` on products defaults to `active: true` only
+- Webhook handlers are stored in an in-memory Map -- register them on application startup
+- `processWebhook()` uses `stripe.webhooks.constructEvent()` for signature verification

package/ai/skills/stacks-plan-review/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: stacks-plan-review
+description: Use for architecture review of Stacks changes — scope review (CEO-level), data flow analysis, dependency analysis, test matrices, and implementation plans. Invoke with /stacks-plan-review.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# /stacks-plan-review — Architecture Review & Planning
+
+You analyze proposed changes at two levels: scope review (are we building the right thing?) and engineering review (are we building it right?).
+
+## Upstream Context
+
+If `/stacks-office-hours` produced a design document, read it. Don't ask the user to re-explain.
+
+## Step 1: Scope Review
+
+### Expansion Analysis — Is this doing too much
+
+```
+| Addition | Core to goal? | Can ship separately? | Risk if included |
+|----------|--------------|---------------------|-----------------|
+| [item] | [yes/no] | [yes/no] | [risk] |
+```
+
+### Reduction Analysis — Is this doing too little
+
+```
+| Missing piece | Needed for v1? | Cost of deferring |
+|---------------|---------------|-------------------|
+| [item] | [yes/no] | [consequence] |
+```
+
+```
+📊 Scope: [RIGHT-SIZED / TOO BROAD / TOO NARROW]
+Recommended scope: [what should be in vs. out]
+```
+
+## Step 2: Data Flow Analysis
+
+Trace data through the Stacks system:
+
+```
+[entry point] → [transformation] (file:function) → [exit point]
+Error paths: [what happens when each step fails]
+```
+
+For Stacks projects, pay attention to:
+- Cross-package data flow in the monorepo (`storage/framework/core/*/`)
+- Build pipeline flow (source → `bun build` → `dist/`)
+- Request flow: route → middleware → action → ORM → database
+- CLI flow: `buddy` command → action → core package
+
+## Step 3: Architecture Review
+
+### Dependency Analysis
+
+```
+### This change depends on:
+| Dependency | Type | Stability | Risk |
+|-----------|------|-----------|------|
+| [@stacksjs/package] | [internal] | [stable/changing] | [what could break] |
+
+### Depends on this change:
+| Consumer | Impact | Migration needed? |
+|----------|--------|-------------------|
+| [package] | [what changes] | [yes/no] |
+```
+
+### Interface Review
+
+For new/changed public interfaces:
+
+```
+### [Interface] (file:line)
+**Before**: [existing signature]
+**After**: [proposed signature]
+**Breaking?**: [yes/no]
+**Migration path**: [how consumers update]
+```
+
+### Consistency Check
+
+- Naming: match existing patterns in the codebase
+- Error handling: does this project throw, return Result types, or use error codes?
+- Config: does it follow `defineX()` pattern from `@stacksjs/config`?
+- Testing: does it follow `bun test` patterns?
+
+## Step 4: Test Matrix
+
+```
+### Unit Tests
+| Function | Test Case | Input | Expected | Priority |
+|----------|-----------|-------|----------|----------|
+
+### Integration Tests
+| Flow | Components | Scenario | Priority |
+|------|-----------|----------|----------|
+
+### Edge Cases
+| Case | Why it matters | Test approach |
+|------|---------------|---------------|
+```
+
+P0: Must have before merge. P1: Should have. P2: Nice to have.
+
+## Step 5: Implementation Plan
+
+```
+### Phase 1: [name]
+- [ ] [task with file references]
+**Checkpoint**: [what should be true]
+
+### Phase 2: [name]
+- [ ] [task]
+**Checkpoint**: [what should be true]
+
+### Rollback Plan
+1. [specific rollback step]
+```
+
+Each phase should be independently mergeable. Run `bun test` at each checkpoint.
+
+## Output
+
+```
+# Plan: [feature/change]
+
+## Scope Assessment
+## Data Flow
+## Architecture Review
+## Test Matrix
+## Implementation Plan
+
+## Summary
+- Scope: [assessment]
+- Breaking changes: [yes/no]
+- New dependencies: [list]
+- Key risk: [biggest risk + mitigation]
+```
+
+## Rules
+
+- **Scope review is not optional.** Even for "just a technical plan."
+- **Be specific about files.** "Update auth" → "Add token validation in `storage/framework/core/auth/src/middleware.ts`"
+- **Test matrix before implementation.** Knowing what to test shapes how you build.
+- **For Stacks monorepo**: always check cross-package impacts.
+
+## Downstream
+
+> **Plan complete.** After implementation, run `/stacks-review` for code review, `/stacks-security-audit` for security, or `/stacks-browse` for QA.