@maestro-js/agent-skills 1.0.0-alpha.2 → 1.0.0-alpha.21

package/skills/maestro-examples/references/chorus/specs/app.md

@@ -0,0 +1,73 @@
+# App Requirements
+
+A community discussion site where users browse channels, read posts, and participate in conversations. Think a simplified Reddit with Twitter-style image layouts.
+
+## Channels
+
+A channel is a named topic area (e.g. "Photography", "Cooking", "Tech News"). Channels are the top-level organizational unit.
+
+- Anyone can browse the list of channels and view a channel's posts without logging in
+- Each channel has a name, a URL-friendly slug (auto-generated from the name, must be unique), a description, and an optional icon/avatar
+- Each channel has a single owner — the user who creates the channel is the owner
+- Each channel has zero or more moderators
+- Only authenticated users can create a channel
+- The owner can edit the channel's name, description, and icon
+- The owner can appoint or remove moderators
+- The owner can transfer ownership to another user
+- Moderators can hide any post or reply within their channel — replies to a hidden post remain visible
+- A channel displays its posts in reverse chronological order (newest first)
+
+## Posts
+
+A post is a piece of content submitted to a channel by an authenticated user.
+
+- Only authenticated users can create a post
+- A post belongs to exactly one channel
+- A post contains text content (required) and optionally up to 4 images
+- Posts display the author's email/name, the timestamp, the number of replies, and the images (if any)
+- Posts cannot be edited or deleted by the author
+- The author can hide their own post — replies to a hidden post remain visible
+- Moderators can also hide posts
+
+### Likes
+
+- Only authenticated users can like a post
+- A user can like a post at most once; unliking removes the like
+- Posts display their total like count
+- The UI indicates whether the current user has liked a post
+
+### Image Display
+
+Posts can include 0–4 images. The layout adapts based on the number of images, following Twitter's image grid pattern:
+
+- **1 image** — single image fills the full width
+- **2 images** — two images side by side, each taking half the width
+- **3 images** — one large image on the left (half width, full height), two stacked on the right (half width each)
+- **4 images** — 2×2 grid, all images equal size
+
+All image containers use a consistent aspect ratio and crop/cover to fit. Clicking an image opens a larger view.
+
+## Replies
+
+A reply is a response to a post. Replies are structurally identical to posts but nested under a parent.
+
+- Only authenticated users can reply
+- A reply contains text content (required) and optionally up to 4 images (same display rules as posts)
+- Replies display the author, timestamp, and images (if any)
+- Replies are displayed in chronological order (oldest first) beneath their parent post
+- Replies cannot be edited or deleted by the author
+- The author can hide their own reply
+- Moderators can also hide replies
+- Replies are single-level only — you reply to a post, not to another reply
+
+## Browsing & Reading
+
+- The home page shows a list of channels sorted by most activity in the last 24 hours (activity = posts, replies, and likes within the channel)
+- Channels are identified in URLs by their slug (e.g. `/c/photography`)
+- Clicking a channel shows its posts (paginated, newest first)
+- Clicking a post shows the full post with all its replies beneath it
+- All browsing and reading is available to unauthenticated users — no login required to read
+
+## Authentication
+
+Authentication is already built into the app. The existing signup, login, logout, password reset, and session management flows remain unchanged. The new features simply gate write actions (creating channels, posting, replying, moderating) behind an authenticated session.

package/skills/maestro-examples/references/chorus/specs/data-models.md

@@ -0,0 +1,48 @@
+# Data Models
+
+Zod schemas for the community discussion site. Each section defines a zod model. Note: zod models are not necessarily one-to-one with database tables.
+
+
+## Channels
+
+
+```ts
+const channelModel = z.object({
+  id: z.number(),
+  ownerProfileId: z.number(),
+  name: z.string(),
+  slug: z.string(),
+  description: z.string(),
+  moderatorProfileIds: z.number().array(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Posts
+
+A reply is just a post with a `replyingToPostId`. Top-level posts have `replyingToPostId: null`. Replies are single-level only — a reply's `replyingToPostId` always points to a top-level post, never to another reply.
+
+```ts
+const postModel = z.object({
+  id: z.number(),
+  channelId: z.number(),
+  profileId: z.number(),
+  replyingToPostId: z.number().nullable(),
+  content: z.string(),
+  images: z.array(z.string().max(500)).max(4),
+  hiddenDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Likes
+
+```ts
+const likeModel = z.object({
+  postId: z.number(),
+  profileId: z.number(),
+  createdDate: isoZ.instant()
+})
+```

package/skills/maestro-examples/references/chorus/specs/database-schema.md

@@ -0,0 +1,59 @@
+# Database Schema
+
+MySQL schema for the community discussion site. Derived from the zod models in `data-models.md`.
+
+## Tables
+
+```sql
+CREATE TABLE channels (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  ownerProfileId INT UNSIGNED NOT NULL,
+  name VARCHAR(255) NOT NULL,
+  slug VARCHAR(255) NOT NULL,
+  description VARCHAR(2000) NOT NULL,
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  UNIQUE KEY uq_channels_slug (slug),
+  CONSTRAINT fk_channels_ownerProfileId FOREIGN KEY (ownerProfileId) REFERENCES profiles (profileId)
+);
+
+CREATE TABLE channelModerators (
+  channelId BIGINT UNSIGNED NOT NULL,
+  profileId INT UNSIGNED NOT NULL,
+  PRIMARY KEY (channelId, profileId),
+  CONSTRAINT fk_channelModerators_channelId FOREIGN KEY (channelId) REFERENCES channels (id),
+  CONSTRAINT fk_channelModerators_profileId FOREIGN KEY (profileId) REFERENCES profiles (profileId)
+);
+
+CREATE TABLE posts (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  channelId BIGINT UNSIGNED NOT NULL,
+  profileId INT UNSIGNED NOT NULL,
+  replyingToPostId BIGINT UNSIGNED,
+  content TEXT NOT NULL,
+  hiddenDate DATETIME(3),
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  KEY idx_posts_channel_created (channelId, createdDate),
+  CONSTRAINT fk_posts_channelId FOREIGN KEY (channelId) REFERENCES channels (id),
+  CONSTRAINT fk_posts_profileId FOREIGN KEY (profileId) REFERENCES profiles (profileId),
+  CONSTRAINT fk_posts_replyingToPostId FOREIGN KEY (replyingToPostId) REFERENCES posts (id)
+);
+
+CREATE TABLE postImages (
+  postId BIGINT UNSIGNED NOT NULL,
+  sortOrder TINYINT UNSIGNED NOT NULL,
+  url VARCHAR(500) NOT NULL,
+  PRIMARY KEY (postId, sortOrder),
+  CONSTRAINT fk_postImages_postId FOREIGN KEY (postId) REFERENCES posts (id)
+);
+
+CREATE TABLE likes (
+  postId BIGINT UNSIGNED NOT NULL,
+  profileId INT UNSIGNED NOT NULL,
+  createdDate DATETIME(3) NOT NULL,
+  PRIMARY KEY (postId, profileId),
+  CONSTRAINT fk_likes_postId FOREIGN KEY (postId) REFERENCES posts (id),
+  CONSTRAINT fk_likes_profileId FOREIGN KEY (profileId) REFERENCES profiles (profileId)
+);
+```

package/skills/maestro-examples/references/chorus/specs/use-cases.md

@@ -0,0 +1,33 @@
+# Use Cases
+
+Use cases for the community discussion site, grouped by entity.
+
+## Channels
+
+| # | Use Case | Auth Required | Actor |
+|---|----------|---------------|-------|
+| C1 | Browse list of channels (sorted by most activity in last 24h) | No | Anyone |
+| C2 | View a channel's posts (paginated, newest first) | No | Anyone |
+| C3 | Create a channel (creator becomes owner) | Yes | User |
+| C4 | Edit channel name, description, or icon | Yes | Owner |
+| C5 | Appoint a moderator to a channel | Yes | Owner |
+| C6 | Remove a moderator from a channel | Yes | Owner |
+| C7 | Transfer channel ownership to another user | Yes | Owner |
+
+## Posts
+
+| # | Use Case | Auth Required | Actor |
+|---|----------|---------------|-------|
+| P1 | View a post with all its replies (chronological) | No | Anyone |
+| P2 | Create a post in a channel (text required, 0-4 images) | Yes | User |
+| P3 | Reply to a post (text required, 0-4 images, single-level only) | Yes | User |
+| P4 | Hide a post (replies remain visible) | Yes | Author or Moderator |
+
+## Likes
+
+| # | Use Case | Auth Required | Actor |
+|---|----------|---------------|-------|
+| L1 | Like a post | Yes | User |
+| L2 | Unlike a post | Yes | User |
+| L3 | View like count on a post | No | Anyone |
+| L4 | View whether current user has liked a post | Yes | User |

package/skills/maestro-examples/references/chorus/tsconfig.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "moduleDetection": "force",
+
+    "jsx": "react-jsx",
+    "allowJs": true,
+    "checkJs": true,
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true,
+
+    "strict": true,
+    "noImplicitAny": false,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+
+    "noEmit": true,
+    "verbatimModuleSyntax": true,
+    "noUncheckedIndexedAccess": true
+  },
+  "exclude": ["node_modules"],
+  "include": ["./src", "./packages/*/src", "./packages/*/tests", "./sandbox/*/src"]
+}

