@sun-asterisk/sungen 2.4.5 → 2.5.0

package/src/orchestrator/project-initializer.ts

@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { execSync } from 'child_process';
+import { AI_RULES_FILE_MAPPING } from './ai-rules-updater';
 
 export class ProjectInitializer {
   private baseCwd: string;
@@ -47,8 +48,9 @@ export class ProjectInitializer {
     // Create tsconfig.json if doesn't exist
     this.createTsConfig();
 
-    // Create specs/base.ts for shared context
+    // Create specs/base.ts for shared context and specs/test-data.ts for runtime data
     this.createSpecsBase();
+    this.createSpecsTestData();
 
     // Create/update .gitignore
     this.updateGitignore();
@@ -62,6 +64,9 @@ export class ProjectInitializer {
     // Create VS Code settings for Copilot auto-attach
     this.createVSCodeSettings();
 
+    // Create root .mcp.json for Claude Code
+    this.createClaudeMCPConfig();
+
     // Display summary
     this.displaySummary(normalizedProjectName);
   }
@@ -190,46 +195,112 @@ export class ProjectInitializer {
   private createVSCodeSettings(): void {
     const settingsPath = path.join(this.cwd, '.vscode', 'settings.json');
 
-    if (fs.existsSync(settingsPath)) {
-      this.skippedItems.push('.vscode/settings.json');
-      return;
-    }
+    if (!fs.existsSync(settingsPath)) {
+      const settingsDir = path.dirname(settingsPath);
+      if (!fs.existsSync(settingsDir)) {
+        fs.mkdirSync(settingsDir, { recursive: true });
+      }
 
-    const settingsDir = path.dirname(settingsPath);
-    if (!fs.existsSync(settingsDir)) {
-      fs.mkdirSync(settingsDir, { recursive: true });
+      const settings = {
+        'github.copilot.chat.agent.runTasks': true,
+        'chat.tools.terminal.autoApprove': {
+          sungen: true,
+          'npx playwright': true,
+        },
+      };
+
+      fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
+      this.createdItems.push('.vscode/settings.json');
+    } else {
+      this.skippedItems.push('.vscode/settings.json');
     }
 
-    const settings = {
-      'github.copilot.chat.agent.runTasks': true,
-      'chat.tools.terminal.autoApprove': {
-        sungen: true,
-        'npx playwright': true,
+    // .vscode/mcp.json (Copilot format) — safe-merge Playwright + Figma entries
+    this.mergeMCPConfig(
+      path.join(this.cwd, '.vscode', 'mcp.json'),
+      'servers',
+      {
+        playwright: {
+          command: 'npx',
+          args: ['@playwright/mcp@latest'],
+        },
+        figma: {
+          type: 'http',
+          url: 'https://mcp.figma.com/mcp',
+        },
       },
-    };
-
-    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n', 'utf-8');
-    this.createdItems.push('.vscode/settings.json');
-
-    // Create MCP config for Playwright browser tools
-    const mcpPath = path.join(this.cwd, '.vscode', 'mcp.json');
-
-    if (fs.existsSync(mcpPath)) {
-      this.skippedItems.push('.vscode/mcp.json');
-      return;
-    }
+      '.vscode/mcp.json',
+    );
+  }
 
-    const mcpConfig = {
-      servers: {
+  /**
+   * Create root .mcp.json for Claude Code — safe-merge Playwright + Figma entries
+   */
+  private createClaudeMCPConfig(): void {
+    this.mergeMCPConfig(
+      path.join(this.cwd, '.mcp.json'),
+      'mcpServers',
+      {
         playwright: {
+          type: 'stdio',
           command: 'npx',
           args: ['@playwright/mcp@latest'],
         },
+        figma: {
+          type: 'http',
+          url: 'https://mcp.figma.com/mcp',
+        },
       },
-    };
+      '.mcp.json',
+    );
+  }
+
+  /**
+   * Add MCP server entries without overwriting user config.
+   * Preserves existing entries with the same key — user edits always win.
+   */
+  private mergeMCPConfig(
+    filePath: string,
+    rootKey: string,
+    newServers: Record<string, unknown>,
+    displayName: string,
+  ): void {
+    const dir = path.dirname(filePath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+
+    let config: Record<string, Record<string, unknown>> = {};
+    const existed = fs.existsSync(filePath);
 
-    fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n', 'utf-8');
-    this.createdItems.push('.vscode/mcp.json');
+    if (existed) {
+      try {
+        config = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+      } catch {
+        this.skippedItems.push(`${displayName} (invalid JSON, skipped)`);
+        return;
+      }
+    }
+
+    if (!config[rootKey] || typeof config[rootKey] !== 'object') {
+      config[rootKey] = {};
+    }
+
+    let added = 0;
+    for (const [name, entry] of Object.entries(newServers)) {
+      if (!config[rootKey][name]) {
+        config[rootKey][name] = entry;
+        added++;
+      }
+    }
+
+    if (added === 0) {
+      this.skippedItems.push(displayName);
+      return;
+    }
+
+    fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    this.createdItems.push(existed ? `${displayName} (updated)` : displayName);
   }
 
   /**
@@ -264,51 +335,14 @@ export class ProjectInitializer {
   }
 
   /**
-   * Create AI rules files for GitHub Copilot and Claude Code
+   * Create AI rules files for GitHub Copilot and Claude Code.
+   * Shares `AI_RULES_FILE_MAPPING` with `sungen update` so a newly added
+   * skill / command template only needs to be registered once.
    */
   private createAIRules(): void {
     const aiTemplateDir = path.join(__dirname, 'templates', 'ai-instructions');
 
-    // File mapping: [templateFile, outputPath]
-    const fileMapping: [string, string][] = [
-      // Config
-      ['claude-config.md', 'CLAUDE.md'],
-      ['copilot-config.md', '.github/copilot-instructions.md'],
-
-      // Commands — Claude Code
-      ['claude-cmd-add-screen.md', '.claude/commands/sungen/add-screen.md'],
-      ['claude-cmd-create-test.md', '.claude/commands/sungen/create-test.md'],
-      ['claude-cmd-run-test.md', '.claude/commands/sungen/run-test.md'],
-      ['claude-cmd-review.md', '.claude/commands/sungen/review.md'],
-
-      // Commands — GitHub Copilot
-      ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
-      ['copilot-cmd-create-test.md', '.github/prompts/sungen-create-test.prompt.md'],
-      ['copilot-cmd-run-test.md', '.github/prompts/sungen-run-test.prompt.md'],
-      ['copilot-cmd-review.md', '.github/prompts/sungen-review.prompt.md'],
-
-      // Skills — Claude Code
-      ['claude-skill-gherkin-syntax.md', '.claude/skills/sungen-gherkin-syntax/SKILL.md'],
-      ['claude-skill-selector-keys.md', '.claude/skills/sungen-selector-keys/SKILL.md'],
-      ['claude-skill-error-mapping.md', '.claude/skills/sungen-error-mapping/SKILL.md'],
-      ['claude-skill-tc-generation.md', '.claude/skills/sungen-tc-generation/SKILL.md'],
-      ['claude-skill-test-design-techniques.md', '.claude/skills/sungen-test-design-techniques/SKILL.md'],
-      ['claude-skill-selector-fix.md', '.claude/skills/sungen-selector-fix/SKILL.md'],
-      ['claude-skill-tc-review.md', '.claude/skills/sungen-tc-review/SKILL.md'],
-      ['claude-skill-viewpoint.md', '.claude/skills/sungen-viewpoint/SKILL.md'],
-
-      // Skills — GitHub Copilot (separate copies with Copilot-friendly descriptions)
-      ['github-skill-sungen-gherkin-syntax.md', '.github/skills/sungen-gherkin-syntax/SKILL.md'],
-      ['github-skill-sungen-selector-keys.md', '.github/skills/sungen-selector-keys/SKILL.md'],
-      ['github-skill-sungen-error-mapping.md', '.github/skills/sungen-error-mapping/SKILL.md'],
-      ['github-skill-sungen-tc-generation.md', '.github/skills/sungen-tc-generation/SKILL.md'],
-      ['github-skill-sungen-test-design-techniques.md', '.github/skills/sungen-test-design-techniques/SKILL.md'],
-      ['github-skill-sungen-selector-fix.md', '.github/skills/sungen-selector-fix/SKILL.md'],
-      ['github-skill-sungen-tc-review.md', '.github/skills/sungen-tc-review/SKILL.md'],
-      ['github-skill-sungen-viewpoint.md', '.github/skills/sungen-viewpoint/SKILL.md'],
-    ];
-
-    for (const [templateFile, outputRelPath] of fileMapping) {
+    for (const [templateFile, outputRelPath] of AI_RULES_FILE_MAPPING) {
       const outputPath = path.join(this.cwd, outputRelPath);
 
       if (fs.existsSync(outputPath)) {
@@ -350,6 +384,27 @@ export class ProjectInitializer {
     this.createdItems.push('specs/generated/base.ts');
   }
 
+  /**
+   * Create specs/test-data.ts for runtime YAML loading
+   */
+  private createSpecsTestData(): void {
+    const testDataPath = path.join(this.cwd, 'specs', 'generated', 'test-data.ts');
+
+    if (fs.existsSync(testDataPath)) {
+      this.skippedItems.push('specs/generated/test-data.ts');
+      return;
+    }
+
+    const baseDir = path.dirname(testDataPath);
+    if (!fs.existsSync(baseDir)) {
+      fs.mkdirSync(baseDir, { recursive: true });
+    }
+
+    const content = this.readTemplate('specs-test-data.ts');
+    fs.writeFileSync(testDataPath, content, 'utf-8');
+    this.createdItems.push('specs/generated/test-data.ts');
+  }
+
   /**
    * Read a template file from the templates directory
    */
@@ -372,26 +427,78 @@ export class ProjectInitializer {
       this.createdItems.push('package.json');
     }
 
-    // Check if @playwright/test is already installed
+    // Ensure standard scripts exist in package.json
+    this.ensurePackageScripts(packageJsonPath);
+
+    // Check which dependencies are missing
+    const requiredDeps = ['@playwright/test', '@types/node', 'yaml'];
+    let missingDeps: string[] = requiredDeps;
     try {
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
-      if (deps['@playwright/test']) {
-        console.log('✓ @playwright/test already installed\n');
-        return;
-      }
+      missingDeps = requiredDeps.filter(d => !deps[d]);
     } catch {
-      // package.json just created, proceed with install
+      // package.json just created, install all
+    }
+
+    if (missingDeps.length === 0) {
+      console.log('✓ All dependencies already installed\n');
+      return;
     }
 
-    // Install Playwright and TypeScript types
-    console.log('📦 Installing @playwright/test and @types/node...\n');
-    execSync('npm install -D @playwright/test @types/node', execOpts);
+    console.log(`📦 Installing ${missingDeps.join(', ')}...\n`);
+    execSync(`npm install -D ${missingDeps.join(' ')}`, execOpts);
 
     console.log('\n🎭 Installing Playwright browsers...\n');
     execSync('npx playwright install', execOpts);
   }
 
+  /**
+   * Ensure package.json has standard Playwright + Sungen scripts.
+   * Only adds missing scripts — never overwrites user customizations.
+   */
+  private ensurePackageScripts(packageJsonPath: string): void {
+    let packageJson: Record<string, any>;
+    try {
+      packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+    } catch {
+      return;
+    }
+
+    if (!packageJson.scripts || typeof packageJson.scripts !== 'object') {
+      packageJson.scripts = {};
+    }
+
+    const standardScripts: Record<string, string> = {
+      'test': 'playwright test specs/generated/',
+      'test:headed': 'playwright test specs/generated/ --headed',
+      'test:debug': 'playwright test specs/generated/ --debug',
+      'test:ui': 'playwright test specs/generated/ --ui',
+      'report': 'playwright show-report',
+      'generate': 'sungen generate --all',
+      'install:browsers': 'npx playwright install chromium',
+    };
+
+    let added = 0;
+    for (const [name, command] of Object.entries(standardScripts)) {
+      // Skip if user already has this script (don't overwrite)
+      // Exception: overwrite the npm init default test script
+      const existing = packageJson.scripts[name];
+      if (existing && existing !== 'echo "Error: no test specified" && exit 1') {
+        continue;
+      }
+      packageJson.scripts[name] = command;
+      added++;
+    }
+
+    if (added > 0) {
+      // Also mark as private (test projects should not be published)
+      packageJson.private = true;
+      fs.writeFileSync(packageJsonPath, JSON.stringify(packageJson, null, 2) + '\n', 'utf-8');
+      console.log(`📝 Added ${added} standard script(s) to package.json\n`);
+    }
+  }
+
   /**
    * Get Playwright configuration template
    */

package/src/orchestrator/screen-manager.ts

@@ -296,6 +296,8 @@ export class ScreenManager {
 
 ## Overview
 - **URL Path:** ${pagePath}
+- **Live URL:** <!-- optional, full URL for live page capture (falls back to baseURL + URL Path) -->
+- **Figma URL:** <!-- optional, Figma frame URL for design-driven capture (requires Figma MCP) -->
 - **Auth Required:** no
 - **Platform:** web
 

package/src/orchestrator/templates/ai-instructions/claude-cmd-add-screen.md

@@ -1,8 +1,8 @@
 ---
 name: add-screen
-description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can auto-capture a live-page screenshot via Playwright MCP'
+description: 'Add a new Sungen screen — scaffolds directories, helps fill spec.md, and can capture visuals from Figma (pre-launch) or live page via the capture skills'
 argument-hint: [screen-name] [url-path]
-allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot
+allowed-tools: Read, Grep, Bash, Glob, Edit, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot
 ---
 
 You are adding a new Sungen screen for test generation.
@@ -25,27 +25,25 @@ Run:
 sungen add --screen <screen> --path <path>
 ```
 
-### 2. Prepare requirements
+### 2. Fill spec.md
 
-Use `AskUserQuestion` to let the user choose how to prepare requirements — this is the foundation for high-quality test generation:
+Use `AskUserQuestion`: *"Fill `spec.md` now?"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
 
-- **Fill `spec.md` + capture live-page screenshot** (Recommended) — best test quality
-- **Fill `spec.md` only** — app not live yet, or no need for visuals
-- **Capture live-page screenshot only** — spec will come later
-- **Skip requirements prep** — proceed to `/sungen:create-test` immediately
+If yes → open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
-**If "Fill `spec.md`" is chosen**: open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states.
+### 3. Capture visual source
 
-**If "Capture live-page screenshot" is chosen**:
-1. Read `baseURL` from `playwright.config.ts` (fall back to `APP_BASE_URL` env, then ask the user).
-2. `browser_navigate` to `<baseURL><path>`.
-3. If redirected to login → ask the user to log in manually in the MCP browser, wait for confirmation, then re-navigate. (No auth persistence needed here — that's handled by Phase 0.5 in `sungen-selector-fix` when tests run.)
-4. `browser_take_screenshot` with `filename: "qa/screens/<screen>/requirements/ui/<screen>.png"`.
-5. If the screen has multiple important states (empty, loaded, error, modal open), offer additional captures named `<screen>-<state>.png`.
+Use `AskUserQuestion`: *"Capture a visual reference for this screen?"* — always offer all three so pre-launch projects work:
 
-If the user has additional UI designs (Figma exports, mockups), suggest copying them to `requirements/ui/`.
+- **Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+- **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+- **Skip** — user will drop images manually into `requirements/ui/` later, or rely on `/sungen:create-test` to prompt again
 
-### 3. Next steps
+Each capture skill writes outputs into `qa/screens/<screen>/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill so behavior stays consistent with `/sungen:create-test`.
+
+If the user has additional UI designs (mockups, hand-drawn sketches), suggest copying them to `requirements/ui/` — `sungen-capture-local` will pick them up during `/sungen:create-test`.
+
+### 4. Next steps
 
 Tell the user what was created, then use `AskUserQuestion` to offer next steps:
 

package/src/orchestrator/templates/ai-instructions/claude-cmd-create-test.md

@@ -2,7 +2,7 @@
 name: create-test
 description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (20+ scenarios per viewpoint)'
 argument-hint: [screen-name]
-allowed-tools: Read, Grep, Bash, Glob, AskUserQuestion
+allowed-tools: Read, Grep, Bash, Glob, Write, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot, mcp__figma__get_design_context, mcp__figma__get_variable_defs, mcp__figma__get_screenshot
 ---
 
 ## Role
@@ -25,10 +25,12 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
      - **Continue without it** — generate tests from spec and other sources only
    - Summarize what you found in requirements and present to the user.
 4. **Screen input** (supplements requirements, or is primary source if no requirements):
-   - Use `AskUserQuestion` to ask: **Figma design** (provide Figma URL — recommended), **UI images** (screenshots/mockups in `requirements/ui/`), or **Live page scan** (optional, via Playwright MCP)?
-   - Recommend Figma or UI images first. Live page scan is optional — useful to verify specs vs actual UI or capture real data.
-   - If live page scan: `browser_navigate` → ONE `browser_snapshot`. If auth redirect → ask user to log in manually. Never use `browser_run_code` or `browser_evaluate` to inject cookies.
-   - If exploring, verify and supplement requirements — flag any discrepancies found.
+   - Use `AskUserQuestion` to ask the user to pick a visual source — always offer all three options so pre-launch projects work:
+     - **Figma design** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill
+     - **UI images** (existing screenshots/mockups in `requirements/ui/`) — invoke `sungen-capture-local` skill
+     - **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill
+   - Each capture skill writes outputs into `qa/screens/<screen>/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill so behavior stays consistent across commands.
+   - After the capture skill returns, cross-check its output against `spec.md` and flag any discrepancies before moving on.
 5. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. When requirements exist, use the "Requirements-Driven Generation" strategy.
 6. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
 7. Show summary, then use `AskUserQuestion` to offer next steps:

package/src/orchestrator/templates/ai-instructions/claude-cmd-delivery.md

@@ -0,0 +1,71 @@
+---
+name: delivery
+description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
+argument-hint: "[screen-name...] (omit for all screens)"
+allowed-tools: Bash, Read, AskUserQuestion
+---
+
+## Role
+
+You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic `sungen delivery` CLI that performs all parsing and CSV export. Your role is minimal — just run the CLI and help the user if pre-flight checks fail.
+
+## Parameters
+
+Parse **screens** from `$ARGUMENTS`:
+- If empty → CLI will process **all** screens in `qa/screens/`
+- If provided → pass them through to the CLI
+
+## Steps
+
+### 1. Invoke the CLI
+
+Run via Bash (single command, no extra parsing):
+
+```bash
+npx sungen delivery <screens>
+```
+
+- If no screen args → just run `npx sungen delivery`
+- If screen args → pass them as positional arguments
+
+The CLI handles:
+- Scope detection (all screens vs specific)
+- Pre-flight source checks with colorful output
+- Parsing `.feature`, `.spec.ts`, `test-data.yaml`, `test-results/results.json`
+- Generating CSV at `qa/deliverables/<screen>-testcases.csv`
+- Printing summary table
+
+### 2. Handle pre-flight failures (if CLI exits non-zero)
+
+If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per screen.
+
+Use `AskUserQuestion` to offer next steps:
+
+**Options:**
+- **Fix missing sources** (Recommended) — Print the suggested commands from CLI output and stop. User will run those commands manually, then re-invoke `/sungen:delivery`.
+- **Continue with available screens** — Re-run as `npx sungen delivery <screens> --continue-on-missing` to skip screens with blocking issues.
+- **Cancel** — Exit.
+
+### 3. Show summary + offer next steps (on success)
+
+Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`:
+
+- **Open a specific CSV** — Help user inspect one of the exported files with Read tool.
+- **Run tests to refresh results** — Suggest `/sungen:run-test <screen>` to update `test-results/results.json`, then re-run delivery.
+- **Export another screen** — User can run `/sungen:delivery <other-screen>`.
+- **Done** — Exit.
+
+## Important notes
+
+- **Do NOT parse files yourself** — the CLI is the source of truth for parsing logic. Your job is orchestration + user interaction.
+- **Do NOT modify feature/spec.ts/test-data files** — the delivery is read-only.
+- **The CLI already respects `@manual` tags, skips `@steps:` base scenarios, groups by Category 2, and generates UTF-8 BOM CSV for Excel compatibility with Vietnamese.**
+- **Pre-flight check is built into the CLI** — use `--skip-preflight` only in CI/automated pipelines where checks are done externally.
+
+## CLI Reference
+
+```
+sungen delivery [screens...]
+  [--skip-preflight]          Skip pre-flight checks (not recommended)
+  [--continue-on-missing]     Skip screens with blocking misses
+```

package/src/orchestrator/templates/ai-instructions/claude-cmd-run-test.md

@@ -18,7 +18,7 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
 2. **Phase 0 — Selector Pre-gen**: if `selectors.yaml` is missing/empty or doesn't cover the feature file's `[Reference]`s, run Phase 0 from `sungen-selector-fix` — confirm with user, `browser_navigate` → one `browser_snapshot` → merge YAML entries.
 3. **Phase 0.5 — Auth Persistence**: if the feature has `@auth:<role>` tags and `specs/.auth/<role>.json` is missing/expired, run Phase 0.5 from `sungen-selector-fix` — user logs in manually in MCP browser → `browser_storage_state` → `specs/.auth/<role>.json`. Offer `sungen makeauth <role>` as CLI fallback only if `browser_storage_state` isn't available in this MCP version.
-4. Compile: `sungen generate --screen <screen>`.
+4. Compile: `sungen generate --screen <screen>` (default: runtime data loading from YAML). Use `--inline-data` only if user requests compile-time hardcoded values.
 
 ## Run & Fix (phased — per `sungen-selector-fix` skill)
 
@@ -27,6 +27,33 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 7. **Phase 3 — Full Run**: Run all tests. Fix only **new** failures (elements unique to `@normal`/`@low`). Max 1 attempt. Don't loop on low-priority failures.
 8. **Phase 4 — Regression**: One final full run. Report results. No more fix loops.
 
+## Playwright command guidelines
+
+**Per-screen JSON results** — each run must write its JSON report to a dedicated path co-located with the `.spec.ts`, so `sungen delivery` can read the correct results per screen:
+
+```bash
+# ✅ Correct — per-screen output file via env var
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<screen>/<screen>-test-result.json \
+  npx playwright test specs/generated/<screen>/<screen>.spec.ts
+```
+
+Output: `specs/generated/<screen>/<screen>-test-result.json`
+
+**DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
+
+```bash
+# ❌ Wrong — --reporter flag disables the config's JSON reporter
+npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=list
+
+# ❌ Wrong — no env var → writes to default test-results/results.json
+# (overwritten on every screen run, loses per-screen tracking)
+npx playwright test specs/generated/<screen>/<screen>.spec.ts
+```
+
+If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
+
+`sungen delivery` reads the per-screen file first, falls back to the global `test-results/results.json` if missing.
+
 ## Next steps
 
 After showing results, use `AskUserQuestion` to offer next steps:

package/src/orchestrator/templates/ai-instructions/claude-config.md

@@ -15,8 +15,12 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-viewpoint` | 10 UI patterns x 4 viewpoints — coverage checklists |
 | `sungen-selector-keys` | YAML key generation from `[Reference]` names, suffixes, lookup priority |
 | `sungen-selector-fix` | Selector generation from live page, auto-fix strategy |
+| `sungen-delivery` | Export Gherkin + Playwright results → CSV test case deliverable |
+| `sungen-capture-figma` | Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP |
+| `sungen-capture-local` | Load existing UI assets (screenshots, mockups, Figma exports) from `requirements/ui/` |
+| `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 
-## Workflow (4 AI commands)
+## Workflow (5 AI commands)
 
 | Command | What it does |
 |---|---|
@@ -24,8 +28,9 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (no selectors) |
 | `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (60% threshold) |
 | `/sungen:run-test <name>` | Generate `selectors.yaml` from live page, compile, run, auto-fix |
+| `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
 
-**Order:** add-screen → create-test → review → run-test.
+**Order:** add-screen → create-test → review → run-test → delivery.
 
 After each command completes, use `AskUserQuestion` to present the next actions as selectable options. Never just print text — always give clickable choices so the user can continue the workflow seamlessly.
 
@@ -35,17 +40,31 @@ After each command completes, use `AskUserQuestion` to present the next actions
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
 ├── selectors/<screen>.yaml        # Element locators (generated during run-test)
-├── test-data/<screen>.yaml        # Test data variables
+├── test-data/<screen>.yaml        # Test data variables (loaded at runtime)
+├── test-data/<screen>.staging.yaml    # Environment override (optional)
+├── test-data/<screen>.production.yaml # Environment override (optional)
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
+
+qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen:delivery)
+qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ```
 
+## Test Data
+
+`{{variable}}` references in `.feature` map to keys in `test-data/<screen>.yaml`. Data is loaded **at runtime** — the same generated `.spec.ts` works across environments without recompiling.
+
+**Environment overrides**: `SUNGEN_ENV=staging npx playwright test` merges `<screen>.staging.yaml` on top of `<screen>.yaml`. Create `<screen>.<env>.yaml` for environment-specific values (different credentials, URLs, test users).
+
 ## CLI Commands
 
 ```bash
 sungen add --screen <name> --path <url-path>               # Scaffold screen directories
 sungen add --screen <name> --path <path> --feature <name>   # Scaffold with sub-feature
-sungen generate --screen <name>                              # Compile .feature → .spec.ts
+sungen generate --screen <name>                              # Compile .feature → .spec.ts (runtime data)
+sungen generate --screen <name> --inline-data                # Compile with hardcoded data (legacy)
 sungen generate --all                                        # Compile all screens
+sungen delivery                                              # Export all screens → CSV + XLSX
+sungen delivery <screen>                                     # Export a single screen
 ```