joycraft 0.5.6 → 0.5.8

package/dist/{chunk-QIYIJ7VR.js → chunk-A2CQG5J5.js}

@@ -904,6 +904,28 @@ Based on their answer, use the appropriate git rules in the Behavioral Boundarie
 - Ask "should I push?" or "should I create a PR?" \u2014 the answer is always yes, just do it
 \`\`\`
 
+### Permission Mode Recommendation
+
+After the git autonomy question and before the risk interview, recommend a Claude Code permission mode based on what you've learned so far. Present this guidance:
+
+> **What permission mode should you use?**
+>
+> | Your situation | Use | Why |
+> |---|---|---|
+> | Autonomous spec execution | \`--permission-mode dontAsk\` + allowlist | Only pre-approved commands run |
+> | Long session with some trust | \`--permission-mode auto\` | Safety classifier reviews each action |
+> | Interactive development | \`--permission-mode acceptEdits\` | Auto-approves file edits, prompts for commands |
+>
+> You do NOT need \`--dangerously-skip-permissions\`. The modes above provide autonomy with safety.
+
+**If the user chose Autonomous git:** Recommend \`auto\` mode as a good default -- it provides autonomy while the safety classifier catches risky operations. Note that \`dontAsk\` is even more autonomous but requires a well-configured allowlist.
+
+**If the user chose Cautious git:** Recommend \`auto\` mode -- it matches their preference for safety with less manual intervention than the default.
+
+**If the risk interview reveals production databases, live APIs, or billing systems:** Upgrade the recommendation to \`dontAsk\` with a tight allowlist. Explain that \`dontAsk\` with explicit deny patterns is safer than \`auto\` for high-risk environments because it uses a deterministic allowlist rather than a classifier.
+
+This is informational only -- do not change the user's permission mode. Just tell them what to use when they launch Claude Code.
+
 ### Risk Interview
 
 Before applying upgrades, ask 3-5 targeted questions to capture what's dangerous in this project. Skip this if \`docs/context/production-map.md\` or \`docs/context/dangerous-assumptions.md\` already exist (offer to update instead).
@@ -1300,6 +1322,26 @@ Adjust the content based on the actual interview responses:
 - Only include NEVER rules for directories/files the user specified
 - If the user allowed certain network tools or package managers, exclude those
 
+## Recommended Permission Mode
+
+After generating the boundaries above, also recommend a Claude Code permission mode. Include this section in your output:
+
+\`\`\`
+### Recommended Permission Mode
+
+You don't need \\\`--dangerously-skip-permissions\\\`. Safer alternatives exist:
+
+| Your situation | Use | Why |
+|---|---|---|
+| Autonomous spec execution | \\\`--permission-mode dontAsk\\\` + allowlist above | Only pre-approved commands run |
+| Long session with some trust | \\\`--permission-mode auto\\\` | Safety classifier reviews each action |
+| Interactive development | \\\`--permission-mode acceptEdits\\\` | Auto-approves file edits, prompts for commands |
+
+**For lockdown mode, we recommend \\\`--permission-mode dontAsk\\\`** combined with the deny patterns above. This gives you full autonomy for allowed operations while blocking everything else -- no classifier overhead, no prompts, and no safety bypass.
+
+\\\`--dangerously-skip-permissions\\\` disables ALL safety checks. The modes above give you autonomy without removing the guardrails.
+\`\`\`
+
 ## Step 4: Offer to Apply
 
 If the user asks you to apply the changes:
@@ -1308,6 +1350,149 @@ If the user asks you to apply the changes:
 2. **For settings.json:** Read the existing \`.claude/settings.json\`, show the user what the \`permissions.deny\` array will look like after adding the new patterns. Ask for confirmation before writing.
 
 **Never auto-apply. Always show the exact changes and wait for explicit approval.**
+`,
+  "joycraft-verify.md": `---
+name: joycraft-verify
+description: Spawn an independent verifier subagent to check an implementation against its spec -- read-only, no code edits, structured pass/fail verdict
+---
+
+# Verify Implementation Against Spec
+
+The user wants independent verification of an implementation. Your job is to find the relevant spec, extract its acceptance criteria and test plan, then spawn a separate verifier subagent that checks each criterion and produces a structured verdict.
+
+**Why a separate subagent?** Anthropic's research found that agents reliably skew positive when grading their own work. Separating the agent doing the work from the agent judging it consistently outperforms self-evaluation. The verifier gets a clean context window with no implementation bias.
+
+## Step 1: Find the Spec
+
+If the user provided a spec path (e.g., \`/joycraft-verify docs/specs/2026-03-26-add-widget.md\`), use that path directly.
+
+If no path was provided, scan \`docs/specs/\` for spec files. Pick the most recently modified \`.md\` file in that directory. If \`docs/specs/\` doesn't exist or is empty, tell the user:
+
+> No specs found in \`docs/specs/\`. Please provide a spec path: \`/joycraft-verify path/to/spec.md\`
+
+## Step 2: Read and Parse the Spec
+
+Read the spec file and extract:
+
+1. **Spec name** -- from the H1 title
+2. **Acceptance Criteria** -- the checklist under the \`## Acceptance Criteria\` section
+3. **Test Plan** -- the table under the \`## Test Plan\` section, including any test commands
+4. **Constraints** -- the \`## Constraints\` section if present
+
+If the spec has no Acceptance Criteria section, tell the user:
+
+> This spec doesn't have an Acceptance Criteria section. Verification needs criteria to check against. Add acceptance criteria to the spec and try again.
+
+If the spec has no Test Plan section, note this but proceed -- the verifier can still check criteria by reading code and running any available project tests.
+
+## Step 3: Identify Test Commands
+
+Look for test commands in these locations (in priority order):
+
+1. The spec's Test Plan section (look for commands in backticks or "Type" column entries like "unit", "integration", "e2e", "build")
+2. The project's CLAUDE.md (look for test/build commands in the Development Workflow section)
+3. Common defaults based on the project type:
+   - Node.js: \`npm test\` or \`pnpm test --run\`
+   - Python: \`pytest\`
+   - Rust: \`cargo test\`
+   - Go: \`go test ./...\`
+
+Build a list of specific commands the verifier should run.
+
+## Step 4: Spawn the Verifier Subagent
+
+Use Claude Code's Agent tool to spawn a subagent with the following prompt. Replace the placeholders with the actual content extracted in Steps 2-3.
+
+\`\`\`
+You are a QA verifier. Your job is to independently verify an implementation against its spec. You have NO context about how the implementation was done -- you are checking it fresh.
+
+RULES -- these are hard constraints, not suggestions:
+- You may READ any file using the Read tool or cat
+- You may RUN these specific test/build commands: [TEST_COMMANDS]
+- You may NOT edit, create, or delete any files
+- You may NOT run commands that modify state (no git commit, no npm install, no file writes)
+- You may NOT install packages or access the network
+- Report what you OBSERVE, not what you expect or hope
+
+SPEC NAME: [SPEC_NAME]
+
+ACCEPTANCE CRITERIA:
+[ACCEPTANCE_CRITERIA]
+
+TEST PLAN:
+[TEST_PLAN]
+
+CONSTRAINTS:
+[CONSTRAINTS_OR_NONE]
+
+YOUR TASK:
+For each acceptance criterion, determine if it PASSES or FAILS based on evidence:
+
+1. Run the test commands listed above. Record the output.
+2. For each acceptance criterion:
+   a. Check if there is a corresponding test and whether it passes
+   b. If no test exists, read the relevant source files to verify the criterion is met
+   c. If the criterion cannot be verified by reading code or running tests, mark it MANUAL CHECK NEEDED
+3. For criteria about build/test passing, actually run the commands and report results.
+
+OUTPUT FORMAT -- you MUST use this exact format:
+
+VERIFICATION REPORT
+
+| # | Criterion | Verdict | Evidence |
+|---|-----------|---------|----------|
+| 1 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
+| 2 | [criterion text] | PASS/FAIL/MANUAL CHECK NEEDED | [what you observed] |
+[continue for all criteria]
+
+SUMMARY: X/Y criteria passed. [Z failures need attention. / All criteria verified.]
+
+If any test commands fail to run (missing dependencies, wrong command, etc.), report the error as evidence for a FAIL verdict on the relevant criterion.
+\`\`\`
+
+## Step 5: Format and Present the Verdict
+
+Take the subagent's response and present it to the user in this format:
+
+\`\`\`
+## Verification Report -- [Spec Name]
+
+| # | Criterion | Verdict | Evidence |
+|---|-----------|---------|----------|
+| 1 | ... | PASS | ... |
+| 2 | ... | FAIL | ... |
+
+**Overall: X/Y criteria passed.**
+
+[If all passed:]
+All criteria verified. Ready to commit and open a PR.
+
+[If any failed:]
+N failures need attention. Review the evidence above and fix before proceeding.
+
+[If any MANUAL CHECK NEEDED:]
+N criteria need manual verification -- they can't be checked by reading code or running tests alone.
+\`\`\`
+
+## Step 6: Suggest Next Steps
+
+Based on the verdict:
+
+- **All PASS:** Suggest committing and opening a PR, or running \`/joycraft-session-end\` to capture discoveries.
+- **Some FAIL:** List the failed criteria and suggest the user fix them, then run \`/joycraft-verify\` again.
+- **MANUAL CHECK NEEDED items:** Explain what needs human eyes and why automation couldn't verify it.
+
+**Do NOT offer to fix failures yourself.** The verifier reports; the human (or implementation agent in a separate turn) decides what to do. This separation is the whole point.
+
+## Edge Cases
+
+| Scenario | Behavior |
+|----------|----------|
+| Spec has no Test Plan | Warn that verification is weaker without a test plan, but proceed by checking criteria through code reading and any available project-level tests |
+| All tests pass but a criterion is not testable | Mark as MANUAL CHECK NEEDED with explanation |
+| 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 |
 `
 };
 var TEMPLATES = {
@@ -1689,13 +1874,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
@@ -1705,9 +1936,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.
@@ -1716,31 +1946,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.
 
 ---
 
@@ -1752,6 +1976,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 |
 
@@ -1900,6 +2125,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
@@ -1907,7 +2430,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
 
@@ -1926,7 +2465,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
@@ -1937,25 +2476,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
+## Test Writing Rules (All Backbones)
 
-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.
+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.
 
-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.
+## Backbone: native (CLI/Binary)
 
-3. **Use vitest.** Import \`describe\`, \`it\`, \`expect\` from \`vitest\`. Use \`beforeEach\`/\`afterEach\` for temp directory setup/teardown.
-
-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';
@@ -1968,39 +2502,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
 #
@@ -2100,7 +2717,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
@@ -2676,4 +3295,4 @@ export {
   SKILLS,
   TEMPLATES
 };
-//# sourceMappingURL=chunk-QIYIJ7VR.js.map
+//# sourceMappingURL=chunk-A2CQG5J5.js.map