package/skills/maestro-examples/references/setlist/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,88 @@
+# Implementation Plan
+
+## Progress
+
+### Refactoring & Architecture (Issues 0–14)
+
+- [x] **#0** — Sidebar: Extract inline components into separate files
+- [x] **#1** — Sidebar: Extract DnD reorder logic into useSidebarDnd hook (depends: #0)
+- [x] **#2** — Sidebar: Remove manual revalidation and useEffects
+- [x] **#3** — Task Detail Panel: Use React key for state reset, remove manual revalidation
+- [x] **#4** — Task Detail Panel: Extract dismiss behavior into a reusable hook
+- [x] **#5** — Context Menu: Replace custom implementation with React Aria Menu
+- [x] **#6** — Project Form: Use Form component and fetcher.Form
+- [x] **#7** — Area Form: Use Form component and fetcher.Form
+- [x] **#8** — App DnD Provider: Extract DragGhost, collision detection, and clean up revalidation
+- [x] **#9** — use-task-reorder: Derive optimistic tasks from fetcher state
+- [x] **#10** — API Routes: Split api.tasks.$id into separate routes per action
+- [x] **#11** — API Routes: Split api.projects.$id into separate routes per action
+- [x] **#12** — API Routes: Split api.areas.$id into separate routes per action
+- [x] **#13** — Create typed hooks for each API action route (depends: #10, #11, #12)
+- [x] **#14** — Sidebar: InlineCreateInput and InlineEditInput should use fetcher.Form (depends: #10, #11, #12)
+
+### E2E Tests (Issues 100–152)
+
+- [x] **#100** — E2E: Request magic link with valid email
+- [x] **#103** — E2E: Verify magic link via URL (depends: #100)
+- [x] **#104** — E2E: Verify magic link via pasted token (depends: #100)
+- [x] **#105** — E2E: Reject invalid or malformed token (depends: #100)
+- [x] **#106** — E2E: Reject already-used token (depends: #103 or #104)
+- [x] **#107** — E2E: Logout (depends: #103 or #104)
+- [x] **#108** — E2E: Sidebar displays built-in views (depends: #107)
+- [x] **#109** — E2E: Navigate to Inbox (depends: #108)
+- [x] **#110** — E2E: Inbox shows only unassigned tasks (depends: #109)
+- [x] **#111** — E2E: Navigate to Today (depends: #108)
+- [x] **#112** — E2E: Today shows overdue tasks (depends: #111)
+- [x] **#113** — E2E: Navigate to Upcoming (depends: #108)
+- [x] **#114** — E2E: Navigate to Completed (depends: #108)
+- [x] **#115** — E2E: Active sidebar highlight (depends: #109, #111, #113, #114)
+- [x] **#116** — E2E: List areas in sidebar (depends: #108)
+- [x] **#117** — E2E: Create an area (depends: #116)
+- [x] **#118** — E2E: Edit area title (depends: #117)
+- [x] **#119** — E2E: Delete an area (depends: #117)
+- [x] **#120** — E2E: Navigate to area detail view (depends: #116)
+- [x] **#121** — E2E: Area expand/collapse (depends: #116, #120)
+- [x] **#122** — E2E: Reorder areas via DnD (depends: #116)
+- [x] **#123** — E2E: Deleted area not in sidebar (depends: #119)
+- [x] **#124** — E2E: View a project's tasks (depends: #120)
+- [x] **#125** — E2E: Create a project (top-level) (depends: #116)
+- [x] **#126** — E2E: Create a project inside an area (depends: #121, #125)
+- [x] **#127** — E2E: Edit project title (depends: #124)
+- [x] **#128** — E2E: Edit project notes and date (depends: #124)
+- [x] **#129** — E2E: Move project into area via DnD (depends: #125, #126)
+- [x] **#130** — E2E: Move project out of area via DnD (depends: #126)
+- [x] **#131** — E2E: Complete a project (depends: #125)
+- [x] **#132** — E2E: Uncomplete a project (depends: #131)
+- [x] **#133** — E2E: Delete a project (depends: #125)
+- [x] **#134** — E2E: Completed project not in sidebar (depends: #131)
+- [x] **#135** — E2E: Reorder top-level projects via DnD (depends: #125)
+- [x] **#136** — E2E: Reorder projects within area (depends: #126)
+- [x] **#137** — E2E: View task details (depends: #124)
+- [x] **#138** — E2E: Create a task in Inbox (depends: #109, #137)
+- [x] **#139** — E2E: Create a task in a project (depends: #124, #137)
+- [x] **#140** — E2E: Edit task (depends: #137)
+- [x] **#141** — E2E: Complete a task (depends: #138)
+- [x] **#142** — E2E: Uncomplete a task (depends: #141)
+- [x] **#143** — E2E: Delete a task (depends: #137)
+- [x] **#144** — E2E: Reorder tasks in Inbox via DnD (depends: #138)
+- [x] **#145** — E2E: Reorder tasks in Today via DnD (depends: #111, #140)
+- [x] **#146** — E2E: Reorder tasks within a project (depends: #139, #140)
+- [x] **#147** — E2E: Complete task removes from active views (depends: #138, #140)
+- [x] **#148** — E2E: Move task from Inbox to project (depends: #138, #139)
+- [x] **#149** — E2E: Move task from Inbox to area (depends: #138, #116)
+- [x] **#150** — E2E: Move task between projects (depends: #139, #146)
+- [x] **#151** — E2E: Move task from project to area (depends: #139, #116)
+- [x] **#152** — E2E: Move task to Inbox by clearing assignment (depends: #140)
+
+## Discoveries
+
+- E2E tests require a running MySQL database. The CI environment doesn't have one, so tests can't be executed here. The test code follows the exact same pattern as `auth.setup.ts` which was verified working in issue #100.
+- The `Document` component in `root.tsx` calls `useLoaderData()` which returns `undefined` inside `ErrorBoundary` context, causing a crash on error pages. This is a pre-existing bug that doesn't affect happy-path flows.
+- The `completed.tsx` route had a bug: `dateFns.format(item.completedDate as Iso.Date, ...)` fails because `completedDate` is an instant (datetime string), not a date string. `dateFns.format` from `iso-fns` requires an `Iso.Date` (e.g., `"2024-01-15"`), not a full instant. Fixed by slicing to extract the date portion: `.slice(0, 10)`.
+- The `TaskSeed` helper used `taskDbProvider.create` which doesn't support `completedDate`. Added `taskDbProvider.seedCreate` (mirroring `projectDbProvider.seedCreate`) and updated `TaskSeed` to use it, enabling seeding tasks with any field including `completedDate` and `deletedDate`.
+- The `createProjectForm` schema had `areaId`, `notes`, and `scheduledDate` as `.nullable()` but not `.default(null)`. The inline sidebar create form only sends `title`, so these fields were missing from FormData and parsed as `undefined`, failing Zod validation. Fixed by adding `.default(null)` to each field so missing values default to `null`.
+- The `CompleteProject` use case was incorrectly calling `taskDbProvider.completeByProjectId(id)` inside a transaction, which completed all tasks when a project was completed. The spec and app requirements state "completing a project does not automatically complete its tasks." Removed the task completion line so only the project itself is marked complete.
+- The `createTaskForm` schema had the same bug as `createProjectForm`: `projectId`, `areaId`, `notes`, and `scheduledDate` were `.nullable()` but not `.default(null)`. The inline create form only sends `title`, so missing fields failed Zod validation. Fixed by adding `.default(null)` to each nullable field.
+- The Today route (`today.tsx`) was missing `onComplete` and `onUncomplete` callbacks on the `TaskList` component (same bug as Inbox). Added `useCompleteTask` and `useUncompleteTask` hooks and passed them as handlers.
+- The `TaskDetailPanel` had no Save button. The edit form only auto-submitted on title Enter key or date change, making it impossible to save notes alone. Added a Save button to the form (matching the project form pattern) so all fields can be explicitly submitted.
+- The Inbox route (`inbox.tsx`) was missing `onComplete` and `onUncomplete` callbacks on the `TaskList` component, so clicking a task's checkbox did nothing. Added `useCompleteTask` and `useUncompleteTask` hooks and passed them as handlers.

