@sun-asterisk/sungen 2.4.6 → 2.5.1

package/src/orchestrator/figma/figma-scaffolder.ts

@@ -0,0 +1,209 @@
+/**
+ * FigmaScaffolder: orchestrates Figma URL → spec_figma.md + ui/*.png.
+ *
+ * Flow: parseFigmaUrl → assertSafeToUse → loadPat → cache check
+ *       → getFileNodes → filterFigmaNode → getImageUrls → downloadImages
+ *       → renderSpecFigma → write files
+ *
+ * Idempotent: re-running overwrites spec_figma.md and PNGs.
+ * spec.md: written only if absent (never overwritten).
+ * Cache: keyed by file+version+node; bypassed when refresh=true.
+ *
+ * Helpers (image download, name utils, stubs) live in figma-scaffolder-helpers.ts.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import ora from 'ora';
+
+import { parseFigmaUrl } from '../../tools/figma/figma-url-parser';
+import { assertSafeToUse, loadPat } from '../../tools/figma/figma-auth';
+import { getFileNodes, getImageUrls } from '../../tools/figma/figma-rest-client';
+import { filterFigmaNode, extractTextLabels, extractVariants } from '../../tools/figma/figma-node-filter';
+import * as FigmaCache from '../../tools/figma/figma-cache';
+import { renderSpecFigma } from './spec-figma-renderer';
+import {
+  sanitizeName,
+  readGeneratorVersion,
+  minimalSpecMd,
+  downloadImages,
+} from './figma-scaffolder-helpers';
+import type { FigmaScaffolderOptions, FigmaScaffolderResult } from './figma-scaffolder-types';
+
+// Max variant images to download in addition to the main frame.
+const MAX_VARIANT_IMAGES = 5;
+
+export class FigmaScaffolder {
+  /**
+   * Orchestrate the full Figma → screen files flow.
+   *
+   * @throws Error with remediation instructions on auth / parse / network failure.
+   */
+  static async run(options: FigmaScaffolderOptions): Promise<FigmaScaffolderResult> {
+    const cwd = options.cwd ?? process.cwd();
+    const refresh = options.refresh ?? false;
+    const scale = options.scale ?? 2;
+    const spinner = ora({ stream: process.stderr });
+
+    // 1. Parse and validate Figma URL
+    const ref = parseFigmaUrl(options.figmaUrl);
+    if (!ref) {
+      throw new Error(
+        `Invalid Figma URL: "${options.figmaUrl}"\n` +
+          'Expected format: https://www.figma.com/design/<KEY>/<name>?node-id=1-23',
+      );
+    }
+    if (!ref.nodeId) {
+      throw new Error(
+        'Figma URL must include a node-id query parameter.\n' +
+          'Select a specific frame in Figma, right-click → "Copy link to selection".',
+      );
+    }
+
+    // 2. Security scan + PAT load
+    spinner.start('Checking Figma auth…');
+    await assertSafeToUse(cwd);
+
+    const pat = loadPat(cwd);
+    if (!pat) {
+      spinner.fail('Figma PAT not found.');
+      throw new Error('Figma PAT is not configured.\nRun: sungen figma auth set');
+    }
+    spinner.succeed('Figma auth OK');
+
+    // 3. Ensure screen directories exist
+    const screenDir = path.join(cwd, 'qa', 'screens', options.screenName);
+    const requirementsDir = path.join(screenDir, 'requirements');
+    const uiDir = path.join(requirementsDir, 'ui');
+    fs.mkdirSync(uiDir, { recursive: true });
+
+    // 4. Resolve node: prefer raw-JSON cache to spare Starter-tier REST quota.
+    // On Figma Starter, `/v1/files/:key/nodes` counts against a tiny daily
+    // bucket (observed Retry-After up to 4+ days). If we already have a
+    // cached raw response, reuse it and skip the call entirely.
+    let versionId: string;
+    let nodeDocument: unknown;
+    let fromCache = false;
+
+    if (!refresh) {
+      const cachedVersion = FigmaCache.findLatestCachedVersion(cwd, ref.fileKey, ref.nodeId);
+      if (cachedVersion) {
+        const cachedRaw = FigmaCache.get(cwd, ref.fileKey, cachedVersion, ref.nodeId, 'raw');
+        if (cachedRaw) {
+          try {
+            nodeDocument = JSON.parse(cachedRaw.toString('utf8'));
+            versionId = cachedVersion;
+            fromCache = true;
+            spinner.info(`Reusing cached Figma node (version ${versionId}) — pass --refresh to re-fetch`);
+          } catch {
+            // Corrupt cache → fall through to API fetch
+          }
+        }
+      }
+    }
+
+    if (!fromCache) {
+      spinner.start(`Fetching Figma node ${ref.nodeId}…`);
+      let nodesResponse: Awaited<ReturnType<typeof getFileNodes>>;
+      try {
+        nodesResponse = await getFileNodes(pat, ref.fileKey, [ref.nodeId]);
+      } catch (err) {
+        spinner.fail('Failed to fetch Figma node.');
+        throw err;
+      }
+
+      versionId = nodesResponse.version;
+      const nodeEntry = nodesResponse.nodes[ref.nodeId];
+      if (!nodeEntry) {
+        spinner.fail(`Node ${ref.nodeId} not found in Figma file.`);
+        throw new Error(
+          `Node "${ref.nodeId}" was not found in file "${ref.fileKey}".\n` +
+            'Check the Figma URL — the node-id may be incorrect.',
+        );
+      }
+      spinner.succeed(`Fetched node: ${nodeEntry.document.name}`);
+      nodeDocument = nodeEntry.document;
+
+      // Persist raw (unfiltered) node JSON for downstream LLM synthesis + future
+      // cache-first runs. Re-runs overwrite atomically.
+      FigmaCache.put(
+        cwd,
+        ref.fileKey,
+        versionId,
+        ref.nodeId,
+        'raw',
+        JSON.stringify(nodeDocument),
+      );
+    }
+
+    // nodeEntry.document shape — trust the cached bytes we wrote earlier.
+    const nodeEntry = { document: nodeDocument as Parameters<typeof filterFigmaNode>[0] };
+
+    // 5. Filter node tree + extract metadata
+    const filteredNode = filterFigmaNode(nodeEntry.document);
+    const textLabels = extractTextLabels(filteredNode);
+    const variants = extractVariants(filteredNode);
+
+    // 6. Resolve image node IDs (main + up to MAX_VARIANT_IMAGES variants)
+    const imageNodeIds = [ref.nodeId, ...variants.slice(0, MAX_VARIANT_IMAGES).map((v) => v.nodeId)];
+    const scaleKind = `${scale}x` as `${number}x`;
+
+    // 7. Warm image cache (skipped when refresh=true)
+    const cachedImages = new Map<string, Buffer>();
+    if (!refresh) {
+      for (const nodeId of imageNodeIds) {
+        const cached = FigmaCache.get(cwd, ref.fileKey, versionId, nodeId, scaleKind);
+        if (cached) cachedImages.set(nodeId, cached);
+      }
+    }
+
+    // 8. Fetch image URLs for uncached nodes
+    const uncachedIds = imageNodeIds.filter((id) => !cachedImages.has(id));
+    let imageUrls: Record<string, string | null> = {};
+    if (uncachedIds.length > 0) {
+      spinner.start(`Fetching image URLs for ${uncachedIds.length} node(s)…`);
+      try {
+        const urlsResponse = await getImageUrls(pat, ref.fileKey, uncachedIds, { scale, format: 'png' });
+        imageUrls = urlsResponse.images;
+      } catch (err) {
+        spinner.fail('Failed to fetch image URLs.');
+        throw err;
+      }
+      spinner.succeed('Image URLs fetched');
+    }
+
+    // 9. Download (or copy from cache) images
+    const frameBaseName = sanitizeName(filteredNode.name);
+    const variantNames = variants.slice(0, MAX_VARIANT_IMAGES).map((v) => v.name);
+    const imagePaths = await downloadImages({
+      cwd, fileKey: ref.fileKey, versionId, uiDir,
+      imageNodeIds, mainNodeId: ref.nodeId, variantNames,
+      cachedImages, imageUrls, frameBaseName, scaleKind, spinner,
+    });
+
+    // 10. Render and write spec_figma.md (always overwritten)
+    spinner.start('Rendering spec_figma.md…');
+    const markdown = renderSpecFigma({
+      filteredNode, variants, textLabels, imagePaths,
+      fileKey: ref.fileKey, nodeId: ref.nodeId, versionId,
+      fetchedAt: new Date().toISOString(),
+      generatorVersion: readGeneratorVersion(cwd),
+    });
+    const specFigmaPath = path.join(requirementsDir, 'spec_figma.md');
+    fs.writeFileSync(specFigmaPath, markdown, 'utf8');
+    spinner.succeed('spec_figma.md written');
+
+    // 11. Write spec.md stub only if absent
+    const specMdPath = path.join(requirementsDir, 'spec.md');
+    const specMdCreated = !fs.existsSync(specMdPath);
+    if (specMdCreated) {
+      fs.writeFileSync(specMdPath, minimalSpecMd(options.screenName), 'utf8');
+      spinner.info('spec.md created (stub — fill in your requirements)');
+    }
+
+    // 12. Evict old cache versions (keep last 3)
+    FigmaCache.bustOldVersions(cwd, ref.fileKey, versionId);
+
+    return { specFigmaPath, imagePaths, specMdCreated };
+  }
+}

