@stacksjs/defaults 0.72.103 → 0.73.0

package/ai/AGENTS.md

@@ -63,12 +63,33 @@ same path under `app/` and it wins.
 
 ## Skills
 
-The framework ships a skill per subsystem under
-`storage/framework/defaults/ai/skills`, each documenting that area
-authoritatively. Read the relevant `SKILL.md` before doing non-trivial work
-rather than guessing at an API.
+The framework ships two kinds of skill under
+`storage/framework/defaults/ai/skills`.
+
+**Subsystem reference**, one per area (`stacks-orm`, `stacks-router`,
+`stacks-queue`, ...), each documenting it authoritatively. Read the relevant
+`SKILL.md` before doing non-trivial work rather than guessing at an API.
+
+**Engineering craft**, which shape how the work happens:
+
+| Situation | Skill |
+|---|---|
+| Which skill fits, and where to cut a session | `stacks-flow` |
+| Stress-test an idea before building it | `stacks-office-hours`, `stacks-grilling` |
+| Answer a design question with throwaway code | `stacks-prototype` |
+| Plan the change: scope, seams, test matrix | `stacks-plan-review`, `stacks-codebase-design` |
+| Name things, keep `CONTEXT.md` and ADRs current | `stacks-domain-modeling` |
+| Build it test-first, one tracer bullet at a time | `stacks-tdd`, `stacks-new-feature` |
+| Something is broken, flaky or slow | `stacks-investigate` |
+| Review the diff on standards and spec | `stacks-review` |
+| A step only a human can take | `stacks-wizard` |
+| Improve the environment for next time | `stacks-retro` |
+| Write a skill or any doc an agent reads | `stacks-writing-for-agents` |
 
 Add your own with `app/Skills/<name>/SKILL.md`, then re-run `buddy setup:ai`.
+A project skill shadows a bundled one of the same name. Read
+`stacks-writing-for-agents` first: it covers the frontmatter the validator
+enforces and how to write a description that actually fires.
 
 ---
 

package/ai/README.md

@@ -38,8 +38,30 @@ reference for a task instead of guessing at an API.
 symlinks by default so skills stay in sync when you upgrade the framework. Pass
 `--copy` if you would rather edit them per project.
 
