@stacksjs/defaults 0.75.109 → 0.75.111

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

@@ -20,7 +20,7 @@ allowed-tools: Read Edit Write Bash Grep Glob
 ```
 core/server/src/
 ├── index.ts               # Re-exports: config, controllers/base, imports, maintenance
-├── config.ts              # config() factory — maps ServerOptions.type to host/port
+├── config.ts              # config() factory - maps ServerOptions.type to host/port
 ├── config-production.ts   # Minimal env-based config for compiled production binaries
 ├── imports.ts             # Auto-import system: scan models/jobs/controllers, register bun plugin
 ├── maintenance.ts         # Laravel-like maintenance mode (down/up/bypass)
@@ -29,78 +29,36 @@ core/server/src/
 
 server/
 ├── src/
-│   ├── index.ts           # Bun.serve() entry point — HTTP + WebSocket + job worker
+│   ├── index.ts           # Bun.serve() HTTP entry and one-shot queue worker
 │   └── utils.ts           # Docker build helpers (cleanCopy, buildDockerImage, useCustomOrDefaultServerConfig)
 ├── build.ts               # Full build pipeline: bundle server + app, post-process, optionally build Docker
 ├── dev                    # Shell script for local/remote Docker dev (mounts volumes)
 ├── Dockerfile             # Multi-stage Bun Docker image (oven/bun:1.3.10)
-├── package.json           # stacks-server v0.70.23
+├── package.json           # stacks-server package
 ├── tsconfig.json          # Extends core tsconfig
 ├── tsconfig.docker.json   # Docker-specific tsconfig with path aliases
 ├── .dockerignore          # Excludes Dockerfile, .git, node_modules, etc.
 └── .gitignore             # Excludes app/, config/, dist/, storage/ (build artifacts)
 ```
 
-## Server Entry Point (server/src/index.ts)
-
-The runtime server uses `Bun.serve()` directly. It handles two modes based on environment variables:
-
-### HTTP Server Mode (default)
-```typescript
-import type { Server, ServerWebSocket } from 'bun'
-
-const server = Bun.serve({
-  port: Number(process.env.PORT) || 3000,
-  development: process.env.APP_ENV?.toLowerCase() !== 'production',
-
-  async fetch(request: Request, server: Server<any>): Promise<Response | undefined> {
-    // Attempt WebSocket upgrade first
-    if (server.upgrade(request)) return
-
-    // Delegate to the Stacks router
-    return serverResponse(request)
-  },
-
-  websocket: {
-    open(_ws: ServerWebSocket): void {},
-    message(_ws: ServerWebSocket, _message: string): void {},
-    close(_ws: ServerWebSocket, _code: number, _reason?: string): void {},
-  },
-})
-```
 
-Key details:
-- `serverResponse()` is imported from `@stacksjs/router` and handles all route matching, middleware, and response generation
-- WebSocket upgrade is attempted before HTTP routing
-- `development` mode is enabled when `APP_ENV` is not `production` or `prod`
-- SIGINT handler gracefully exits the process
+## Server Entry Point (server/src/index.ts)
 
-### Queue Worker Mode
-When `QUEUE_WORKER` env var is set, the same entry point runs a single job instead of starting the HTTP server:
+The HTTP runtime delegates fetch requests to serverResponse from
+`@stacksjs/router/runtime`. It has no WebSocket upgrade handlers. Realtime
+clients connect to the separate authenticated broadcast server described by
+`stacks-realtime`.
 
-```typescript
-if (process.env.QUEUE_WORKER) {
-  const jobName = process.env.JOB.replace(/\.ts$/, '').replace(/[^a-zA-Z0-9_-]/g, '')
-  const jobModule = await import(`./app/Jobs/${jobName}`)
-
-  await retry(() => jobModule.default.handle(), {
-    backoffFactor: Number(process.env.JOB_BACKOFF_FACTOR) || 2,
-    retries: Number(process.env.JOB_RETRIES) || 3,
-    initialDelay: Number(process.env.JOB_INITIAL_DELAY) || 1000,
-    jitter: process.env.JOB_JITTER === 'true',
-  })
-
-  process.exit(0)
-}
-```
+PORT defaults to 3000; APP_ENV production/prod disables development mode.
+Production enables reusePort for replacement instances on supported platforms.
+SIGTERM stops accepting connections and drains in-flight requests, with a
+SHUTDOWN_GRACE_MS deadline (default fifteen seconds). Supervisors still own
+restart and deploy health-gating policy.
 
