@sun-asterisk/sungen 2.5.2 → 2.6.0

package/src/orchestrator/flow-manager.ts

@@ -0,0 +1,243 @@
+/**
+ * Flow Manager
+ * Manages flow definition files in qa/flows directory
+ * Flows are independent E2E test journeys spanning multiple screens
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface FlowOptions {
+  name: string;
+  path?: string;
+  description?: string;
+}
+
+export class FlowManager {
+  private cwd: string;
+  private flowsDir: string;
+
+  constructor() {
+    this.cwd = process.cwd();
+    this.flowsDir = path.join(this.cwd, 'qa', 'flows');
+  }
+
+  async addFlow(options: FlowOptions): Promise<void> {
+    this.validateFlowName(options.name);
+
+    const flowName = this.normalizeFlowName(options.name);
+    const flowDir = path.join(this.flowsDir, flowName);
+
+    const featuresDir = path.join(flowDir, 'features');
+    const selectorsDir = path.join(flowDir, 'selectors');
+    const testDataDir = path.join(flowDir, 'test-data');
+    const requirementsDir = path.join(flowDir, 'requirements');
+    const requirementsUiDir = path.join(requirementsDir, 'ui');
+
+    const featurePath = path.join(featuresDir, `${flowName}.feature`);
+    const selectorPath = path.join(selectorsDir, `${flowName}.yaml`);
+    const testDataPath = path.join(testDataDir, `${flowName}.yaml`);
+
+    if (fs.existsSync(flowDir)) {
+      console.error(`Error: Flow "${options.name}" already exists at ${flowDir}`);
+      process.exit(1);
+    }
+
+    console.log(`Creating flow: ${options.name}\n`);
+
+    try {
+      if (!fs.existsSync(this.flowsDir)) {
+        fs.mkdirSync(this.flowsDir, { recursive: true });
+      }
+      fs.mkdirSync(featuresDir, { recursive: true });
+      fs.mkdirSync(selectorsDir, { recursive: true });
+      fs.mkdirSync(testDataDir, { recursive: true });
+      fs.mkdirSync(requirementsUiDir, { recursive: true });
+    } catch (error) {
+      console.error(`Error: Failed to create directories`);
+      console.error(`  ${error instanceof Error ? error.message : String(error)}`);
+      process.exit(1);
+    }
+
+    fs.writeFileSync(featurePath, this.generateFeatureTemplate(options, flowName), 'utf-8');
+
+    const startPath = options.path || '/login';
+    fs.writeFileSync(selectorPath, [
+      `# ${options.name} Flow Selectors`,
+      `# Namespace keys by screen to avoid duplicates: "login:submit", "awards:submit"`,
+      ``,
+      `# --- Login screen ---`,
+      `login:`,
+      `  type: 'page'`,
+      `  value: '${startPath}'`,
+      ``,
+      `# "login:email":`,
+      `#   type: 'testid'`,
+      `#   value: 'email-input'`,
+      ``,
+      `# "login:submit":`,
+      `#   type: 'role'`,
+      `#   value: 'button'`,
+      `#   name: 'Login'`,
+      ``,
+    ].join('\n'), 'utf-8');
+
+    fs.writeFileSync(testDataPath, [
+      `# ${options.name} Flow Test Data`,
+      `# Namespace by phase: login.email, submission.nominee`,
+      `# Reference in features using {{variable}} syntax`,
+      ``,
+    ].join('\n'), 'utf-8');
+
+    const specPath = path.join(requirementsDir, 'spec.md');
+    fs.writeFileSync(specPath, this.generateSpecTemplate(options, flowName), 'utf-8');
+
+    const viewpointPath = path.join(requirementsDir, 'test-viewpoint.md');
+    fs.writeFileSync(viewpointPath, this.generateViewpointTemplate(options), 'utf-8');
+
+    console.log(`Created files:`);
+    console.log(`  ${path.relative(this.cwd, featurePath)}`);
+    console.log(`  ${path.relative(this.cwd, selectorPath)}`);
+    console.log(`  ${path.relative(this.cwd, testDataPath)}`);
+    console.log(`  ${path.relative(this.cwd, specPath)}`);
+    console.log(`  ${path.relative(this.cwd, viewpointPath)}`);
+    console.log(`  ${path.relative(this.cwd, requirementsUiDir)}/`);
+    console.log('');
+
+    console.log('Next steps:');
+    console.log(`  1. Fill requirements/spec.md with flow specification (screens, transitions, business rules)`);
+    console.log(`     Optionally add UI designs to requirements/ui/`);
+    console.log(`  2. Generate test cases: /sungen:create-test ${flowName}`);
+    console.log(`  3. Compile: sungen generate --flow ${flowName}`);
+    console.log(`  4. Run: npx playwright test\n`);
+  }
+
+  private validateFlowName(name: string): void {
+    if (!name || name.trim().length === 0) {
+      console.error('Error: Flow name cannot be empty');
+      process.exit(1);
+    }
+    if (!/[a-zA-Z0-9]/.test(name)) {
+      console.error('Error: Flow name must contain at least one alphanumeric character');
+      process.exit(1);
+    }
+  }
+
+  private normalizeFlowName(name: string): string {
+    return name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '')
+      .replace(/-+/g, '-');
+  }
+
+  private generateSpecTemplate(options: FlowOptions, flowName: string): string {
+    const startPath = options.path || '/login';
+    return `# ${options.name} Flow Specification
+
+## Overview
+- **Start URL:** ${startPath}
+- **Auth Required:** no
+- **Platform:** web
+
+## Screens in Flow
+<!-- List all screens this flow visits, in order -->
+
+| # | Screen | URL Path | Description |
+|---|--------|----------|-------------|
+| 1 | [Screen Name] | ${startPath} | [What user does here] |
+
+## Flow Steps
+
+### Step 1: [Screen Name]
+- **Action:** [What the user does]
+- **Expected:** [What should happen]
+- **Transition:** Navigates to Step 2
+
+## Business Rules
+<!-- Rules that affect the flow: permissions, conditions, limits -->
+- [Rule 1]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+  }
+
+  private generateViewpointTemplate(options: FlowOptions): string {
+    return [
+      `# ${options.name} Flow — Test Viewpoints`,
+      '',
+      '## Edge Cases',
+      '',
+      '<!-- Sample — replace with actual edge cases for this flow:',
+      '- Network drops between screen transitions — should resume or show error?',
+      '- Session expires mid-flow — should redirect to login and preserve progress?',
+      '- Browser back button at step 3 — should return to step 2 with data intact?',
+      '- Complete flow twice rapidly — should prevent duplicate submissions',
+      '-->',
+      '',
+      '## Known Issues',
+      '',
+      '<!-- Sample — replace with actual known issues:',
+      '- [BUG-001] Form data lost if user navigates away and returns',
+      '- [BUG-002] Confirmation page shows stale data on slow connections',
+      '-->',
+      '',
+      '## Design Decisions',
+      '',
+      '<!-- Sample — replace with actual design decisions:',
+      '- Flow requires completing all steps in order (no skip)',
+      '- Draft is auto-saved at each step transition',
+      '- Cancel at any step discards the entire flow',
+      '-->',
+      '',
+      '## Cross-Screen Concerns',
+      '',
+      '<!-- Sample — replace with actual cross-screen concerns:',
+      '- Auth role must remain consistent across all screens',
+      '- Data entered in step 1 must be visible in confirmation (step 3)',
+      '- Error in step 2 should allow returning to step 1 without re-entering data',
+      '-->',
+      '',
+      '## Priority Viewpoints',
+      '',
+      '<!-- Rate importance for this flow (High / Medium / Low / Skip):',
+      '',
+      '| VP | Priority | Reason |',
+      '|---|----------|--------|',
+      '| VP-UI | Medium | Standard forms across screens |',
+      '| VP-VAL | High | Cross-screen validation rules |',
+      '| VP-LOGIC | High | Multi-step business logic, state transitions |',
+      '| VP-SEC | Medium | Auth must persist, role-based access at each screen |',
+      '-->',
+      '',
+    ].join('\n');
+  }
+
+  private generateFeatureTemplate(options: FlowOptions, flowName: string): string {
+    const description = options.description || `complete the ${options.name} flow`;
+
+    return `@flow
+Feature: ${options.name} Flow
+
+  As a user
+  I want to ${description}
+  So that I can accomplish my end-to-end goal
+
+  Background:
+    Given User is on [Login] page
+
+  @high @auth:user
+  Scenario: User login successfully
+    When User fill [Login:Email] field with {{login.email}}
+    And User fill [Login:Password] field with {{login.password}}
+    And User click [Login:Submit] button
+    Then User see [Dashboard] page
+
+  Scenario: Sample next step for ${options.name}
+    When User click [Dashboard:Element] button
+    Then User see "expected result" text
+`;
+  }
+}

package/src/orchestrator/project-initializer.ts

@@ -90,6 +90,7 @@ export class ProjectInitializer {
     const dirs = [
       'qa',
       'qa/screens',
+      'qa/flows',
       'specs',
       'specs/generated',
       'specs/storage',

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

@@ -0,0 +1,88 @@
+---
+name: add-flow
+description: 'Add a new Sungen flow — scaffolds directories for E2E cross-screen testing, helps fill spec.md, and can capture visuals via the capture skills'
+argument-hint: [flow-name] [--path <start-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
+---
+
+You are adding a new Sungen flow for E2E cross-screen test generation.
+
+## Parameters
+
+Parse from `$ARGUMENTS`:
+- **flow** — flow name (e.g., `award-submission`, `user-onboarding`)
+- **--path \<url\>** — starting page URL path (default: `/login`)
+- **--description \<text\>** — flow description (optional)
+
+If **flow** is missing, ask: "What is the flow name? (e.g., `award-submission`, `user-onboarding`)"
+If **path** is missing, ask: "What is the starting URL path? (e.g., `/login`)"
+
+## Steps
+
+### 1. Scaffold the flow
+
+```bash
+sungen add-flow --flow <name> --path <path>
+```
+
+This creates:
+```
+qa/flows/<name>/
+├── features/<name>.feature        # Gherkin with @flow tag, Background, sample scenarios
+├── selectors/<name>.yaml          # Namespaced keys: "login:submit", "awards:submit"
+├── test-data/<name>.yaml          # Namespaced data: login.email, submission.nominee
+└── requirements/
+    ├── spec.md                    # Flow specification
+    └── ui/                        # Screenshots, mockups
+```
+
+### 1a. Identify the screens in the flow
+
+Ask the user: "Which screens does this flow visit, in order? (e.g., login → dashboard → award-form → confirmation)"
+
+Record the screen list — you will need it for:
+- Filling `spec.md` (Step 3)
+- Suggesting `[Screen:Element]` namespace prefixes
+- Capturing visuals per screen (Step 2)
+
+### 2. Capture visual source
+
+Use `AskUserQuestion`: *"Pick a visual source for this flow's screens:"*
+- **Figma designs** (Recommended for pre-launch) — invoke `sungen-capture-figma` skill for each screen
+- **Live page scan** (dev/staging is up) — invoke `sungen-capture-live` skill for each screen URL
+- **Local images** — invoke `sungen-capture-local` skill to load from `requirements/ui/`
+- **Skip** — user will drop images manually into `requirements/ui/` later
+
+Each capture skill writes outputs into `qa/flows/<name>/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`.
+
+### 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/flows/<name>/requirements/spec.md` and help the user fill:
+- **Screens list** — ordered list of screens with URL paths
+- **Flow steps** — what the user does at each screen
+- **Transitions** — what triggers navigation between screens
+- **Business rules** — cross-screen validation, state that persists
+- **Test data** — what data is entered at each screen
+
+Reference the captured visuals from Step 2 to suggest field names, form elements, and UI states.
+
+### 4. Next steps
+
+Tell the user what was created, then use `AskUserQuestion` to offer next steps:
+
+- **`/sungen:create-test <name>`** — Create test scenarios for the flow (Recommended)
+- **Done for now** — I'll come back later
+
+If user picks `/sungen:create-test`, **you MUST use the Skill tool** to invoke it. Do NOT generate test cases yourself — the skill auto-loads `sungen-gherkin-syntax` and `sungen-tc-generation`.
+
+## Key Rules
+
+- Flows are **independent** from screens — own selectors, own test-data
+- Selectors use `[Screen:Element]` namespace format with colon
+- YAML keys must be **quoted** due to colon: `"login:submit":`
+- Test data namespaced by phase: `login.email`, `submission.nominee`
+- `@flow` tag required at feature level
+- `Background:` should only contain the starting page navigation
+- Each scenario = one phase of the journey

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

@@ -19,13 +19,16 @@ You are a **Senior QA Engineer** specialized in test case design. You structure
 
 ## Parameters
 
-Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
+Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+
+**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode. Else check `qa/screens/<name>/` → screen mode. This determines paths, generation strategy, and CLI commands.
 
 ## Steps
 
-1. Verify `qa/screens/<screen>/` exists. If not → `/sungen:add-screen` first.
+1. **Flow**: Verify `qa/flows/<name>/` exists. If not → `/sungen:add-flow` first.
+   **Screen**: Verify `qa/screens/<name>/` exists. If not → `/sungen:add-screen` first.
 2. Check if `.feature` file already has scenarios. If yes → use `AskUserQuestion` to ask the update mode (see `sungen-tc-generation` skill for details). If no → fresh creation.
-3. **Read requirements & resolve visual source** — check `qa/screens/<screen>/requirements/`:
+3. **Read requirements & resolve visual source** — check `qa/<screens|flows>/<name>/requirements/`:
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
    - If `test-viewpoint.md` exists → read it. If it only contains HTML comments (scaffold template), use `AskUserQuestion` to ask:
      - **Fill test-viewpoint.md first** — I'll help you identify edge cases, known issues, and design decisions for this screen before generating tests
@@ -44,13 +47,13 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
    Summarize what you found in requirements and present to the user.
 
-4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. When requirements exist, use the "Requirements-Driven Generation" strategy.
-5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills.
+4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy.
+5. Generate or update `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag.
 6. Show summary, then use `AskUserQuestion` to offer next steps:
 
-- **`/sungen:review <screen>`** — Review syntax, coverage, viewpoint quality (Recommended)
-- **`/sungen:run-test <screen>`** — Skip review, generate selectors and run tests now
-- **`/sungen:create-test <screen>`** — Expand coverage: add @normal + @low scenarios
+- **`/sungen:review <name>`** — Review syntax, coverage, viewpoint quality (Recommended)
+- **`/sungen:run-test <name>`** — Skip review, generate selectors and run tests now
+- **`/sungen:create-test <name>`** — Expand coverage: add @normal + @low scenarios
 - **Done for now** — I'll come back later
 
 **No selectors.yaml** — selectors are generated during `/sungen:run-test`.

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

@@ -11,17 +11,19 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 ## Parameters
 
-Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
+Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+
+**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
 ## Steps
 
-1. Read `qa/screens/<screen>/features/<screen>.feature` and `qa/screens/<screen>/test-data/<screen>.yaml`. If missing → `/sungen:create-test` first.
-2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). Use `sungen-viewpoint` for pattern checklists.
-3. **Unverified Selectors check** — if `qa/screens/<screen>/selectors/<screen>.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric (see `sungen-tc-review` skill for report format). Does NOT affect the 60% threshold.
+1. Read `<base>/<name>/features/<name>.feature` and `<base>/<name>/test-data/<name>.yaml`. If missing → `/sungen:create-test` first.
+2. Follow the `sungen-tc-review` skill — score 3 dimensions: Syntax (30pts), Coverage (40pts), Viewpoint (30pts). **For flows**, also apply the "Flow Review Additions" section. Use `sungen-viewpoint` for pattern checklists.
+3. **Unverified Selectors check** — if `<base>/<name>/selectors/<name>.yaml` exists, count lines matching `@needs-live-verify`. Include in the review report as a non-scoring metric. Does NOT affect the 60% threshold.
 4. Output review report per `sungen-tc-review` format. **>= 60%**: PASS. **< 60%**: FAIL with recommendations.
 5. If FAIL and user confirms → update test cases following `sungen-gherkin-syntax` and `sungen-tc-generation` skills, then re-review.
 6. After PASS (or user decides to proceed), use `AskUserQuestion` to offer next steps:
 
-- **`/sungen:run-test <screen>`** — Generate selectors, compile, and run tests (Recommended)
-- **`/sungen:create-test <screen>`** — Add more test cases before running
+- **`/sungen:run-test <name>`** — Generate selectors, compile, and run tests (Recommended)
+- **`/sungen:create-test <name>`** — Add more test cases before running
 - **Done for now** — I'll come back later

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

@@ -11,11 +11,13 @@ You are a **Senior Developer**. Use `sungen-selector-fix`, `sungen-selector-keys
 
 ## Parameters
 
-Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
+Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+
+**Auto-detect context**: check if `qa/flows/<name>/` exists → flow mode (base path: `qa/flows/<name>/`). Else check `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
 
 ## Pre-run (phased — per `sungen-selector-fix` skill)
 
-1. Verify `qa/screens/<screen>/` has `.feature` + `test-data.yaml`.
+1. Verify `<base>/<name>/` 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, apply the following decision tree before running Phase 0 from `sungen-selector-fix`:
 
    ```
@@ -29,14 +31,14 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
                    2. Apply selector heuristics from sungen-figma-source skill (testid > role+name > placeholder > label > locator > text)
                    3. Write selectors.yaml — every provisional entry gets this comment on the line above:
                           # @needs-live-verify source=figma node_id=<id>
-                   4. Compile: sungen generate --screen <screen> — must succeed
+                   4. Compile: Screen: sungen generate --screen <name>. Flow: sungen generate --flow <name> — must succeed
                    5. Phase 1 smoke check runs; tests using unverified selectors may fail
                       → auto-fix triggers on next run-test invocation when a live page is available
              NO  → hard stop: print the following message and stop:
                    "Cannot generate selectors: no live page URL and no spec_figma.md found.
                     Options:
                     • Provide the live URL so Playwright MCP can snapshot the page, OR
-                    • Run: sungen add --screen <screen> --figma <figma-url>  to generate spec_figma.md first"
+                    • Run: sungen add --screen <name> --figma <figma-url>  to generate spec_figma.md first"
    ```
 
    **Auto-fix on subsequent runs**: when `run-test` is invoked again with a reachable live page, Phase 0 compares the DOM snapshot against existing `selectors.yaml` entries. Entries tagged `# @needs-live-verify` are treated as candidates — if the actual selector differs, the entry is replaced and the comment removed (entry becomes verified). Entries that already match are also promoted to verified (comment removed).
@@ -50,7 +52,7 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
      name: "Submit"
    ```
 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>` (default: runtime data loading from YAML). Use `--inline-data` only if user requests compile-time hardcoded values.
+4. Compile: **Screen**: `sungen generate --screen <name>`. **Flow**: `sungen generate --flow <name>`. 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)
 
@@ -61,15 +63,17 @@ Parse **screen** from `$ARGUMENTS`. If missing, ask the user.
 
 ## 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:
+**Per-screen/flow 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:
 
 ```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
-```
+# ✅ Screen
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/<name>/<name>.spec.ts
 
-Output: `specs/generated/<screen>/<screen>-test-result.json`
+# ✅ Flow
+PLAYWRIGHT_JSON_OUTPUT_NAME=specs/generated/flows/<name>/<name>-test-result.json \
+  npx playwright test specs/generated/flows/<name>/<name>.spec.ts
+```
 
 **DO NOT** pass `--reporter=...` flag — it overrides the reporters from `playwright.config.ts` and disables the JSON reporter that `sungen delivery` depends on.
 

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

@@ -21,22 +21,28 @@ You generate 3 files for sungen — a Gherkin compiler that produces Playwright
 | `sungen-capture-live` | Capture a live running page via Playwright MCP (snapshot + screenshot) |
 | `sungen-figma-source` | Figma URL → spec_figma.md + ui/*.png + provisional selectors |
 
-## Workflow (5 AI commands)
+## Workflow (6 AI commands)
 
 | Command | What it does |
 |---|---|
 | `/sungen:add-screen <name> <path>` | Scaffold `qa/screens/<name>/` directories |
-| `/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:add-flow <name> [--path <url>]` | Scaffold `qa/flows/<name>/` directories for E2E cross-screen testing |
+| `/sungen:create-test <name>` | Generate `.feature` + `test-data.yaml` (auto-detects screen or flow) |
+| `/sungen:review <name>` | Score syntax, coverage, viewpoint quality (auto-detects screen or flow) |
+| `/sungen:run-test <name>` | Generate `selectors.yaml`, compile, run, auto-fix (auto-detects screen or flow) |
 | `/sungen:delivery [name...]` | Export test cases → CSV for QA delivery (all screens if no arg) |
 
-**Order:** add-screen → create-test → review → run-test → delivery.
+**Screen path:** add-screen → create-test → review → run-test → delivery.
+**Flow path:** add-flow → create-test → review → run-test → delivery.
+
+`create-test`, `review`, and `run-test` auto-detect context: if `qa/flows/<name>/` exists → flow mode, else `qa/screens/<name>/` → screen mode.
 
 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.
 
 ## File Structure
 
+### Screen (single-screen testing)
+
 ```
 qa/screens/<screen-name>/
 ├── features/<screen>.feature      # Gherkin scenarios
@@ -47,9 +53,27 @@ qa/screens/<screen-name>/
 └── requirements/
     ├── spec.md                    # Screen specification (primary source)
     └── ui/                        # Screenshots, mockups
+```
+
+### Flow (E2E cross-screen testing)
 
-qa/deliverables/<screen>-testcases.csv  # Exported test cases (from /sungen:delivery)
-qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
+```
+qa/flows/<flow-name>/
+├── features/<flow>.feature        # Gherkin with @flow tag, [Screen:Element] refs
+├── selectors/<flow>.yaml          # Namespaced keys: "login:submit", "awards:title"
+├── test-data/<flow>.yaml          # Namespaced data: login.email, submission.nominee
+├── test-data/<flow>.staging.yaml      # Environment override (optional)
+├── test-data/<flow>.production.yaml   # Environment override (optional)
+└── requirements/
+    ├── spec.md                    # Flow specification (screens, steps, transitions)
+    └── ui/                        # Screenshots, mockups
+```
+
+Flows are **independent** from screens — own selectors, own test-data. Selectors use colon-namespaced keys (`"login:submit":`) to avoid duplicate element names across screens.
+
+```
+qa/deliverables/<name>-testcases.csv   # Exported test cases (from /sungen:delivery)
+qa/deliverables/<name>-testcases.xlsx  # Styled workbook for client hand-off
 ```
 
 ## Test Data
@@ -61,11 +85,18 @@ qa/deliverables/<screen>-testcases.xlsx # Styled workbook for client hand-off
 ## CLI Commands
 
 ```bash
+# Screen
 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 (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
+
+# Flow
+sungen add-flow --flow <name> --path <start-url>            # Scaffold flow directories
+sungen generate --flow <name>                                # Compile flow .feature → .spec.ts
+
+# All
+sungen generate --all                                        # Compile all screens and flows
+sungen delivery                                              # Export all → CSV + XLSX
+sungen delivery <name>                                       # Export a single screen or flow
 ```

package/src/orchestrator/templates/ai-instructions/claude-skill-capture-live.md

@@ -61,6 +61,18 @@ Where `<timestamp>` is `YYYYMMDD-HHMM` in local time (e.g. `live-20260421-1430.p
 
 This gives users a visual record they can reference later without re-scanning.
 
+### 6a. Verify unauthenticated redirect target (flow capture only)
+
+When capturing for a **flow** that includes security scenarios (e.g., "unauthenticated user cannot access X"):
+
+1. Open a **fresh incognito/unauthenticated** browser context (no storage state).
+2. `browser_navigate` to the protected route (e.g., `/dashboard`).
+3. Record the **actual redirect URL** — do NOT assume it goes to `/login`. The app may redirect to `/register`, `/`, or any other route.
+4. Report the redirect target to the caller: *"Unauthenticated access to `/dashboard` redirects to `/register`"*.
+5. The caller must use the **actual redirect URL** in Gherkin assertions (e.g., `Then User is on [Register] page`), never an assumed one.
+
+Skip this step if the flow has no security scenarios or the user explicitly says to skip.
+
 ### 6. Detect discrepancies vs spec
 
 If `spec.md` exists, briefly cross-check the snapshot against spec sections: