@sun-asterisk/sungen 2.5.2 → 2.6.1

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-fix.md

@@ -24,6 +24,28 @@ Run tests in priority waves — catch fundamental issues early, fix critical pat
 
 If existing selectors already cover the feature file, **skip Phase 0** and go straight to compile + Phase 1.
 
+### Flow Mode: Screen Selector Reference
+
+When running Phase 0 for a **flow** (`qa/flows/<name>/`), check existing screen selectors first before snapshotting live pages. Screen selectors are already verified and proven — reuse them to save time and reduce errors.
+
+**Steps (before the standard Phase 0 steps):**
+
+1. **Parse screen references**: read the `.feature` file for `[Screen:Element]` references. Group by screen name (e.g., `Login`, `Awards`, `Dashboard`).
+2. **For each referenced screen**, check `qa/screens/<screen>/selectors/<screen>.yaml`:
+   - **If exists** → copy matching entries to the flow's `selectors.yaml`, remapping keys to namespace format:
+     - Screen key `submit` with screen `login` → flow key `"login:submit"`
+     - Screen key `email-field` with screen `login` → flow key `"login:email-field"`
+     - Preserve the full selector definition (type, value, name, etc.)
+     - Mark these entries as **verified** (no `@needs-live-verify` comment needed)
+   - **If not found** → add this screen to the "needs live snapshot" list
+3. **Elements not found in any screen selector** → also added to the "needs live snapshot" list
+4. **If "needs live snapshot" list is empty** → Phase 0 screen-reference covered everything, skip to compile
+5. **If "needs live snapshot" list is non-empty** → continue with the standard Phase 0 steps below, but only generate selectors for the missing elements (don't re-snapshot elements already copied from screens)
+
+**Merge rule**: screen-referenced entries take priority over provisional (Figma-sourced) entries. If an element was previously generated from Figma with `@needs-live-verify`, the screen-verified entry replaces it.
+
+**Important**: flow selectors remain private — they live in the flow's own YAML file. This is just initialization from screen data, not a runtime dependency.
+
 ### Steps
 
 1. **Confirm with the user** via `AskUserQuestion`: *"Generate selectors from the live page via Playwright MCP now?"* — offer **Yes, scan live page** / **Skip (use existing selectors.yaml)** / **Cancel**.
@@ -39,9 +61,10 @@ If existing selectors already cover the feature file, **skip Phase 0** and go st
    - Selector priority: follow the table in **Diagnosis & Fix § Step 3** (`testid` > `role`+name > `placeholder` > `label` > `locator` > `text`).
    - Copy names **character-for-character** from the snapshot. Never infer from the Gherkin label.
    - If an element is auto-inferable per `sungen-selector-keys` § Auto-Infer, **omit it** from YAML — keep the file minimal.
-7. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
-8. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
-9. **Compile**: `sungen generate --screen <screen>` — then proceed to Phase 1.
+7. **Substring ambiguity check**: for each `role` + `name` selector, check if any other element in the snapshot has a name that **contains** this name as a substring (e.g., `"Đăng ký"` vs `"Đăng ký bằng Google"`). If yes → add `exact: true` to prevent strict mode violation at runtime.
+8. **Merge, don't overwrite**: preserve the page selector and any user-authored entries in `selectors.yaml`. Only add missing keys.
+9. **Show summary + confirm**: list the keys that will be added, ask the user to approve, then write the file.
+10. **Compile**: **Screen**: `sungen generate --screen <screen>`. **Flow**: `sungen generate --flow <flow>`. Then proceed to Phase 1.
 
 ### Common Phase 0 pitfalls
 
@@ -204,6 +227,7 @@ Array.from(document.querySelectorAll('[data-testid]'))
 Common fixes:
 - Name mismatch → copy exact name from snapshot
 - Multiple matches → add `nth` or `exact: true`
+- Substring ambiguity (e.g., `"Submit"` matches `"Submit"` and `"Submit & Continue"`) → add `exact: true`
 - No accessible name → use `testid` or `locator` (CSS)
 - Element in iframe → add `frame` field
 - Dynamic content → use `testid` or structural `role` + `nth`
@@ -212,7 +236,11 @@ Common fixes:
 
 Always recompile before re-running:
 ```bash
+# Screen
 sungen generate --screen <screen>
+
+# Flow
+sungen generate --flow <flow>
 ```
 
 Then re-run only the current phase's failing tests, not all tests.

package/src/orchestrator/templates/ai-instructions/claude-skill-selector-keys.md

@@ -27,6 +27,51 @@ Copy the text from `[Reference]` as-is, then lowercase. Unicode characters (Viet
 4. **Keep all Unicode characters as-is** (Vietnamese diacritics, Japanese, etc.)
 5. **Keys use spaces** (not dots) as word separators
 
+## Flow Namespaced Keys
+
+In `@flow` features, selectors are namespaced by screen using colon: `[Screen:Element]` → YAML key `"screen:element"` (quoted).
+
+```
+[Login:Email]        → "login:email"
+[Login:Submit]       → "login:submit"
+[Dashboard:Awards]   → "dashboard:awards"
+[Awards:Submit]      → "awards:submit"
+```
+
+**Rules:**
+1. Same lowercase + Unicode rules as standard keys
+2. Colon separates screen prefix from element name
+3. **YAML keys must be quoted** because of the colon: `"login:email":`
+4. Page references don't need prefix: `[Login]` → `login:` (page type)
+5. Prevents duplicate names across screens (e.g., `"login:submit"` vs `"awards:submit"`)
+
+```yaml
+# Flow selectors — each screen section namespaced
+login:
+  type: 'page'
+  value: '/login'
+
+"login:email":
+  type: 'testid'
+  value: 'email-input'
+
+"login:submit":
+  type: 'role'
+  value: 'button'
+  name: 'Login'
+
+awards:
+  type: 'page'
+  value: '/awards'
+
+"awards:submit":
+  type: 'role'
+  value: 'button'
+  name: 'Submit Award'
+```
+
+**Type and nth suffixes still apply:** `"login:submit--button"`, `"awards:item--3"`
+
 ## Type-Suffixed Keys
 
 When the same label is used for different element types, add `--type` suffix:

package/src/orchestrator/templates/ai-instructions/claude-skill-tc-generation.md

@@ -161,6 +161,29 @@ Scenario: Reset filters to default
 
 For one-time setup/teardown. Most screens don't need these.
 
+### `@parallel` — when tests need independent browser state
+
+Add `@parallel` at feature level when:
+
+1. **Multiple auth groups** (required) — e.g., `@auth:user` + `@no-auth` scenarios. Serial mode uses one shared context and cannot mix auth roles. Compiler will error without this tag.
+2. **Validation-heavy features** (recommended) — each scenario fills forms with different invalid data and needs a clean form. Serial shared page keeps previous test's input.
+
+Serial (default) is best for: CRUD flows, sequential user journeys, UI checks on the same page.
+
+```gherkin
+@parallel @auth:user
+@cleanup:forms
+Feature: kudos Screen
+
+  @critical
+  Scenario: Send kudos
+    ...
+
+  @critical @no-auth
+  Scenario: Unauthenticated user is redirected
+    ...
+```
+
 ## Output Format
 
 **Feature file** — `qa/screens/<screen>/features/<screen>.feature`
@@ -237,4 +260,73 @@ valid_email: admin@staging.example.com
 valid_password: StagingPass456
 ```
 
+## Flow Test Generation
+
+When generating tests for a **flow** (`qa/flows/<name>/`), adapt the strategy:
+
+### Structure
+
+- **Background** — starting page only: `Given User is on [Login] page`
+- **Scenarios** — each phase of the E2E journey as a separate scenario
+- **Selector refs** — use `[Screen:Element]` namespace format (see `sungen-gherkin-syntax`)
+- **Test data** — namespace by phase: `login.email`, `submission.nominee`
+- **Feature tag** — `@flow` required at feature level
+
+### Flow vs Screen Differences
+
+| Aspect | Screen | Flow |
+|---|---|---|
+| Section focus | UI patterns per section | Journey phases across screens |
+| Viewpoints | VP-UI, VP-VAL, VP-LOGIC, VP-SEC per section | VP-LOGIC (flow transitions), VP-SEC (auth persistence), VP-VAL (cross-screen data) |
+| Tier 1 focus | Happy path + required validation per section | Happy path through entire flow + auth + key error recovery |
+| Background | Navigate to screen | Navigate to starting page |
+
+### Flow-specific scenarios to generate
+
+| Category | Examples |
+|---|---|
+| **Happy path** | Complete flow end-to-end with valid data |
+| **Auth persistence** | Auth state maintained across screen transitions |
+| **Error recovery** | Invalid input mid-flow → fix → continue |
+| **Incomplete flow** | User abandons at each phase → state cleanup |
+| **Cross-screen data** | Data entered on screen A visible on screen B |
+
+### Output Format (Flow)
+
+```gherkin
+@flow @auth:user
+Feature: Award Submission Flow
+
+  Background:
+    Given User is on [Login] page
+
+  @critical
+  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
+
+  @critical
+  Scenario: User navigates to awards and submits
+    When User click [Dashboard:Awards] link
+    Then User see [Awards] page
+    When User fill [Awards:Nominee] field with {{submission.nominee}}
+    And User click [Awards:Submit] button
+    Then User see {{success_message}} message
+```
+
+**Test data** — `qa/flows/<name>/test-data/<name>.yaml`, namespaced by phase:
+
+```yaml
+login:
+  email: "admin@example.com"
+  password: "secret123"
+submission:
+  nominee: "John Doe"
+success_message: "Award submitted successfully"
+```
+
+**Environment overrides** work the same: `<name>.<env>.yaml` merged at runtime via `SUNGEN_ENV`.
+
 **Do NOT generate**: `selectors.yaml` (created during run-test), Playwright code (sungen compiles).

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

@@ -89,6 +89,36 @@ Do NOT mark `@manual` when data is visible in snapshot or documented in spec —
 
 ---
 
+## Flow Review Additions
+
+When reviewing a `@flow` feature (`qa/flows/<name>/`), apply standard scoring PLUS these flow-specific checks:
+
+### Syntax — additional checks
+- `[Screen:Element]` format used consistently (not mixing bare `[Element]` refs)
+- YAML keys quoted with colon: `"login:submit":` not `login:submit:`
+- `@flow` tag present at feature level
+
+### Coverage — additional dimensions
+| Dimension | Pts (from existing 40) | What to check |
+|---|---|---|
+| Screen transitions | (part of State transitions) | Each screen-to-screen navigation tested |
+| Auth persistence | (part of Happy paths) | Auth state maintained across transitions |
+| Error recovery mid-flow | (part of Negative cases) | Invalid input at each phase → fix → continue |
+| Cross-screen data | (part of Edge cases) | Data entered on screen A asserted on screen B |
+
+### Viewpoint — flow-specific classification
+- **VP-LOGIC** — screen transitions, navigation flow, auth persistence
+- **VP-VAL** — cross-screen data consistency, form data carried across pages
+- **VP-SEC** — auth state across redirects, permission changes mid-flow
+- VP-UI is typically minimal in flows (focus on functionality over layout)
+
+### Checklist — flow-specific items
+11. **Missing screen transitions** — flow visits 4 screens but only 2 transitions tested? Add missing
+12. **Orphan scenarios** — scenario doesn't connect to previous/next phase? Flag broken flow
+13. **Selector namespace consistency** — mixing `[Submit]` and `[Login:Submit]` in same flow? Standardize
+
+---
+
 ## Output Format
 
 ```markdown

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

@@ -0,0 +1,86 @@
+---
+name: sungen-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>]'
+agent: 'agent'
+tools: [vscode, execute, read, agent, edit, search, todo]
+---
+
+**Input**: Flow name and optional starting URL (e.g., `/sungen-add-flow award-submission --path /login`).
+
+You are adding a new Sungen flow for E2E cross-screen test generation.
+
+## Parameters
+
+- **flow** — ${input:flow:flow name (e.g., award-submission, user-onboarding)}
+- **--path \<url\>** — starting page URL path (default: `/login`)
+- **--description \<text\>** — flow description (optional)
+
+## Steps
+
+### 1. Scaffold the flow
+
+Run with #tool:terminal:
+```bash
+sungen add-flow --flow ${input:flow} --path ${input:path}
+```
+
+This creates:
+```
+qa/flows/${input:flow}/
+├── features/${input:flow}.feature        # Gherkin with @flow tag, Background, sample scenarios
+├── selectors/${input:flow}.yaml          # Namespaced keys: "login:submit", "awards:submit"
+├── test-data/${input:flow}.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
+
+Ask: *"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/${input:flow}/requirements/ui/` and reports back a summary. Do not inline capture logic here — always delegate to the skill.
+
+### 3. Fill spec.md
+
+Ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+
+If yes → open `qa/flows/${input:flow}/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 and offer next steps:
+
+- **`/sungen-create-test ${input:flow}`** — Generate test scenarios for the flow (Recommended)
+- **Done for now** — I'll come back later
+
+## 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/copilot-cmd-create-test.md

@@ -6,7 +6,7 @@ agent: 'agent'
 tools: [vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']
 ---
 
-**Input**: Screen name (e.g., `/sungen-create-test admin-users`).
+**Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
 
 ## Role
 
@@ -14,13 +14,16 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
 ## Parameters
 
-- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+- **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
+
+**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. Verify `qa/screens/${input:screen}/` exists. If not → run `/sungen-add-screen` first.
+1. **Flow**: Verify `qa/flows/${input:name}/` exists. If not → `/sungen-add-flow` first.
+   **Screen**: Verify `qa/screens/${input:name}/` exists. If not → `/sungen-add-screen` first.
 2. Check if `.feature` already has scenarios. If yes → summarize existing coverage and ask: **1) Add new sections**, **2) Add viewpoints to existing sections**, or **3) Replace all**. See `sungen-tc-generation` skill for update mode details.
-3. **Read requirements & resolve visual source** — check `qa/screens/${input:screen}/requirements/`:
+3. **Read requirements & resolve visual source** — check `<base>/${input: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), ask:
      - **1) Fill test-viewpoint.md first** — identify edge cases, known issues, and design decisions before generating tests