package/skills/maestro-examples/references/setlist/config/db-migrate.ts

@@ -0,0 +1,9 @@
+export default async function (env: Record<string, string | undefined>) {
+  return {
+    DB_HOST: env.DB_HOST ?? 'localhost',
+    DB_PORT: env.DB_PORT ?? '3310',
+    DB_USER: env.DB_USER ?? 'setlist',
+    DB_PASSWORD: env.DB_PASSWORD ?? '',
+    DB_DATABASE: env.DB_DATABASE ?? 'setlist'
+  }
+}

package/skills/maestro-examples/references/setlist/config/queue-processor.ts

@@ -0,0 +1,11 @@
+import getServicesConfig from './services.ts'
+
+export default async function (env: Record<string, string | undefined>) {
+  const servicesConfig = await getServicesConfig(env)
+
+  return {
+    ...servicesConfig,
+    QUEUE_CONCURRENCY: env.QUEUE_CONCURRENCY ?? '1',
+    QUEUE_POLL_INTERVAL: env.QUEUE_POLL_INTERVAL ?? '5000'
+  }
+}

package/skills/maestro-examples/references/setlist/config/services.ts

@@ -0,0 +1,16 @@
+export default async function (env: Record<string, string | undefined>) {
+  return {
+    DB_HOST: env.DB_HOST ?? 'localhost',
+    DB_PORT: env.DB_PORT ?? '3306',
+    DB_USER: env.DB_USER ?? 'setlist',
+    DB_PASSWORD: env.DB_PASSWORD ?? '',
+    DB_DATABASE: env.DB_DATABASE ?? 'setlist',
+    ENCRYPTION_KEY: env.ENCRYPTION_KEY,
+    HASH_KEY: env.HASH_KEY,
+    MAIL_FROM: env.MAIL_FROM ?? 'noreply@setlist.app',
+    BASE_URL: env.BASE_URL ?? 'http://localhost:3000',
+    ENV_NAME: env.ENV_NAME ?? 'local',
+    AWS_REGION: env.AWS_REGION ?? 'us-east-1', 
+    TZ: 'America/Chicago'
+  }
+}