-Environment variables for job execution:
-- `QUEUE_WORKER` -- enables worker mode (any truthy value)
-- `JOB` -- job file name (e.g., `SendEmail.ts`), sanitized to prevent path traversal
-- `JOB_RETRIES` -- retry count (default: 3)
-- `JOB_BACKOFF_FACTOR` -- exponential backoff multiplier (default: 2)
-- `JOB_INITIAL_DELAY` -- initial retry delay in ms (default: 1000)
-- `JOB_JITTER` -- enable jitter on retries (`'true'` to enable)
+With QUEUE_WORKER set, this entry instead loads the sanitized JOB file and runs
+its handle with retry. JOB_RETRIES, JOB_BACKOFF_FACTOR, JOB_INITIAL_DELAY and
+JOB_JITTER configure that one-shot mode. It is distinct from the durable
+`buddy queue:work` processor.
 
 ## Server Config (core/server/src/config.ts)
 
@@ -178,25 +136,19 @@ const config = {
 
 Used by `start.ts` (the production binary entry point) with `SKIP_CONFIG_LOADING=true` to bypass dynamic config imports.
 
+
 ## Production Start (core/server/src/start.ts)
 
-Entry point for compiled production binaries. Sequence:
+The compiled-binary entry marks binary mode and disables external runtime config
+loading. It reads appRouteRegistry at runtime, loads manual routes first, then
+tries `@stacksjs/orm/routes` with a checkout-relative fallback. Missing ORM
+routes warn; unresolved registered route middleware aborts startup rather than
+serving an unguarded route. Bun receives `hostname`, not a host option.
 
-1. Sets `__STACKS_BINARY_MODE__ = true` on `globalThis` (prevents auto-registration in routes)
-2. Sets `SKIP_CONFIG_LOADING = 'true'` env var
-3. Imports `loadRoutes` and `serve` from `@stacksjs/router`
-4. Loads routes from the `app/Routes.ts` registry via `loadRoutes(routeRegistry)`
-5. Loads ORM auto-generated routes from `../../orm/routes` (model CRUD endpoints)
-6. Calls `serve({ port, host })` to start the Bun HTTP server
-
-```typescript
-// Production startup flow
-loadRoutes(routeRegistry)
-  .then(async () => {
-    await import('../../orm/routes')   // ORM auto-routes (after manual routes)
-    serve({ port: config.server.port, host: config.server.host })
-  })
-```
+Unhandled rejections reach the shared report hook; uncaught exceptions report,
+flush logging and exit so a supervisor can restart. This entry's startup contract
+differs from the Docker HTTP entry and the STX production views server; inspect
+the selected build/deploy entrypoint before copying environment assumptions.
 
 ## Auto-Imports System (core/server/src/imports.ts)
 
@@ -215,7 +167,7 @@ Scan order (user overrides framework overrides defaults):
 
 Outputs:
 - `.d.ts` file: `storage/framework/types/server-auto-imports.d.ts`
-- ESLint config: `storage/framework/server-auto-imports.json`
+- Compatibility manifest: storage/framework/server-auto-imports.json; lint remains pickier
 - Runtime index files: `storage/framework/auto-imports/` (see below)
 
 ### generateAutoImportFiles()
@@ -245,15 +197,15 @@ Internal helper that scans a directory for `.ts` files (excluding `.d.ts`, `inde
 
 ```typescript
 class Controller {
-  protected json(data: any, status?: number): ResponseData      // default status: 200
-  protected success(data: any): ResponseData                     // alias for json(data, 200)
-  protected created(data: any): ResponseData                     // json(data, 201)
+  protected json(data: unknown, status?: ResponseStatus): Response      // default status: 200
+  protected success(data: unknown): Response                     // alias for json(data, 200)
+  protected created(data: unknown): Response                     // json(data, 201)
   protected noContent(): any                                     // response.noContent()
-  protected error(message: string, status?: number): ResponseData // json({ error }, 500)
-  protected notFound(message?: string): ResponseData             // error(msg, 404)
-  protected unauthorized(message?: string): ResponseData         // error(msg, 401)
-  protected forbidden(message?: string): ResponseData            // error(msg, 403)
-  protected validate(request: Request, rules: Record<string, any>): Promise<void>
+  protected error(message: string, status?: ResponseStatus): Response // json({ error }, 500)
+  protected notFound(message?: string): Response             // error(msg, 404)
+  protected unauthorized(message?: string): Response         // error(msg, 401)
+  protected forbidden(message?: string): Response            // error(msg, 403)
+  protected validate(request: Request, rules: Record<string, unknown>): Promise<void>
 }
 ```
 
@@ -453,7 +405,7 @@ Shell script for running the Docker container locally or against remote storage
 ./dev local
 # docker run -p 3000:3000 -v app:/usr/src/app/app -v config:... -v storage:... stacks
 
-# Remote/EFS (default — uses /mnt/efs for storage)
+# Remote/EFS (default - uses /mnt/efs for storage)
 ./dev
 # Same volume mounts but storage points to /mnt/efs
 ```
@@ -501,3 +453,13 @@ Shell script for running the Docker container locally or against remote storage
 - The Docker image runs as non-root user `bun` with `/usr/src/storage` as a persistent volume
 - `build.ts` strips `export { ENV_KEY, ENV_SECRET, fromEnv }` from bundled output as a workaround for a Bun bundler issue
 - `tsconfig.docker.json` has path aliases that remap `@stacksjs/*` to `core/*/dist` -- this is critical for the Docker build to resolve packages without workspace symlinks
+
+
+## Runtime evidence
+
+Read `storage/framework/server/src/index.ts`, `core/server/src/start.ts`,
+`core/buddy/src/production-server.ts` and `core/server/src/imports.ts` for the
+selected runtime. Controller validation awaits the request macro and propagates
+failure (`core/server/src/controllers/base.ts`); helpers return actual Response
+objects. Runtime globals come from the same resolver as app/default models, not
+from ambient type declarations alone. See stacks-auto-imports for that contract.

package/ai/skills/stacks-setup-deep-modules/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-setup-deep-modules/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## setup-ts-deep-modules
+
+Source: [skills/in-progress/setup-ts-deep-modules/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/in-progress/setup-ts-deep-modules/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`. This workflow is in progress upstream.
+
+Honor real Stacks package exports and prove public-entrypoint, fixture, and cycle rules with a Bun-based check; do not assume src/packages root files are the public surface.

package/ai/skills/stacks-setup-deep-modules/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: stacks-setup-deep-modules
+description: Configure and prove public-entrypoint, test-fixture, and dependency-cycle rules for TypeScript packages in Stacks.
+disable-model-invocation: true
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Set up deep modules
+
+The Stacks-native counterpart to Matt Pocock's `setup-ts-deep-modules` workflow.
+Read `stacks-codebase-design` and [the adaptation rules](../stacks-flow/ENGINEERING.md).
+Source and MIT attribution are in [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+The source workflow is in progress upstream.
+
+## Discover the actual surface
+
+Read the package manifests, export maps, TypeScript aliases, existing boundary
+checks, and CI. Framework packages live under `storage/framework/core/`; app
+modules use the project's established layout. Do not create `src/packages`
+or assume every root file is public when a package has an explicit export map.
+
+Record public entrypoints, implementation paths, test fixtures, and exceptions.
+Preserve intentional subpath exports and development-condition resolution.
+Use the smallest check that can express the actual boundary.
+
+## Rules to enforce
+
+- Callers outside a package use its public entrypoints or declared subpaths.
+- Implementation files within a package can import each other.
+- Tests exercise public behavior and can import their own fixtures. Internal
+  tests need an explicitly documented seam, not a blanket deep-import exemption.
+- Dependency cycles fail where the project forbids them. Inspect existing
+  intentional cycles before adding a rule that breaks the whole repository.
+
+Honor the project's current tool if it already enforces these rules. Otherwise
+write a TypeScript check run by Bun using resolved import paths and the real
+export maps. A regex over import strings alone cannot establish resolved
+package ownership or detect every import form. If dependency-cruiser is
+already installed or explicitly requested, verify its current configuration
+API before extending it. Preserve existing rules and better-dx dependencies.
+
+## Prove the check
+
+Wire the check into the existing quality command or CI. Use a temporary fixture
+to observe a clean pass, a failure for an outside deep import, and a clean pass
+after removing it. Repeat for a disallowed test import and a cycle. Keep these
+checks as focused regression tests when adding a new checker. Clean up temporary
+violations and verify the repository's intended exports remain usable.
+
+Document the real convention beside the packages and add a pointer in canonical
+`AGENTS.md`. Completion means the demonstrated violations fail deterministically
+and the current valid surface passes. A request to set up checks does not
+authorize unrelated package moves, a commit, or a new example package.

package/ai/skills/stacks-setup-engineering/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-setup-engineering/NOTICE.md

@@ -0,0 +1,10 @@
+# Source and license
+
+The upstream MIT notice is preserved in [LICENSE](LICENSE).
+
+## setup-matt-pocock-skills
+
+Source: [skills/engineering/setup-matt-pocock-skills/SKILL.md](https://github.com/mattpocock/skills/blob/49dd158d1076134a641b33efb035946536778336/skills/engineering/setup-matt-pocock-skills/SKILL.md),
+revision `49dd158d1076134a641b33efb035946536778336`.
+
+Ported with Stacks skill names, canonical guidance, local-tracker fallback, TypeScript/Bun tooling, and conditional external actions.

package/ai/skills/stacks-setup-engineering/PLAYBOOK.md

@@ -0,0 +1,115 @@
+> Adapted playbook. Read [the Stacks rules](../stacks-flow/ENGINEERING.md) first. Commit, push, publish, and tracker mutations are conditional on the user's authorization.
+
+
+# Setup Matt Pocock's Skills
+
+Scaffold the per-repo configuration that the engineering skills assume:
+
+- **Issue tracker**: where issues live (GitHub by default; local markdown is also supported out of the box)
+- **Triage labels**: the strings used for the five canonical triage roles
+- **Domain docs**: where `GLOSSARY.md` and ADRs live, and the consumer rules for reading them
+
+This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.
+
+## Process
+
+### 1. Explore
+
+Look at the current repo to understand its starting state. Read whatever exists; don't assume:
+
+- `git remote -v` and `.git/config`: is this a GitHub repo? Which one?
+- `AGENTS.md` and `CLAUDE.md` at the repo root: does either exist? Is there already an `## Agent skills` section in either?
+- `GLOSSARY.md` and `GLOSSARY-MAP.md` at the repo root
+- `docs/adr/` and any `src/*/docs/adr/` directories
+- `docs/agents/`: does this skill's prior output already exist?
+- `.scratch/`: a sign that a local-markdown issue tracker convention is already in use
+- Is the `stacks-triage` skill installed? (a `stacks-triage` skill folder alongside this one, or `stacks-triage` in your available skills.) This decides whether Section B runs at all.
+- Monorepo signals: a `pnpm-workspace.yaml`, a `workspaces` field in `package.json`, or a populated `packages/*` with its own `src/`. These are present only in a genuinely large multi-package repo; their absence means single-context, which is almost every repo.
+
+### 2. Present findings and ask
+
+Summarise what's present and what's missing. Then take the sections in order. One section, one answer, then the next.
+
+Lead each section with the recommended answer so the user can accept it in a word. Give a one-line explainer only when the choice genuinely branches; skip the section entirely when exploration already settled it (Section B when `stacks-triage` isn't installed, Section C when there's no monorepo).
+
+**Section A: Issue tracker.**
+
+> Explainer: The "issue tracker" is where issues live for this repo. Skills like `stacks-to-tickets`, `stacks-triage`, and `stacks-to-spec` read from and write to it. They need to know whether to call `gh issue create`, write a markdown file under `.scratch/`, or follow some other workflow you describe. Pick the place you actually track work for this repo.
+
+Default posture: these skills were designed for GitHub. If a `git remote` points at GitHub, propose that. If a `git remote` points at GitLab (`gitlab.com` or a self-hosted host), propose GitLab. Otherwise (or if the user prefers), offer:
+
+- **GitHub**: issues live in the repo's GitHub Issues (uses the `gh` CLI)
+- **GitLab**: issues live in the repo's GitLab Issues (uses the [`glab`](https://gitlab.com/gitlab-org/cli) CLI)
+- **Local markdown**: issues live as files under `.scratch/<feature>/` in this repo (good for solo projects or repos without a remote)
+- **Other** (Jira, Linear, etc.): ask the user to describe the workflow in one paragraph; the skill will record it as freeform prose
+
+Record the choice in `docs/agents/issue-tracker.md`. The GitHub and GitLab templates carry a "PRs as a request surface" flag, defaulted **off**. Leave it off and don't raise it: a user who wants external PRs in the triage queue can flip the flag in the file later.
+
+**Section B: Triage label vocabulary.** Skip this section entirely if the `stacks-triage` skill isn't installed (exploration told you), since an uninstalled skill needs no labels.
+
+If it is installed, ask exactly one question:
+
+> Do you want to keep the default triage labels? (recommended: **yes**)
+
+The defaults are the five canonical roles, each label string equal to its name: `needs-triage`, `needs-info`, `ready-for-agent`, `ready-for-human`, `wontfix`. On **yes**, write them as-is. Only if the user says no, usually because their tracker already uses other names (e.g. `bug:triage` for `needs-triage`), collect the overrides so `stacks-triage` applies existing labels instead of creating duplicates.
+
+**Section C: Domain docs.** Default to **single-context** (one `GLOSSARY.md` + `docs/adr/` at the repo root). This fits almost every repo; write it without asking.
+
+Offer **multi-context** (a root `GLOSSARY-MAP.md` pointing to per-context `GLOSSARY.md` files) only when exploration found monorepo signals. Then confirm which layout they want.
+
+### 3. Confirm and edit
+
+Show the user a draft of:
+
+- The `## Agent skills` block to add to whichever of `CLAUDE.md` / `AGENTS.md` is being edited (see step 4 for selection rules)
+- The contents of `docs/agents/issue-tracker.md`, `docs/agents/domain.md`, and `docs/agents/triage-labels.md` (the last only when `stacks-triage` is installed)
+
+Let them edit before writing.
+
+### 4. Write
+
+**Pick the file to edit:**
+
+- Edit canonical `AGENTS.md`. A symlinked `CLAUDE.md` follows it automatically.
+- If only an authored `CLAUDE.md` exists, preserve it and explain the Stacks layout before proposing migration.
+- If neither exists, use the Stacks starter guidance when creating the requested setup.
+
+Keep one canonical source and preserve authored instructions. Do not overwrite or duplicate a team's guidance as a side effect of tracker setup.
+
+If an `## Agent skills` block already exists in the chosen file, update its contents in-place rather than appending a duplicate. Don't overwrite user edits to the surrounding sections.
+
+The block:
+
+```markdown
+## Agent skills
+
+### Issue tracker
+
+[one-line summary of where issues are tracked]. See `docs/agents/issue-tracker.md`.
+
+### Triage labels
+
+[one-line summary of the label vocabulary]. See `docs/agents/triage-labels.md`.
+
+### Domain docs
+
+[one-line summary of layout: "single-context" or "multi-context"]. See `docs/agents/domain.md`.
+```
+
+Include the `### Triage labels` sub-block, and write `docs/agents/triage-labels.md`, only when `stacks-triage` is installed and Section B ran. When it isn't, both are omitted.
+
+When Section B ran on GitHub or GitLab, create each configured label the tracker lacks (`gh label create` / `glab label create`).
+
+Then write the docs files using the seed templates in this skill folder as a starting point:
+
+- [issue-tracker-github.md](issue-tracker-github.md): GitHub issue tracker
+- [issue-tracker-gitlab.md](issue-tracker-gitlab.md): GitLab issue tracker
+- [issue-tracker-local.md](issue-tracker-local.md): local-markdown issue tracker
+- [triage-labels.md](triage-labels.md): label mapping (only if `stacks-triage` is installed)
+- [domain.md](domain.md): domain doc consumer rules + layout
+
+For "other" issue trackers, write `docs/agents/issue-tracker.md` from scratch using the user's description.
+
+### 5. Done
+
+Tell the user the setup is complete and which engineering skills will now read from these files. Mention they can edit `docs/agents/*.md` directly later; re-running this skill is only necessary if they want to switch issue trackers or restart from scratch.

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

@@ -0,0 +1,24 @@
+---
+name: stacks-setup-engineering
+description: Configure tracker conventions, triage roles, and domain documentation for Stacks engineering workflows.
+disable-model-invocation: true
+license: MIT
+compatibility: Bun >= 1.3.0, TypeScript
+allowed-tools: Read Edit Write Bash Grep Glob
+---
+
+# Setup Engineering
+
+Read [the Stacks adaptation rules](../stacks-flow/ENGINEERING.md), then
+[PLAYBOOK.md](PLAYBOOK.md). The playbook preserves this workflow's decision
+criteria; the Stacks rules govern APIs, tooling, tracking, and authorization.
+
+Credit: adapted from Matt Pocock's `setup-matt-pocock-skills` skill, MIT licensed.
+See [NOTICE.md](NOTICE.md) and [LICENSE](LICENSE).
+
+## Completion
+
+Produce the requested behavior or reviewable artifact and satisfy the
+playbook's completion criteria. Preserve existing decisions and user edits.
+Use the native Stacks skills for implementation and verification, and carry
+existing authorization through the workflow.

package/ai/skills/stacks-setup-engineering/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`GLOSSARY.md`** at the repo root, or
+- **`GLOSSARY-MAP.md`** at the repo root if it exists: it points at one `GLOSSARY.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/stacks-domain-modeling` skill (reached via `/stacks-grill-with-docs` and `/stacks-improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── GLOSSARY.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `GLOSSARY-MAP.md` at the root):
+
+```
+/
+├── GLOSSARY-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── GLOSSARY.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── GLOSSARY.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `GLOSSARY.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/stacks-domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_

package/ai/skills/stacks-setup-engineering/issue-tracker-github.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitHub
+
+Issues and specs for this repo live as GitHub issues. Use the `gh` CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `gh issue create --title "..." --body "..."`. Use a heredoc for multi-line bodies.
+- **Read an issue**: `gh issue view <number> --json number,title,body,labels,comments`.
+- **List issues**: `gh issue list --state open --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'` with appropriate `--label` and `--state` filters.
+- **Make an issue a sub-issue of a parent**: `gh issue create --parent <parent> ...`, or `gh issue edit <parent> --add-sub-issue <child>` afterwards (`gh` 2.94+). Older `gh`: `gh api --method POST repos/<owner>/<repo>/issues/<parent>/sub_issues -F sub_issue_id=<child-db-id>` (database id, as in **Blocking** below). Without sub-issues, put `Part of #<parent>` at the top of the child body.
+- **Comment on an issue**: `gh issue comment <number> --body "..."`
+- **Apply / remove labels**: `gh issue edit <number> --add-label "..."` / `--remove-label "..."`
+- **Close**: `gh issue close <number> --comment "..."`
+
+Infer the repo from `git remote -v`; `gh` does this automatically when run inside a clone.
+
+## Pull requests as a triage surface
+
+**PRs as a request surface: no.** _(Set to `yes` if this repo treats external PRs as feature requests; `/stacks-triage` reads this flag.)_
+
+When set to `yes`, PRs run through the same labels and states as issues, using the `gh pr` equivalents:
+
+- **Read a PR**: `gh pr view <number> --comments` and `gh pr diff <number>` for the diff.
+- **List external PRs for triage**: `gh api --paginate 'repos/{owner}/{repo}/pulls?state=open' --jq '.[] | select(.author_association | IN("OWNER","MEMBER","COLLABORATOR") | not) | {number, title, author: .user.login, author_association, labels: [.labels[].name]}'`.
+- **Comment / label / close**: `gh pr comment`, `gh pr edit --add-label`/`--remove-label`, `gh pr close`.
+
+GitHub shares one number space across issues and PRs, so a bare `#42` may be either: resolve with `gh pr view 42` and fall back to `gh issue view 42`.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitHub issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Read it as in **Read an issue** above.
+
+## Wayfinding operations
+
+Used by `/stacks-wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `gh issue create --label wayfinder:map`.
+- **Child ticket**: an issue linked to the map as a GitHub sub-issue (see **Make an issue a sub-issue of a parent**). Where sub-issues aren't enabled, add the child to a task list in the map body and put `Part of #<map>` at the top of the child body. Labels: `wayfinder:<type>` (`stacks-research`/`stacks-prototype`/`stacks-grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitHub's **native issue dependencies**, the canonical, UI-visible representation. Add an edge with `gh api --method POST repos/<owner>/<repo>/issues/<child>/dependencies/blocked_by -F issue_id=<blocker-db-id>`, where `<blocker-db-id>` is the blocker's numeric **database id** (`gh api repos/<owner>/<repo>/issues/<n> --jq .id`, _not_ the `#number` or `node_id`). GitHub reports `issue_dependencies_summary.blocked_by` (open blockers only, the live gate). Where dependencies aren't available, fall back to a `Blocked by: #<n>, #<n>` line at the top of the child body. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: list the map's open children (`gh issue list --state open`, scoped to the map's sub-issues / task list), drop any with an open blocker (`issue_dependencies_summary.blocked_by > 0`, or an open issue in the `Blocked by` line) or an assignee; first in map order wins.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, the session's first write.
+- **Resolve**: `gh issue comment <n> --body "<answer>"`, then `gh issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/ai/skills/stacks-setup-engineering/issue-tracker-gitlab.md

@@ -0,0 +1,46 @@
+# Issue tracker: GitLab
+
+Issues and specs for this repo live as GitLab issues. Use the [`glab`](https://gitlab.com/gitlab-org/cli) CLI for all operations.
+
+## Conventions
+
+- **Create an issue**: `glab issue create --title "..." --description "..."`. Use a heredoc for multi-line descriptions. Pass `--description -` to open an editor.
+- **Read an issue**: `glab issue view <number> --comments`. Use `-F json` for machine-readable output.
+- **List issues**: `glab issue list -O json` with appropriate `--label` filters.
+- **Comment on an issue**: `glab issue note <number> --message "..."`. GitLab calls comments "notes".
+- **Apply / remove labels**: `glab issue update <number> --label "..."` / `--unlabel "..."`. Multiple labels can be comma-separated or by repeating the flag.
+- **Close**: `glab issue close <number>`. `glab issue close` does not accept a closing comment, so post the explanation first with `glab issue note <number> --message "..."`, then close.
+- **Merge requests**: GitLab calls PRs "merge requests". Use `glab mr create`, `glab mr view`, `glab mr note`, etc., the same shape as `gh pr ...` with `mr` in place of `stacks-pr` and `note`/`--message` in place of `comment`/`--body`.
+
+Infer the repo from `git remote -v`; `glab` does this automatically when run inside a clone.
+
+## Merge requests as a triage surface
+
+**MRs as a request surface: no.** _(Set to `yes` if this repo treats external merge requests as feature requests; `/stacks-triage` reads this flag.)_
+
+When set to `yes`, MRs run through the same labels and states as issues, using the `glab mr` equivalents:
+
+- **Read an MR**: `glab mr view <number> --comments` and `glab mr diff <number>` for the diff.
+- **List external MRs for triage**: `glab mr list -F json`, then keep only MRs whose author is not a project member/owner (a contributor's MR, not a maintainer's in-flight work).
+- **Comment / label / close**: `glab mr note`, `glab mr update --label`/`--unlabel`, `glab mr close`.
+
+Unlike GitHub, GitLab numbers issues and MRs separately, so `#42` is unambiguous once you know which surface the maintainer means.
+
+## When a skill says "publish to the issue tracker"
+
+Create a GitLab issue.
+
+## When a skill says "fetch the relevant ticket"
+
+Run `glab issue view <number> --comments`.
+
+## Wayfinding operations
+
+Used by `/stacks-wayfinder`. The **map** is a single issue with **child** issues as tickets.
+
+- **Map**: a single issue labelled `wayfinder:map`, holding the Notes / Decisions-so-far / Fog body. `glab issue create --label wayfinder:map`. (On GitLab tiers with native epics, an epic may hold the map instead; a labelled issue works everywhere.)
+- **Child ticket**: an issue carrying `Part of #<map>` at the top of its description and labels `wayfinder:<type>` (`stacks-research`/`stacks-prototype`/`stacks-grilling`/`task`). Once claimed, the ticket is assigned to the driving dev.
+- **Blocking**: GitLab's **native blocking link**, the canonical, UI-visible representation. Add it with the `/blocked_by #<n>` quick action, posted as a note (`glab issue note <child> --message "/blocked_by #<blocker>"`). Native blocking links are a Premium/Ultimate feature; on the free tier (or where unavailable) fall back to a `Blocked by: #<n>, #<n>` line at the top of the description. A ticket is unblocked when every blocker is closed.
+- **Frontier query**: `glab issue list -O json` scoped to the map's children, drop any with an open blocker: a native `blocked_by` link to an open issue (`glab api projects/:id/issues/<child-iid>/links`), or an open issue in the `Blocked by` line, or an assignee; first in map order wins.
+- **Claim**: `glab issue update <n> --assignee @me`, the session's first write.
+- **Resolve**: `glab issue note <n> --message "<answer>"`, then `glab issue close <n>`, then append a context pointer (gist + link) to the map's Decisions-so-far.

package/ai/skills/stacks-setup-engineering/issue-tracker-local.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at `.scratch/<feature-slug>/issues/<NN>-<slug>.md`, numbered from `01`, never a single combined tickets file
+- Triage state is recorded as a `Status:` line near the top of each issue file (see `triage-labels.md` for the role strings)
+- Comments and conversation history append to the bottom of the file under a `## Comments` heading
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/` (creating the directory if needed).
+
+## When a skill says "fetch the relevant ticket"
+
+Read the file at the referenced path. The user will normally pass the path or the issue number directly.
+
+## Wayfinding operations
+
+Used by `/stacks-wayfinder`. The **map** is a file with one **child** file per ticket.
+
+- **Map**: `.scratch/<effort>/map.md` (the Notes / Decisions-so-far / Fog body).
+- **Child ticket**: `.scratch/<effort>/issues/NN-<slug>.md`, numbered from `01`, with the question in the body. A `Type:` line records the ticket type (`stacks-research`/`stacks-prototype`/`stacks-grilling`/`task`); a `Status:` line records `claimed`/`resolved`.
+- **Blocking**: a `Blocked by: NN, NN` line near the top. A ticket is unblocked when every file it lists is `resolved`.
+- **Frontier**: scan `.scratch/<effort>/issues/` for files that are open, unblocked, and unclaimed; first by number wins.
+- **Claim**: set `Status: claimed` and save before any work.
+- **Resolve**: append the answer under an `## Answer` heading, set `Status: resolved`, then append a context pointer (gist + link) to the map's Decisions-so-far in `map.md`.