package/src/orchestrator/figma/node-path-collapser.ts

@@ -0,0 +1,38 @@
+/**
+ * Pure helper: collapse consecutive repeated segments in a Figma node path.
+ *
+ * Delimiter: " > " (space-angle-space).
+ * Collapsed runs use the multiplication sign × (U+00D7).
+ *
+ * Examples:
+ *   "A > B > C"                              → "A > B > C"          (unchanged)
+ *   "A > B > B > C"                          → "A > B×2 > C"
+ *   "Container > Container > Container > X"  → "Container×3 > X"
+ *   "A > A > A > A > A > B > C"             → "A×5 > B > C"
+ *   "A"                                       → "A"                  (single)
+ *   ""                                        → ""                   (empty)
+ */
+export function collapseNodePath(path: string): string {
+  if (!path) return path;
+
+  const DELIMITER = ' > ';
+  const segments = path.split(DELIMITER);
+
+  const collapsed: string[] = [];
+  let i = 0;
+
+  while (i < segments.length) {
+    const current = segments[i];
+    let count = 1;
+
+    // Count consecutive identical segments
+    while (i + count < segments.length && segments[i + count] === current) {
+      count++;
+    }
+
+    collapsed.push(count > 1 ? `${current}×${count}` : current);
+    i += count;
+  }
+
+  return collapsed.join(DELIMITER);
+}

