@stacksjs/defaults 0.75.109 → 0.75.111

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

@@ -8,283 +8,102 @@ allowed-tools: Read Edit Write Bash Grep Glob
 
 # Stacks Events
 
-Tiny (~200b) functional event emitter based on mitt, with Stacks-specific model events and action-based listener resolution.
+Use the native event bus for process-local application and model events. Use
+`stacks-realtime` for network broadcasting and `stacks-queue` for durable work.
 
-## Key Paths
-- Core package: `storage/framework/core/events/src/index.ts` (single file -- entire implementation)
-- Application events: `app/Events.ts`
-- Listener setup: `app/Listener.ts`
-- Listeners: `app/Listeners/`
-- Event types: `storage/framework/types/events.ts`
+## Dispatch and completion
 
-## Core mitt Implementation (index.ts)
+`@stacksjs/events` exports `dispatch`, `dispatchAsync`,
+`dispatchAndCollect`, `listen`, `once`, `off` and `emitter`.
 
-The entire event system is a single `mitt()` factory function that returns an `Emitter<Events>` object:
+- `dispatch(name, payload)` invokes handlers immediately and returns void.
+  Async handlers continue without blocking the caller; errors are logged.
+- `await dispatchAsync(name, payload)` awaits matching handlers in sequence.
+  Rejections are logged and appear as undefined results, so this does not prove
+  that every handler succeeded.
+- `await dispatchAndCollect(name, payload)` returns a result for each handler:
+  `{ ok: true, value }` or `{ ok: false, error }`. Inspect failures when
+  downstream work determines the response.
 
-```typescript
-export default function mitt<Events>(all?: EventHandlerMap<Events>): Emitter<Events>
-```
+Payloadless events are supported by the emitter. Exact handlers receive the
+payload; wildcard and glob handlers receive `(eventName, payload)`.
 
-### Emitter Interface
-```typescript
-interface Emitter<Events> {
-  all: EventHandlerMap<Events>  // Map<keyof Events | '*', Handler[]>
+`emitter.on(name, handler, { priority })` sorts higher priorities first
+within each handler bucket. Equal priority preserves registration order.
+Exact handlers run before glob buckets, then `*` handlers. Snapshotting keeps
+subscription changes during a dispatch from corrupting iteration.
 
-  on<Key>(type: Key, handler: Handler<Events[Key]>): void
-  on(type: '*', handler: WildcardHandler<Events>): void
+## Typed application events
 
-  off<Key>(type: Key, handler?: Handler<Events[Key]>): void
-  off(type: '*', handler?: WildcardHandler<Events>): void
+`StacksEvents` combines built-in auth events and the augmentable
+`AppEvents` interface. Declare an application event before dispatching it:
 
-  emit<Key>(type: Key, event?: Events[Key]): void
-}
-```
-
-### How emit() Works
-1. Gets handlers array from `all.get(type)` -- calls each with `handler(event)`
-2. Gets wildcard handlers from `all.get('*')` -- calls each with `handler(type, event)`
-3. Handlers are called via `.slice()` copy to avoid mutation during iteration
-4. Each handler is wrapped in try-catch with `console.error` logging
-5. Error in one handler does NOT prevent other handlers from executing
-6. Both type-matched AND wildcard handlers run (wildcards run second)
-7. If `event` is `undefined`, handlers are NOT called
-
-### on() / off() Behavior
-- `on(type, handler)`: pushes to handlers array (creates array if first handler)
-- `off(type, handler)`: splices handler from array by index
-- `off(type)` (no handler): replaces handlers array with empty `[]`
-- Handler maps use `Map<string, Array<Handler>>` internally
-
-## Stacks Event System Exports
-
-The package creates a single `mitt<StacksEvents>()` instance and exports multiple aliases:
-
-```typescript
-import { dispatch, listen, off, emitter, events, useEvent, useListen, useEvents, all } from '@stacksjs/events'
-
-// Dispatch an event
-dispatch('user:registered', { id: 1, email: 'user@example.com' })
-
-// Listen for an event
-listen('user:registered', (data) => {
-  console.log('New user:', data.email)
-})
-
-// Wildcard listener (catches ALL events)
-listen('*', (type, data) => {
-  console.log(`Event ${type}:`, data)
-})
-
-// Remove a specific listener
-off('user:registered', handler)
-
-// Direct emitter access
-emitter.on('event', handler)
-emitter.off('event', handler)
-emitter.emit('event', data)
-emitter.all  // Map of all handlers
-```
-
-### Export Aliases
-| Export | Maps To |
-|--------|---------|
-| `dispatch` | `emitter.emit` |
-| `useEvent` | `emitter.emit` (alias for `dispatch`) |
-| `listen` | `emitter.on` |
-| `useListen` | `emitter.on` (alias for `listen`) |
-| `off` | `emitter.off` |
-| `emitter` | the mitt instance |
-| `events` | the mitt instance (alias for `emitter`) |
-| `useEvents` | the mitt instance (alias for `emitter`) |
-| `all` | `emitter.all` (the handler Map) |
-| `mitt` | the factory function itself |
-
-### Type Aliases
-```typescript
-type Dispatch = <Key extends keyof StacksEvents>(type: Key, event: StacksEvents[Key]) => void
-type Listen = <Key extends keyof StacksEvents>(type: Key, handler: Handler<StacksEvents[Key]>) => void
-type Off = <Key extends keyof StacksEvents>(type: Key, handler?: Handler<StacksEvents[Key]>) => void
-```
-
-## Built-in Event Types (StacksEvents)
+~~~ts
+import { dispatch, listen } from '@stacksjs/events'
 
