@sun-asterisk/sungen 2.0.3 → 2.1.1

package/src/generators/test-generator/code-generator.ts

@@ -229,7 +229,8 @@ export class CodeGenerator {
 
     // Generate all scenarios with feature tags for inheritance
     // Skip scenarios tagged with @manual
-    const scenarios: string[] = [];
+    // Track auth role per scenario for grouping
+    const renderedScenarios: Array<{ code: string; authRole?: string }> = [];
     for (const scenario of feature.scenarios) {
       if (isManual(scenario.tags)) {
         if (this.options.verbose) {
@@ -237,22 +238,63 @@ export class CodeGenerator {
         }
         continue;
       }
-      scenarios.push(
-        await this.generateScenario(
-          scenario,
-          !!feature.background,
-          feature.tags || []
-        )
+
+      // Resolve auth tags for @extend scenarios (same logic as generateScenario)
+      let authFeatureTags = feature.tags || [];
+      if (scenario.extendsName) {
+        const baseScenario = this.stepsRegistry.get(scenario.extendsName);
+        if (baseScenario) {
+          authFeatureTags = [...baseScenario.tags, ...authFeatureTags];
+        }
+      }
+      const authRole = getEffectiveAuthRole(scenario.tags, authFeatureTags);
+
+      const code = await this.generateScenario(
+        scenario,
+        !!feature.background,
+        feature.tags || []
       );
+      renderedScenarios.push({ code, authRole });
     }
 
+    // Group scenarios by auth role for nested test.describe blocks
+    // This ensures test.use({ storageState }) only applies to its group
+    const authGroupMap = new Map<string, string[]>();
+    const groupOrder: string[] = [];
+    for (const { code, authRole } of renderedScenarios) {
+      const key = authRole || '';
+      if (!authGroupMap.has(key)) {
+        authGroupMap.set(key, []);
+        groupOrder.push(key);
+      }
+      authGroupMap.get(key)!.push(code);
+    }
+
+    const authGroups = groupOrder.map(key => ({
+      authRole: key || undefined,
+      scenarios: authGroupMap.get(key)!,
+    }));
+
+    // Determine rendering strategy:
+    // - Single group: flat structure (test.use at describe level if auth)
+    // - Multiple groups: nested describes per auth role
+    const needsGrouping = authGroups.length > 1;
+    const scenarios = renderedScenarios.map(s => s.code);
+
+    // For single group, extract the auth role to put test.use at describe level
+    const singleAuthRole = !needsGrouping && authGroups.length === 1
+      ? authGroups[0].authRole
+      : undefined;
+
     // Use adapter to render the complete test file structure
     return this.adapter.renderTestFile({
       imports: '', // Not used in template as it's rendered separately
       featureName: feature.name,
       featureDescription: feature.description,
       background,
-      scenarios,
+      scenarios: needsGrouping ? [] : scenarios,
+      authGroups: needsGrouping ? authGroups : undefined,
+      singleAuthRole,
     });
   }
 

package/src/generators/test-generator/patterns/assertion-patterns.ts

@@ -419,32 +419,32 @@ export const assertionPatterns: StepPattern[] = [
   {
     name: 'should-contain-text',
     matcher: (step: ParsedStep) =>
-      step.text.includes('should contain') && !!step.selectorRef && !!(step.value || step.dataRef),
+      (step.text.includes('should contain') || step.text.includes('contains')) && !!step.selectorRef && !!(step.value || step.dataRef),
     resolver: (step, context): StepTemplateData => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
-      const expectedText = step.value || `\${${step.dataRef}}`;
+      const expectedText = step.value || context.dataResolver.resolveData(step.dataRef!, context.featureName);
       return {
         templateName: 'contain-text-assertion',
         data: { ...resolved, expectedText },
         comment: `Assert ${step.selectorRef} contains "${step.value || step.dataRef}"`,
       };
     },
-    priority: 9,
+    priority: 12,
   },
   {
     name: 'should-have-text',
     matcher: (step: ParsedStep) =>
-      step.text.includes('should have text') && !!step.selectorRef && !!(step.value || step.dataRef),
+      (step.text.includes('should have text') || step.text.includes('has text')) && !!step.selectorRef && !!(step.value || step.dataRef),
     resolver: (step, context): StepTemplateData => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
-      const expectedText = step.value || `\${${step.dataRef}}`;
+      const expectedText = step.value || context.dataResolver.resolveData(step.dataRef!, context.featureName);
       return {
         templateName: 'have-text-assertion',
         data: { ...resolved, expectedText },
         comment: `Assert ${step.selectorRef} has text "${step.value || step.dataRef}"`,
       };
     },
-    priority: 10,
+    priority: 12,
   },
   {
     name: 'is-empty',
@@ -591,4 +591,60 @@ export const assertionPatterns: StepPattern[] = [
     },
     priority: 8,
   },
+  {
+    name: 'is-loading',
+    matcher: (step: ParsedStep) =>
+      /\b(see|sees)\s+\[/.test(step.text) && /\bis loading\b/.test(step.text) && !!step.selectorRef,
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'loading-assertion',
+        data: { ...resolved, selectorRef: step.selectorRef },
+        comment: `Assert ${step.selectorRef} is loading`,
+      };
+    },
+    priority: 11,
+  },
+  {
+    name: 'is-selected',
+    matcher: (step: ParsedStep) =>
+      /\b(see|sees)\s+\[/.test(step.text) && /\bis selected\b/.test(step.text) && !!step.selectorRef,
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'selected-assertion',
+        data: { ...resolved, selectorRef: step.selectorRef },
+        comment: `Assert ${step.selectorRef} is selected`,
+      };
+    },
+    priority: 11,
+  },
+  {
+    name: 'is-sorted-ascending',
+    matcher: (step: ParsedStep) =>
+      /\b(see|sees)\s+\[/.test(step.text) && /\bsorted ascending\b/.test(step.text) && !!step.selectorRef,
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'sorted-assertion',
+        data: { ...resolved, selectorRef: step.selectorRef, sortDirection: 'ascending' },
+        comment: `Assert ${step.selectorRef} is sorted ascending`,
+      };
+    },
+    priority: 12,
+  },
+  {
+    name: 'is-sorted-descending',
+    matcher: (step: ParsedStep) =>
+      /\b(see|sees)\s+\[/.test(step.text) && /\bsorted descending\b/.test(step.text) && !!step.selectorRef,
+    resolver: (step, context): StepTemplateData => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'sorted-assertion',
+        data: { ...resolved, selectorRef: step.selectorRef, sortDirection: 'descending' },
+        comment: `Assert ${step.selectorRef} is sorted descending`,
+      };
+    },
+    priority: 12,
+  },
 ];