+### Two kinds
+
+Most bundled skills are **subsystem reference**: one per part of the framework,
+model-invoked, found by the agent from the task at hand. A smaller set are
+**engineering craft** skills that shape how the work happens rather than which
+package it touches: `stacks-flow` routes between them, and `stacks-grilling`,
+`stacks-codebase-design`, `stacks-tdd`, `stacks-domain-modeling`,
+`stacks-prototype`, `stacks-wizard`, `stacks-handoff` and
+`stacks-writing-for-agents` are the rest. Several are adapted from
+[mattpocock/skills](https://github.com/mattpocock/skills) (MIT), with credit in
+each `SKILL.md`.
+
+Each skill also has a page in the documentation site, under `docs/skills/`, one
+per skill with a landing page per section. `tests/unit/skills-docs-contract.test.ts`
+fails when a skill gains or loses a page, so the two cannot drift apart.
+
+### Adding your own
+
 To add a project-specific skill, or to shadow a bundled one, create
-`app/Skills/<name>/SKILL.md`. `@stacksjs/skills` searches `app/Skills` first and
-falls back to this directory - the same app-overrides-defaults model the rest of
-the framework uses - and `setup:ai` links the winner, so a project skill also
-wins in the agent's directory.
+`app/Skills/<name>/SKILL.md`. Read `stacks-writing-for-agents` before you do:
+it covers the frontmatter `validateSkill()` enforces, the invocation choice, and
+how to write a description that fires when it should.
+
+`@stacksjs/skills` searches `app/Skills` first and falls back to this directory,
+the same app-overrides-defaults model the rest of the framework uses, and
+`setup:ai` links the winner, so a project skill also wins in the agent's
+directory.

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-actions
-description: Use when working with Stacks server actions — creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 80+ default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
+description: Use when working with Stacks server actions - creating actions in app/Actions/, auto-generated API actions from the useApi model trait, the 80+ default framework actions (auth, dashboard, commerce, content, deployment, jobs), action request/response handling, or action registration. Covers @stacksjs/actions and storage/framework/defaults/app/Actions/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-ai
-description: Use when integrating AI capabilities into a Stacks application — using Anthropic/OpenAI/Ollama/AWS Bedrock drivers, image generation (DALL-E), vision analysis, RAG/vector search, embeddings, MCP (Model Context Protocol) clients, text summarization, sentiment analysis, content classification, personalization, or the buddy AI assistant. Covers @stacksjs/ai and config/ai.ts.
+description: Use when integrating AI capabilities into a Stacks application - using Anthropic/OpenAI/Ollama/AWS Bedrock drivers, image generation (DALL-E), vision analysis, RAG/vector search, embeddings, MCP (Model Context Protocol) clients, text summarization, sentiment analysis, content classification, personalization, or the buddy AI assistant. Covers @stacksjs/ai and config/ai.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-alias
-description: Use when working with path aliases in a Stacks project — import resolution, module aliasing, or debugging import paths. Covers @stacksjs/alias which defines 260+ path mappings for the entire framework.
+description: Use when working with path aliases in a Stacks project - import resolution, module aliasing, or debugging import paths. Covers @stacksjs/alias which defines 260+ path mappings for the entire framework.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-analytics
-description: Use when adding analytics to a Stacks application — configuring Fathom or self-hosted analytics, generating tracking scripts, privacy-friendly analytics setup, or the analytics configuration. Covers @stacksjs/analytics and config/analytics.ts.
+description: Use when adding analytics to a Stacks application - configuring Fathom or self-hosted analytics, generating tracking scripts, privacy-friendly analytics setup, or the analytics configuration. Covers @stacksjs/analytics and config/analytics.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-api
-description: Use when building, modifying, or debugging API endpoints in a Stacks application — defining routes, handling requests, API middleware, working with the API server, HTTP client (fetcher), API resources, or OpenAPI generation. Covers both @stacksjs/api utilities and the stacks-api server implementation.
+description: Use when building, modifying, or debugging API endpoints in a Stacks application - defining routes, handling requests, API middleware, working with the API server, HTTP client (fetcher), API resources, or OpenAPI generation. Covers both @stacksjs/api utilities and the stacks-api server implementation.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-arrays
-description: Use when working with array utilities in Stacks — statistical operations (average, median, mode, standard deviation, z-score, percentile, covariance), array manipulation (unique, flatten, partition, shuffle, sample, move), containment checks, or the Arr facade. Covers @stacksjs/arrays.
+description: Use when working with array utilities in Stacks - statistical operations (average, median, mode, standard deviation, z-score, percentile, covariance), array manipulation (unique, flatten, partition, shuffle, sample, move), containment checks, or the Arr facade. Covers @stacksjs/arrays.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-auto-imports/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: stacks-auto-imports
-description: Use when working with the Stacks auto-import system — understanding how browser and server auto-imports work, configuring auto-imported functions/models/composables, the auto-import manifests, type generation, or how globals are injected. Covers the auto-import pipeline at storage/framework/auto-imports/.
+description: Use when working with the Stacks auto-import system - understanding how browser and server auto-imports work, configuring auto-imported functions/models/composables, the auto-import manifests, type generation, or how globals are injected. Covers the auto-import pipeline at storage/framework/auto-imports/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-browse
-description: Use for headless browser QA on Stacks applications — navigation, screenshots, responsive testing, console/network monitoring, and accessibility snapshots. Dependency-free: drives a system browser over the Chrome DevTools Protocol using only Bun (no Playwright/Puppeteer). Invoke with /stacks-browse.
+description: Use for headless browser QA on Stacks applications - navigation, screenshots, responsive testing, console/network monitoring, and accessibility snapshots. Dependency-free, driving a system browser over the Chrome DevTools Protocol using only Bun (no Playwright/Puppeteer). Invoke with /stacks-browse.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, a Chromium-family browser on the machine
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-browser
-description: Use when working with browser/frontend functionality in Stacks — the useAuth composable (login, register, logout, token management), Stripe billing utilities (loadCardElement, confirmPayment), the API fetch client, browser model loading, or auto-imported browser utilities. Covers @stacksjs/browser.
+description: Use when working with browser/frontend functionality in Stacks - the useAuth composable (login, register, logout, token management), Stripe billing utilities (loadCardElement, confirmPayment), the API fetch client, browser model loading, or auto-imported browser utilities. Covers @stacksjs/browser.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-buddy
-description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) — understanding all 50+ commands with their flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
+description: Use when working with the Stacks CLI (buddy/bud/stacks/stx) - understanding all 50+ commands with their flags and options, adding custom commands, the make:* scaffolding commands, development server commands, build commands, deployment commands, email/mail commands, environment management, or domain/DNS commands. Covers @stacksjs/buddy and all CLI command files.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-build
-description: Use when working with the Stacks build system — building component libraries, CLI binaries, server Docker images, documentation, or the framework core. Covers @stacksjs/build, buddy build commands, build actions, and the server build pipeline.
+description: Use when working with the Stacks build system - building component libraries, CLI binaries, server Docker images, documentation, or the framework core. Covers @stacksjs/build, buddy build commands, build actions, and the server build pipeline.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob
@@ -29,7 +29,8 @@ actions/src/build/
 ├── server.ts             # Build server Docker image
 ├── core.ts               # Build all framework core packages
 ├── stacks.ts             # Orchestrate CLI + core builds
