@sun-asterisk/sungen 3.2.2 → 3.2.3

package/src/orchestrator/templates/{ai-instructions/claude-cmd-add-screen.md → ai-src/commands/add-screen.md}

@@ -1,64 +1,148 @@
 ---
 name: add-screen
-description: 'Add a new Sungen screen or a sub-feature to an existing one — 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] [--feature <name>] [--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
+description: "Add a new Sungen screen or a sub-feature to an existing one — scaffolds directories, helps fill spec.md, and can capture visuals via Figma (pre-launch) or Playwright MCP (web) / Appium MCP (mobile)"
+argument-hint: "[screen-name] [url-path] [--feature <name>] [--figma <url>] [--reach <steps>] [--platform android|ios]"
+order: 10
+claude-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"
+copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
+codex-trigger: "Run when the user asks to add or scaffold a NEW screen/page to test. Step 1 of the sungen workflow. Do NOT use for flows, creating test cases, or running tests."
 ---
+{{^cap parallel-subagents}}
+**Input**: Screen name and URL path (e.g., `/sungen-add-screen login /login`).
+Optionally include a Figma URL: `/sungen-add-screen login /login --figma https://www.figma.com/design/...`.
+To add a sub-feature file to an existing screen: `/sungen-add-screen awards --feature modal`.
 
+{{/cap}}
 You are adding a new Sungen screen for test generation, or extending an existing screen with an additional `.feature` file (sub-feature).
 
 ## Parameters
 
