joycraft 0.5.7 → 0.5.9

package/dist/{chunk-G342HURJ.js → chunk-Y6GBN6R4.js}

@@ -1493,6 +1493,183 @@ Based on the verdict:
 | Subagent can't run tests (missing deps) | Report the error as FAIL evidence |
 | No specs found and no path given | Tell user to provide a spec path or create a spec first |
 | Spec status is "Complete" | Still run verification -- "Complete" means the implementer thinks it's done, verification confirms |
+`,
+  "joycraft-bugfix.md": `---
+name: joycraft-bugfix
+description: Structured bug fix workflow \u2014 triage, diagnose, discuss with user, write a focused spec, hand off for implementation
+---
+
+# Bug Fix Workflow
+
+You are fixing a bug. Follow this process in order. Do not skip steps.
+
+**Guard clause:** If the user's request is clearly a new feature \u2014 not a bug, error, or unexpected behavior \u2014 say:
+"This sounds like a new feature rather than a bug fix. Try \`/joycraft-new-feature\` for a guided feature workflow."
+Then stop.
+
+---
+
+## Phase 1: Triage
+
+Establish what's broken. Your goal is to reproduce the bug or at minimum understand the symptom clearly.
+
+**Ask / gather:**
+- What is the symptom? (error message, unexpected behavior, crash, wrong output)
+- What are the steps to reproduce?
+- What is the expected behavior vs. actual behavior?
+- When did it start? (recent change, always been this way, intermittent)
+- Any relevant logs, screenshots, or error output?
+
+**Actions:**
+- If the user provides an error message or stack trace, read the referenced files immediately
+- If steps to reproduce are provided, try to reproduce the bug (run the failing command, test, or request)
+- If the bug is intermittent or hard to reproduce, gather more context: environment, OS, versions, config
+
+**Done when:** You can describe the symptom in one sentence and have either reproduced it or have enough context to diagnose without reproduction.
+
+---
+
+## Phase 2: Diagnose
+
+Find the root cause. Read code, trace the execution path, identify what's wrong and why.
+
+**Actions:**
+- Start from the error site (stack trace, failing test, broken UI) and trace backward
+- Read the relevant source files \u2014 don't guess based on file names alone
+- Identify the specific line(s), condition, or logic error causing the bug
+- Check git blame or recent commits if the bug was introduced by a recent change
+- Look for related bugs \u2014 is this a symptom of a deeper issue?
+
+**Done when:** You can explain the root cause in 2-3 sentences: what's wrong, why it's wrong, and where in the code it happens.
+
+---
+
+## Phase 3: Discuss
+
+Present your findings to the user. Do NOT start writing code or a spec yet.
+
+**Present:**
+1. **Symptom:** What the user sees (confirm your understanding matches theirs)
+2. **Root cause:** What's actually wrong in the code and why
+3. **Proposed fix:** What you think the fix is \u2014 be specific (which files, what changes)
+4. **Risk assessment:** What could go wrong with this fix? Any side effects?
+5. **Scope check:** Is this a simple fix or does it touch multiple systems?
+
+**Ask:**
+- "Does this match what you're seeing?"
+- "Are you comfortable with this approach, or do you want to explore alternatives?"
+- If the fix is large or risky: "Should we decompose this into smaller specs?"
+
+**Done when:** The user agrees with the diagnosis and proposed fix direction.
+
+---
+
+## Phase 4: Spec the Fix
+
+Write a bug fix spec to \`docs/specs/YYYY-MM-DD-bugfix-name.md\`. Create the \`docs/specs/\` directory if it doesn't exist.
+
+**Why:** Even bug fixes deserve a spec. It forces clarity on what "fixed" means, ensures test-first discipline, and creates a traceable record of the fix.
+
+Use this template:
+
+\`\`\`markdown
+# Fix [Bug Description] \u2014 Bug Fix Spec
+
+> **Parent Brief:** none (bug fix)
+> **Issue/Error:** [error message, issue link, or symptom description]
+> **Status:** Ready
+> **Date:** YYYY-MM-DD
+> **Estimated scope:** [1 session / N files / ~N lines]
+
+---
+
+## Bug
+
+What is broken? Describe the symptom the user experiences.
+
+## Root Cause
+
+What is wrong in the code and why? Name the specific file(s) and line(s).
+
+## Fix
+
+What changes will fix this? Be specific \u2014 describe the code change, not just "fix the bug."
+
+## Acceptance Criteria
+
+- [ ] [The bug no longer occurs \u2014 describe the correct behavior]
+- [ ] [No regressions in related functionality]
+- [ ] Build passes
+- [ ] Tests pass
+
+## Test Plan
+
+| Acceptance Criterion | Test | Type |
+|---------------------|------|------|
+| [Bug no longer occurs] | [Test that reproduces the bug, then verifies the fix] | [unit/integration/e2e] |
+| [No regressions] | [Existing tests still pass, or new regression test] | [unit/integration] |
+
+**Execution order:**
+1. Write a test that reproduces the bug \u2014 it should FAIL (red)
+2. Run the test to confirm it fails
+3. Apply the fix
+4. Run the test to confirm it passes (green)
+5. Run the full test suite to check for regressions
+
+**Smoke test:** [The bug reproduction test \u2014 fastest way to verify the fix works]
+
+**Before implementing, verify your test harness:**
+1. Run the reproduction test \u2014 it must FAIL (if it passes, you're not testing the actual bug)
+2. The test must exercise your actual code \u2014 not a reimplementation or mock
+3. Identify your smoke test \u2014 it must run in seconds, not minutes
+
+## Constraints
+
+- MUST: [any hard requirements for the fix]
+- MUST NOT: [any prohibitions \u2014 e.g., don't change the public API]
+
+## Affected Files
+
+| Action | File | What Changes |
+|--------|------|-------------|
+
+## Edge Cases
+
+| Scenario | Expected Behavior |
+|----------|------------------|
+\`\`\`
+
+**For trivial bugs:** The spec will be short. That's fine \u2014 the structure is the point, not the length.
+
+**For large bugs that span multiple files/systems:** Consider whether this should be decomposed into multiple specs. If so, create a brief first using \`/joycraft-new-feature\`, then decompose. A bug fix spec should be implementable in a single session.
+
+---
+
+## Phase 5: Hand Off
+
+Tell the user:
+
+\`\`\`
+Bug fix spec is ready: docs/specs/YYYY-MM-DD-bugfix-name.md
+
+Summary:
+- Bug: [one sentence]
+- Root cause: [one sentence]
+- Fix: [one sentence]
+- Estimated: 1 session
+
+To execute: Start a fresh session and:
+1. Read the spec
+2. Write the reproduction test (must fail)
+3. Apply the fix (test must pass)
+4. Run full test suite
+5. Run /joycraft-session-end to capture discoveries
+6. Commit and PR
+
+Ready to start?
+\`\`\`
+
+**Why:** A fresh session for implementation produces better results. This diagnostic session has context noise from exploration \u2014 a clean session with just the spec is more focused.
 `
 };
 var TEMPLATES = {
@@ -1874,13 +2051,59 @@ is required, though you can add one via the GitHub Checks API if you prefer.
 
 ---
 
+## Testing by Stack Type
+
+The scenario agent selects the appropriate test format based on the project's
+testing backbone. Each backbone tests the same holdout principle \u2014 observable
+behavior only, no source imports \u2014 but uses different tools.
+
+### Web Apps (Playwright)
+
+For Next.js, Vite, Nuxt, Remix, and other web frameworks. Tests run against a
+dev server or preview URL using a headless browser.
+
+- **Template:** \`example-scenario-web.spec.ts\`
+- **Config:** \`playwright.config.ts\`
+- **Package:** \`package-web.json\` (use instead of \`package.json\` for web projects)
+- **Run:** \`npx playwright test\`
+
+### Mobile Apps (Maestro)
+
+For React Native, Flutter, and native iOS/Android. Tests are declarative YAML
+flows that interact with a running app on a simulator.
+
+- **Template:** \`example-scenario-mobile.yaml\`
+- **Login sub-flow:** \`example-scenario-mobile-login.yaml\`
+- **Setup guide:** \`README-mobile.md\`
+- **Run:** \`maestro test example-scenario-mobile.yaml\`
+
+### API Backends (HTTP)
+
+For Express, FastAPI, Django, and other API-only backends. Tests send HTTP
+requests using Node.js built-in \`fetch\`.
+
+- **Template:** \`example-scenario-api.test.ts\`
+- **Run:** \`npx vitest run\`
+
+### CLI Tools & Libraries (native)
+
+For CLI tools, npm packages, and non-UI projects. Tests invoke the built
+binary via \`spawnSync\` and assert on stdout/stderr.
+
+- **Template:** \`example-scenario.test.ts\`
+- **Run:** \`npx vitest run\`
+
+---
+
 ## Adding scenarios
 
 ### Rules
 
-1. **Behavioral, not structural.** Test what the tool does, not how it is
-   built internally. Invoke the binary; assert on stdout, exit codes, and
-   filesystem state. Never import from \`../main-repo/src\`.
+These rules apply to ALL backbones:
+
+1. **Behavioral, not structural.** Test what the app does from a user's
+   perspective. For web: navigate and assert on content. For CLI: run commands
+   and check output. For API: send requests and check responses.
 
 2. **End-to-end.** Each test should represent something a real user would
    actually do. If you would not put it in a demo or docs example, reconsider
@@ -1890,9 +2113,8 @@ is required, though you can add one via the GitHub Checks API if you prefer.
    see source code. Any \`import\` that reaches into \`../main-repo/src\` breaks
    the pattern.
 
-4. **Independent.** Each test must be able to run in isolation. Use \`beforeEach\`
-   / \`afterEach\` to set up and tear down temp directories. Do not share mutable
-   state between tests.
+4. **Independent.** Each test must be able to run in isolation. No shared
+   mutable state between tests.
 
 5. **Deterministic.** Avoid network calls, timestamps, or random values in
    assertions unless the feature under test genuinely involves them.
@@ -1901,31 +2123,25 @@ is required, though you can add one via the GitHub Checks API if you prefer.
 
 \`\`\`
 $SCENARIOS_REPO/
-\u251C\u2500\u2500 example-scenario.test.ts   # Starter file \u2014 replace with real scenarios
+\u251C\u2500\u2500 example-scenario.test.ts           # CLI/binary scenario template
+\u251C\u2500\u2500 example-scenario-web.spec.ts       # Web app scenario template (Playwright)
+\u251C\u2500\u2500 example-scenario-api.test.ts       # API backend scenario template
+\u251C\u2500\u2500 example-scenario-mobile.yaml       # Mobile app scenario template (Maestro)
+\u251C\u2500\u2500 example-scenario-mobile-login.yaml # Reusable login sub-flow
+\u251C\u2500\u2500 playwright.config.ts               # Playwright config (web projects)
+\u251C\u2500\u2500 package.json                       # Default (vitest for CLI/API)
+\u251C\u2500\u2500 package-web.json                   # Alternative (Playwright for web)
+\u251C\u2500\u2500 README-mobile.md                   # Mobile testing setup guide
 \u251C\u2500\u2500 workflows/
-\u2502   \u2514\u2500\u2500 run.yml                # CI workflow (do not rename)
-\u251C\u2500\u2500 package.json
+\u2502   \u251C\u2500\u2500 run.yml                        # CI workflow (do not rename)
+\u2502   \u2514\u2500\u2500 generate.yml                   # Scenario generation workflow
+\u251C\u2500\u2500 prompts/
+\u2502   \u2514\u2500\u2500 scenario-agent.md              # Scenario agent instructions
 \u2514\u2500\u2500 README.md
 \`\`\`
 
-Add new \`.test.ts\` files at the top level or in subdirectories. Vitest will
-discover them automatically.
-
-### Example structure
-
-\`\`\`ts
-import { spawnSync } from "node:child_process";
-import { join } from "node:path";
-
-const CLI = join(__dirname, "..", "main-repo", "dist", "cli.js");
-
-it("init creates a CLAUDE.md file", () => {
-  const tmp = mkdtempSync(join(tmpdir(), "scenario-"));
-  const { status } = spawnSync("node", [CLI, "init", tmp], { encoding: "utf8" });
-  expect(status).toBe(0);
-  expect(existsSync(join(tmp, "CLAUDE.md"))).toBe(true);
-});
-\`\`\`
+Use the template that matches your project's stack. Remove the ones you
+don't need.
 
 ---
 
@@ -1937,6 +2153,7 @@ it("init creates a CLAUDE.md file", () => {
 | Visible to agent | Yes | No |
 | What they test | Units, modules, logic | End-to-end behavior |
 | Import source code | Yes | Never |
+| Test method | Unit test framework | Depends on backbone (Playwright/Maestro/vitest/fetch) |
 | Run on every push | Yes | Yes (via dispatch) |
 | Purpose | Catch regressions fast | Validate real behavior |
 
@@ -2085,6 +2302,304 @@ describe("CLI: init command (example \u2014 replace with your real scenarios)",
   }
 }
 `,
+  "scenarios/package-web.json": `{
+  "name": "$SCENARIOS_REPO",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "playwright test"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.50.0"
+  }
+}
+`,
+  "scenarios/playwright.config.ts": `import { defineConfig } from '@playwright/test';
+
+/**
+ * Playwright configuration for holdout scenario tests.
+ *
+ * BASE_URL can be set to test against a preview deployment URL
+ * or defaults to http://localhost:3000 for local dev server testing.
+ */
+export default defineConfig({
+  testDir: '.',
+  testMatch: '**/*.spec.ts',
+  timeout: 60_000,
+  retries: 0,
+  use: {
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+    headless: true,
+    screenshot: 'only-on-failure',
+  },
+  projects: [
+    { name: 'chromium', use: { browserName: 'chromium' } },
+  ],
+});
+`,
+  "scenarios/example-scenario-web.spec.ts": `/**
+ * Example Web Scenario Test (Playwright)
+ *
+ * This file is a template for scenario tests against web applications.
+ * The holdout pattern applies: test the running app through its UI,
+ * never import source code from the main repo.
+ *
+ * The main repo is available at ../main-repo and is already built.
+ * Tests run against either:
+ *   - A dev server started from ../main-repo (default)
+ *   - A preview deployment URL (set BASE_URL env var)
+ *
+ * DO:
+ *   - Navigate to pages, click elements, fill forms, assert on visible content
+ *   - Use page.locator() with accessible selectors (role, text, test-id)
+ *   - Keep each test fully independent
+ *
+ * DON'T:
+ *   - Import from ../main-repo/src \u2014 that defeats the holdout
+ *   - Test internal implementation details
+ *   - Rely on specific CSS classes or DOM structure (use accessible selectors)
+ */
+
+import { test, expect } from '@playwright/test';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+
+const MAIN_REPO = join(__dirname, '..', 'main-repo');
+let serverProcess: ChildProcess | undefined;
+
+/**
+ * Wait for a URL to become reachable.
+ */
+async function waitForServer(url: string, timeoutMs = 60_000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status < 500) return;
+    } catch {
+      // Server not ready yet
+    }
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  throw new Error(\`Server at \${url} did not become ready within \${timeoutMs}ms\`);
+}
+
+test.beforeAll(async () => {
+  // If BASE_URL is set, skip starting a dev server \u2014 test against the provided URL
+  if (process.env.BASE_URL) return;
+
+  serverProcess = spawn('npm', ['run', 'dev'], {
+    cwd: MAIN_REPO,
+    stdio: 'pipe',
+    env: { ...process.env, PORT: '3000' },
+  });
+
+  await waitForServer('http://localhost:3000');
+});
+
+test.afterAll(async () => {
+  if (serverProcess) {
+    serverProcess.kill('SIGTERM');
+    serverProcess = undefined;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Example scenarios \u2014 replace with real tests for your application
+// ---------------------------------------------------------------------------
+
+test.describe('Home page', () => {
+  test('loads successfully and shows main heading', async ({ page }) => {
+    await page.goto('/');
+    // Replace with your app's actual heading or key element
+    await expect(page.locator('h1')).toBeVisible();
+  });
+
+  test('navigates to a subpage', async ({ page }) => {
+    await page.goto('/');
+    // Replace with your app's actual navigation
+    // await page.click('text=About');
+    // await expect(page).toHaveURL(/\\/about/);
+    // await expect(page.locator('h1')).toContainText('About');
+  });
+});
+`,
+  "scenarios/example-scenario-api.test.ts": `/**
+ * Example API Scenario Test
+ *
+ * This file is a template for scenario tests against API-only backends.
+ * The holdout pattern applies: test the running server via HTTP requests,
+ * never import route handlers or source code from the main repo.
+ *
+ * The main repo is available at ../main-repo and is already built.
+ * Tests run against either:
+ *   - A server started from ../main-repo (default)
+ *   - A deployed URL (set BASE_URL env var)
+ *
+ * Uses Node.js built-in fetch \u2014 no additional HTTP client dependencies.
+ *
+ * DO:
+ *   - Send HTTP requests to endpoints, assert on status codes and response bodies
+ *   - Test realistic user actions (create, read, update, delete flows)
+ *   - Keep each test fully independent
+ *
+ * DON'T:
+ *   - Import from ../main-repo/src \u2014 that defeats the holdout
+ *   - Use supertest or similar tools that import the app directly
+ *   - Test internal implementation details
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { spawn, type ChildProcess } from 'node:child_process';
+import { join } from 'node:path';
+
+const MAIN_REPO = join(__dirname, '..', 'main-repo');
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+let serverProcess: ChildProcess | undefined;
+
+/**
+ * Wait for a URL to become reachable.
+ */
+async function waitForServer(url: string, timeoutMs = 60_000): Promise<void> {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url);
+      if (res.ok || res.status < 500) return;
+    } catch {
+      // Server not ready yet
+    }
+    await new Promise(r => setTimeout(r, 1000));
+  }
+  throw new Error(\`Server at \${url} did not become ready within \${timeoutMs}ms\`);
+}
+
+beforeAll(async () => {
+  // If BASE_URL is set externally, skip starting a server
+  if (process.env.BASE_URL) return;
+
+  serverProcess = spawn('npm', ['start'], {
+    cwd: MAIN_REPO,
+    stdio: 'pipe',
+    env: { ...process.env, PORT: '3000' },
+  });
+
+  await waitForServer(BASE_URL);
+}, 90_000);
+
+afterAll(() => {
+  if (serverProcess) {
+    serverProcess.kill('SIGTERM');
+    serverProcess = undefined;
+  }
+});
+
+// ---------------------------------------------------------------------------
+// Example scenarios \u2014 replace with real tests for your API
+// ---------------------------------------------------------------------------
+
+describe('API health', () => {
+  it('GET / returns a success status', async () => {
+    const res = await fetch(\`\${BASE_URL}/\`);
+    expect(res.status).toBeLessThan(500);
+  });
+});
+
+describe('API endpoints', () => {
+  it('GET /api/example returns JSON', async () => {
+    const res = await fetch(\`\${BASE_URL}/api/example\`);
+    // Replace with your actual endpoint
+    // expect(res.status).toBe(200);
+    // const body = await res.json();
+    // expect(body).toHaveProperty('data');
+  });
+
+  it('POST /api/example creates a resource', async () => {
+    // Replace with your actual endpoint and payload
+    // const res = await fetch(\\\`\\\${BASE_URL}/api/example\\\`, {
+    //   method: 'POST',
+    //   headers: { 'Content-Type': 'application/json' },
+    //   body: JSON.stringify({ name: 'test' }),
+    // });
+    // expect(res.status).toBe(201);
+    // const body = await res.json();
+    // expect(body).toHaveProperty('id');
+  });
+
+  it('returns 404 for unknown routes', async () => {
+    const res = await fetch(\`\${BASE_URL}/api/does-not-exist\`);
+    expect(res.status).toBe(404);
+  });
+});
+`,
+  "scenarios/example-scenario-mobile.yaml": `# Example Mobile Scenario Test (Maestro)
+#
+# This file is a template for scenario tests against mobile applications.
+# The holdout pattern applies: test the running app through its UI,
+# never reference source code from the main repo.
+#
+# Maestro tests are declarative YAML flows that interact with a running
+# app on a simulator/emulator. Install Maestro:
+#   curl -Ls "https://get.maestro.mobile.dev" | bash
+#
+# Run this flow:
+#   maestro test example-scenario-mobile.yaml
+#
+# DO:
+#   - Tap elements, fill inputs, assert on visible text
+#   - Use runFlow for reusable sub-flows (e.g., login)
+#   - Use assertWithAI for natural-language assertions
+#
+# DON'T:
+#   - Reference source code paths or internal identifiers
+#   - Depend on exact pixel positions (use text and accessibility labels)
+
+appId: com.example.myapp  # Replace with your app's bundle identifier
+name: "Core User Journey"
+tags:
+  - smoke
+  - holdout
+---
+# Step 1: Launch the app
+- launchApp
+
+# Step 2: Login (using a reusable sub-flow)
+- runFlow: example-scenario-mobile-login.yaml
+
+# Step 3: Verify the main screen loaded
+- assertVisible: "Home"
+
+# Step 4: Navigate to a feature
+# - tapOn: "Settings"
+# - assertVisible: "Account"
+
+# Step 5: AI-powered assertion (natural language)
+# - assertWithAI: "The main dashboard is visible with navigation tabs at the bottom"
+
+# Step 6: Go back
+# - back
+# - assertVisible: "Home"
+`,
+  "scenarios/example-scenario-mobile-login.yaml": `# Reusable Login Sub-Flow (Maestro)
+#
+# This flow handles authentication. Other flows include it via:
+#   - runFlow: example-scenario-mobile-login.yaml
+#
+# Replace the selectors and credentials with your app's actual login flow.
+
+appId: com.example.myapp
+name: "Login"
+---
+- assertVisible: "Sign In"
+- tapOn: "Email"
+- inputText: "test@example.com"
+- tapOn: "Password"
+- inputText: "testpassword123"
+- tapOn: "Log In"
+- assertVisible: "Home"  # Verify login succeeded
+`,
+  "scenarios/README-mobile.md": '# Mobile Scenario Testing with Maestro\n\nThis guide explains how to set up and run mobile holdout scenario tests using [Maestro](https://maestro.dev/).\n\n## Prerequisites\n\n- **Maestro CLI:** `curl -Ls "https://get.maestro.mobile.dev" | bash`\n- **Java 17+** (required by Maestro)\n- **Simulator/Emulator:**\n  - iOS: Xcode with iOS Simulator (macOS only)\n  - Android: Android Studio with an AVD configured\n\n> **Important:** Joycraft does not install Maestro or manage simulators. This is your responsibility.\n\n## Running Tests Locally\n\n```bash\n# Boot your simulator/emulator first, then:\nmaestro test example-scenario-mobile.yaml\n\n# Run all flows in a directory:\nmaestro test .maestro/\n```\n\n## Writing Flows\n\nMaestro flows are declarative YAML. Core commands:\n\n| Command | Purpose |\n|---------|--------|\n| `launchApp` | Start or restart the app |\n| `tapOn: "text"` | Tap an element by visible text or test ID |\n| `inputText: "value"` | Type into a focused field |\n| `assertVisible: "text"` | Assert an element is on screen |\n| `assertNotVisible: "text"` | Assert an element is NOT on screen |\n| `scroll` | Scroll down |\n| `back` | Press the back button |\n| `runFlow: file.yaml` | Run a reusable sub-flow |\n| `assertWithAI: "description"` | Natural-language assertion (AI-powered) |\n\n## CI Options\n\n### Option A: Maestro Cloud (paid, easiest)\n\nUpload your app binary and flows to Maestro Cloud. No simulator management.\n\n```yaml\n- uses: mobile-dev-inc/action-maestro-cloud@v2\n  with:\n    api-key: ${{ secrets.MAESTRO_API_KEY }}\n    app-file: app.apk  # or app.ipa\n    workspace: .\n```\n\n### Option B: Self-hosted emulator (free, more setup)\n\nSpin up an Android emulator on a Linux runner or iOS simulator on a macOS runner.\n\n> **Cost note:** macOS GitHub Actions runners are ~10x more expensive than Linux runners.\n\n## The Holdout Pattern\n\nThese tests live in the scenarios repo, separate from the main codebase. The scenario agent generates them from specs. They test observable behavior through the app\'s UI \u2014 never referencing source code or internal implementation.\n',
   "scenarios/prompts/scenario-agent.md": `You are a QA engineer working in a holdout test repository. You CANNOT access the main repository's source code. Your job is to write or update behavioral scenario tests based on specs that are pushed from the main repo.
 
 ## What You Have Access To
@@ -2092,7 +2607,23 @@ describe("CLI: init command (example \u2014 replace with your real scenarios)",
 - This scenarios repository (test files, \`specs/\` mirror, \`package.json\`)
 - The incoming spec (provided below)
 - A list of existing test files and spec mirrors (provided below)
-- The main repo is available at \`../main-repo\` and is already built \u2014 you can invoke its CLI or entry point via \`execSync\`/\`spawnSync\`, but you MUST NOT import from \`../main-repo/src\`
+- The main repo is available at \`../main-repo\` and is already built
+- The testing strategy for this project (provided below)
+
+## Testing Strategy
+
+This project uses the **$TESTING_BACKBONE** testing backbone.
+
+Select the correct test format based on the backbone:
+
+| Backbone | Tool | Test Format | File Extension | How to Test |
+|----------|------|-------------|---------------|-------------|
+| \`playwright\` | Playwright | Browser-based E2E | \`.spec.ts\` | Navigate pages, click elements, assert on visible content |
+| \`maestro\` | Maestro | YAML flows | \`.yaml\` | Tap elements, fill inputs, assert on screen state |
+| \`api\` | fetch (Node.js built-in) | HTTP requests | \`.test.ts\` | Send requests to endpoints, assert on responses |
+| \`native\` | vitest + spawnSync | CLI/binary invocation | \`.test.ts\` | Run commands, assert on stdout/stderr/exit codes |
+
+If the backbone is not provided or unrecognized, default to \`native\`.
 
 ## Triage Decision Tree
 
@@ -2111,7 +2642,7 @@ If you SKIP, write a brief comment in the relevant test file (or a new one) expl
 - A new output format or file that gets generated
 - A new user-facing behavior that doesn't map to any existing test file
 
-Name the file after the feature area: \`[feature-area].test.ts\`. One feature area per test file.
+Name the file after the feature area using the correct extension for the backbone.
 
 ### UPDATE \u2014 Modify an existing test file if the spec:
 - Changes behavior that is already tested
@@ -2122,25 +2653,20 @@ Match to the most relevant existing test file by feature area.
 
 **If you are unsure whether a spec is user-facing, err on the side of writing a test.**
 
-## Test Writing Rules
-
-1. **Behavioral only.** Test observable output \u2014 stdout, stderr, exit codes, files created/modified on disk. Never test internal implementation details or import source modules.
+## Test Writing Rules (All Backbones)
 
-2. **Use \`execSync\` or \`spawnSync\`.** Invoke the built binary at \`../main-repo/dist/cli.js\` (or whatever the main repo's entry point is). Check \`../main-repo/package.json\` to find the correct entry point if unsure.
+1. **Behavioral only.** Test observable behavior \u2014 what a real user would see. Never test internal implementation details or import source modules.
+2. **Each test is fully independent.** No shared mutable state between tests.
+3. **Assert on realistic user actions.** Write tests that reflect what a real user would do.
+4. **Never import from the parent repo's source.** If you find yourself writing \`import { ... } from '../main-repo/src/...'\`, stop \u2014 that defeats the holdout.
 
-3. **Use vitest.** Import \`describe\`, \`it\`, \`expect\` from \`vitest\`. Use \`beforeEach\`/\`afterEach\` for temp directory setup/teardown.
+## Backbone: native (CLI/Binary)
 
-4. **Each test is fully independent.** No shared mutable state between tests. Each test that touches the filesystem gets its own temp directory via \`mkdtempSync\`.
-
-5. **Assert on realistic user actions.** Write tests that reflect what a real user would do \u2014 not what the implementation happens to do.
-
-6. **Never import from the parent repo's source.** If you find yourself writing \`import { ... } from '../main-repo/src/...'\`, stop \u2014 that defeats the holdout.
-
-## Test File Template
+Use when the project is a CLI tool, library, or has no web/mobile UI.
 
 \`\`\`typescript
-import { execSync, spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, rmSync, readFileSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
@@ -2153,39 +2679,122 @@ function runCLI(args: string[], cwd?: string) {
     cwd: cwd ?? process.cwd(),
     env: { ...process.env, NO_COLOR: '1' },
   });
-  return {
-    stdout: result.stdout ?? '',
-    stderr: result.stderr ?? '',
-    status: result.status ?? 1,
-  };
+  return { stdout: result.stdout ?? '', stderr: result.stderr ?? '', status: result.status ?? 1 };
 }
 
-describe('[feature area]: [behavior being tested]', () => {
+describe('[feature area]', () => {
   let tmpDir: string;
+  beforeEach(() => { tmpDir = mkdtempSync(join(tmpdir(), 'scenarios-')); });
+  afterEach(() => { rmSync(tmpDir, { recursive: true, force: true }); });
 
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), 'scenarios-'));
+  it('[observable behavior]', () => {
+    const { stdout, status } = runCLI(['command', 'args'], tmpDir);
+    expect(status).toBe(0);
+    expect(stdout).toContain('expected output');
   });
+});
+\`\`\`
 
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
+## Backbone: playwright (Web Apps)
+
+Use when the project is a web application (Next.js, Vite, Nuxt, etc.).
+
+\`\`\`typescript
+import { test, expect } from '@playwright/test';
+
+// Tests run against BASE_URL (configured in playwright.config.ts)
+// The dev server is started automatically or BASE_URL points to a preview deploy
+
+test.describe('[feature area]', () => {
+  test('[observable behavior]', async ({ page }) => {
+    await page.goto('/');
+    await expect(page.locator('h1')).toBeVisible();
   });
 
-  it('[specific observable behavior]', () => {
-    const { stdout, status } = runCLI(['command', 'args'], tmpDir);
-    expect(status).toBe(0);
-    expect(stdout).toContain('expected output');
+  test('[user interaction]', async ({ page }) => {
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.click('button[type="submit"]');
+    await expect(page).toHaveURL(/dashboard/);
   });
 });
 \`\`\`
 
+## Backbone: api (API Backends)
+
+Use when the project is an API-only backend (Express, FastAPI, etc.).
+
+\`\`\`typescript
+import { describe, it, expect } from 'vitest';
+
+const BASE_URL = process.env.BASE_URL || 'http://localhost:3000';
+
+describe('[feature area]', () => {
+  it('[endpoint behavior]', async () => {
+    const res = await fetch(\\\`\\\${BASE_URL}/api/endpoint\\\`);
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toHaveProperty('data');
+  });
+
+  it('[error handling]', async () => {
+    const res = await fetch(\\\`\\\${BASE_URL}/api/not-found\\\`);
+    expect(res.status).toBe(404);
+  });
+});
+\`\`\`
+
+## Backbone: maestro (Mobile Apps)
+
+Use when the project is a mobile application (React Native, Flutter, native iOS/Android).
+
+\`\`\`yaml
+appId: com.example.myapp
+name: "[feature area]: [behavior being tested]"
+tags:
+  - holdout
+---
+- launchApp
+- tapOn: "Sign In"
+- inputText: "test@example.com"
+- tapOn: "Submit"
+- assertVisible: "Welcome"
+# Use assertWithAI for complex visual assertions:
+# - assertWithAI: "The dashboard shows a list of recent items"
+\`\`\`
+
+## Graceful Degradation
+
+If the primary backbone tool is not available in this repo, fall back to the next deepest testable layer:
+
+| Layer | What's Tested | When to Use |
+|-------|-------------|-------------|
+| **Layer 4: UI** | Full user flows through browser/simulator | \`@playwright/test\` or Maestro is installed |
+| **Layer 3: API** | HTTP requests against running server | Server can be started from \`../main-repo\` |
+| **Layer 2: Logic** | Unit tests via test runner | Test runner (vitest/jest) is available |
+| **Layer 1: Static** | Build, typecheck, lint | Build toolchain is available |
+
+**Fallback rules:**
+- If backbone is \`playwright\` but \`@playwright/test\` is NOT in this repo's \`package.json\`: fall back to \`api\` (fetch-based HTTP tests)
+- If backbone is \`maestro\` but no simulator context is available: fall back to \`api\` if a server can be started, else \`native\`
+- If backbone is \`api\` but no server start script exists: fall back to \`native\`
+- \`native\` is always available as the floor
+
+Start each test file with a comment indicating the testing layer:
+\`// Testing Layer: [4|3|2|1] - [UI|API|Logic|Static]\`
+
+If you fell back from the intended backbone, note this in your commit message:
+\`scenarios: [action] for [spec] (layer: [N], reason: [why])\`
+
 ## Checklist Before Committing
 
 - [ ] Decision: SKIP / NEW / UPDATE (and why)
+- [ ] Correct backbone selected (or fallback justified)
 - [ ] Tests assert on observable behavior, not implementation
 - [ ] No imports from \`../main-repo/src\`
-- [ ] Each test has its own temp directory if it touches the filesystem
-- [ ] File is named after the feature area, not the spec
+- [ ] Each test is independent (own temp dir, own state)
+- [ ] File uses the correct extension for the backbone
+- [ ] Testing layer comment at top of file
 `,
   "scenarios/workflows/generate.yml": `# Scenario Generation Workflow
 #
@@ -2285,7 +2894,9 @@ jobs:
           ## Context
 
           Existing test files in this repo: \${{ steps.context.outputs.existing_tests }}
-          Existing spec mirrors: \${{ steps.context.outputs.existing_specs }}"
+          Existing spec mirrors: \${{ steps.context.outputs.existing_specs }}
+
+          Testing backbone: \${{ github.event.client_payload.testing_backbone || 'native' }}"
 
       # \u2500\u2500 7. Commit any changes the agent made \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
       - name: Commit scenario changes
@@ -2861,4 +3472,4 @@ export {
   SKILLS,
   TEMPLATES
 };
-//# sourceMappingURL=chunk-G342HURJ.js.map
+//# sourceMappingURL=chunk-Y6GBN6R4.js.map