package/src/generators/test-generator/patterns/form-patterns.ts

@@ -70,7 +70,7 @@ export const formPatterns: StepPattern[] = [
   {
     name: 'check-checkbox',
     matcher: (step: ParsedStep) =>
-      step.text.includes('checks') && !!step.selectorRef,
+      (step.text.includes('checks') || step.text.match(/\bcheck\b/)) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {
@@ -84,7 +84,7 @@ export const formPatterns: StepPattern[] = [
   {
     name: 'uncheck-checkbox',
     matcher: (step: ParsedStep) =>
-      step.text.includes('unchecks') && !!step.selectorRef,
+      (step.text.includes('unchecks') || step.text.match(/\buncheck\b/)) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {
@@ -151,7 +151,7 @@ export const formPatterns: StepPattern[] = [
   {
     name: 'clear-input',
     matcher: (step: ParsedStep) =>
-      step.text.includes('clears') && !!step.selectorRef,
+      (step.text.includes('clears') || step.text.match(/\bclear\b/)) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {

package/src/generators/test-generator/patterns/interaction-patterns.ts

@@ -135,7 +135,7 @@ export const interactionPatterns: StepPattern[] = [
   {
     name: 'hover-element',
     matcher: (step: ParsedStep) =>
-      step.text.includes('hovers') && !!step.selectorRef,
+      (step.text.includes('hovers') || step.text.match(/\bhover\b/)) && !!step.selectorRef,
     resolver: (step, context) => {
       const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
       return {
@@ -305,4 +305,96 @@ export const interactionPatterns: StepPattern[] = [
     },
     priority: 8,
   },
+  {
+    name: 'toggle-switch',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('toggles') || step.text.match(/\btoggle\b/)) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'toggle-action',
+        data: { ...resolved, selectorRef: step.selectorRef },
+        comment: `Toggle ${step.selectorRef}`,
+      };
+    },
+    priority: 9,
+  },
+  {
+    name: 'drag-to',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('drags') || step.text.match(/\bdrag\b/)) &&
+      /\bto\s+\[/.test(step.text) && !!step.selectorRef,
+    resolver: (step, context) => {
+      // Extract both selector refs: [Source] ... to [Target]
+      const allRefs = step.text.match(/\[([^\]]+)\]/g);
+      if (!allRefs || allRefs.length < 2) {
+        return {
+          templateName: 'drag-action',
+          data: { strategy: 'text', value: step.selectorRef, targetLocator: 'page.locator(\'TODO\')' },
+          comment: `Drag ${step.selectorRef} (missing target)`,
+        };
+      }
+      const sourceRef = allRefs[0].slice(1, -1);
+      const targetRef = allRefs[1].slice(1, -1);
+
+      const sourceResolved = context.selectorResolver.resolveSelector(sourceRef, undefined, step.elementType, step.nth);
+      const targetResolved = context.selectorResolver.resolveSelector(targetRef, undefined, undefined, 0);
+
+      // Build target locator expression from resolved selector
+      let targetLocator: string;
+      switch (targetResolved.strategy) {
+        case 'role':
+          targetLocator = targetResolved.name
+            ? `page.getByRole('${targetResolved.role}', { name: '${targetResolved.name}' })`
+            : `page.getByRole('${targetResolved.role}')`;
+          break;
+        case 'testid':
+          targetLocator = `page.getByTestId('${targetResolved.value}')`;
+          break;
+        case 'text':
+          targetLocator = `page.getByText('${targetResolved.value}')`;
+          break;
+        case 'locator':
+          targetLocator = `page.locator('${targetResolved.value}')`;
+          break;
+        default:
+          targetLocator = `page.getByText('${targetRef}')`;
+      }
+
+      return {
+        templateName: 'drag-action',
+        data: { ...sourceResolved, targetLocator },
+        comment: `Drag ${sourceRef} to ${targetRef}`,
+      };
+    },
+    priority: 10,
+  },
+  {
+    name: 'expand-element',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('expands') || step.text.match(/\bexpand\b/)) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'expand-action',
+        data: { ...resolved, selectorRef: step.selectorRef, direction: 'expand' },
+        comment: `Expand ${step.selectorRef}`,
+      };
+    },
+    priority: 9,
+  },
+  {
+    name: 'collapse-element',
+    matcher: (step: ParsedStep) =>
+      (step.text.includes('collapses') || step.text.match(/\bcollapse\b/)) && !!step.selectorRef,
+    resolver: (step, context) => {
+      const resolved = context.selectorResolver.resolveSelector(step.selectorRef!, undefined, step.elementType, step.nth);
+      return {
+        templateName: 'expand-action',
+        data: { ...resolved, selectorRef: step.selectorRef, direction: 'collapse' },
+        comment: `Collapse ${step.selectorRef}`,
+      };
+    },
+    priority: 9,
+  },
 ];

package/src/generators/test-generator/template-engine.ts

@@ -89,6 +89,7 @@ export class TemplateEngine {
     // Switch/case helpers for cleaner strategy routing
     Handlebars.registerHelper('switch', function(value: any, options: any) {
       this.switchValue = value;
+      this.switchMatched = false;
       this.switchDefaulted = false;
       return options.fn(this);
     });
@@ -238,6 +239,8 @@ export class TemplateEngine {
     featureDescription?: string;
     background?: string;
     scenarios: string[];
+    authGroups?: Array<{ authRole?: string; scenarios: string[] }>;
+    singleAuthRole?: string;
   }): string {
     return this.render('test-file', data);
   }
@@ -251,6 +254,7 @@ export class TemplateEngine {
   renderScenario(data: {
     scenarioName: string;
     steps: Array<{ comment?: string; code: string }>;
+    authRole?: string;
   }): string {
     return this.render('scenario', data);
   }

package/src/orchestrator/project-initializer.ts

@@ -5,6 +5,7 @@
 
 import * as fs from 'fs';
 import * as path from 'path';
+import { execSync } from 'child_process';
 
 export class ProjectInitializer {
   private baseCwd: string;
@@ -12,7 +13,7 @@ export class ProjectInitializer {
   private createdItems: string[] = [];
   private skippedItems: string[] = [];
 
-  constructor() {
+  constructor(private baseUrl: string) {
     this.baseCwd = process.cwd();
     this.cwd = this.baseCwd;
   }
@@ -37,6 +38,9 @@ export class ProjectInitializer {
     // Create directories
     this.createDirectories();
 
+    // Ensure package.json and install Playwright
+    await this.setupDependencies();
+
     // Create playwright config if doesn't exist
     this.createPlaywrightConfig();
 
@@ -99,7 +103,8 @@ export class ProjectInitializer {
       return;
     }
 
-    const configContent = this.getPlaywrightConfigTemplate();
+    const configContent = this.getPlaywrightConfigTemplate()
+      .replace('https://example.com', this.baseUrl);
     fs.writeFileSync(configPath, configContent, 'utf-8');
     this.createdItems.push('playwright.config.ts');
   }
@@ -174,9 +179,6 @@ export class ProjectInitializer {
       });
     }
 
-    // Check for Playwright installation
-    this.checkDependencies();
-
     console.log('\nNext steps:');
     let stepIndex = 1;
     if (projectName) {
@@ -192,48 +194,54 @@ export class ProjectInitializer {
    * Create AI rules files for GitHub Copilot and Claude Code
    */
   private createAIRules(): void {
-    const rulesContent = this.getAIRulesContent();
-
-    // GitHub Copilot: .github/copilot-instructions.md
-    const githubDir = path.join(this.cwd, '.github');
-    const copilotPath = path.join(githubDir, 'copilot-instructions.md');
-    if (!fs.existsSync(copilotPath)) {
-      if (!fs.existsSync(githubDir)) {
-        fs.mkdirSync(githubDir, { recursive: true });
-      }
-      fs.writeFileSync(copilotPath, rulesContent, 'utf-8');
-      this.createdItems.push('.github/copilot-instructions.md');
-    } else {
-      this.skippedItems.push('.github/copilot-instructions.md');
-    }
+    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-make-tc.md', '.claude/commands/sungen/make-tc.md'],
+      ['claude-cmd-make-test.md', '.claude/commands/sungen/make-test.md'],
+
+      // Commands — GitHub Copilot
+      ['copilot-cmd-add-screen.md', '.github/prompts/sungen-add-screen.prompt.md'],
+      ['copilot-cmd-make-tc.md', '.github/prompts/sungen-make-tc.prompt.md'],
+      ['copilot-cmd-make-test.md', '.github/prompts/sungen-make-test.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'],
+
+      // Skills — GitHub Copilot
+      ['copilot-skill-gherkin-syntax.md', '.github/prompts/sungen-gherkin-syntax.prompt.md'],
+      ['copilot-skill-selector-keys.md', '.github/prompts/sungen-selector-keys.prompt.md'],
+      ['copilot-skill-error-mapping.md', '.github/prompts/sungen-error-mapping.prompt.md'],
+    ];
 
-    // Claude Code: CLAUDE.md
-    const claudePath = path.join(this.cwd, 'CLAUDE.md');
-    if (!fs.existsSync(claudePath)) {
-      fs.writeFileSync(claudePath, rulesContent, 'utf-8');
-      this.createdItems.push('CLAUDE.md');
-    } else {
-      this.skippedItems.push('CLAUDE.md');
-    }
+    for (const [templateFile, outputRelPath] of fileMapping) {
+      const outputPath = path.join(this.cwd, outputRelPath);
 
-    // Gherkin Dictionary: docs/gherkin-dictionary.md
-    const docsDir = path.join(this.cwd, 'docs');
-    const dictPath = path.join(docsDir, 'gherkin-dictionary.md');
-    if (!fs.existsSync(dictPath)) {
-      // Copy from sungen package if available, otherwise generate stub
-      const packageDictPath = path.join(__dirname, '..', '..', 'docs', 'gherkin-dictionary.md');
-      if (!fs.existsSync(docsDir)) {
-        fs.mkdirSync(docsDir, { recursive: true });
+      if (fs.existsSync(outputPath)) {
+        this.skippedItems.push(outputRelPath);
+        continue;
       }
-      if (fs.existsSync(packageDictPath)) {
-        fs.copyFileSync(packageDictPath, dictPath);
-      } else {
-        fs.writeFileSync(dictPath, '# Sungen Gherkin Dictionary\n\nSee https://github.com/sun-asterisk/sungen for the full dictionary.\n', 'utf-8');
+
+      const outputDir = path.dirname(outputPath);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
       }
-      this.createdItems.push('docs/gherkin-dictionary.md');
-    } else {
-      this.skippedItems.push('docs/gherkin-dictionary.md');
+
+      const templatePath = path.join(aiTemplateDir, templateFile);
+      const content = fs.readFileSync(templatePath, 'utf-8');
+      fs.writeFileSync(outputPath, content, 'utf-8');
+      this.createdItems.push(outputRelPath);
     }
+
   }
 
   /**
@@ -244,30 +252,38 @@ export class ProjectInitializer {
     return fs.readFileSync(templatePath, 'utf-8');
   }
 
-  /**
-   * Get AI rules content (shared between Copilot and Claude)
-   */
-  private getAIRulesContent(): string {
-    return this.readTemplate('ai-rules.md');
-  }
-
   /**
    * Check for required dependencies
    */
-  private checkDependencies(): void {
+  private async setupDependencies(): Promise<void> {
+    const packageJsonPath = path.join(this.cwd, 'package.json');
+    const execOpts = { cwd: this.cwd, stdio: 'inherit' as const };
+
+    // Initialize package.json if it doesn't exist
+    if (!fs.existsSync(packageJsonPath)) {
+      console.log('📦 No package.json found. Initializing...\n');
+      execSync('npm init -y', execOpts);
+      this.createdItems.push('package.json');
+    }
+
+    // Check if @playwright/test is already installed
     try {
-      const packageJsonPath = path.join(this.cwd, 'package.json');
       const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
       const deps = { ...packageJson.dependencies, ...packageJson.devDependencies };
-
-      if (!deps['@playwright/test']) {
-        console.log('\n⚠️  Playwright not detected. Install with:');
-        console.log('   npm install -D @playwright/test');
-        console.log('   npx playwright install');
+      if (deps['@playwright/test']) {
+        console.log('✓ @playwright/test already installed\n');
+        return;
       }
-    } catch (error) {
-      // Ignore if can't read package.json
+    } catch {
+      // package.json just created, proceed with install
     }
+
+    // Install Playwright
+    console.log('📦 Installing @playwright/test...\n');
+    execSync('npm install -D @playwright/test', execOpts);
+
+    console.log('\n🎭 Installing Playwright browsers...\n');
+    execSync('npx playwright install', execOpts);
   }
 
   /**

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

@@ -0,0 +1,42 @@
+---
+name: add-screen
+description: 'Add a new Sungen screen — scaffolds directories and delegates to make-tc for test case creation'
+argument-hint: [screen-name] [url-path]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+You are adding a new Sungen screen for test generation.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
+- **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`)
+
+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`)"
+
+## Steps
+
+### 1. Scaffold the screen
+
+Run:
+```bash
+sungen add --screen <screen> --path <path>
+```
+
+### 2. Create test cases
+
+Ask the user: "Would you like to create test cases now?"
+
+If yes, delegate to `/sungen:make-tc <screen>` to handle:
+- Exploring the live page or analyzing static designs
+- Gathering test viewpoints (UI/UX, Validation, Logic, Security)
+- Generating the 3 files (feature, selectors, test-data)
+
+### 3. Confirm
+
+Tell the user what was created and next steps:
+- If the page requires authentication before exploring via browser, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute this command yourself.**
+- Edit the generated files as needed
+- Run `sungen generate --screen <screen>` to compile to Playwright `.spec.ts`

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

@@ -0,0 +1,60 @@
+---
+name: make-tc
+description: 'Create test cases for a Sungen screen — gathers viewpoints, explores live page or static designs, generates feature/selectors/test-data files'
+argument-hint: [screen-name]
+allowed-tools: Read, Grep, Bash, Glob
+---
+
+## Role
+
+You are a **Senior QA Engineer** specialized in test case design. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-selector-keys` skills.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **screen** — screen name (e.g., `login`, `dashboard`)
+
+If missing, ask the user.
+
+## Steps
+
+### 1. Verify screen exists
+
+Check `qa/screens/<screen>/` exists. If not, tell user to run `/sungen:add-screen` first.
+
+### 2. Determine source mode
+
+Ask: "Do you have a **live page** or **static designs** (screenshots, Figma, images)?"
+
+**Live page →** explore via browser (see CLAUDE.md for Playwright MCP rules). If auth needed, check `specs/.auth/<role>.json` exists — if not, read `baseURL` from `playwright.config.ts` and tell the user to manually run: `sungen makeauth <role> --url <baseURL>` (e.g., `sungen makeauth admin --url http://localhost:3000`). **Do NOT execute `sungen makeauth` yourself.** Wait for the user to confirm auth is ready before proceeding.
+
+**Static designs →** ask user to provide screenshot paths, Figma exports, or UI descriptions. Note: selectors will be best-guess until live page is available.
+
+Present discovered elements to user, then proceed.
+
+### 3. Gather test viewpoints
+
+| VP Category | Description |
+|---|---|
+| **UI/UX** | Default screen appearance, static elements, default states |
+| **Validation** | Field/form validation, error messages |
+| **Logic** | Business logic, happy paths, redirects |
+| **Security** | Auth guards, permission checks |
+
+For each viewpoint, gather: **UI Target**, **Test Viewpoint**, **Expected Result**.
+
+User can provide all at once as a table:
+```
+| VP Category | UI Target | Test Viewpoint | Expected Result |
+```
+
+### 4. Generate files
+
+Generate the 3 files following `sungen-gherkin-syntax` and `sungen-selector-keys` skill rules:
+- `qa/screens/<screen>/features/<screen>.feature` — one Scenario per viewpoint
+- `qa/screens/<screen>/selectors/<screen>.yaml`
+- `qa/screens/<screen>/test-data/<screen>.yaml`
+
+### 5. Confirm
+
+Show what was generated. Next: `sungen generate --screen <screen>`