@sun-asterisk/sungen 3.2.2-beta.9 → 3.2.3-beta.3

package/src/orchestrator/screen-manager.ts

@@ -6,6 +6,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { chromium } from '@playwright/test';
+import { readCapabilities } from '../harness/capability';
 
 export interface ScreenOptions {
   name: string;
@@ -13,6 +14,20 @@ export interface ScreenOptions {
   capture?: boolean;
   feature?: string;
   description?: string;
+  /**
+   * Optional per-OS tag emitter: 'android' | 'ios'. When set, the feature stub
+   * gets @platform:android or @platform:ios for OS-specific screens. Does NOT
+   * affect directory routing (always qa/screens/). Mobile project is detected via
+   * qa/capabilities.yaml, not this flag.
+   */
+  platform?: string;
+  /**
+   * Mobile navigation recipe (the in-app web-path analog). A `>`-separated list of nav steps
+   * that take the app from launch to THIS screen, e.g. "tap [My Page] tab > tap [Settings] row".
+   * Scaffolded into the feature's Background after the `Given User is on [Home] screen` anchor.
+   * Mobile-only; ignored (with a warning) for web projects. Omit when this IS the launcher screen.
+   */
+  reach?: string;
 }
 
 export class ScreenManager {
@@ -31,15 +46,31 @@ export class ScreenManager {
     // Validate screen name
     this.validateScreenName(options.name);
 
+    // Detect project platform from qa/capabilities.yaml (single source of truth)
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    // --reach is mobile-only; warn and drop when the project is web
+    if (options.reach && !isMobile) {
+      console.warn(
+        `Warning: --reach is a mobile navigation recipe and is ignored for web projects ` +
+        `(web screens are addressed by their --path URL). Dropping it.`
+      );
+      options = { ...options, reach: undefined };
+    }
+
     // Normalize screen name for directory
     const screenName = this.normalizeScreenName(options.name);
+    // Always use qa/screens/ regardless of platform (1-platform model — no qa/mobile/ tree)
     const screenDir = path.join(this.screensDir, screenName);
 
-    // Derive filename: --feature flag creates "<screen>-<feature>" name
+    // Derive filename: --feature flag creates "<screen>-<feature>" name.
+    // For mobile, `path` is the app entry (pkg/Activity), NOT a URL — never derive
+    // the filename from it; use the screen name instead.
     let filename: string;
     if (options.feature) {
       filename = `${screenName}-${this.normalizeScreenName(options.feature)}`;
-    } else if (options.path) {
+    } else if (options.path && !isMobile) {
       filename = this.extractFilenameFromPath(options.path);
     } else {
       filename = screenName;
@@ -92,18 +123,25 @@ export class ScreenManager {
     const featureContent = this.generateFeatureTemplate(options, filename);
     fs.writeFileSync(featurePath, featureContent, 'utf-8');
 
-    // Generate empty selector YAML (with page entry)
+    // Generate empty selector YAML. Web gets a `page` entry (the route); mobile
+    // selectors come from Appium MCP at run-test, so it's just a header comment.
     if (!fs.existsSync(selectorPath)) {
-      const pagePath = options.path || `/${screenName}`;
-      fs.writeFileSync(selectorPath, [
-        `# ${options.name} Screen Selectors`,
-        `# Fill via AI or manually`,
-        ``,
-        `${screenName}:`,
-        `  type: 'page'`,
-        `  value: '${pagePath}'`,
-        ``,
-      ].join('\n'), 'utf-8');
+      const selectorLines = isMobile
+        ? [
+            `# ${options.name} Screen Selectors (mobile)`,
+            `# Generated at /sungen:run-test via Appium MCP — accessibility-id preferred.`,
+            ``,
+          ]
+        : [
+            `# ${options.name} Screen Selectors`,
+            `# Fill via AI or manually`,
+            ``,
+            `${screenName}:`,
+            `  type: 'page'`,
+            `  value: '${options.path || `/${screenName}`}'`,
+            ``,
+          ];
+      fs.writeFileSync(selectorPath, selectorLines.join('\n'), 'utf-8');
     }
 
     // Generate empty test-data YAML
@@ -186,9 +224,9 @@ export class ScreenManager {
       ].join('\n'), 'utf-8');
     }
 
-    // Auto-screenshot: capture page only when --capture is set (requires --path)
+    // Auto-screenshot: capture page only when --capture is set and not mobile (requires --path)
     // Use filename (not screenName) so each feature gets its own screenshots
-    if (options.capture && options.path) {
+    if (options.capture && options.path && !isMobile) {
       await this.captureScreenshot(options.path, requirementsUiDir, filename);
     }
 
@@ -204,12 +242,21 @@ export class ScreenManager {
     }
     console.log('');
 
-    console.log('Next steps:');
-    console.log(`  1. Fill requirements/spec.md with screen spec (fields, validation, business rules)`);
-    console.log(`     Optionally add UI designs to requirements/ui/ (screenshots, mockups)`);
-    console.log(`  2. Generate test cases: /sungen:create-test ${screenName} (or /sungen-create-test)`);
-    console.log(`  3. Compile: sungen generate --screen ${screenName}`);
-    console.log(`  4. Run: npx playwright test\n`);
+    if (isMobile) {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with screen spec (elements, actions, business rules)`);
+      console.log(`     Use /sungen:add-screen with sungen-capture-mobile to scan via Appium MCP`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${screenName}`);
+      console.log(`  3. Compile: sungen generate --screen ${screenName} --framework appium`);
+      console.log(`  4. Run: npm run test:mobile\n`);
+    } else {
+      console.log('Next steps:');
+      console.log(`  1. Fill requirements/spec.md with screen spec (fields, validation, business rules)`);
+      console.log(`     Optionally add UI designs to requirements/ui/ (screenshots, mockups)`);
+      console.log(`  2. Generate test cases: /sungen:create-test ${screenName} (or /sungen-create-test)`);
+      console.log(`  3. Compile: sungen generate --screen ${screenName}`);
+      console.log(`  4. Run: npx playwright test\n`);
+    }
   }
 
   /**
@@ -291,6 +338,57 @@ export class ScreenManager {
   }
 
   private generateSpecTemplate(options: ScreenOptions, screenName: string): string {
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    if (isMobile) {
+      const appEntry = options.path || this.readWdioAppEntry() || '<appPackage>';
+      return `# ${options.name} Screen Specification
+
+## Overview
+- **App Entry:** ${appEntry}
+- **Platform:** mobile (Android + iOS)
+- **Auth Required:** no
+- **Reach:** ${options.reach || '<!-- nav recipe: how to reach this screen from app launch, e.g. "tap [My Page] tab > tap [Settings] row" -->'}
+
+## Sections
+
+### Section: [Section Name]
+- **Type:** list | card | form | modal | navigation | tab-bar
+- **Description:** [Brief description of this section]
+
+#### Elements
+| Element | Type | Identifier | Notes |
+|---------|------|------------|-------|
+| [Element Name] | button | accessibility-id | [tap target, e.g., submits form] |
+
+#### Actions
+| Action | Element | Behavior |
+|--------|---------|----------|
+| [Action Name] | button | [What happens on tap] |
+
+#### States
+| State | Condition | Visual |
+|-------|-----------|--------|
+| Default | Screen load | [Default appearance] |
+| Loading | After tap | [Loading indicator] |
+| Error | Action fails | [Error appearance] |
+| Success | Action complete | [Success behavior] |
+
+## Business Rules
+<!-- Rules that affect test logic: limits, permissions, conditions -->
+- [Rule 1]
+
+## Accessibility
+<!-- Accessibility IDs, content-desc, aria-labels -->
+- Accessibility IDs: [element: id]
+
+## Notes
+<!-- Edge cases, known issues, environment-specific behavior -->
+- [Note 1]
+`;
+    }
+
     const pagePath = options.path || `/${screenName}`;
     return `# ${options.name} Screen Specification
 
@@ -348,9 +446,48 @@ export class ScreenManager {
 
   private generateFeatureTemplate(options: ScreenOptions, filename: string): string {
     const screenName = this.normalizeScreenName(options.name);
-    const featurePath = options.path || `/${screenName}`;
     const description = options.description || `interact with the ${options.name} screen`;
 
+    const caps = readCapabilities(this.cwd);
+    const isMobile = caps.platform === 'mobile';
+
+    if (isMobile) {
+      // Determine platform tag: --platform android/ios emits a per-OS tag for OS-specific screens.
+      // Default (no --platform) = cross-platform, no OS-specific tag.
+      const platformTag =
+        options.platform === 'android' ? '@platform:android'
+        : options.platform === 'ios' ? '@platform:ios'
+        : '@platform:mobile';
+
+      // App entry: explicit --path → wdio.conf.ts default → placeholder.
+      const appEntry = options.path || this.readWdioAppEntry() || '<appPackage>';
+
+      // Navigation recipe (Background block)
+      const background = this.buildMobileBackground(options.reach);
+
+      return `${platformTag}
+Feature: ${options.name} Screen
+
+  As a user
+  I want to ${description}
+  So that I can accomplish my tasks
+  Path: ${appEntry}
+
+  # Mobile (Appium) — selectors generated at /sungen:run-test via Appium MCP.
+  # Use accessibility-id selectors; assert text content with \`header with {{var}}\`
+  # (compiles to content-desc/label via toHaveAttribute). See sungen-mobile-gestures
+  # for swipe/long-press/scroll steps.
+
+${background}
+  @high
+  Scenario: Sample scenario for ${options.name}
+    When User tap [element]
+    Then User see [result] header with {{result_text}}
+`;
+    }
+
+    // Web feature stub
+    const featurePath = options.path || `/${screenName}`;
     return `Feature: ${options.name} Screen
 
   As a user
@@ -367,4 +504,82 @@ export class ScreenManager {
     Then User see [result] text with {{success}}
 `;
   }
+
+  /**
+   * Read the default app entry (`<appPackage>/<appActivity>`) from the project's wdio.conf.ts so a
+   * mobile `add-screen` without `--path` scaffolds a real, runnable `Path:` matching the configured
+   * app instead of a `<placeholder>`. Supports both the env-default form
+   * (`APP_PACKAGE = process.env.APP_PACKAGE || '…'`) and the literal capability form
+   * (`'appium:appPackage': '…'`). Returns null when wdio.conf.ts is absent or unparseable.
+   */
+  private readWdioAppEntry(): string | null {
+    const wdioPath = path.join(this.cwd, 'wdio.conf.ts');
+    if (!fs.existsSync(wdioPath)) return null;
+    let src: string;
+    try {
+      src = fs.readFileSync(wdioPath, 'utf-8');
+    } catch {
+      return null;
+    }
+    const pick = (re: RegExp): string | undefined => src.match(re)?.[1]?.trim();
+    const pkg =
+      pick(/APP_PACKAGE\s*=\s*process\.env\.APP_PACKAGE\s*\|\|\s*['"]([^'"]+)['"]/) ??
+      pick(/['"]appium:appPackage['"]\s*:\s*['"]([^'"]+)['"]/);
+    if (!pkg) return null;
+    const activity =
+      pick(/APP_ACTIVITY\s*=\s*process\.env\.APP_ACTIVITY\s*\|\|\s*['"]([^'"]+)['"]/) ??
+      pick(/['"]appium:appActivity['"]\s*:\s*['"]([^'"]+)['"]/);
+    return activity ? `${pkg}/${activity}` : pkg;
+  }
+
+  /**
+   * Build the Background block for a mobile screen — the navigation recipe (in-app web-path
+   * analog). Line 1 is the `Given User is on [Home] screen` launcher/landing anchor; each step
+   * from `--reach` (a `>`-separated list) becomes a `When/And User <step>` nav line, taking the
+   * app from launch to THIS screen. capture-mobile replays these to land on the target screen
+   * before scanning. With no recipe, emit a guided stub (anchor + commented placeholder).
+   */
+  private buildMobileBackground(reach?: string): string {
+    // Normalize one nav segment to a bare step body ("tap [My Page] tab"): drop any leading
+    // Gherkin keyword and a leading "User " so we can re-emit "When/And User <body>" cleanly.
+    const normalizeStep = (raw: string): string =>
+      raw
+        .trim()
+        .replace(/^(given|when|and|then|but)\s+/i, '')
+        .replace(/^user\s+/i, '')
+        .trim();
+
+    const steps = (reach || '')
+      .split('>')
+      .map(normalizeStep)
+      .filter(Boolean);
+
+    if (steps.length === 0) {
+      // No recipe → guided stub. Keep the anchor (correct as-is when this IS the launcher
+      // screen); the comments tell create-test / capture-mobile how to fill the nav steps.
+      return [
+        '  Background:',
+        '    # Navigation recipe — how to reach THIS screen from app launch (the in-app',
+        '    # web-path analog). Line 1 is the launcher/landing screen the app opens on;',
+        '    # add a `When/And User tap [...]` per hop to reach this screen. capture-mobile',
+        '    # replays these so Appium lands here (not the launcher) before scanning. Leave',
+        '    # only the anchor if this IS the launcher screen. Prefill with',
+        '    # --reach "tap [Tab] > tap [Row]" at add-screen time.',
+        '    Given User is on [Home] screen',
+        '    # When User tap [<tab or button that leads to this screen>]',
+        '',
+      ].join('\n');
+    }
+
+    const navLines = steps.map(
+      (body, i) => `    ${i === 0 ? 'When' : 'And'} User ${body}`,
+    );
+    return [
+      '  Background:',
+      '    # Navigation recipe — replayed by capture-mobile to land on this screen before scanning.',
+      '    Given User is on [Home] screen',
+      ...navLines,
+      '',
+    ].join('\n');
+  }
 }

package/src/orchestrator/templates/ai-src/README.md

@@ -0,0 +1,58 @@
+# ai-src — the SINGLE SOURCE for sungen's AI assistant assets
+
+**Author skills, commands, and config HERE. Nothing else.** Do NOT create or edit a
+`templates/ai-instructions/` folder — that per-assistant layout is retired. (A CI guardrail
+in `golden-skills.test.ts` fails the build if it reappears.)
+
+## Layout
+```
+ai-src/
+├── skills/<name>/SKILL.md      # one skill (+ optional aux .md fragments, e.g. viewpoint groups)
+├── commands/<name>.md          # one workflow command (structured frontmatter, see below)
+└── config/{claude,copilot,codex}.md   # per-assistant config (CLAUDE.md / copilot-instructions / AGENTS.md)
+```
+
+## How it ships
+`sungen init` / `sungen update` call `ai-skills/build.ts` → `buildOutputs(adapters)`, which
+renders each source file per assistant:
+
+| Assistant | skill output | command output | config output |
+|-----------|--------------|----------------|---------------|
+| claude    | `.claude/skills/<n>/SKILL.md` | `.claude/commands/sungen/<n>.md` | `CLAUDE.md` |
+| copilot   | `.github/skills/<n>/SKILL.md` | `.github/prompts/sungen-<n>.prompt.md` | `.github/copilot-instructions.md` |
+| codex     | `.agents/skills/<n>/SKILL.md` | `.agents/skills/sungen-<n>/SKILL.md` (commands become skills) | `AGENTS.md` |
+
+`--assistant claude|copilot|codex|all` (repeatable, default `claude`) selects targets.
+
+## Per-assistant deltas — cap-fences
+When one assistant needs different wording (e.g. Claude has parallel sub-agents, Copilot is
+sequential), fence the delta. Claude is the **canonical** content; other adapters strip down.
+
+```
+{{#cap parallel-subagents}}
+...kept only for adapters that HAVE the cap (claude)...
+{{/cap}}
+{{^cap parallel-subagents}}
+...kept only for adapters that LACK it (copilot, codex)...
+{{/cap}}
+```
+Valid cap tags live in `ai-skills/cap-stripper.ts` (`VALID_CAPS`). An unknown tag or an
+unclosed fence FAILS the build — never a silent drop.
+
+## Command frontmatter
+```
+---
+name: create-test                 # omit if Claude command had no name line
+description: "<canonical Claude description>"
+argument-hint: [screen-name]      # verbatim Claude form
+order: 20                          # workflow step (advisory; parallel paths may share)
+claude-tools: "Read, Grep, ..."   # Claude allowed-tools (verbatim)
+copilot-tools: "[vscode, ...]"    # Copilot tools array
+codex-trigger: "Run when the user asks to ..."   # explicit Codex trigger (disambiguation)
+---
+<body, may contain cap-fences>
+```
+
+## After editing
+Run `npm test` (or `tsx src/orchestrator/ai-skills/golden-skills.test.ts`). If you
+intentionally changed output, re-freeze fixtures: add `--update`, then review the diff.

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

@@ -1,36 +1,65 @@
 ---
 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'
+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
+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, todo]"
+codex-trigger: "Run when the user asks to add a NEW cross-screen end-to-end flow. Step 1 (flow variant). Do NOT use for a single screen, creating test cases, or running tests."
 ---
+{{^cap parallel-subagents}}
+**Input**: Flow name and optional starting URL (e.g., `/sungen-add-flow award-submission --path /login`).
 
+{{/cap}}
 You are adding a new Sungen flow for E2E cross-screen test generation.
 
 ## Parameters
 
+{{#cap parallel-subagents}}
 Parse from `$ARGUMENTS`:
 - **flow** — flow name (e.g., `award-submission`, `user-onboarding`)
+{{/cap}}
+{{^cap parallel-subagents}}
+- **flow** — ${input:flow:flow name (e.g., award-submission, user-onboarding)}
+{{/cap}}
 - **--path \<url\>** — starting page URL path (default: `/login`)
 - **--description \<text\>** — flow description (optional)
 
+{{#cap parallel-subagents}}
 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`)"
 
+{{/cap}}
 ## Steps
 
 ### 1. Scaffold the flow
 
+{{^cap parallel-subagents}}
+Run with #tool:terminal:
+{{/cap}}
 ```bash
+{{#cap parallel-subagents}}
 sungen add-flow --flow <name> --path <path>
+{{/cap}}
+{{^cap parallel-subagents}}
+sungen add-flow --flow ${input:flow} --path ${input:path}
+{{/cap}}
 ```
 
 This creates:
 ```
+{{#cap parallel-subagents}}
 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
+{{/cap}}
+{{^cap parallel-subagents}}
+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
+{{/cap}}
 └── requirements/
     ├── spec.md                    # Flow specification
     └── ui/                        # Screenshots, mockups
@@ -47,19 +76,39 @@ Record the screen list — you will need it for:
 
 ### 2. Capture visual source
 
+{{#cap parallel-subagents}}
 Use `AskUserQuestion`: *"Pick a visual source for this flow's screens:"*
+{{/cap}}
+{{^cap parallel-subagents}}
+Ask: *"Pick a visual source for this flow's screens:"*
+{{/cap}}
 - **Figma designs** (Recommended for pre-launch) — invoke `sungen-capture` skill (mode figma-mcp) for each screen
 - **Live page scan** (dev/staging is up) — invoke `sungen-capture` skill (mode live) for each screen URL
 - **Local images** — invoke `sungen-capture` skill (mode local) to load from `requirements/ui/`
 - **Skip** — user will drop images manually into `requirements/ui/` later
 
+{{#cap parallel-subagents}}
 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`.
+{{/cap}}
+{{^cap parallel-subagents}}
+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.
+{{/cap}}
 
 ### 3. Fill spec.md
 
+{{#cap parallel-subagents}}
 Use `AskUserQuestion`: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+{{/cap}}
+{{^cap parallel-subagents}}
+Ask: *"Fill `spec.md` now? (You can reference the captured visuals)"* — offer **Yes, fill now (Recommended)** / **Skip, fill later**.
+{{/cap}}
 
+{{#cap parallel-subagents}}
 If yes → open `qa/flows/<name>/requirements/spec.md` and help the user fill:
+{{/cap}}
+{{^cap parallel-subagents}}
+If yes → open `qa/flows/${input:flow}/requirements/spec.md` and help the user fill:
+{{/cap}}
 - **Screens list** — ordered list of screens with URL paths
 - **Flow steps** — what the user does at each screen
 - **Transitions** — what triggers navigation between screens
@@ -70,13 +119,25 @@ Reference the captured visuals from Step 2 to suggest field names, form elements
 
 ### 4. Next steps
 
+{{#cap parallel-subagents}}
 Tell the user what was created, then use `AskUserQuestion` to offer next steps:
+{{/cap}}
+{{^cap parallel-subagents}}
+Tell the user what was created and offer next steps:
+{{/cap}}
 
+{{#cap parallel-subagents}}
 - **`/sungen:create-test <name>`** — Create test scenarios for the flow (Recommended)
+{{/cap}}
+{{^cap parallel-subagents}}
+- **`/sungen-create-test ${input:flow}`** — Generate test scenarios for the flow (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}}
 ## Key Rules
 
 - Flows are **independent** from screens — own selectors, own test-data