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

package/skills/maestro-examples/references/setlist/setlist-web/tests/views-navigate-to-inbox.test.ts

@@ -0,0 +1,21 @@
+import { test, expect } from '@playwright/test'
+
+test('clicking Inbox in sidebar navigates to inbox view with active highlight', async ({ page }) => {
+  // Start from a different view so we can verify navigation
+  await page.goto('/today')
+
+  const nav = page.getByRole('navigation')
+  const inboxLink = nav.getByRole('link', { name: 'Inbox' })
+
+  // Click the Inbox link
+  await inboxLink.click()
+
+  // Verify URL changed to /inbox
+  await expect(page).toHaveURL('/inbox')
+
+  // Verify Inbox heading is visible
+  await expect(page.getByRole('heading', { name: 'Inbox' })).toBeVisible()
+
+  // Verify the Inbox link is highlighted as active
+  await expect(inboxLink).toHaveClass(/active/)
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/views-navigate-to-today.test.ts

@@ -0,0 +1,42 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@setlist/services'
+import { TEST_CONSTANTS, localDate } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+const today = localDate()
+
+const seedData = H.SeedPipe(
+  H.TaskSeed({ id: 9110, userId, title: 'NavToday Task', scheduledDate: today, listPosition: 'a0', scheduledPosition: 'a0' })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('clicking Today in sidebar navigates to today view with active highlight', async ({ page }) => {
+  // Start from a different view so we can verify navigation
+  await page.goto('/inbox')
+
+  const nav = page.getByRole('navigation')
+  const todayLink = nav.getByRole('link', { name: 'Today' })
+
+  // Click the Today link
+  await todayLink.click()
+
+  // Verify URL changed to /today
+  await expect(page).toHaveURL('/today')
+
+  // Verify Today heading is visible
+  await expect(page.getByText(/Good (morning|afternoon|evening)/)).toBeVisible()
+
+  // Verify the seeded task is visible
+  await expect(page.getByRole('row', { name: 'NavToday Task' })).toBeVisible()
+
+  // Verify the Today link is highlighted as active
+  await expect(todayLink).toHaveClass(/active/)
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/views-navigate-to-upcoming.test.ts

@@ -0,0 +1,59 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@setlist/services'
+import { TEST_CONSTANTS, localDate } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+const tomorrow = localDate(1)
+const nextWeek = localDate(7)
+
+const seedData = H.SeedPipe(
+  H.TaskSeed({
+    id: 9130,
+    userId,
+    title: 'Tomorrow Task',
+    scheduledDate: tomorrow,
+    listPosition: 'a0',
+    scheduledPosition: 'a0'
+  }),
+  H.TaskSeed({
+    id: 9131,
+    userId,
+    title: 'Next Week Task',
+    scheduledDate: nextWeek,
+    listPosition: 'a1',
+    scheduledPosition: 'a0'
+  })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('clicking Upcoming in sidebar navigates to upcoming view with tasks grouped by date', async ({ page }) => {
+  // Start from a different view so we can verify navigation
+  await page.goto('/inbox')
+
+  const nav = page.getByRole('navigation')
+  const upcomingLink = nav.getByRole('link', { name: 'Upcoming' })
+
+  // Click the Upcoming link
+  await upcomingLink.click()
+
+  // Verify URL changed to /upcoming
+  await expect(page).toHaveURL('/upcoming')
+
+  // Verify Upcoming heading is visible
+  await expect(page.getByRole('heading', { name: 'Upcoming' })).toBeVisible()
+
+  // Verify the seeded tasks are visible
+  await expect(page.getByRole('row', { name: 'Tomorrow Task' })).toBeVisible()
+  await expect(page.getByRole('row', { name: 'Next Week Task' })).toBeVisible()
+
+  // Verify the Upcoming link is highlighted as active
+  await expect(upcomingLink).toHaveClass(/active/)
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/views-sidebar-built-in-views.test.ts

@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test'
+
+test('sidebar displays all four built-in views in order', async ({ page }) => {
+  await page.goto('/inbox')
+
+  const nav = page.getByRole('navigation')
+
+  // Verify all four built-in view links are visible
+  await expect(nav.getByRole('link', { name: 'Inbox' })).toBeVisible()
+  await expect(nav.getByRole('link', { name: 'Today' })).toBeVisible()
+  await expect(nav.getByRole('link', { name: 'Upcoming' })).toBeVisible()
+  await expect(nav.getByRole('link', { name: 'Completed' })).toBeVisible()
+
+  // Verify order: Inbox, Today, Upcoming, Completed
+  const links = nav.locator('a')
+  const allTexts = await links.allTextContents()
+  const viewNames = ['Inbox', 'Today', 'Upcoming', 'Completed']
+  const indices = viewNames.map((name) => allTexts.findIndex((text) => text.includes(name)))
+
+  for (let i = 1; i < indices.length; i++) {
+    expect(indices[i]!, `${viewNames[i]} should appear after ${viewNames[i - 1]}`).toBeGreaterThan(indices[i - 1]!)
+  }
+})

package/skills/maestro-examples/references/setlist/setlist-web/tests/views-today-shows-overdue.test.ts

@@ -0,0 +1,48 @@
+import { test, expect } from '@playwright/test'
+import { H } from '@setlist/services'
+import { TEST_CONSTANTS, localDate } from './constants'
+
+const userId = TEST_CONSTANTS.userId
+
+const today = localDate()
+const yesterday = localDate(-1)
+
+const seedData = H.SeedPipe(
+  H.TaskSeed({
+    id: 9120,
+    userId,
+    title: 'Overdue Task',
+    scheduledDate: yesterday,
+    listPosition: 'a0',
+    scheduledPosition: 'a0'
+  }),
+  H.TaskSeed({
+    id: 9121,
+    userId,
+    title: 'OverdueView Today Task',
+    scheduledDate: today,
+    listPosition: 'a1',
+    scheduledPosition: 'a1'
+  })
+)
+
+test.beforeAll(async () => {
+  await seedData.setup()
+})
+
+test.afterAll(async () => {
+  await seedData.teardown()
+})
+
+test('today view shows overdue tasks alongside tasks scheduled for today', async ({ page }) => {
+  await page.goto('/today')
+
+  // Verify the Today heading is visible
+  await expect(page.getByText(/Good (morning|afternoon|evening)/)).toBeVisible()
+
+  // The overdue task (yesterday) should be visible
+  await expect(page.getByRole('row', { name: 'Overdue Task' })).toBeVisible()
+
+  // The today task should also be visible
+  await expect(page.getByRole('row', { name: 'OverdueView Today Task' })).toBeVisible()
+})

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

@@ -0,0 +1,22 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "types": ["vite/client"],
+    "rootDirs": [".", ".react-router/types"],
+    "paths": {
+      "~/*": ["./app/*"]
+    }
+  },
+  "include": [
+    "app",
+    "tests",
+    "vite.config.ts",
+    "react-router.config.ts",
+    ".react-router",
+    "./environment.d.ts",
+    "playwright.config.ts"
+  ]
+}

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

@@ -0,0 +1,37 @@
+import { reactRouter } from '@react-router/dev/vite'
+import { sentryReactRouter } from '@sentry/react-router'
+import tailwindcss from '@tailwindcss/vite'
+import { iconsSpritesheet } from 'vite-plugin-icons-spritesheet'
+import { defineConfig } from 'vite'
+import tsconfigPaths from 'vite-tsconfig-paths'
+import { envOnlyMacros } from 'vite-env-only'
+
+export default defineConfig((config) => ({
+  plugins: [
+    envOnlyMacros(),
+    tsconfigPaths(),
+    tailwindcss(),
+    reactRouter(),
+    sentryReactRouter(
+      {
+        org: process.env.SENTRY_ORG,
+        project: process.env.SENTRY_PROJECT,
+        authToken: process.env.SENTRY_AUTH_TOKEN
+      },
+      config
+    ),
+    iconsSpritesheet({
+      inputDir: 'icons',
+      outputDir: 'app/icons',
+      fileName: 'sprite.svg',
+      withTypes: true,
+      typesOutputFile: 'app/icons/types.ts',
+      iconNameTransformer: (name) => name,
+      formatter: 'prettier'
+    })
+  ],
+  server: {
+    port: 3000,
+    strictPort: true
+  }
+}))

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

@@ -0,0 +1,69 @@
+# App Requirements
+
+A personal task manager modeled after Things. Users organize their work into tasks, projects, and areas. Tasks have titles, notes, scheduled dates, and can be completed or reordered via drag-and-drop.
+
+## Areas
+
+An area is a sphere of responsibility — an ongoing concern with no end date (e.g. "Health", "Work", "Finance").
+
+- An area has a title (required)
+- An area contains zero or more projects and zero or more standalone tasks (tasks not in a project)
+- Areas cannot be completed — they are ongoing
+- An area can be deleted
+- Areas appear in the sidebar and can be reordered via drag-and-drop
+
+## Projects
+
+A project is a collection of related tasks that work toward a specific goal. Projects are finite — they have a clear endpoint.
+
+- A project has a title (required) and notes (optional)
+- A project can have a scheduled date
+- A project belongs to at most one area
+- A project contains zero or more tasks, ordered by the user via drag-and-drop
+- A project can be completed — completing a project does not automatically complete its tasks
+- A project can be deleted
+- Projects appear in the sidebar and can be reordered via drag-and-drop
+
+## Tasks
+
+A task is the core unit of work.
+
+- A task has a title (required) and notes (optional, rich text)
+- A task can have a scheduled date — the date the user plans to work on it
+- A task can be completed by checking a checkbox; completed tasks move to a "Completed" view
+- A task can be deleted
+- Tasks belong to the Inbox by default if not assigned to a project or area or scheduled for a day
+- Tasks can be reordered via drag-and-drop within any list they appear in
+- A task can optionally belong to one project
+- A task can optionally belong to one area (inherited from its project, or assigned directly if the task has no project)
+
+## Views
+
+The app provides several built-in views for browsing tasks:
+
+- **Inbox** — tasks that have not been assigned to a project or area. The default landing place for new tasks. Tasks are ordered by the user via drag-and-drop.
+- **Today** — tasks whose scheduled date is today, plus overdue tasks. Ordered by the user via drag-and-drop.
+- **Upcoming** — a calendar-style view showing tasks grouped by their scheduled date, looking forward in time
+- **Completed** — all completed tasks, shown in reverse chronological order of completion
+
+## Dates
+
+- **Scheduled date**: the date the user intends to start or work on the task. Setting a scheduled date to today causes the task to appear in the Today view.
+
+## Drag-and-Drop Reordering
+
+- Tasks can be reordered via drag-and-drop within any list: Inbox, Today, a project's task list, or an area's task list
+- Projects and areas can be reordered in the sidebar via drag-and-drop
+- A task can be moved into a different project or area by dragging it
+- Reordering persists across sessions
+
+## Completion
+
+- Clicking a task's checkbox marks it as complete with a timestamp
+- Completed tasks disappear from active views and move to the Completed view
+- A completed task can be uncompleted, returning it to its original location
+- Projects can also be completed via a checkbox; a completed project disappears from the sidebar and moves to the Completed view
+
+## Authentication
+
+Authentication uses magic links — no passwords. A user enters their email, receives a link, and clicking it logs them in. The email also includes the raw token as a copyable string so the user can paste it into a login form on a different device. Uses `@maestro-js/auth` with `loginById()` after validating a selector/verifier token pair (same pattern as password reset links). All tasks, projects, and areas belong to the authenticated user. There is no sharing or collaboration — this is a single-user-per-account app.

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

@@ -0,0 +1,92 @@
+# Data Models
+
+Zod schemas for the personal task manager. Each section defines a zod model. Note: zod models are not necessarily one-to-one with database tables.
+
+## Users
+
+A user is a single account holder.
+
+```ts
+const userModel = z.object({
+  id: z.number(),
+  email: z.string(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Magic Links
+
+Authentication uses magic links sent via email — no passwords. The flow mirrors password reset tokens: a selector/verifier pair is generated, the verifier hash is stored, and the full token is emailed as a link. Clicking the link validates the token and calls `Auth.loginById()` to establish a session. The email also includes the raw token as a copyable string so users can paste it into a login form on a different device.
+
+```ts
+const magicLinkModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  selector: z.string(),
+  verifierHash: z.string(),
+  usedDate: isoZ.instant().nullable(),
+  expirationDate: isoZ.instant(),
+  createdDate: isoZ.instant()
+})
+```
+
+## Areas
+
+An area is an ongoing sphere of responsibility with no end date.
+
+```ts
+const areaModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  title: z.string(),
+  position: z.string(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Projects
+
+A project is a finite collection of tasks working toward a specific goal. A project optionally belongs to an area. Top-level projects (no area) share the sidebar position space with areas.
+
+```ts
+const projectModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  areaId: z.number().nullable(),
+  title: z.string(),
+  notes: z.string().nullable(),
+  scheduledDate: isoZ.date().nullable(),
+  position: z.string(),
+  completedDate: isoZ.instant().nullable(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```
+
+## Tasks
+
+A task is the core unit of work. A task optionally belongs to a project and/or an area. Tasks not assigned to a project, area, or scheduled date appear in the Inbox.
+
+`listPosition` orders the task within its container (project, area, or inbox). Moving a task between containers resets its `listPosition`. `scheduledPosition` orders the task within its scheduled date. Rescheduling a task resets its `scheduledPosition`.
+
+```ts
+const taskModel = z.object({
+  id: z.number(),
+  userId: z.number(),
+  projectId: z.number().nullable(),
+  areaId: z.number().nullable(),
+  title: z.string(),
+  notes: z.string().nullable(),
+  scheduledDate: isoZ.date().nullable(),
+  listPosition: z.string(),
+  scheduledPosition: z.string().nullable(),
+  completedDate: isoZ.instant().nullable(),
+  deletedDate: isoZ.instant().nullable(),
+  createdDate: isoZ.instant(),
+  lastModifiedDate: isoZ.instant()
+})
+```

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

@@ -0,0 +1,76 @@
+# Database Schema
+
+MySQL schema for the personal task manager. Derived from the zod models in `data-models.md`.
+
+## Tables
+
+```sql
+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/specs/drag-and-drop.md

@@ -0,0 +1,89 @@
+# Drag-and-Drop Technical Writeup
+
+Implementation plan for drag-and-drop reordering across the Setlist app using `@dnd-kit/core` + `@dnd-kit/sortable` + `@dnd-kit/utilities`.
+
+## Surfaces
+
+There are three distinct drag-and-drop contexts:
+
+| Context                                               | Draggable Items           | Drop Targets                                   | Cross-container?                          |
+| ----------------------------------------------------- | ------------------------- | ---------------------------------------------- | ----------------------------------------- |
+| Sidebar                                               | Areas, top-level projects | Reorder within sidebar; drop project onto area | Yes (project into/out of area)            |
+| Task list (Inbox, Today, Project detail, Area detail) | Tasks                     | Reorder within the current list                | No (reorder only)                         |
+| Task cross-container move                             | Tasks                     | Sidebar areas and projects                     | Yes (move task to different project/area) |
+
+## Position Strategy
+
+See [position-ordering.md](position-ordering.md) for the fractional indexing algorithm, `generateKeyBetween` implementation, position column definitions, and usage examples (reorder, insert, cross-container moves, new item creation).
+
+## Frontend Architecture
+
+### DnD Kit Setup
+
+```
+<DndContext>                          // one per page/layout
+  <SortableContext items={...}>       // one per sortable list
+    <SortableItem />                  // wraps each draggable item
+  </SortableContext>
+</DndContext>
+```
+
+### Sensors
+
+Use `useSensor(PointerSensor, { activationConstraint: { distance: 5 } })` to prevent accidental drags on click. Add `KeyboardSensor` for accessibility.
+
+### Collision Detection
+
+- **Single-list reorder**: `closestCenter` (default) works well
+- **Cross-container moves** (task to sidebar project/area): use `pointerWithin` or `rectIntersection` so the drop target is the container the pointer is inside
+
+### Overlay
+
+Use `<DragOverlay>` to render a styled clone of the dragged item. This avoids layout shifts in the source list during the drag.
+
+### Optimistic Updates
+
+1. `onDragEnd` fires with `active` (dragged item) and `over` (drop target)
+2. Immediately reorder the local state (React state or cache) so the UI updates without waiting for the server
+3. Fire the API call in the background
+4. On failure, roll back local state and show an error toast
+
+## Use Case Mapping
+
+| Use Case                    | Drag Source        | Drop Target                 | Fields Updated                                                   |
+| --------------------------- | ------------------ | --------------------------- | ---------------------------------------------------------------- |
+| AR5 — Reorder areas         | Area in sidebar    | Between areas in sidebar    | `areas.position`                                                 |
+| PR8 — Reorder projects      | Project in sidebar | Between projects in sidebar | `projects.position`                                              |
+| PR4 — Move project to area  | Project in sidebar | Area in sidebar             | `projects.position`, `projects.areaId`                           |
+| T8 — Reorder tasks in list  | Task in list view  | Between tasks in same list  | `tasks.listPosition`                                             |
+| T8 — Reorder tasks in Today | Task in Today view | Between tasks in Today      | `tasks.scheduledPosition`                                        |
+| T4 — Move task to project   | Task in any list   | Project in sidebar          | `tasks.listPosition`, `tasks.projectId`, `tasks.areaId`          |
+| T4 — Move task to area      | Task in any list   | Area in sidebar             | `tasks.listPosition`, `tasks.areaId`, `tasks.projectId` (nulled) |
+
+## Sidebar Mixed List
+
+The sidebar contains both areas and top-level projects in a single sortable list. Since both entity types share the same position space, they interleave by `position` value.
+
+To model this with dnd-kit, use a single `<SortableContext>` with a unified items array:
+
+```ts
+const sidebarItems = [...areas, ...topLevelProjects]
+  .sort((a, b) => a.position.localeCompare(b.position))
+  .map(item => ({ id: `${'areaId' in item ? 'project' : 'area'}-${item.id}`, ...item }))
+```
+
+Prefixed IDs (`area-1`, `project-5`) let `onDragEnd` determine the entity type and call the correct API.
+
+## Edge Cases
+
+- **Completed/deleted items**: exclude from sortable lists — they don't participate in drag-and-drop
+- **Moving a task out of inbox**: when a task gains a `projectId` or `areaId`, it's no longer an inbox task. No special handling needed — inbox is defined by the absence of project, area, and scheduled date.
+- **Moving a task to inbox**: set `projectId` and `areaId` to `null`. The task reappears in inbox if it also has no `scheduledDate`.
+
+## Dependencies
+
+```
+@dnd-kit/core
+@dnd-kit/sortable
+@dnd-kit/utilities
+```