-├── component-libs.ts     # Build component libraries (Vue + Web)
+├── component-libs.ts     # Build the `components` library packages
+├── libs.ts               # Build every configured library package
 ├── docs.ts               # Build documentation
 ├── desktop.ts            # Build desktop app
 └── views.ts              # Build frontend views
@@ -40,7 +41,7 @@ actions/src/build/
 ```typescript
 type BuildOption =
   | 'components' | 'webComponents' | 'elements'
-  | 'functions' | 'docs' | 'views' | 'stacks' | 'all' | 'buddy' | 'server'
+  | 'functions' | 'libs' | 'docs' | 'views' | 'stacks' | 'all' | 'buddy' | 'server'
 
 type BuildOptions = { [key in BuildOption]: boolean } & CliOptions
 
@@ -62,7 +63,8 @@ buddy build                    # Interactive build
 buddy build components         # All component libraries
 buddy build:components         # Alias
 buddy build:web-components     # Web Components library only
-buddy build:functions          # Functions library
+buddy build:functions          # The `functions` library packages
+buddy build:libs               # Every configured library package
 buddy build:cli                # Buddy CLI binary
 buddy build:server             # Server Docker image
 buddy build:core               # All framework core packages
@@ -75,6 +77,7 @@ buddy build:views              # Frontend views
 buddy build -c    # --components
 buddy build -w    # --web-components
 buddy build -f    # --functions
+buddy build -l    # --libs
 buddy build -d    # --docs
 buddy build -b    # --buddy
 buddy build -s    # --stacks
@@ -101,6 +104,70 @@ const result = await Bun.build({
 await outro({ dir: import.meta.dir, startTime, result })
 ```
 