package/skills/maestro-examples/references/setlist/config/setlist-web.ts

@@ -0,0 +1,12 @@
+import getServicesConfig from './services.ts'
+
+export default async function (env: Record<string, string | undefined>) {
+  const servicesConfig = await getServicesConfig(env)
+
+  return {
+    ...servicesConfig,
+    PORT: env.PORT ?? '3000',
+    SESSION_COOKIE_NAME: 'setlist_session',
+    SESSION_COOKIE_SECURE: servicesConfig.ENV_NAME !== 'local' ? 'true' : 'false'
+  }
+}

package/skills/maestro-examples/references/setlist/infrastructure/cdk/index.ts

@@ -0,0 +1,56 @@
+import * as path from 'path'
+import { App, Duration, Stack } from 'aws-cdk-lib'
+import { AuroraMysqlEngineVersion } from 'aws-cdk-lib/aws-rds'
+import { AuroraDatabase, Email, LambdaFunction, ReactRouterSsrSiteLambda, Vpc } from '@maestro-js/aws-cdk-recipes'
+
+const app = new App()
+const stack = new Stack(app, 'Setlist')
+
+// VPC
+const network = new Vpc(stack, 'Network', {
+  natGateways: 'single',
+  wireguard: true
+})
+
+// Aurora MySQL database
+const db = new AuroraDatabase(stack, 'Database', {
+  engine: 'mysql',
+  version: AuroraMysqlEngineVersion.VER_3_08_0,
+  database: 'setlist',
+  scaling: { pauseAfter: '5 minutes' },
+  deletionProtection: false,
+  vpc: network.vpc
+})
+
+db.connections.allowDefaultPortFrom(network.securityGroup, 'WireGuard VPN access')
+
+// SES email for magic links
+new Email(stack, 'Email', {
+  sender: 'setlist@marcatopartners.com',
+  configurationSetName: 'setlist'
+})
+
+// React Router SSR app on Lambda + CloudFront
+new ReactRouterSsrSiteLambda(stack, 'SsrApp', {
+  path: path.join(import.meta.dirname, '../../setlist-web'),
+  vpc: network,
+  environment: {
+    DB_HOST: db.host,
+    DB_PORT: String(db.port),
+    DB_DATABASE: 'setlist',
+    DB_USER: 'root'
+  }
+})
+
+// Queue processor Lambda
+new LambdaFunction(stack, 'QueueProcessor', {
+  handler: 'queue-processor.handler',
+  vpc: network.vpc,
+  timeout: Duration.minutes(5),
+  environment: {
+    DB_HOST: db.host,
+    DB_PORT: String(db.port),
+    DB_DATABASE: 'setlist',
+    DB_USER: 'root'
+  }
+})