package/src/orchestrator/figma/spec-figma-renderer.ts

@@ -0,0 +1,80 @@
+/**
+ * Pure function: filtered Figma node → spec_figma.md envelope string.
+ *
+ * The envelope is deterministic and stable across runs: frontmatter,
+ * auto-gen banner, Frame metadata, Screenshots, and a SYNTHESIS marker.
+ * Narrative sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
+ * Data Columns, Navigation) are appended BELOW the marker by the
+ * sungen-figma-source skill, which reads the raw cached node JSON.
+ *
+ * Section renderers live in spec-figma-section-renderers.ts.
+ *
+ * This module never reads from disk or makes network calls.
+ */
+
+import type {
+  FilteredFigmaNode,
+  FigmaTextLabel,
+  FigmaVariantDefinition,
+} from '../../tools/figma/figma-client-types';
+import {
+  renderFrontmatter,
+  renderFrame,
+  renderScreenshots,
+  SYNTHESIS_MARKER,
+} from './spec-figma-section-renderers';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface RenderSpecFigmaInput {
+  /** Root filtered node (the requested frame / component). */
+  filteredNode: FilteredFigmaNode;
+  /** Variant definitions from a COMPONENT_SET parent, or [] if none. Kept for compatibility. */
+  variants: FigmaVariantDefinition[];
+  /** Flat text labels extracted from the node tree. Kept for compatibility. */
+  textLabels: FigmaTextLabel[];
+  /** Relative paths of downloaded image files (e.g., ["ui/home.png", "ui/home-dark.png"]). */
+  imagePaths: string[];
+  /** Figma file key. */
+  fileKey: string;
+  /** Node ID in API form (e.g. "1:23"). */
+  nodeId: string;
+  /** Figma file version ID at fetch time. */
+  versionId: string;
+  /** ISO timestamp of when data was fetched. */
+  fetchedAt: string;
+  /** Generator version string (e.g., "sungen v2.4.5"). */
+  generatorVersion: string;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the deterministic envelope for spec_figma.md.
+ * The LLM synthesis step (sungen-figma-source skill) appends the narrative
+ * sections AFTER the SYNTHESIS_MARKER comment. Re-synthesis replaces
+ * everything from the marker to EOF.
+ *
+ * Pure function — no I/O side effects.
+ */
+export function renderSpecFigma(input: RenderSpecFigmaInput): string {
+  const sections = [
+    renderFrontmatter(input),
+    '',
+    '> Envelope is AUTO-GENERATED. Narrative sections below the marker are LLM-synthesized.',
+    '> To refine, copy useful parts into ../spec.md (authoritative).',
+    '',
+    renderFrame(input.filteredNode),
+    '',
+    renderScreenshots(input.imagePaths),
+    '',
+    SYNTHESIS_MARKER,
+    '',
+  ];
+
+  return sections.join('\n') + '\n';
+}

package/src/orchestrator/figma/spec-figma-section-renderers.ts

@@ -0,0 +1,46 @@
+/**
+ * Section-render helpers for spec-figma-renderer.ts.
+ *
+ * After the shift to LLM-synthesized narrative sections, the envelope only
+ * needs: frontmatter, Frame metadata, Screenshots, and the SYNTHESIS marker.
+ * All prose sections (Purpose, ASCII Layout, Regions, Actions, Form Fields,
+ * Data Columns, Navigation) are appended below the marker by the
+ * sungen-figma-source skill.
+ *
+ * Pure — no I/O.
+ */
+
+import type { FilteredFigmaNode } from '../../tools/figma/figma-client-types';
+import type { RenderSpecFigmaInput } from './spec-figma-renderer';
+
+/**
+ * Sentinel comment that separates the deterministic envelope (above) from
+ * the LLM-synthesized narrative (below). Re-synthesis replaces everything
+ * from this marker to EOF.
+ */
+export const SYNTHESIS_MARKER = '<!-- SYNTHESIS-BELOW -->';
+
+export function renderFrontmatter(input: RenderSpecFigmaInput): string {
+  return [
+    '---',
+    'source: figma',
+    `file_key: ${input.fileKey}`,
+    `node_id: ${input.nodeId}`,
+    `figma_version_id: ${input.versionId}`,
+    `fetched_at: ${input.fetchedAt}`,
+    `generator: ${input.generatorVersion}`,
+    '---',
+  ].join('\n');
+}
+
+export function renderFrame(node: FilteredFigmaNode): string {
+  const bb = node.boundingBox;
+  const dims = bb ? `${bb.w}x${bb.h}` : '—';
+  return ['## Frame', `- Name: ${node.name}`, `- Dimensions: ${dims}`, `- Type: ${node.type}`].join('\n');
+}
+
+export function renderScreenshots(imagePaths: string[]): string {
+  if (imagePaths.length === 0) return '## Screenshots\n- (no images downloaded)';
+  const items = imagePaths.map((p, i) => `- \`${p}\` — ${i === 0 ? 'default state' : `variant ${i}`}`);
+  return ['## Screenshots', ...items].join('\n');
+}

package/src/orchestrator/project-initializer.ts

@@ -48,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();
@@ -383,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
    */
@@ -405,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/templates/ai-instructions/claude-cmd-add-screen.md

@@ -1,7 +1,7 @@
 ---
 name: add-screen
 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]