@@ -30,7 +33,7 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
    1. If `spec_figma.md` exists → read it as Figma supplement (PAT flow already completed during `add-screen`). Do NOT call any `mcp__figma__*` tool.
    2. If `ui/` has images (`.png`, `.jpg`, etc.) → read them for visual context (layout, element positions, states).
    3. If neither exists → ask: *"No visual source found. Pick one:"*
-      - **1) Figma PAT** — ask for URL, run `sungen add --screen ${input:screen} --figma '<url>'`, then invoke `sungen-figma-source` skill
+      - **1) Figma PAT** — ask for URL, run `sungen add --screen ${input:name} --figma '<url>'`, then invoke `sungen-figma-source` skill
       - **2) Figma MCP** — invoke `sungen-capture-figma` skill
       - **3) Live page scan** — invoke `sungen-capture-live` skill
       - **4) Skip** — generate from spec.md only
@@ -39,13 +42,13 @@ You are a **Senior QA Engineer**. You structure test cases by viewpoint categori
 
    Summarize what you found in requirements and present to the user.
 
-4. Identify screen sections → ask user which to focus on (per `sungen-tc-generation` skill). When requirements exist, use the "Requirements-Driven Generation" strategy. Present sections as a numbered list and let user pick.
-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. Present sections as a numbered list and let user pick.
+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 and offer next steps:
 