package/skills/maestro-examples/references/setlist/infrastructure/cdk.context.json

@@ -0,0 +1,5 @@
+{
+  "acknowledged-issue-numbers": [
+    34892
+  ]
+}

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/20260316000000_init.ts

@@ -0,0 +1,16 @@
+import type { DbMigrations } from '@maestro-js/db-migrate'
+import { readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export async function up(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '20260316000000_init-up.sql'), 'utf-8')
+  await db.statement(sql)
+}
+
+export async function down(db: DbMigrations.Db) {
+  const sql = await readFile(join(__dirname, 'sqls', '20260316000000_init-down.sql'), 'utf-8')
+  await db.statement(sql)
+}

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/20260317000000_add-queue-and-recurring-job-tables.ts

@@ -0,0 +1,22 @@
+import type { DbMigrations } from '@maestro-js/db-migrate'
+import { readFile } from 'node:fs/promises'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export async function up(db: DbMigrations.Db) {
+  const sql = await readFile(
+    join(__dirname, 'sqls', '20260317000000_add-queue-and-recurring-job-tables-up.sql'),
+    'utf-8'
+  )
+  await db.statement(sql)
+}
+
+export async function down(db: DbMigrations.Db) {
+  const sql = await readFile(
+    join(__dirname, 'sqls', '20260317000000_add-queue-and-recurring-job-tables-down.sql'),
+    'utf-8'
+  )
+  await db.statement(sql)
+}

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/sqls/20260316000000_init-down.sql

@@ -0,0 +1,5 @@
+DROP TABLE IF EXISTS tasks;
+DROP TABLE IF EXISTS projects;
+DROP TABLE IF EXISTS areas;
+DROP TABLE IF EXISTS magicLinks;
+DROP TABLE IF EXISTS users;

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/sqls/20260316000000_init-up.sql

@@ -0,0 +1,68 @@
+CREATE TABLE users (
+  id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  email VARCHAR(255) NOT NULL,
+  credentialsInvalidBefore DATETIME(3),
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  UNIQUE KEY uq_users_email (email)
+);
+
+CREATE TABLE magicLinks (
+  id INT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  userId INT UNSIGNED NOT NULL,
+  selector VARCHAR(255) NOT NULL,
+  verifierHash VARCHAR(255) NOT NULL,
+  usedDate DATETIME(3),
+  expirationDate DATETIME(3) NOT NULL,
+  createdDate DATETIME(3) NOT NULL,
+  UNIQUE KEY uq_magicLinks_selector (selector),
+  CONSTRAINT fk_magicLinks_userId FOREIGN KEY (userId) REFERENCES users (id)
+);
+
+CREATE TABLE areas (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  userId INT UNSIGNED NOT NULL,
+  title VARCHAR(255) NOT NULL,
+  position VARCHAR(255) NOT NULL,
+  deletedDate DATETIME(3),
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  CONSTRAINT fk_areas_userId FOREIGN KEY (userId) REFERENCES users (id)
+);
+
+CREATE TABLE projects (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  userId INT UNSIGNED NOT NULL,
+  areaId BIGINT UNSIGNED,
+  title VARCHAR(255) NOT NULL,
+  notes TEXT,
+  scheduledDate DATE,
+  position VARCHAR(255) NOT NULL,
+  completedDate DATETIME(3),
+  deletedDate DATETIME(3),
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  CONSTRAINT fk_projects_userId FOREIGN KEY (userId) REFERENCES users (id),
+  CONSTRAINT fk_projects_areaId FOREIGN KEY (areaId) REFERENCES areas (id)
+);
+
+CREATE TABLE tasks (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT PRIMARY KEY,
+  userId INT UNSIGNED NOT NULL,
+  projectId BIGINT UNSIGNED,
+  areaId BIGINT UNSIGNED,
+  title VARCHAR(255) NOT NULL,
+  notes TEXT,
+  scheduledDate DATE,
+  listPosition VARCHAR(255) NOT NULL,
+  scheduledPosition VARCHAR(255),
+  completedDate DATETIME(3),
+  deletedDate DATETIME(3),
+  createdDate DATETIME(3) NOT NULL,
+  lastModifiedDate DATETIME(3) NOT NULL,
+  KEY idx_tasks_userId_scheduledDate (userId, scheduledDate),
+  KEY idx_tasks_userId_completedDate (userId, completedDate),
+  CONSTRAINT fk_tasks_userId FOREIGN KEY (userId) REFERENCES users (id),
+  CONSTRAINT fk_tasks_projectId FOREIGN KEY (projectId) REFERENCES projects (id),
+  CONSTRAINT fk_tasks_areaId FOREIGN KEY (areaId) REFERENCES areas (id)
+);

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/sqls/20260317000000_add-queue-and-recurring-job-tables-down.sql

@@ -0,0 +1,2 @@
+DROP TABLE IF EXISTS recurringJobs;
+DROP TABLE IF EXISTS queueMessages;

package/skills/maestro-examples/references/setlist/infrastructure/db-migrations/sqls/20260317000000_add-queue-and-recurring-job-tables-up.sql

@@ -0,0 +1,21 @@
+CREATE TABLE queueMessages (
+  id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+  attempt INT UNSIGNED NOT NULL DEFAULT 0,
+  queue VARCHAR(255) NOT NULL,
+  status ENUM('waiting', 'processing', 'succeeded', 'failed', 'failedPermanently') NOT NULL DEFAULT 'waiting',
+  scheduledDate DATETIME NOT NULL,
+  enqueuedDate DATETIME NOT NULL DEFAULT NOW(),
+  startedDate DATETIME,
+  completedDate DATETIME,
+  body JSON,
+  result TEXT,
+  lockId BIGINT UNSIGNED DEFAULT NULL,
+  PRIMARY KEY (id, attempt),
+  INDEX locking_pop (lockId, status, scheduledDate),
+  INDEX queue (queue)
+);
+
+CREATE TABLE recurringJobs (
+  name VARCHAR(255) NOT NULL PRIMARY KEY,
+  lastRunDate DATETIME DEFAULT NULL
+);

package/skills/maestro-examples/references/setlist/infrastructure/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@setlist/infrastructure",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "cdk-synth": "cdk synth --app 'node ./cdk/index.ts'",
+    "cdk-diff": "cdk diff --app 'node ./cdk/index.ts'",
+    "cdk-deploy": "cdk deploy --all --app 'node ./cdk/index.ts'",
+    "cdk-destroy": "cdk destroy --app 'node ./cdk/index.ts'",
+    "aws-whoami": "aws sts get-caller-identity"
+  },
+  "dependencies": {
+    "@maestro-js/aws-cdk-recipes": "^1.0.0-alpha.21",
+    "@maestro-js/db-migrate": "^1.0.0-alpha.21",
+    "aws-cdk": "^2.1106.1",
+    "aws-cdk-lib": "^2.178.0",
+    "constructs": "^10.4.2",
+    "esbuild": "^0.25.0"
+  }
+}

package/skills/maestro-examples/references/setlist/infrastructure/tsconfig.json

@@ -0,0 +1,8 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "moduleResolution": "nodenext",
+    "module": "nodenext"
+  },
+  "include": ["."]
+}

package/skills/maestro-examples/references/setlist/package.json

@@ -0,0 +1,19 @@
+{
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "fks-cascade": "maestro config:run --config services -- node ./scripts/foreign-key-delete-behavior.ts cascade",
+    "fks-restrict": "maestro config:run --config services -- node ./scripts/foreign-key-delete-behavior.ts restrict"
+  },
+  "dependencies": {
+    "@maestro-js/config": "^1.0.0-alpha.21",
+    "@setlist/services": "workspace:*"
+  },
+  "devDependencies": {
+    "@maestro-js/cli": "^1.0.0-alpha.21",
+    "@maestro-js/db-migrate": "^1.0.0-alpha.21",
+    "@maestro-js/db": "^1.0.0-alpha.21",
+    "@types/node": "^22.19.11",
+    "tsx": "^4.21.0"
+  }
+}