+argument-hint: [screen-name] [url-path] [--figma <url>]
 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
 ---
 
@@ -11,37 +11,82 @@ You are adding a new Sungen screen for test generation.
 
 Parse from `$ARGUMENTS`:
 - **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
-- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`)
+- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - optional when `--figma` is provided
+- **--figma \<url\>** — Figma share URL (optional)
+- **--refresh** — bypass Figma cache and re-fetch (optional, use with `--figma`)
+- **--scale \<n\>** — PNG export scale factor, default 2 (optional)
+- **--hi-res** — export at 4× scale, shorthand for `--scale 4` (optional)
 
 If **screen** is missing, ask: "What is the screen name? (e.g., `login`, `dashboard`)"
-If **path** is missing, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+If **path** is missing and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
 
 ## Steps
 
 ### 1. Scaffold the screen
 
-Run:
+**Standard path (no `--figma`):**
 ```bash
 sungen add --screen <screen> --path <path>
 ```
 
-### 2. Fill spec.md
+**Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
 
-Use `AskUserQuestion`: *"Fill `spec.md` now?"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+Invoke the `sungen-figma-source` skill by running:
+```bash
+sungen add --screen <screen> --figma '<url>' [--path <path>] [--refresh] [--scale <n>]
+# Single-quote the URL — Figma links contain `&` which bash otherwise treats as a background operator.
+```
+
+This CLI command automatically:
+1. Parses the Figma URL and fetches the design node.
+2. Downloads frame + variant PNGs to `qa/screens/<screen>/requirements/ui/`.
+3. Writes `qa/screens/<screen>/requirements/spec_figma.md` (auto-generated, always overwritten on re-run).
+4. Creates `qa/screens/<screen>/requirements/spec.md` stub **only if the file does not already exist** — never overwrites existing human content.
+
+**Important coexistence rules:**
+- `--figma` and `--path` can be passed together: `--path` provides the live URL for `run-test`; `--figma` provides design context.
+- `spec.md` is the human-authored source of truth. Never modify it automatically.
+- `spec_figma.md` is auto-generated — always overwritten; tell the user to copy useful sections into `spec.md`.
+- `--capture` (Playwright screenshot) and `--figma` can be used simultaneously; they produce different outputs.
+
+**If Figma auth is missing**, the command will fail with a message like:
+> Figma PAT is not configured. Run: sungen figma auth set
+
+In that case, guide the user to run `sungen figma auth set` and retry.
 
-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.
+### 1a. Synthesize narrative sections (Figma branch only)
 
-### 3. Capture visual source
+After `sungen add --figma` succeeds, the envelope of `spec_figma.md` is deterministic but the narrative below the `<!-- SYNTHESIS-BELOW -->` marker is empty. Invoke the `sungen-figma-source` skill to fill it:
 
-Use `AskUserQuestion`: *"Capture a visual reference for this screen?"* — always offer all three so pre-launch projects work:
+1. Read `qa/screens/<screen>/requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter.
+2. Read the cached raw node JSON at `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores).
+3. Follow the skill's 7-section template (Purpose / ASCII Layout / Regions / Actions / Form Fields / Data Columns / Navigation) and **replace** everything from the marker to EOF.
+4. Preserve the envelope above the marker byte-for-byte.
 
+**Review gate.** Before moving on, show the user the synthesized narrative and use `AskUserQuestion`:
+
+- **Approve** — narrative looks right, continue to Step 2
+- **Edit** — user will tweak `spec_figma.md` now; wait for confirmation before continuing
+- **Cancel** — abort; advise the user that `spec.md` was NOT modified and they can re-run `sungen add --figma --refresh` later
+
+### 2. Capture visual source
+
+**If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Use `AskUserQuestion` to offer:
+- **Continue** — Figma visuals are enough (Recommended)
+- **Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture-live` skill)
+
+**If standard path (no `--figma`)** → go straight to source selection. Use `AskUserQuestion`: *"Pick a visual source for this screen:"*
 - **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
+- **Skip** — user will drop images manually into `requirements/ui/` later
 
 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`.
+### 3. Fill spec.md
+
+Use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+
+If yes → open `qa/screens/<screen>/requirements/spec.md` and help the user fill sections, fields, validation rules, business rules, and states. Reference the captured visuals from Step 2 to suggest field names, form elements, and UI states. Especially prompt for the optional **Figma URL** and **Live URL** fields in Overview — those unlock auto-capture without re-asking next run.
 
 ### 4. Next steps