+{{#cap parallel-subagents}}
 Parse from `$ARGUMENTS`:
 - **screen** — screen name (e.g., `login`, `dashboard`, `settings`)
 - **path** — URL path (e.g., `/login`, `/dashboard`, `/settings`) - optional when `--figma` is provided or when adding a sub-feature to an existing screen
 - **`--feature <name>`** — sub-feature name to add to an existing screen (e.g., `modal`, `filter`, `create-flow`). Creates `<screen>-<feature>.feature` + matching `selectors/<screen>-<feature>.yaml` + `test-data/<screen>-<feature>.yaml` without touching the screen's other files. Use this when one screen has multiple `.feature` files (e.g. main listing + modal + filter panel).
+{{/cap}}
+{{^cap parallel-subagents}}
+- **screen** — ${input:screen:screen name (e.g., login, dashboard)}
+- **path** — ${input:path:URL path (e.g., /login, /dashboard)} — optional when --figma is provided or when adding a sub-feature
+- **`--feature <name>`** — sub-feature name to add to an existing screen (e.g., `modal`, `filter`, `create-flow`). Creates `<screen>-<feature>.feature` + matching `selectors/<screen>-<feature>.yaml` + `test-data/<screen>-<feature>.yaml` without touching the screen's other files. Use this when one screen has multiple `.feature` files.
+{{/cap}}
 - **`--figma <url>`** — Figma share URL (optional)
+{{#cap parallel-subagents}}
 - **`--refresh`** — bypass Figma cache and re-fetch (optional, use with `--figma`)
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`--refresh`** — bypass Figma cache and re-fetch (optional, use with --figma)
+{{/cap}}
 - **`--scale <n>`** — PNG export scale factor, default 2 (optional)
+{{#cap parallel-subagents}}
 - **`--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 and **`--feature`** is NOT used and `--figma` was NOT provided, ask: "What is the URL path? (e.g., `/login`, `/dashboard`)"
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`--hi-res`** — export at 4× scale, shorthand for --scale 4 (optional)
+{{/cap}}
 
 **Mode detection** — before invoking the CLI, check whether `qa/screens/<screen>/` already exists:
 - Screen does NOT exist → fresh screen creation (need `--path` unless `--figma` provided)
 - Screen exists AND `--feature <name>` provided → sub-feature mode (skip spec.md, only generate the 3 new files)
 - Screen exists AND no `--feature` → ask the user whether they meant to add a sub-feature (offer `--feature <suggested-name>`) or refresh visuals only (with `--figma`)
 
+## Platform Detection
+
+Read `qa/capabilities.yaml` and check the `platform` field.
+
+- If `platform: mobile` → follow the **mobile path** (see "Mobile capture" step below, uses Appium MCP)
+- If `platform: web` or field absent → follow the **web path** (standard, uses Playwright MCP)
+
+For **mobile** projects:
+- **Live capture**: use **Appium MCP** (`select_device` → `appium_session_management(create)` → `appium_screenshot`)
+- **Navigation**: use `--reach "<steps>"` to describe UI navigation (e.g., `"tap [My Page] tab > tap [Settings] row"`)
+- **Device platform**: Optional `--platform android|ios` (defaults to Android if omitted)
+
 ## Steps
 
 ### 1. Scaffold the screen (or sub-feature)
 
+{{#cap parallel-subagents}}
 **Standard path (no `--figma`, no `--feature`):**
+{{/cap}}
+{{^cap parallel-subagents}}
+**Standard path (no --figma, no --feature):**
+
+Run with #tool:terminal:
+{{/cap}}
 ```bash
+{{#cap parallel-subagents}}
 sungen add --screen <screen> --path <path>
+{{/cap}}
+{{^cap parallel-subagents}}
+sungen add --screen ${input:screen} --path ${input:path}
+{{/cap}}
 ```
 
 **Sub-feature mode (`--feature <name>` provided):**
+{{^cap parallel-subagents}}
+
+Run with #tool:terminal:
+{{/cap}}
 ```bash
+{{#cap parallel-subagents}}
 sungen add --screen <screen> --feature <name> [--path <path>]
 # Generates qa/screens/<screen>/{features,selectors,test-data}/<screen>-<name>.{feature,yaml,yaml}
 # Existing screen files (awards.feature, spec.md, …) are untouched.
 # --path is optional — defaults to /<screen> when omitted. Pass --path only if the sub-feature lives at a different URL.
+{{/cap}}
+{{^cap parallel-subagents}}
+sungen add --screen ${input:screen} --feature <name> [--path ${input:path}]
+# Generates qa/screens/${input:screen}/{features,selectors,test-data}/${input:screen}-<name>.{feature,yaml,yaml}
+# Existing screen files (spec.md, awards.feature, …) are untouched.
+# --path is optional — defaults to /${input:screen} when omitted.
+{{/cap}}
 ```
 
+{{#cap parallel-subagents}}
 **Figma branch (when `--figma <url>` is in `$ARGUMENTS`):**
+{{/cap}}
+{{^cap parallel-subagents}}
+**Figma branch (when --figma \<url\> is provided):**
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Invoke the `sungen-capture` skill (mode figma-pat) by running:
+{{/cap}}
+{{^cap parallel-subagents}}
+Run with #tool:terminal:
+{{/cap}}
 ```bash
+{{#cap parallel-subagents}}
 sungen add --screen <screen> --figma '<url>' [--path <path>] [--feature <name>] [--refresh] [--scale <n>]
 # Single-quote the URL — Figma links contain `&` which bash otherwise treats as a background operator.
+{{/cap}}
+{{^cap parallel-subagents}}
+sungen add --screen ${input:screen} --figma <figma-url> [--path ${input:path}] [--feature <name>] [--refresh] [--scale <n>]
+{{/cap}}
 # --feature can be combined with --figma when the new sub-feature has its own Figma frame.
 ```
 
 This CLI command automatically:
 1. Parses the Figma URL and fetches the design node.
+{{#cap parallel-subagents}}
 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.
+{{/cap}}
+{{^cap parallel-subagents}}
+2. Downloads frame + variant PNGs to `qa/screens/${input:screen}/requirements/ui/`.
+3. Writes `qa/screens/${input:screen}/requirements/spec_figma.md` (auto-generated, always overwritten on re-run).
+4. Creates `qa/screens/${input:screen}/requirements/spec.md` stub **only if the file does not already exist** — never overwrites existing human content.
+{{/cap}}
 
 **Important coexistence rules:**
+{{#cap parallel-subagents}}
 - `--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`.
@@ -66,56 +150,137 @@ This CLI command automatically:
 
 **If Figma auth is missing**, the command will fail with a message like:
 > Figma PAT is not configured. Run: sungen figma auth set
-
+{{/cap}}
+{{^cap parallel-subagents}}
+- `--figma` and `--path` can be passed together.
+- `spec.md` is the human-authored source of truth — never modify it automatically.
+- `spec_figma.md` is auto-generated — tell the user to copy useful sections into `spec.md`.
+- `--capture` (Playwright screenshot) and `--figma` can be used simultaneously.
+{{/cap}}
+
+{{#cap parallel-subagents}}
 In that case, guide the user to run `sungen figma auth set` and retry.
+{{/cap}}
+{{^cap parallel-subagents}}
+**If Figma auth is missing**, guide the user to run `sungen figma auth set` and retry.
+{{/cap}}
 
 ### 1a. Synthesize narrative sections (Figma branch only)
 
+{{#cap parallel-subagents}}
 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-capture` skill (mode figma-pat) to fill it:
+{{/cap}}
+{{^cap parallel-subagents}}
+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-capture` skill (mode figma-pat):
+{{/cap}}
 
+{{#cap parallel-subagents}}
 1. Read `qa/screens/<screen>/requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter.
+{{/cap}}
+{{^cap parallel-subagents}}
+1. Read `qa/screens/${input:screen}/requirements/spec_figma.md` frontmatter for `file_key`, `node_id`, `figma_version_id`.
+{{/cap}}
 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.
 
+{{#cap parallel-subagents}}
 **Review gate.** Before moving on, show the user the synthesized narrative and use `AskUserQuestion`:
+{{/cap}}
+{{^cap parallel-subagents}}
+**Review gate.** Before moving on, show the user the synthesized narrative and ask:
+{{/cap}}
 
+{{#cap parallel-subagents}}
 - **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
+{{/cap}}
+{{^cap parallel-subagents}}
+- **1) Approve** — narrative looks right, continue to Step 2
+- **2) Edit** — user will tweak `spec_figma.md` now; wait for confirmation before continuing
+- **3) Cancel** — abort; advise the user that `spec.md` was NOT modified and they can re-run `sungen add --figma --refresh` later
+{{/cap}}
 
 ### 2. Capture visual source
 
+{{#cap parallel-subagents}}
 **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` skill (mode live))
-
+{{/cap}}
+{{^cap parallel-subagents}}
+**If Figma branch (Step 1) already downloaded PNGs** → visuals already exist. Offer:
+- **1) Continue** — Figma visuals are enough (Recommended)
+- **2) Also capture live page** — supplement Figma with real page scan (invoke `sungen-capture` skill (mode live))
+{{/cap}}
+
+{{#cap parallel-subagents}}
 **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` skill (mode figma-mcp)
 - **Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live)
 - **Skip** — user will drop images manually into `requirements/ui/` later
-
+{{/cap}}
+{{^cap parallel-subagents}}
+**If standard path (no --figma)** → go straight to source selection:
+- **1) Figma design** (Recommended for pre-launch) — invoke `sungen-capture` skill (mode figma-mcp)
+- **2) Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live)
+- **3) Skip** — user will drop images manually into `requirements/ui/` later
+{{/cap}}
+
+{{#cap parallel-subagents}}
 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`.
+{{/cap}}
+{{^cap parallel-subagents}}
+Each capture skill writes outputs into `qa/screens/${input:screen}/requirements/ui/` and reports back. Do not inline capture logic here — delegate to the skill so behavior stays consistent with `/sungen-create-test`.
+{{/cap}}
 
 ### 3. Fill spec.md
 
 **Skip this step when `--feature` was used** — the screen's existing `spec.md` is reused for all sub-features; only suggest the user append a new section for the sub-feature if useful (e.g. `## Modal — Confirm Withdrawal`).
 
+{{#cap parallel-subagents}}
 For fresh screen creation, use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+{{/cap}}
+{{^cap parallel-subagents}}
+For fresh screen creation, ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **1) Yes, fill now (Recommended)** / **2) Skip, fill later**.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 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.
+{{/cap}}
+{{^cap parallel-subagents}}
+If yes → open `qa/screens/${input: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.
+{{/cap}}
 
 ### 4. Next steps
 
+{{#cap parallel-subagents}}
 Tell the user what was created. When `--feature` was used, list the 3 new files explicitly (`features/<screen>-<name>.feature`, `selectors/<screen>-<name>.yaml`, `test-data/<screen>-<name>.yaml`) and remind that `/sungen:create-test` currently operates at the screen level — it will see both the parent feature and the new sub-feature and ask which one to update.
+{{/cap}}
+{{^cap parallel-subagents}}
+Tell the user what was created. When `--feature` was used, list the 3 new files explicitly (`features/${input:screen}-<name>.feature`, `selectors/${input:screen}-<name>.yaml`, `test-data/${input:screen}-<name>.yaml`) and remind that `/sungen-create-test` currently operates at the screen level — it will see both the parent feature and the new sub-feature and ask which one to update.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 Then use `AskUserQuestion` to offer next steps:
+{{/cap}}
+{{^cap parallel-subagents}}
+Then offer next steps:
+{{/cap}}
 
+{{#cap parallel-subagents}}
 - **`/sungen:create-test <screen>`** — Create test cases from requirements/designs (Recommended)
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`/sungen-create-test ${input:screen}`** — Create test cases from requirements/designs (Recommended)
+{{/cap}}
 - **Done for now** — I'll come back later
 
+{{#cap parallel-subagents}}
 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`.
 
+{{/cap}}
 ## CLI Reference
 
 ```

package/src/orchestrator/templates/{ai-instructions/claude-cmd-create-test.md → ai-src/commands/create-test.md}

@@ -1,10 +1,13 @@
 ---
 name: create-test
-description: 'Create or update test cases for a Sungen screen — generates feature + test-data files (tier-based: critical+high first, expand later)'
+description: "Create or update test cases for a Sungen screen — generates feature + test-data files (tier-based: critical+high first, expand later)"
 argument-hint: [screen-name]
-allowed-tools: Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot
+order: 20
+claude-tools: "Read, Grep, Bash, Glob, Write, AskUserQuestion, Skill, mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_take_screenshot"
+copilot-tools: "[vscode, execute, read, agent, edit, search, web, browser, todo, 'playwright/*']"
+codex-trigger: "Run when the user asks to CREATE, generate, write, or author test cases / a .feature file for a screen or flow. Step 2 (after add-screen/add-flow, before run-test). Do NOT use for executing, running, or compiling existing tests."
 ---
-
+{{#cap parallel-subagents}}
 ## ⛔ HARD RULE — No Figma MCP when PAT data exists
 
 If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
@@ -12,25 +15,55 @@ If `spec_figma.md` exists OR the user provides a Figma URL for the PAT flow:
 - Run `sungen add --screen <screen> --figma '<url>'` via Bash (**single-quote the URL**) then invoke the `sungen-capture` skill (**mode figma-pat**).
 
 ---
+{{/cap}}
+{{^cap parallel-subagents}}
+**Input**: Screen or flow name (e.g., `/sungen-create-test admin-users`).
+{{/cap}}
 
 ## Role
 
+{{#cap parallel-subagents}}
 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 `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. Focus on **Gherkin scenarios and test data only** — selectors are handled during `/sungen:run-test`.
+{{/cap}}
+{{^cap parallel-subagents}}
+You are a **Senior QA Engineer**. You structure test cases by viewpoint categories and translate UI into Gherkin test cases following the `sungen-gherkin-syntax` and `sungen-tc-generation` skills. **Tier 1 (critical+high) first** — expand coverage later. **Gherkin scenarios and test data only** — selectors are handled during `/sungen-run-test`.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 **Quality is built in, not a second command.** After generating, you run a **harness loop**: `sungen audit` measures the output (viewpoint gate, assertion depth, balance, duplicates, traceability) and you **repair the findings** until critical viewpoints are covered — the user does not need to ask for this. Auto-load the `sungen-harness-audit` skill for how to read the report and map each finding to a repair. (`/sungen:design` is an **alias** of this command.)
+{{/cap}}
+{{^cap parallel-subagents}}
+**Quality is built in.** After generating, run a **harness loop**: `sungen audit` measures the output and you **repair the findings** until critical viewpoints are covered — the user does not ask for this. Use the `sungen-harness-audit` skill. (`/sungen-design` is an **alias** of this command.)
+{{/cap}}
 
 ## Parameters
 
+{{#cap parallel-subagents}}
 Parse **name** from `$ARGUMENTS`. If missing, ask the user.
+{{/cap}}
+{{^cap parallel-subagents}}
+- **name** — ${input:name:screen or flow name (e.g., login, award-submission)}
+{{/cap}}
 
+{{#cap parallel-subagents}}
 **Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode. Else `qa/screens/<name>/` → screen mode. This determines paths, generation strategy, and CLI commands.
+{{/cap}}
+{{^cap parallel-subagents}}
+**Auto-detect context**: check if `qa/api/<name>/` or `qa/api/flows/<name>/` exists → **API unit mode** (below). Else if `qa/flows/<name>/` → flow mode (base path: `qa/flows/<name>/`). Else `qa/screens/<name>/` → screen mode (base path: `qa/screens/<name>/`).
+{{/cap}}
 
 ## API unit mode (driver-api)
 
+{{#cap parallel-subagents}}
 If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` skill end-to-end** instead of the screen/flow steps below: `sungen context --area <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --area <name>` gate + the `sungen-reviewer` sub-agent + repair loop to businessDepth ≥ 0.7** → record + trace. Then jump to the "Converge" next-step options (recommend `/sungen:run-test <name>`). The capture / viewpoint-group / selector steps do **not** apply.
+{{/cap}}
+{{^cap parallel-subagents}}
+If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the design loop differs — **no visual capture, no selectors**; the contract is the named-endpoint catalog. **Follow the `sungen-api-design` skill end-to-end** instead of the screen/flow steps: `sungen context --area <name>` (discover) → API viewpoint overview → generate `@api`/`@cases`/flow/`@concurrent`/`@query` scenarios → **`sungen audit --area <name>` gate + reviewer + repair loop to businessDepth ≥ 0.7** → record + trace. Then recommend `/sungen-run-test <name>`. The capture / viewpoint-group / selector steps do **not** apply.
+{{/cap}}
 
 ## Steps
 
+{{#cap parallel-subagents}}
 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.
@@ -39,30 +72,67 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
      - **Tier 1 — Critical & High priority** — ~10-15 scenarios/section: happy paths, core validation, security basics **(Recommended)**
      - **Full coverage (incremental)** — Tier 1 + 2 + 3, written tier-by-tier in batches (`Write` T1 → `Edit` append T2 → `Edit` append T3). Safe on any output-token budget.
      - **Full coverage (single pass)** — generate everything in one go (~40-60 scenarios/section). Faster, but **only if you raised your output cap** (`CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`) — otherwise it errors mid-generation. For power users on a high-token model/config.
+{{/cap}}
+{{^cap parallel-subagents}}
+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 update mode (options depend on which tiers already exist — see `sungen-tc-generation` skill for details).
+   - If no → fresh creation. **Write the feature file incrementally** (successive writes/edits, ≈10-15 scenarios per call) — never emit the whole suite in one response, or it can exceed the model's output-token cap (`response exceeded the N output token maximum`). Ask generation scope:
+     - **1) Tier 1 — Critical & High priority** — ~10-15 scenarios/section: happy paths, core validation, security basics **(Recommended)**
+     - **2) Full coverage (incremental)** — Tier 1 + 2 + 3, written tier-by-tier in batches. Safe on any output-token budget.
+     - **3) Full coverage (single pass)** — everything in one go (~40-60 scenarios/section). Faster, but **only if you raised your output cap** (`CLAUDE_CODE_MAX_OUTPUT_TOKENS ≥ 64000`) — otherwise it errors mid-generation. For power users on a high-token model/config.
+{{/cap}}
 3. **Read project context + screen requirements**
 
    **Project context** — check `qa/context.md` (project root, not screen-specific):
    - If exists → read it. Extract: roles, testing strategy directives, global business rules, error patterns.
    - Summarize what you found in one line (e.g. `"Roles: admin/staff/user | Strategy: focus security, skip VP-UI T1 | 2 global rules"`).
+{{#cap parallel-subagents}}
    - These are carried into the Coverage Map when invoking `sungen-tc-generation`.
+{{/cap}}
+{{^cap parallel-subagents}}
+   - These are carried into the Coverage Map when invoking the `sungen-tc-generation` skill.
+{{/cap}}
    - If absent → continue without it, no action needed.
 
+{{#cap parallel-subagents}}
    **Screen requirements** — check `qa/<screens|flows>/<name>/requirements/`:
+{{/cap}}
+{{^cap parallel-subagents}}
+   **Screen requirements** — check `<base>/${input:name}/requirements/`:
+{{/cap}}
    - If `spec.md` exists → read it as PRIMARY source (sections, fields, validation rules, business rules, states).
+{{#cap parallel-subagents}}
    - 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
      - **Continue without it** — generate tests from spec and other sources only
 
    **Context discovery (prefer an isolated agent).** Reading all sources here can flood this context. **Claude Code:** spawn the **`sungen-discovery`** sub-agent (Task tool, `subagent_type: sungen-discovery`) to read spec/figma/ui/live in isolation and return a **compact discovery report** (sources, completeness, conflicts, recommended route, key facts); use that report instead of pasting raw sources. **Copilot / no sub-agents:** do the reading inline as below.
+{{/cap}}
+{{^cap parallel-subagents}}
+   - 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
+     - **2) Continue without it** — generate tests from spec and other sources only
+{{/cap}}
 
    **Auto-detect visual source** — do NOT ask the user to pick a source. Instead, check what already exists and use it:
    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).
+{{#cap parallel-subagents}}
    3. If neither exists → use `AskUserQuestion` to ask: *"No visual source found. Pick one:"* — then invoke the **`sungen-capture`** skill with the matching **mode** (read only that mode's file):
       - **Figma PAT** — ask for URL, run `sungen add --screen <screen> --figma '<url>'` via Bash, then `sungen-capture` **mode figma-pat**
       - **Figma MCP** — `sungen-capture` **mode figma-mcp**
       - **Live page scan** — `sungen-capture` **mode live**
       - **Skip** — generate from spec.md only
+{{/cap}}
+{{^cap parallel-subagents}}
+   3. If neither exists → ask: *"No visual source found. Pick one:"* — then invoke the **`sungen-capture`** skill with the matching **mode** (read only that mode's file):
+      - **1) Figma PAT** — ask for URL, run `sungen add --screen ${input:name} --figma '<url>'`, then `sungen-capture` **mode figma-pat**
+      - **2) Figma MCP** — `sungen-capture` **mode figma-mcp**
+      - **3) Live page scan** — `sungen-capture` **mode live**
+      - **4) Skip** — generate from spec.md only
+{{/cap}}
 
    (When `spec_figma.md` exists, that is also `sungen-capture` **mode figma-pat**; when `ui/` images exist, that is **mode local**.)
 
@@ -70,6 +140,7 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
 
    Summarize what you found in requirements and present to the user.
 
+{{#cap parallel-subagents}}
 4. Follow the `sungen-tc-generation` skill for section identification, viewpoint generation, and output format. **Viewpoint loading discipline:** `sungen-viewpoint` is a **router** — from the page-type (form / list / detail / auth / dashboard …) read **only the matching group file(s)** (e.g. a login screen → group-e-identity; a product list → group-c-data-explore), never all five groups. This keeps the generation context lean. **For flows**, use the "Flow Test Generation" section in the skill. When requirements exist, use the "Requirements-Driven Generation" strategy. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections.
 5. Generate `.feature` + `test-data.yaml` following `sungen-gherkin-syntax` and `sungen-tc-generation`. **Partition the work into shards and generate them in parallel** when there are ≥2.
 
@@ -111,24 +182,67 @@ If the unit is **api-first** (`qa/api/<name>/` or `qa/api/flows/<name>/`), the d
    - **Ledger each phase** (so `sungen trace` can map the whole process): pick one `runId` at the start (e.g. a timestamp) and append `sungen ledger record --screen <name> --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>` (add `--tokens-in/--tokens-out` if known). The `--run` id groups this invocation so `trace`/`ledger report` show THIS run, not a mix of past runs. Do this for **every** phase, not just repair.
 
 6. **Converge — show the trace.** Run `sungen trace --screen <name>` and present to the user: the process map (phases + repair rounds), bottlenecks, and the **HUMAN-LOOP FOCUS** (@manual scenarios they must verify) + audit score & gate status & residual/cross-screen gaps. Then use `AskUserQuestion` to offer next steps based on which tier was just generated:
-
+{{/cap}}
+{{^cap parallel-subagents}}
+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. **For Tier 1**, apply the **Lightweight Guard** — verify required fields, validation rules, business rules, security checks, and key state transitions all have TCs after generation. **For Tier 2+**, **MUST** apply the full **Mapping Contract** — walk every `spec.md` section top-to-bottom and produce the indicated TCs per Table 1; handle `test-viewpoint.md` per Table 2. Do not silently skip sections. 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. Generate **group-by-group** (one viewpoint group at a time, tier-by-tier `Write`/`Edit` batches) to stay under the output-token cap. **For flows**: use `[Screen:Element]` namespace format, namespace test-data by phase, add `@flow` tag.
+   > **No parallel fan-out here.** Copilot has no sub-agents, so generation is sequential (the Claude Code variant fans out one `sungen-generator` per viewpoint group and merges). Same output, no speedup.
+5.4. **Depth self-check (deterministic — BEFORE the audit).** Run `sungen depth-lint --screen ${input:name}`. It splits every shallow business-critical scenario into **DEEPEN IN PLACE** (add a real value assertion — the printed `template` is a theme-keyed hint, apply judgment to the actual claim; never fake one onto a visibility/behavior scenario) and **CROSS-SCREEN** (route to a flow / tag `@manual:Mx` + reason — removes it from the depth denominator honestly). Act on both, re-run until `deepen` is empty (or only honest over-counts remain), THEN gate. Lifts first-pass `businessDepth` mechanically instead of via 2–3 repair rounds.
+5.5. **Quality gate & repair (harness — always run).** Per `sungen-harness-audit`: run `sungen audit --screen ${input:name}` (structural), THEN do an **independent semantic review inline** using the `sungen-reviewer` criteria (does each scenario's steps PROVE its title/viewpoint? observable Thens? business-critical assertion depth?). Merge both sets of issues; if gate FAILs / findings exist, repair (budget 3) and re-audit — GATE missing theme → generate it (cross-screen → **automate it in the flow** via `/sungen:add-flow`, NOT a full `@manual` screen duplicate — `sungen audit` flags an automatable `@manual` as `MANUAL-AUTOMATABLE`; reserve `@manual:Mx` for true judgment/missing-capability); DEPTH → add data assertions; BALANCE → add business-core first; TRACE → align VP ids. Never fake a pass.
+5.6. **Record.** `sungen manifest --screen ${input:name}`. Ledger **each phase** (not just repair) — pick one `runId` at the start and pass it so `trace`/`ledger report` show THIS run, not a mix: `sungen ledger record --screen ${input:name} --run <runId> --step <discovery|viewpoint|gherkin|audit|repair:N> --ms <elapsed>`. On re-run, start with `sungen manifest --screen ${input:name} --diff` and only regenerate changed sections.
+6. **Converge — show the trace.** Run `sungen trace --screen ${input:name}` and present: process map (phases + repair rounds), bottlenecks, **HUMAN-LOOP FOCUS** (@manual to verify), audit score + gate + residual gaps. Then offer next steps based on which tier was just generated:
+{{/cap}}
+
+{{#cap parallel-subagents}}
    > The harness gate + reviewer already ran above — you do **not** need `/sungen:review` as a next step (it's the independent checkpoint for hand/prompt-authored or pre-delivery cases). Recommend `run-test` or expanding coverage.
+{{/cap}}
+{{^cap parallel-subagents}}
+   > The harness gate + reviewer already ran above — `/sungen-review` is the independent checkpoint (hand/prompt-authored or pre-delivery), not a needed next step here.
+{{/cap}}
 
+{{#cap parallel-subagents}}
    **Optional — exploration mode (Loop 2).** The suite above is the deterministic, official output. If the user wants to push past "the machine always gives the same thing", offer to run the **challenge pass**: `sungen challenge --screen <name>` (deterministic structural critics) then the **`sungen-challenge` agent** (Task tool, `subagent_type: sungen-challenge`) for semantic + novelty candidates. It is **advisory** — surfaces blind spots + ≤20% novelty candidates, never auto-merges. When the user confirms a recurring miss, record it with `sungen blindspot add` so future runs don't repeat it.
+{{/cap}}
+{{^cap parallel-subagents}}
+   **Optional — exploration mode (Loop 2).** The suite above is the deterministic official output. To push past "same output every time", offer the **challenge pass**: run `sungen challenge --screen ${input:name}` (deterministic structural critics), then apply the `sungen-challenge` criteria inline for semantic + novelty candidates. Advisory only — surfaces blind spots + ≤20% novelty candidates, never auto-merges. Record a confirmed recurring miss with `sungen blindspot add` so future runs don't repeat it.
+{{/cap}}
 
    **After Tier 1 generation:**
+{{#cap parallel-subagents}}
    - **`/sungen:run-test <name>`** — Generate selectors and run tests now (Recommended)
    - **`/sungen:create-test <name>`** — Expand coverage: add @normal + @low scenarios (Tier 2)
+{{/cap}}
+{{^cap parallel-subagents}}
+   - **`/sungen-run-test ${input:name}`** — Generate selectors and run tests now (Recommended)
+   - **`/sungen-create-test ${input:name}`** — Expand coverage: add @normal + @low scenarios (Tier 2)
+{{/cap}}
    - **Done for now** — I'll come back later
 
    **After Tier 2 generation:**
+{{#cap parallel-subagents}}
    - **`/sungen:create-test <name>`** — Deep coverage: add BVA combos, cross-field validation, negative inputs, race conditions (Tier 3) (Recommended)
    - **`/sungen:run-test <name>`** — Generate selectors and run tests now
+{{/cap}}
+{{^cap parallel-subagents}}
+   - **`/sungen-create-test ${input:name}`** — Deep coverage: add BVA combos, cross-field validation, negative inputs, race conditions (Tier 3) (Recommended)
+   - **`/sungen-run-test ${input:name}`** — Generate selectors and run tests now
+{{/cap}}
    - **Done for now** — I'll come back later
 
    **After Tier 3 or Full generation:**
+{{#cap parallel-subagents}}
    - **`/sungen:run-test <name>`** — Generate selectors and run tests now (Recommended)
    - **`/sungen:create-test <name>`** — Add more sections if the screen changed
+{{/cap}}
+{{^cap parallel-subagents}}
+   - **`/sungen-run-test ${input:name}`** — Generate selectors and run tests now (Recommended)
+   - **`/sungen-create-test ${input:name}`** — Add more sections if the screen changed
+{{/cap}}
    - **Done for now** — I'll come back later
 
+{{#cap parallel-subagents}}
 **No selectors.yaml** — selectors are generated during `/sungen:run-test`.
+{{/cap}}
+{{^cap parallel-subagents}}
+**No selectors.yaml** — selectors are generated during `/sungen-run-test`.
+{{/cap}}

package/{dist/orchestrator/templates/ai-instructions/claude-cmd-dashboard.md → src/orchestrator/templates/ai-src/commands/dashboard.md}

@@ -1,10 +1,12 @@
 ---
 name: dashboard
-description: 'Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export.'
+description: "Build a single-file HTML dashboard with test cases + pass/fail results, history trends, compare runs, and CSV/XLSX export."
 argument-hint: "[screen-name...] (omit for all)"
-allowed-tools: Bash, Read, AskUserQuestion
+order: 60
+claude-tools: "Bash, Read, AskUserQuestion"
+copilot-tools: "[read, execute, edit, vscode/askQuestions]"
+codex-trigger: "Run when the user asks to OPEN or view the sungen results dashboard."
 ---
-
 ## Role
 
 You are a **QA Reporting Engineer**. Your job is to invoke the deterministic `sungen dashboard` CLI which builds a self-contained HTML report. The HTML is shareable as-is (open via `file://`, no server required).
@@ -19,10 +21,20 @@ Parse **screens** from `$ARGUMENTS`:
 
 ### 1. Invoke the CLI
 
+{{#cap parallel-subagents}}
 Prefer the local `./bin/sungen.js` when it exists (this is the canonical entry point when developing sungen itself, and ships any unpublished features the global package doesn't have yet). Fall back to `npx sungen` for downstream projects that consume sungen as a dependency.
+{{/cap}}
+{{^cap parallel-subagents}}
+Prefer the local `./bin/sungen.js` when it exists (sungen monorepo dev). Fall back to `npx sungen` for downstream projects.
+{{/cap}}
 
 ```bash
+{{#cap parallel-subagents}}
 # Local-first dispatcher — works in both the sungen monorepo and consumer projects:
+{{/cap}}
+{{^cap parallel-subagents}}
+# Local-first dispatcher — works in both monorepo and consumer projects:
+{{/cap}}
 [ -x ./bin/sungen.js ] && ./bin/sungen.js dashboard <screens> || npx sungen dashboard <screens>
 ```
 
@@ -40,9 +52,19 @@ The CLI handles:
 
 ### 2. Show the result + offer next steps
 
+{{#cap parallel-subagents}}
 Forward the CLI's summary verbatim, then use `AskUserQuestion`:
+{{/cap}}
+{{^cap parallel-subagents}}
+Forward the CLI's summary verbatim, then ask the user what they want next:
+{{/cap}}
 
+{{#cap parallel-subagents}}
 - **Open the dashboard** — Suggest `npx sungen dashboard --open` to open in the default browser, or just open `qa/dashboard/index.html` manually.
+{{/cap}}
+{{^cap parallel-subagents}}
+- **Open the dashboard** — Suggest `npx sungen dashboard --open` or open `qa/dashboard/index.html` manually.
+{{/cap}}
 - **Re-run after a test run** — Run `/sungen:run-test <screen>` to refresh `test-results/results.json`, then re-invoke `/sungen:dashboard`.
 - **Build for a single screen** — Run `/sungen:dashboard <screen>` to scope the report.
 - **Share the file** — The HTML at `qa/dashboard/index.html` can be emailed / Slacked / committed; recipients open it directly without any server.