-```typescript
-// @stacksjs/events
-interface AuthEvents {
-  'user:registered': UserRegisteredEvent
-  'user:logged-in': UserLoggedInEvent
-  'user:logged-out': UserLoggedOutEvent
-  'user:password-reset': UserPasswordEvent
-  'user:password-changed': UserPasswordEvent
-}
-
-// Augmentation target - model events land here, and so do yours.
-interface AppEvents {}
-
-type StacksEvents = AppEvents & AuthEvents
-type EventName = keyof StacksEvents & string
-```
-
-There is **no** trailing index signature, deliberately: an arbitrary event name is
-what made `dispatch('user:creatd', …)` compile and reach nobody. Declare an
-application's own events on `AppEvents` and the typo becomes a compile error.
-
-```typescript
 declare module '@stacksjs/events' {
   interface AppEvents {
     'invoice:settled': { id: number, total: number }
   }
 }
-```
-
-## Model Events
-
-Every model with the `observe: true` trait emits **eight** events:
-
-| Event | When | Payload |
-|---|---|---|
-| `{model}:saving` | before any write | the model object |
-| `{model}:creating` / `:updating` / `:deleting` | before that write | the model object |
-| `{model}:created` / `:updated` / `:deleted` | after that write | the row |
-| `{model}:saved` | after insert OR update | the row |
 