-- **`/sungen-review ${input:screen}`** — Review syntax, coverage, viewpoint quality (Recommended)
-- **`/sungen-run-test ${input:screen}`** — Skip review, generate selectors and run tests now
-- **`/sungen-create-test ${input:screen}`** — Expand coverage: add @normal + @low scenarios
+- **`/sungen-review ${input:name}`** — Review syntax, coverage, viewpoint quality (Recommended)
+- **`/sungen-run-test ${input:name}`** — Skip review, generate selectors and run tests now
+- **`/sungen-create-test ${input: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/copilot-cmd-delivery.md

@@ -1,7 +1,7 @@
 ---
 name: sungen-delivery
 description: 'Export Gherkin scenarios + Playwright results to CSV test case file for QA delivery.'
-argument-hint: "[screen-name...] (omit for all screens)"
+argument-hint: "[name...] (omit for all screens and flows)"
 tools: [read, execute, edit, vscode/askQuestions]
 ---
 
@@ -11,9 +11,9 @@ You are a **QA Test Delivery Engineer**. Your job is to invoke the deterministic
 
 ## Parameters
 
-Parse **screens** from `$ARGUMENTS`:
-- If empty → CLI will process **all** screens in `qa/screens/`
-- If provided → pass them through to the CLI
+Parse **names** from `$ARGUMENTS`:
+- If empty → CLI will process **all** screens in `qa/screens/` and flows in `qa/flows/`
+- If provided → pass them through to the CLI (auto-detects screen vs flow per name)
 
 ## Steps
 
@@ -22,28 +22,29 @@ Parse **screens** from `$ARGUMENTS`:
 Run via Bash (single command, no extra parsing):
 
 ```bash