+## Releasing libraries out of `resources/`
+
+`resources/functions` and `resources/components` are not limited to one npm
+package each. `config/library.ts` carries a `packages` array, and each entry
+claims a slice of one of those directories by glob and becomes its own package
+with its own name, manifest, dist and version:
+
+```ts
+// config/library.ts
+packages: [
+  // A file may be claimed by more than one package.
+  { name: '@acme/fx', kind: 'functions', include: ['*.ts'], exclude: ['internal/**'] },
+  { name: '@acme/fx-dates', kind: 'functions', include: ['dates/**'] },
+  { name: '@acme/ui', kind: 'components', include: ['ui/**'], prefix: 'acme' },
+  { name: '@acme/elements', kind: 'web-components', include: ['ui/**'], prefix: 'acme' },
+]
+```
+
+The older single-package `functions` / `webComponents` keys still work: they
+normalize into the same list, so a config written before `packages` existed
+keeps building exactly one package. When `packages` is set, they are ignored.
+
+| Kind | Built by | Published entry |
+|---|---|---|
+| `functions` | sources staged into the package's `src/`, then `transpilePackage` | `dist/index.js`, one module per source |
+| `components` | stx `buildComponentLibrary` | `dist/index.js`, tree-shakeable per-component modules |
+| `web-components` | the same compile | `dist/bundle.js`, one self-registering script |
+
+```bash
+buddy libs                 # what each package resolved to, on disk
+buddy libs --json          # the same, machine-readable
+buddy build:libs           # build them all (also `buddy build --libs`)
+buddy build:functions      # just the `functions` packages
+buddy build:components     # just the `components` packages
+buddy build:web-components # just the `web-components` packages
+buddy libs:publish --dry-run
+buddy libs:publish         # after a build; refuses a package with no dist
+```
+
+Packages build in `storage/framework/libs/packages/<dir>/`, where `<dir>` is
+the unscoped npm name unless the entry sets `dir`. The whole directory is
+generated and gitignored.
+
+### Things that will stop a build, on purpose
+
+- **A package that matches no files.** Nearly always a typo'd glob, and the
+  alternative is publishing an empty tarball. The release path skips unmatched
+  packages instead, so an app that never filled in `resources/` is not blocked.
+- **Two packages that resolve to the same directory** (`@acme/ui` and
+  `@other/ui` both unscope to `ui`). Give one an explicit `dir`.
+- **stx ambient globals in a `functions` package.** `state`, `useDark` and the
+  rest are injected into an stx page entry and exported by nothing, so a
+  bundled copy compiles and then throws `ReferenceError` on the consumer's
+  first call. Either import the names explicitly, or set `runtime: 'stx'` on
+  the package to declare that it is only ever consumed from inside an stx app.
+
+### Release flow
+
+`buddy release` runs `generate/lib-entries`, which stages sources and writes
+each manifest without compiling — so a broken library config fails before a tag
+exists rather than after. Versions follow the project version unless a package
+pins its own, which is why the build (not the generate) is what CI runs after
+the bump, and `buddy libs:publish` after that.
+
 ## Build Utilities (index.ts)
 
 ```typescript
@@ -157,7 +224,14 @@ enum Action {
 - **Server build mutates import paths** — stage 5 rewrites references in compiled output
 - **Core build is sequential** — packages built one at a time, failures collected and reported
 - **Docker build requires cloud config** — only builds if cloud deployment is enabled
-- **Component libraries use Vite** — unlike the rest which uses Bun.build
+- **Component libraries compile through stx**, not Vite. `buildComponentLibrary`
+  emits its own index and each generated component registers its custom element
+  on import, which is why a `web-components` package needs no entry file of its
+  own — it publishes `bundle.js` instead of `index.js`.
+- **A library barrel is generated with `.ts` specifiers on purpose.**
+  `transpilePackage` rewrites relative `.ts` to `.js` on the way into `dist`. An
+  extensionless specifier survives as-is and only resolves under Bun, so the
+  package installs cleanly and fails on first import from Node or Vite.
 - **`build:stacks` builds CLI first** — Buddy binary compiled before core packages
 - **Server build cleans aggressively** — deletes app, config, dist, docs, storage before rebuild
 - **The build package has @babel deps** — uses Babel for AST traversal during export cleanup

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-cache
-description: Use when implementing caching in Stacks — memory cache, Redis cache, cache-aside pattern (getOrSet), TTL management, cache stats, or cache configuration. Covers @stacksjs/cache and config/cache.ts.
+description: Use when implementing caching in Stacks - memory cache, Redis cache, cache-aside pattern (getOrSet), TTL management, cache stats, or cache configuration. Covers @stacksjs/cache and config/cache.ts.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-calendar
-description: Use when working with calendar functionality in Stacks — exporting events to Google Calendar, Outlook, Yahoo, or ICS format, the CalendarLink interface for event definitions, timezone handling, all-day events, or calendar URL generation. Covers @stacksjs/calendar-api.
+description: Use when working with calendar functionality in Stacks - exporting events to Google Calendar, Outlook, Yahoo, or ICS format, the CalendarLink interface for event definitions, timezone handling, all-day events, or calendar URL generation. Covers @stacksjs/calendar-api.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-chat
-description: Use when implementing chat messaging in Stacks — sending messages to Slack (webhooks, bot tokens, block kit), Discord (webhooks, bot tokens, embeds), Microsoft Teams (adaptive cards, webhooks), the BaseChatDriver abstraction, retry logic, or multi-channel chat routing. Covers @stacksjs/chat.
+description: Use when implementing chat messaging in Stacks - sending messages to Slack (webhooks, bot tokens, block kit), Discord (webhooks, bot tokens, embeds), Microsoft Teams (adaptive cards, webhooks), the BaseChatDriver abstraction, retry logic, or multi-channel chat routing. Covers @stacksjs/chat.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-cli
-description: Use when building CLI commands or tools with Stacks — the @stacksjs/cli package for creating commands with argument parsing, option handling, colored output, tables, progress indicators, prompts, or integrating with the buddy command system. Covers @stacksjs/cli and app/Commands/.
+description: Use when building CLI commands or tools with Stacks - the @stacksjs/cli package for creating commands with argument parsing, option handling, colored output, tables, progress indicators, prompts, or integrating with the buddy command system. Covers @stacksjs/cli and app/Commands/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-cloud
-description: Use when deploying or managing cloud infrastructure for Stacks — AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/.
+description: Use when deploying or managing cloud infrastructure for Stacks - AWS deployment via CloudFormation/CDK, server mode (EC2, ALB, VPC), serverless mode (Lambda, API Gateway, CloudFront), jump boxes, domain management (Route53), S3 storage, SES email, edge computing, security groups, IAM, or the cloud configuration. Covers @stacksjs/cloud, @stacksjs/deploy, storage/framework/cloud/, and cloud/.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript, AWS
 allowed-tools: Read Edit Write Bash Grep Glob

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

@@ -1,6 +1,6 @@
 ---
 name: stacks-cms
-description: Use when working with the CMS in a Stacks application — posts, authors, pages, categories, tags, comments, blog configuration, RSS feeds, or sitemaps. Covers @stacksjs/cms, CMS models, routes, and actions.
+description: Use when working with the CMS in a Stacks application - posts, authors, pages, categories, tags, comments, blog configuration, RSS feeds, or sitemaps. Covers @stacksjs/cms, CMS models, routes, and actions.
 license: MIT
 compatibility: Bun >= 1.3.0, TypeScript
 allowed-tools: Read Edit Write Bash Grep Glob

package/ai/skills/stacks-codebase-design/DEEPENING.md

@@ -0,0 +1,79 @@
+# Deepening
+
+How to deepen a cluster of shallow modules safely, given its dependencies.
+Assumes the vocabulary in [SKILL.md](SKILL.md): **module**, **interface**,
+**seam**, **adapter**.
+
+## Dependency categories
+
+When assessing a candidate for deepening, classify its dependencies. The
+category decides how the deepened module is tested across its seam.
+
+### 1. In-process
+
+Pure computation, in-memory state, no I/O. In Stacks: `@stacksjs/strings`,
+`@stacksjs/arrays`, `@stacksjs/collections`, `@stacksjs/datetime`, validation
+rules, most of what lives in `resources/functions/`. Always deepenable. Merge the
+modules and test through the new interface directly. No adapter needed.
+
+### 2. Local-substitutable
+
+Dependencies with a local test stand-in. In Stacks this is the common case and
+the framework already provides the stand-ins:
+
+- The database. `setupDatabase()` / `refreshDatabase()` from `@stacksjs/testing`
+  give you a real SQLite instance at `database/stacks_testing.sqlite`.
+- The cache. The `memory` driver stands in for `redis`.
+- The queue. `fake()` / `restore()` from `@stacksjs/queue` stand in for a real
+  worker.
+- Storage. The local driver stands in for S3.
+
+Deepenable whenever the stand-in exists. The deepened module is tested with the
+stand-in running in the suite. The seam is internal, and no port appears at the
+module's external interface.
+
+### 3. Remote but owned (ports and adapters)
+
+Your own services across a network boundary. In Stacks this is the API server
+and its typed client, a Lambda in serverless mode, or a second tenant on the same
+box. Define a **port** at the seam. The deep module owns the logic, the transport
+is injected as an **adapter**. Tests use an in-memory adapter, production uses
+the HTTP one.
+
+Recommendation shape: *"Define a port at the seam, implement an HTTP adapter for
+production and an in-memory adapter for testing, so the logic sits in one deep
+module even though it is deployed across a network."*
+
+### 4. True external (mock)
+
+Third-party services you do not control: Stripe, SES, Twilio, Meilisearch,
+Algolia, Anthropic, OpenAI, Route53, Hetzner. The deepened module takes the
+external dependency as an injected port, and tests provide a mock adapter. This
+is what the driver packages already do: `BaseChatDriver`, the email drivers, the
+AI drivers. When you add a fifth external service, add a driver rather than a
+call site.
+
+## Seam discipline
+
+- **One adapter means a hypothetical seam. Two adapters means a real one.** Do
+  not introduce a port unless at least two adapters are justified, typically
+  production plus test. A single-adapter seam is just indirection.
+- **Internal seams versus external seams.** A deep module can have internal
+  seams, private to its implementation and used by its own tests, as well as the
+  external seam at its interface. Do not expose internal seams through the
+  interface just because tests use them.
+- **Do not put a seam where the framework already gives you one.** The `app/`
+  override model, the driver config in `config/*.ts`, and the model traits are
+  existing seams. A hand-rolled indirection beside one of them is a second way to
+  do the same thing.
+
+## Testing strategy: replace, do not layer
+
+- Old unit tests on the shallow modules become waste once tests at the deepened
+  module's interface exist. Delete them.
+- Write the new tests at the deepened module's interface. The **interface is the
+  test surface**.
+- Assert on observable outcomes through the interface, not internal state.
+- Tests should survive internal refactors because they describe behaviour. If a
+  test has to change when the implementation changes, it is testing past the
+  interface.

package/ai/skills/stacks-codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,72 @@
+# Design it twice
+
+When you want to explore alternative interfaces for a chosen deepening
+candidate, use this parallel sub-agent pattern. Based on "Design It Twice"
+(Ousterhout): your first idea is unlikely to be the best.
+
+Uses the vocabulary in [SKILL.md](SKILL.md): **module**, **interface**, **seam**,
+**adapter**, **leverage**.
+
+## Process
+
+### 1. Frame the problem space
+
+Before spawning sub-agents, write a user-facing explanation of the problem space
+for the chosen candidate:
+
+- The constraints any new interface would need to satisfy.
+- The dependencies it relies on, and which category they fall into (see
+  [DEEPENING.md](DEEPENING.md)).
+- A rough illustrative code sketch to make the constraints concrete. Not a
+  proposal.
+
+Show this to the user, then proceed to step 2 immediately. The user reads and
+thinks while the sub-agents work.
+
+### 2. Spawn sub-agents
+
+Spawn three or more sub-agents in parallel. Each must produce a **radically
+different** interface for the deepened module.
+
+Prompt each with a separate technical brief: file paths, coupling details, the
+dependency category, what sits behind the seam. The brief is independent of the
+user-facing explanation in step 1. Give each agent a different design constraint:
+
+- Agent 1: minimise the interface. One to three entry points, maximum leverage
+  per entry point.
+- Agent 2: maximise flexibility. Support many use cases and extension.
+- Agent 3: optimise for the most common caller. Make the default case trivial.
+- Agent 4, where it applies: design around ports and adapters for the cross-seam
+  dependencies.
+
+Include both this skill's vocabulary and the project's `CONTEXT.md` vocabulary in
+each brief, so the agents name things consistently with the architecture language
+and the domain language at once.
+
+Each sub-agent outputs:
+
+1. The interface: types, entry points, params, plus invariants, ordering and
+   error modes.
+2. A usage example showing how callers use it.
+3. What the implementation hides behind the seam.
+4. Dependency strategy and adapters.
+5. Trade-offs: where leverage is high, where it is thin.
+
+### 3. Present and compare
+
+Present the designs one at a time so the user can absorb each, then compare them
+in prose. Contrast by **depth** (leverage at the interface), **locality** (where
+change concentrates) and **seam placement**.
+
+Finish with your own recommendation: which design is strongest and why. If
+elements from different designs combine well, propose the hybrid. Be opinionated.
+The user wants a strong read, not a menu.
+
+## In a Stacks project
+
+Two constraints narrow the design space before you start, so state them in every
+brief:
+
+- A capability that varies per environment belongs behind a driver in
+  `config/*.ts`, not behind a hand-rolled abstraction.
+- A capability that varies per model belongs in a trait, not in a base class.