-Model name is lowercased: `'user:created'`, `'post:updated'`, `'teammember:saved'`.
-
-A **before** listener can cancel the write by returning `false`:
-
-```ts
-listen('user:deleting', (model) => {
-  if (model.attributes.email.endsWith('@example.com'))
-    return false   // the delete does not happen
+listen('invoice:settled', invoice => {
+  console.log(invoice.id, invoice.total)
 })
-```
-
-Before-events carry the model object (`.attributes` holds the row); after-events
-carry the row itself.
-
-### The payloads are typed, and nothing generates them
-
-`listen('user:created', user => user.emial)` is a compile error - the payload is
-the User row, with the columns your model declares.
-
-`storage/framework/types/model-events.d.ts` derives the whole map from the models
-barrel with a mapped type:
-
-```ts
-type ModelAfterEvents = {
-  [K in keyof Models & string as `${Lowercase<K>}:${AfterEvent}`]: ModelRow<Models[K]>
-}
-```
-
-So a model existing IS its events existing - there is no generated list to keep in
-agreement, and nothing to re-run after adding a model. (It replaced an 817-line
-generated file, and before that a hand-maintained one that listed three events per
-model and typed every payload `Record<string, any>`.)
-
-Declare your own events by augmenting `AppEvents`:
-
-```ts
-declare module '@stacksjs/events' {
-  interface AppEvents {
-    'invoice:overdue': { id: number, daysLate: number }
-  }
-}
-```
-
-Events are dispatched via lazy `import('@stacksjs/events').then(({ dispatch }) => dispatch(...))` to avoid circular dependencies. If the import fails (e.g., browser context), errors are silently caught.
-
-The `observe` trait can be:
-- `true` -- emits all three events (create, update, delete)
-- `['create', 'update']` -- emits only specified events
-- `false` / undefined -- no events
-
-There is no model list to keep here. Every model in `storage/framework/auto-imports/models.ts`
-has its eight events, and that barrel is generated from disk for the runtime, so the
-answer to "which models emit events" is "the ones that exist".
-
-## Event-to-Listener Mapping (app/Events.ts)
-
-```typescript
-import { defineEvents } from '@stacksjs/events'
-
-export default defineEvents({
-  'user:registered': ['SendWelcomeEmail'],
-  'user:created': ['NotifyUser'],
-})
-```
-
-Both halves are checked. A key must be an event that exists (`EventName`, above);
-a value must name a listener that is on disk (`ListenerName`, generated into
-`storage/framework/types/actions.d.ts` from `app/Listeners/`, `app/Actions/` and
-the framework defaults behind them). `satisfies Events` is equivalent and still
-supported; `defineEvents` is preferred because it also keeps the literal types,
-so `keyof typeof events` is the two names the file declares rather than `string`.
-
-## Listener Resolution (app/Listener.ts)
-
-`handleEvents()` delegates to `registerAppListeners()`, which registers both
-conventions and is idempotent:
-
-```typescript
-import { registerAppListeners } from '@stacksjs/events'
-import { path as p } from '@stacksjs/path'
-
-export async function handleEvents(): Promise<number> {
-  return registerAppListeners({ base: p.projectPath() })
-}
-```
-
-Names in the map resolve against `app/Listeners/`, `app/Actions/`, then the same
-two directories under the framework defaults - first match wins.
-
-### Registration Flow
-1. **The map**: `registerFromMap()` imports `app/Events.ts` and, for each name,
-   resolves a module with a `handle` method out of `app/Listeners/`,
-   `app/Actions/` or the framework defaults, then subscribes it to that event
-   directly. A name that resolves to nothing is warned about by name.
-2. **The scan**: `discoverListeners()` walks `app/Listeners/` and registers any
-   default export shaped `{ listensTo, handle }`. `listensTo` may be an array.
-3. **Dedup**: every `(event, module)` pair is claimed once per process, so a
-   listener that appears in both conventions - or a dev server that re-runs
-   boot - registers once rather than twice.
-4. **Payload check**: if the resolved action declares `validations`, a dispatched
-   payload that does not match them is warned about. It is not thrown: the
-   dispatcher has already committed the thing the event announces.
-
-### Where it is called from
-- `injectGlobalAutoImports()` (`@stacksjs/server`), so every path that dispatches -
-  HTTP, `buddy seed`, a scheduled job, a console command - has listeners on the bus
-- `handleEvents()` in `app/Listener.ts`, the app's own override hook
-
-Both on the same boot in dev. The claim registry is what keeps that from being
-two of every listener.
-
-## Implementation Details
-
-### Thread Safety
-- handlers are stored in arrays -- `emit()` calls `.slice()` before iterating to safely handle additions/removals during iteration
-
-### Synchronous vs Asynchronous
-- **`emit` is synchronous**: it calls handlers directly and does not await them; an async handler's rejection is logged rather than lost
-- **`emitAsync` / `dispatchAsync` awaits** every matching handler and resolves with their results
-- **Registration is asynchronous**: resolving a listener name imports a module
-
-### Memory
-- The emitter is one per *process*, keyed on `Symbol.for('stacks.events.emitter')` rather than per copy of the package -- two installed copies would otherwise be two separate buses, and a dispatch into the wrong one looks exactly like a dispatch nobody listened for
-- Resolved listener modules are held by the closures registered on the emitter, so adding an action requires a restart
-
-## Gotchas
-- Events are functional, not class-based -- no need to create event classes
-- The emitter is a **singleton** -- shared across the entire application process
-- Wildcard `'*'` listeners receive `(type, event)` -- regular handlers receive just `(event)`
-- Listeners in `app/Events.ts` are **names** (strings), not file paths or handler functions -- resolved against `app/Listeners/`, `app/Actions/`, then the framework defaults
-- The listener module must export a default with a `handle(event)` method
-- Event dispatch is **synchronous** but listener resolution (dynamic import) happens once, at boot
-- Model events only fire when the model has `observe: true` (or array) trait set
-- The event system is ~200 bytes total -- it is intentionally minimal
-- Listeners are resolved once at boot, so adding an action requires a server restart
-- If `evt` is `undefined`, handlers are NOT called (`emit` checks `if (evt !== undefined)`)
-- The `'*'` event type cannot be manually emitted -- it only receives forwarded events
-- `off(type)` without a handler argument clears ALL handlers for that type (sets to empty array, not delete)
-- `StacksEvents` has **no** index signature: an undeclared event name is a compile error, not a dispatch into the void. Declare your own on `AppEvents`
-- Error logging in mitt uses `console.error` (not `@stacksjs/logging`) to avoid circular dependencies
+dispatch('invoice:settled', { id: 1, total: 1200 })
+~~~
+
+Built-in auth names include `user:registered`, `user:logged-in`,
+`user:logged-out`, `user:password-reset` and `user:password-changed`.
+Read their payload types from `core/events/src/index.ts` rather than guessing.
+
+## Application listeners
+
+`app/Events.ts` default-exports `defineEvents({ event: [listenerName] })`.
+Names resolve against application listeners, application actions, then framework
+defaults. A standalone module in `app/Listeners/` may instead default-export
+`defineListener({ listensTo, handle })`. Its handler is `(payload, eventName)`,
+including for a glob subscription, because the discovery layer adapts the bus.
+
+`registerAppListeners()` loads both conventions at boot and deduplicates each
+event/module pair. `injectGlobalAutoImports()` calls it for HTTP, CLI, scheduler
+and seeding entrypoints. `app/Listener.ts` may call the same registration hook.
+Adding a listener requires a process restart. See `stacks-listeners` for files.
+
+## Model lifecycle
+
+`traits.observe` opts a model into lifecycle events. Before events are
+`saving`, `creating`, `updating` and `deleting`; after events are
+`created`, `updated`, `deleted` and `saved`. Names lowercase the model
+name, for example `teammember:saved`.
+
+Before handlers receive the model object, with its row under `.attributes`;
+returning exactly false cancels the write. After handlers receive the row.
+The ORM awaits the before-event result; that is separate from ordinary
+fire-and-forget application dispatch. See `stacks-models` and `stacks-orm`
+for which writes emit hooks, bulk operations and transaction boundaries.
+Model event types derive from the models barrel in
+`storage/framework/types/model-events.d.ts`.
+
+## Isolation and cleanup
+
+`createEmitter<EventMap>()` creates an isolated emitter; the compatibility
+`mitt`/default export is its alias. The application singleton uses a global
+symbol so duplicate installed copies share the same bus in one process.
+It is not cross-process messaging.
+
+`once` removes its listener after the first invocation. `off(name, handler)`
+removes by identity; `off(name)` clears that bucket.
+`emitter.removeAllListeners(name?)` removes a bucket or all listeners;
+`listenerCount(name)` counts only the exact bucket, not matching patterns.
+`scopedEvents(prefix)` and `scope(emitter, prefix)` provide prefixed names
+without creating another bus. Read their prefix composition in the source
+before combining them with an application's named events.
+
+## Source and verification
+
+- Public API and async behavior: `storage/framework/core/events/src/index.ts`.
+- Discovery and typed listener adapters: `core/events/src/discover.ts`.
+- Retained tests: `native-emitter.test.ts`, `priority-and-collect.test.ts`,
+  `scope.test.ts`, `register.test.ts`, `shared-emitter.test.ts` under
+  `storage/framework/core/events/tests/`.

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