-npx sungen delivery <screens>
+npx sungen delivery <names>
 ```
 
-- If no screen args → just run `npx sungen delivery`
-- If screen args → pass them as positional arguments
+- If no args → just run `npx sungen delivery` (exports all screens + flows)
+- If args → pass them as positional arguments (auto-detects screen vs flow)
 
 The CLI handles:
-- Scope detection (all screens vs specific)
+- Scope detection (all screens + flows vs specific names)
+- Auto-detect: `qa/flows/<name>/` → flow, `qa/screens/<name>/` → screen
 - 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`
+- Generating CSV at `qa/deliverables/<name>-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.
+If the CLI exits with blocking issues, it will have already printed a clear table showing exactly what's missing per target.
 
 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.
+- **Continue with available targets** — Re-run as `npx sungen delivery <names> --continue-on-missing` to skip targets with blocking issues.
 - **Cancel** — Exit.
 
 ### 3. Show summary + offer next steps (on success)
@@ -51,8 +52,8 @@ Use `AskUserQuestion` to offer next steps:
 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>`.
+- **Run tests to refresh results** — Suggest `/sungen-run-test <name>` to update test results, then re-run delivery.
+- **Export another target** — User can run `/sungen-delivery <other-name>`.
 - **Done** — Exit.
 
 ## Important notes