@@ -119,13 +119,16 @@ faker.word.adjective() / .noun()
 Model attributes declare a `factory` function receiving `faker`:
 
 ```typescript
-{
+import { schema } from '@stacksjs/validation'
+
+// Attribute entries inside defineModel({ attributes: ... })
+const attributes = {
   name: {
-    validator: { rule: 'string', min: 3, max: 255 },
+    validation: { rule: schema.string().min(3).max(255) },
     factory: faker => faker.company.name(),
   },
   status: {
-    validator: { rule: 'enum', options: ['active', 'inactive'] },
+    validation: { rule: schema.enum(['active', 'inactive']) },
     factory: faker => faker.helpers.arrayElement(['active', 'inactive']),
   },
 }
@@ -133,14 +136,17 @@ Model attributes declare a `factory` function receiving `faker`:
 
 ### How Seeding Works
 1. Model needs `traits: { useSeeder: { count: N } }`
-2. `generateRecord()` calls `attr.factory(faker)` for each attribute
+2. `generateRecord()` calls `attr.factory(faker, generated)` for each attribute;
+   generated contains earlier declared attributes before password hashing
 3. Falls back to `attr.default` if factory fails
 4. Converts camelCase → snake_case for DB columns
 5. Auto-hashes password fields (bcrypt)
 6. Inserts in batches of 100
-7. Order: User (0), Team (1), Project (2), everything else (10)
+7. Model dependencies determine seeding order, so included parent models seed
+   before their dependents. Application Seeder classes additionally use static
+   order and tags; read `stacks-database` for that separate pass.
 
-### Smart Default Inference (no factory defined)
+### Smart Default Inference (when a factory throws and has no explicit default)
 - `is*`, `has*`, `*able` → `false`
 - `*count`, `*amount`, `*quantity` → `0`
 - `*url`, `*link` → `'https://example.com'`
@@ -148,11 +154,20 @@ Model attributes declare a `factory` function receiving `faker`:
 - `*name` → `faker.person.fullName()`
 - Unknown → `null`
 
+An attribute with neither factory nor default is skipped, not filled by this
+inference. App models override framework models even when opting out of model
+seeding. Auth/account models are protected from routine seeding; review the
+actual protected-model and includeDefaults/fresh/allowProtected behavior before
+choosing a destructive development reset. Seed records are fixture data, not
+random values suitable for real credentials or financial claims.
+
 ## Gotchas
-- **Not @faker-js/faker** — wrapper around `ts-mocker`. Most APIs compatible but not all
-- **Custom modules override base** — lorem, datatype, location, company, vehicle, helpers are custom
-- **Vehicle module is fully custom** — hardcoded manufacturer/model lists, not from ts-mocker
-- **Factory receives faker** — signature is `(faker: Faker) => value`, not `() => value`
-- **Password detection is heuristic** — by name pattern or `hidden: true` attribute
-- **Seeder batch size is 100** — records inserted in chunks
-- **Model seeding order matters** — User first, then Team, Project, everything else
+- **Not @faker-js/faker** - wrapper around `ts-mocker`. Most APIs compatible but not all
+- **Custom modules override base** - lorem, datatype, location, company, vehicle, helpers are custom
+- **Vehicle module is fully custom** - hardcoded manufacturer/model lists, not from ts-mocker
+- **Factory receives context** - `(faker, generated) => value` can use fields
+  declared earlier in the same model; do not depend on fields declared later.
+- **Password detection is heuristic** - by password-like names, or a hidden
+  attribute whose name also includes pass; hidden alone does not hash a field.
+- **Seeder batch size is 100** - records inserted in chunks
+- **Model seeding order matters** - the dependency graph drives parent ordering.

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

@@ -0,0 +1,41 @@
+---
+name: stacks-feature-flags
+description: Use when implementing per-user or per-team feature rollouts, persisted flag values, percentage experiments, or weighted variants. Covers @stacksjs/feature-flags and config/feature-flags.ts.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Scoped feature flags
+
+This package manages user-targeted runtime values. Framework bundle enablement
+through the named `feature()` export from `@stacksjs/config` is a different
+surface; read stacks-features.
+
+## Define, scope, and evaluate
+
+Import Feature or createFeatureFlags from @stacksjs/feature-flags. Definitions
+can be fixed values or resolvers. Feature.for(scope) returns a scoped facade
+with async value/values/all, active/inactive, activate/deactivate/forget and
+when/unless. Await evaluations and writes; they are not synchronous booleans.
+
+percentage(percent) and variants(weights) deterministically bucket a flag name
+and scope key. Keep scope identities stable to preserve cohort assignment.
+The manager supports explicit missing-flag behavior and evaluation listeners.
+Changing a definition is not the same as forgetting already-persisted values.
+
+## Drivers and boundaries
+
+The global Feature facade resolves configured memory or database storage lazily.
+Memory state is process-local. The SQL driver supports the dialects checked by
+configuredDriver, and failures raise FeatureFlagStoreError rather than silently
+switching a production experiment to memory. Inspect the actual config and
+store schema before rollout. Persisted value types are validated by the package.
+
+Do not send private cohort inputs to the browser or use a feature flag as the
+only authorization check. Test stable scope keys, variant assignment, missing
+definitions, persistence, concurrent evaluation and explicit value overrides.
+
+Source: core/feature-flags/src/{index,manager,scope,strategies,schema,value}.ts
+and drivers/. Retained evidence: manager, global, scope, strategies and both
+driver test suites.

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

@@ -0,0 +1,46 @@
+---
+name: stacks-features
+description: Use when installing or disabling optional Stacks bundles, understanding model/migration/view gates, or choosing default route bundles. Covers @stacksjs/features and @stacksjs/config feature controls.
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Optional framework bundles
+
+The installable bundles are declared by FEATURE_NAMES in @stacksjs/features/names.
+They include dashboard, commerce, cms, forms, marketing, monitoring, realtime
+and queue. FEATURE_FILES and FEATURE_TABLES own scaffold and migration selection.
+
+## Installation and gates
+
+Use buddy <feature>:install or the corresponding uninstall command after
+checking its current help. Installation publishes the feature's app scaffold;
+config/<feature>.ts enabled controls the feature. There is no required central
+config/features.ts manifest. Preserve application-owned overrides during changes.
+
+feature(name), enableFeature, disableFeature, resetFeature and listFeatures from
+@stacksjs/config read config and runtime overrides. With no config section,
+only dashboard defaults on. A present config object without an enabled field
+counts as enabled, and its optional env gate can restrict environments.
+Runtime overrides are process-local, not a persisted rollout system.
+
+Auth and email also have config gates but are not installable bundle names.
+Auth model loading does not by itself mount every default auth endpoint.
+STACKS_DEFAULT_ROUTES explicitly selects route bundles; an explicit selection
+has different precedence from default feature-driven selection. Read stacks-routes.
+
+## Schema and discovery
+
+The migration corpus excludes disabled bundle tables while protecting app-owned
+models. Turning off a feature is not permission to drop its production data.
+Package discovery can add resource roots; components require explicit opt-in
+because bare component tags are process-wide.
+
+STACKS_CANONICAL_FEATURES is an artifact-generation mode, not a production
+configuration shortcut. Use stacks-feature-flags for scoped experiments.
+Test the enabled app surface, route selection, preserved overrides and no-op
+reinstallation rather than checking only a package's presence.
+
+Source: core/features/src/{names,index}.ts, core/config/src/features.ts,
+core/router/src/route-loader.ts and buddy feature lifecycle tests.

package/ai/skills/stacks-flow/ENGINEERING.md

@@ -0,0 +1,84 @@
+# Stacks adaptation of the engineering workflows
+
+This shared reference applies to the Matt Pocock ports listed in
+[upstream-skills.json](upstream-skills.json). Read it with the selected skill.
+Stacks conventions and explicit user instructions govern the adapted playbooks.
+
+## Context, skills, and tracking
+
+Read `AGENTS.md`, the relevant Stacks package skill, existing specs, and ADRs.
+Use the existing domain source: `CONTEXT.md`, or `GLOSSARY.md` when that is the
+project's established glossary. Follow an existing context map in a multi-context
+repository. Keep glossary terms separate from implementation decisions and
+create domain files only when a resolved term or decision needs recording.
+
+The translated skill names are the entrypoints. Read a skill before relying on
+its summary or skipping a step. A Skill tool is optional: reading `SKILL.md`
+and its relevant references provides the same instructions.
+
+Read `docs/agents/issue-tracker.md` and `docs/agents/triage-labels.md` when present.
+If no tracker convention exists, use local specs and one Markdown file per
+ticket under `.scratch/<feature>/issues/`. Configure a remote tracker only when
+requested. Spec synthesis, ticket drafting, and local planning can proceed
+without an account or a setup ceremony.
+
+Existing authorization and resolved decisions carry forward. Confirm an
+uncertain seam, destination, or consequential choice when necessary; do not
+re-ask settled preferences or impose a permission prompt for each reversible
+step. A planning interview resolves human decisions, not facts the agent can read.
+
+## Implementation and verification
+
+Use TypeScript and Bun. Application files override framework defaults. Read the
+subsystem skill before calling Stacks APIs. Build features in the model,
+generated migration, action, route, and test order, one tracer bullet at a time.
+A spec or ticket names observable acceptance criteria and genuine blockers.
+
+Use `./buddy lint` through pickier, never an extra linter or formatter. Use
+`./buddy typecheck` for application code and `bun run typecheck` for framework
+internals. Run focused Bun tests during the loop and the appropriate buddy
+test suite before finishing. Preserve the user-defined test seams and exercise
+real behavior through public interfaces.
+
+UI uses stx and Crosswind, signals and composables, and Iconify classes. Read
+the design skill before visually important work. Reports may use standalone
+HTML with local CSS; do not introduce Tailwind or React into the application.
+Copied example commands for other package managers are conceptual; use Bun and
+the repository's actual scripts. Do not duplicate better-dx tooling.
+
+## Parallel work and long-running tasks
+
+Use subagents when the invoked workflow asks for parallel work and the harness
+supports it. Otherwise work sequentially through the same dependency frontier.
+Treat user decisions as human-in-the-loop work; a subagent cannot answer them
+for the user. Give workers context pointers, a concrete scope, acceptance
+criteria, and a disjoint edit surface. Preserve existing user edits.
+
+For an implementation graph, integrate completed work before unblocking
+dependent tickets. Validate the combined result and distinguish completed,
+blocked, and unstarted work. Do not silently reset a worktree with changes.
+Archive only task-owned temporary worktrees after preserving needed work.
+
+Research files are cited primary-source evidence. Background orchestration is
+optional, not a precondition for answering a research question. Do not create
+recurring schedules or a long-running goal merely because an upstream playbook
+mentions them; use native tools when the user requests that behavior.
+
+## Git and external actions
+
+Only commit or push when asked. Use conventional commits and branch off the
+default branch before a requested commit. An upstream "commit", "push", or
+"publish" step is conditional on the user's authorization. Never close or
+alter tracker issues, post comments, or send a questionnaire merely because
+the draft is complete. Perform the requested external action when authorized;
+otherwise return its concrete draft.
+
+Attach any created or actively reviewed PR using the harness's artifact tool
+when available. Preserve authored `AGENTS.md`; generated agent files are
+per-developer. Setup guidance edits the canonical guidance, not an independent
+copy of a symlinked `CLAUDE.md`.
+
+Generate user-visible copy with regular hyphens and ordinary punctuation.
+Keep quotes, secrets, executable code, and source evidence accurate. Redact
+secrets from reports and handoffs. Completion is the requested behavior or
+reviewable artifact with its relevant checks, not an unsolicited deployment.

package/ai/skills/stacks-flow/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Pocock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ai/skills/stacks-flow/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## ask-matt
+
+Source: [skills/engineering/ask-matt/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/ask-matt/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Reviewed against the existing Stacks workflow. Stacks API guidance is retained; current workflow changes and supporting references are integrated where applicable.