@@ -65,7 +66,7 @@ Forward the CLI's summary table to the user verbatim. Then use `AskUserQuestion`
 ## CLI Reference
 
 ```
-sungen delivery [screens...]
+sungen delivery [names...]
   [--skip-preflight]          Skip pre-flight checks (not recommended)
-  [--continue-on-missing]     Skip screens with blocking misses
+  [--continue-on-missing]     Skip targets with blocking misses
 ```

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

@@ -6,7 +6,7 @@ agent: 'agent'
 tools: [vscode, read, edit, search, todo]
 ---
 
-**Input**: Screen name (e.g., `/sungen-review admin-users`).
+**Input**: Screen or flow name (e.g., `/sungen-review admin-users`).
 
 ## Role
 
@@ -14,17 +14,19 @@ You are a **Senior QA Reviewer**. You evaluate Gherkin test cases using the `sun
 
 ## Parameters
 
-- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+- **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
+
+**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/${input:screen}/features/${input:screen}.feature` and `qa/screens/${input:screen}/test-data/${input: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/${input:screen}/selectors/${input: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), offer next steps:
 
-- **`/sungen-run-test ${input:screen}`** — Generate selectors, compile, and run tests (Recommended)
-- **`/sungen-create-test ${input:screen}`** — Add more test cases before running
+- **`/sungen-run-test ${input:name}`** — Generate selectors, compile, and run tests (Recommended)
+- **`/sungen-create-test ${input:name}`** — Add more test cases before running
 - **Done for now** — I'll come back later

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

@@ -1,7 +1,7 @@
 ---
 name: sungen-run-test
 description: 'Generate selectors + auth state via Playwright MCP, compile, and run Playwright tests — auto-fixes selectors on failure'
-argument-hint: '[screen-name]'
+argument-hint: '[name]'
 tools: [read, execute, edit, vscode/askQuestions, playwright/*]
 ---
 
@@ -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,25 +63,27 @@ 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.
 
 ```bash
 # ❌ Wrong — --reporter flag disables the config's JSON reporter
-npx playwright test specs/generated/<screen>/<screen>.spec.ts --reporter=list
+npx playwright test specs/generated/<name>/<name>.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
+npx playwright test specs/generated/<name>/<name>.spec.ts
 ```
 
 If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter override.
@@ -91,10 +95,10 @@ If you want to filter scenarios, use `-g "<pattern>"` instead of a reporter over
 After showing results, use `AskUserQuestion` to offer next steps:
 
 If all tests **passed**:
-- **`/sungen:create-test <screen>`** — Add more test cases (Recommended)
+- **`/sungen-create-test <name>`** — Add more test cases (Recommended)
 - **Done** — All tests passed, I'm finished
 
 If tests **failed** (after retries):
-- **`/sungen:run-test <screen>`** — Re-run after manual fixes
-- **`/sungen:create-test <screen>`** — Revise test cases
+- **`/sungen-run-test <name>`** — Re-run after manual fixes
+- **`/sungen-create-test <name>`** — Revise test cases
 - **Done for now** — I'll fix manually later