@sun-asterisk/sungen 2.7.0-beta.1 → 3.0.0-beta.71

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

@@ -1,142 +0,0 @@
----
-name: sungen-capture-figma
-description: 'Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP. Auto-loaded by create-test when user picks Figma as the visual source.'
-user-invocable: false
----
-
-## Purpose
-
-Pull **structured design data** (layout, typography, colors, component tree, design tokens) and a **PNG screenshot** from a Figma frame URL, so `sungen-tc-generation` can author Gherkin + test-data before a live domain exists.
-
-Use this when the project is pre-launch, or when Figma is the source of truth and the live build lags the design.
-
----
-
-## Prerequisites
-
-- **Figma MCP server** (`https://mcp.figma.com/mcp`, HTTP transport) connected in the user's `.mcp.json` — `sungen init` scaffolds this automatically. On first use, Claude Code opens a browser for Figma OAuth. Official tools: `get_design_context`, `get_variable_defs`, `get_screenshot`.
-- Figma account signed in with access to the file. **Dev/Full seats** get per-minute rate limits; **Starter/View seats** get monthly tool-call limits.
-- A Figma URL with both **fileKey** and **nodeId** in it.
-
-If the MCP is not connected, **do not fail silently** — tell the user:
-> "Figma MCP not detected. Run `sungen init` to scaffold the config, or manually add `figma` with `url: https://mcp.figma.com/mcp` to `.mcp.json`. Then sign in when Claude Code prompts."
-
-Then stop.
-
----
-
-## Steps
-
-### 1. Resolve Figma URL
-
-Prefer in this order:
-
-1. `Figma URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
-2. If empty or missing → `AskUserQuestion`: *"Paste the Figma frame URL"* (free text)
-
-Accept any of these URL shapes:
-
-```
-https://www.figma.com/file/<fileKey>/<title>?node-id=<nodeId>
-https://www.figma.com/design/<fileKey>/<title>?node-id=<nodeId>
-https://www.figma.com/proto/<fileKey>/<title>?node-id=<nodeId>
-```
-
-Parse:
-- `fileKey` = the segment after `/file/`, `/design/`, or `/proto/`
-- `nodeId` = the `node-id` query param (may use `-` or `:` — pass through as-is; MCP accepts both)
-
-If `node-id` is missing, ask the user to select a frame in Figma and copy the **frame URL** specifically (not the file root URL).
-
-### 2. Fetch design context
-
-Call **both** in parallel:
-
-```
-get_design_context({ fileKey, nodeId })
-get_variable_defs({ fileKey, nodeId })
-```
-
-`get_design_context` returns layout, typography, color values, component structure, spacing.
-`get_variable_defs` returns named design tokens (color/spacing/typography variables).
-
-### 3. Fetch screenshot
-
-```
-get_screenshot({ fileKey, nodeId })
-```
-
-Save the returned PNG to:
-
-```
-qa/screens/<screen>/requirements/ui/figma-<sanitized-nodeId>.png
-```
-
-Sanitize `nodeId` for filesystem: replace `:` and `-` with `_`. Example: `42-15` → `figma-42_15.png`.
-
-### 4. Write metadata dump
-
-Combine the design context + variables into a Markdown summary at:
-
-```
-qa/screens/<screen>/requirements/ui/figma-meta.md
-```
-
-Format:
-
-```markdown
-# Figma Capture — <nodeId>
-
-**Source:** <full Figma URL>
-**Captured:** <ISO date>
-
-## Components
-<hierarchical list of component names + variants from get_design_context>
-
-## Typography
-<font families, sizes, weights, line heights>
-
-## Colors
-<color tokens + raw hex values>
-
-## Spacing & Layout
-<spacing tokens, auto-layout specs>
-
-## Text Content
-<visible text strings from the frame — used by tc-generation to populate test-data>
-```
-
-This file is consumed by `sungen-tc-generation` as a secondary source alongside `spec.md`.
-
-### 5. Report back
-
-Output a short summary to the user:
-
-> Captured Figma frame `<nodeId>`:
-> - Components: N
-> - Text strings: M
-> - Design tokens: K
-> - Screenshot: `qa/screens/<screen>/requirements/ui/figma-<nodeId>.png`
-> - Metadata: `requirements/ui/figma-meta.md`
-
-Then hand back to the calling command.
-
----
-
-## Error handling
-
-| Error | Action |
-|---|---|
-| MCP tool not available | Print setup instructions, stop, do not fall back silently |
-| `fileKey` missing from URL | Ask user to paste a valid frame URL |
-| `nodeId` missing from URL | Ask user to right-click a frame in Figma → *Copy link to selection* |
-| `get_design_context` 403 | Ask user to check Dev Mode seat on that file |
-| `get_screenshot` returns no image | Continue with metadata only; warn user no PNG was captured |
-
----
-
-## What this skill does NOT do
-
-- Does not generate Gherkin (that's `sungen-tc-generation`)
-- Does not write `selectors.yaml` (that's `/sungen:run-test`)
-- Does not validate the design against live UI (future skill: `sungen-capture-live` can be run afterwards for cross-check)

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

@@ -1,112 +0,0 @@
----
-name: sungen-capture-live
-description: 'Capture a live running page via Playwright MCP — snapshot + screenshot for visual context. Auto-loaded by create-test when user picks Live page scan.'
-user-invocable: false
----
-
-## Purpose
-
-Navigate a running application, take **one accessibility snapshot** and **one screenshot**, and save them as visual context for test generation. Use when the app is live (dev, staging, or production with read-only access) and you want the tests grounded in the actual rendered UI.
-
-This skill handles auth gracefully: if the page redirects to login, it asks the user to sign in manually rather than injecting cookies.
-
----
-
-## Prerequisites
-
-- Playwright MCP connected.
-- Dev/staging server reachable (or a public URL).
-- `playwright.config.ts` exists at the project root (for `baseURL` fallback).
-
----
-
-## Steps
-
-### 1. Resolve target URL
-
-Resolve in this order:
-
-1. `Live URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
-2. `baseURL` from `playwright.config.ts` + `URL Path` from `spec.md`
-3. If neither works → `AskUserQuestion`: *"Paste the full URL for the page to scan"*
-
-### 2. Navigate
-
-`browser_navigate` to the resolved URL.
-
-### 3. Handle auth redirect
-
-If the page redirects to a login route (URL contains `/login`, `/signin`, `/auth`, or the page title/content indicates a login screen):
-
-1. Tell the user which login URL they landed on.
-2. `AskUserQuestion`:
-   - **I'll log in manually** — wait for user confirmation, then re-navigate to the target URL
-   - **Skip live scan** — tell caller to invoke `sungen-capture-local` instead
-   - **Cancel**
-3. **Never** inject cookies or localStorage via `browser_evaluate` or `browser_run_code`. Auth belongs to the user.
-
-### 4. Snapshot
-
-Take **ONE** `browser_snapshot`. This accessibility tree is the primary AI context — it contains roles, names, text, and structure that the tc-generation skill uses to identify sections and fields.
-
-### 5. Screenshot (optional but recommended)
-
-Take **ONE** `browser_take_screenshot` with `fullPage: true`. Save to:
-
-```
-qa/screens/<screen>/requirements/ui/live-<timestamp>.png
-```
-
-Where `<timestamp>` is `YYYYMMDD-HHMM` in local time (e.g. `live-20260421-1430.png`).
-
-This gives users a visual record they can reference later without re-scanning.
-
-### 6a. Verify unauthenticated redirect target (flow capture only)
-
-When capturing for a **flow** that includes security scenarios (e.g., "unauthenticated user cannot access X"):
-
-1. Open a **fresh incognito/unauthenticated** browser context (no storage state).
-2. `browser_navigate` to the protected route (e.g., `/dashboard`).
-3. Record the **actual redirect URL** — do NOT assume it goes to `/login`. The app may redirect to `/register`, `/`, or any other route.
-4. Report the redirect target to the caller: *"Unauthenticated access to `/dashboard` redirects to `/register`"*.
-5. The caller must use the **actual redirect URL** in Gherkin assertions (e.g., `Then User is on [Register] page`), never an assumed one.
-
-Skip this step if the flow has no security scenarios or the user explicitly says to skip.
-
-### 6. Detect discrepancies vs spec
-
-If `spec.md` exists, briefly cross-check the snapshot against spec sections:
-
-- Fields listed in spec but not in snapshot → flag as *missing in UI*
-- Elements visible in snapshot but not in spec → flag as *missing in spec*
-
-Report findings but **do not** auto-edit `spec.md` — let the user decide.
-
-### 7. Report back
-
-> Captured live page `<URL>`:
-> - Snapshot: <N> interactive elements detected
-> - Screenshot: `requirements/ui/live-<timestamp>.png`
-> - Discrepancies vs spec: <count, or "none">
-
-Hand back to the calling command.
-
----
-
-## What this skill does NOT do
-
-- Does not run tests
-- Does not generate `selectors.yaml` (that's `/sungen:run-test`)
-- Does not inject auth state (user logs in manually)
-- Does not crawl — scans **exactly one** page per invocation
-- Does not generate Gherkin — that's `sungen-tc-generation`
-
----
-
-## Relationship to other capture skills
-
-- `sungen-capture-figma` — design source of truth (pre-launch)
-- `sungen-capture-local` — any image the user dropped in `requirements/ui/`
-- `sungen-capture-live` — this skill, verifies/supplements against the running app
-
-All three write to `requirements/ui/` and report back to the caller. They are mutually exclusive per create-test run, but a user can run create-test multiple times with different sources to layer context.

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

@@ -1,73 +0,0 @@
----
-name: sungen-capture-local
-description: 'Load existing UI assets (screenshots, Figma exports, hand-drawn mockups) from requirements/ui/. Auto-loaded by create-test when user picks UI images as the visual source.'
-user-invocable: false
----
-
-## Purpose
-
-Use **pre-existing images** in `qa/screens/<screen>/requirements/ui/` as visual context for test generation. No network, no MCP, no live site required — works for any design tool (Figma export, Sketch, Penpot, Zeplin, hand-drawn, screenshots of a staging env).
-
-This is the **baseline fallback**: if live domain is down and Figma MCP isn't configured, this always works as long as the user drops images in the folder.
-
----
-
-## Steps
-
-### 1. List available images
-
-Glob `qa/screens/<screen>/requirements/ui/*.{png,jpg,jpeg,webp,gif}` and report count + filenames.
-
-Filter out metadata files (e.g. `figma-meta.md` written by `sungen-capture-figma`) — those are read by `tc-generation` separately, not treated as images here.
-
-### 2. Handle empty folder
-
-If no images found:
-
-1. Tell the user the folder is empty, with the full path so they can navigate there in Finder.
-2. `AskUserQuestion`:
-   - **I'll drop images now** — wait for user to confirm, then re-glob
-   - **Switch to Figma URL** — tell caller to invoke `sungen-capture-figma` instead
-   - **Switch to live page scan** — tell caller to invoke `sungen-capture-live` instead
-   - **Cancel** — abort create-test
-3. If user picks "drop images now", wait for their confirmation message (e.g. "done") then re-run step 1.
-
-### 3. Read images for context
-
-Use the `Read` tool on each image file — Claude Code can read PNG/JPG/WebP directly as visual context.
-
-For large sets (>10 images), ask the user which are primary and which are states/variants, to avoid loading too much visual context at once.
-
-### 4. Summarize
-
-Output a short summary:
-
-> Loaded N image(s) from `qa/screens/<screen>/requirements/ui/`:
-> - `<filename-1>` — <one-line description of what's visible>
-> - `<filename-2>` — <one-line description>
-> ...
-
-Hand back to the calling command.
-
----
-
-## File naming hints for users
-
-When this skill reports back, nudge users toward consistent filenames so future runs are self-documenting:
-
-- `<section>-default.png` — baseline state of a section
-- `<section>-error.png` — error state
-- `<section>-loading.png` — loading state
-- `<section>-empty.png` — empty state
-- `full-page.png` / `viewport.png` — whole screen (auto-generated by `sungen add --capture`)
-
-Don't enforce — just suggest if filenames are ambiguous.
-
----
-
-## What this skill does NOT do
-
-- Does not download images from external URLs
-- Does not generate images (no AI image generation)
-- Does not modify existing images (no crop/resize)
-- Does not generate Gherkin — that's `sungen-tc-generation`

package/src/orchestrator/templates/ai-instructions/copilot-skill-figma-source.md

@@ -1,151 +0,0 @@
----
-name: sungen-figma-source
-description: 'Figma URL → spec_figma.md envelope + LLM-synthesized narrative from cached raw node JSON. Auto-loaded when --figma flag present or spec_figma.md exists.'
-user-invocable: false
----
-
-## When This Skill Loads
-
-Auto-load triggers (any one is sufficient):
-
-- Any sungen AI command invoked with `--figma` flag
-- `requirements/spec_figma.md` exists in the screen directory
-- User mentions a Figma URL or says "generate from Figma"
-
----
-
-## Prerequisites
-
-- [ ] `sungen figma auth check` succeeds — PAT is stored and valid
-- [ ] Figma file URL is available (shared file or frame link)
-- [ ] If auth missing → run `sungen figma auth set` and follow the walkthrough
-
-**Never paste the PAT into any transcript, spec file, or commit.**
-
----
-
-## Two-Layer Architecture
-
-`spec_figma.md` has two layers separated by the `<!-- SYNTHESIS-BELOW -->` marker:
-
-| Layer | Producer | Overwrite Rule |
-|---|---|---|
-| **Envelope** (above marker) | sungen CLI | Regenerated each `sungen figma` run — deterministic |
-| **Narrative** (below marker) | This skill (LLM) | Replaced on re-synthesis — everything from marker to EOF |
-
-The envelope contains: YAML frontmatter, Frame metadata, Screenshots. The narrative is synthesized by YOU from the cached raw Figma node JSON.
-
----
-
-## Inputs You Read
-
-The scaffolder persists a raw (unfiltered) Figma node tree to:
-
-```
-.sungen/figma-cache/<fileKey>/<versionId>/<nodeId>-raw.json
-```
-
-Read this file + the envelope frontmatter of `requirements/spec_figma.md` + any PNGs under `requirements/ui/`. You MUST NOT call the Figma REST API directly — the PAT is not available to you.
-
----
-
-## Synthesis Task
-
-Append 7 narrative sections below `<!-- SYNTHESIS-BELOW -->`. Each section is inferred from the raw node tree (names, types, `characters`, layout bounds, auto-layout direction, componentProperties):
-
-### 1. Purpose
-One paragraph. What screen is this? Primary user goal? Infer from frame name + top-level text + dominant CTA.
-
-### 2. ASCII Layout
-Rough spatial sketch using box characters. Reflect top-bottom / left-right ordering from absoluteBoundingBox. Keep under ~20 lines. Example:
-
-```
-┌──────────────────────────────────────┐
-│ [Logo]                     [Sign In] │
-├──────────────────────────────────────┤
-│  Welcome back                        │
-│  ┌────────────────────────────────┐  │
-│  │ email@example.com              │  │
-│  └────────────────────────────────┘  │
-│  [ Continue ]                        │
-└──────────────────────────────────────┘
-```
-
-### 3. Regions
-Bulleted list of the major layout regions (header, sidebar, main, footer, modal, etc.) with a one-line purpose each. Use auto-layout frames as region hints.
-
-### 4. Actions
-Every interactive element the user can trigger. Derive from nodes whose name/type suggests a button, link, icon-button, menu-item, toggle, etc. Format:
-
-```
-- **<Action name>** — <what it does> (source: <node name>)
-```
-
-### 5. Form Fields
-Every input the user can fill. Include label, type (text/email/password/select/checkbox/radio/textarea/date), required hint if inferable, and placeholder.
-
-```
-| Label | Type | Required | Placeholder |
-|---|---|---|---|
-```
-
-Omit entirely (write `_none_`) if no inputs exist.
-
-### 6. Data Columns
-If the screen shows a table, list, or card grid — enumerate the columns/fields displayed per row. Otherwise write `_none_`.
-
-### 7. Navigation
-Outgoing links, tab bars, breadcrumbs, back buttons — anything that moves the user to another screen. Include both explicit navigation components and implicit CTAs that navigate.
-
----
-
-## Synthesis Workflow
-
-1. Read `requirements/spec_figma.md` — note `file_key`, `node_id`, `figma_version_id` from frontmatter
-2. Read `.sungen/figma-cache/<file_key>/<figma_version_id>/<safe_node_id>-raw.json` (colons in node_id become underscores)
-3. Traverse the tree. Collect: names, types, `characters`, `componentProperties`, `absoluteBoundingBox`
-4. Produce the 7 sections above
-5. **Locate the insertion point** in `spec_figma.md`:
-   - **If `<!-- SYNTHESIS-BELOW -->` is present** → replace everything from the marker (inclusive) to EOF with: the marker line, a blank line, then the 7 sections.
-   - **If the marker is NOT present** (older `spec_figma.md` pre-envelope-refactor, or hand-edited file) → locate the last non-empty line of the envelope (usually the end of `## Screenshots`), append a blank line, then write the marker, another blank line, then the 7 sections. Do NOT delete any existing envelope content.
-   - **If the file is missing entirely** → advise the user to re-run `sungen add --screen <screen> --figma <url> --refresh` to regenerate the envelope first. Do not fabricate one.
-6. Preserve the envelope (frontmatter + Frame + Screenshots) byte-for-byte. Never touch content above the marker.
-
----
-
-## Re-synthesis
-
-- If the envelope's `figma_version_id` changed → envelope is fresh; re-run synthesis
-- If only the narrative is stale (user wants a rewrite) → truncate from marker to EOF and regenerate
-- Never edit content ABOVE the marker — that is the scaffolder's territory
-
----
-
-## Selector Heuristics (for downstream `run-test`)
-
-During `run-test` Phase 0, provisional selectors can be seeded from the raw JSON:
-
-| Figma Signal | Provisional YAML Entry |
-|---|---|
-| Node name ends `Button`, has text | `role: button` + `name: "<text>"` |
-| Node name ends `Input`/`Field` | `placeholder: "<placeholder text>"` |
-| Node name ends `Link`, has text | `role: link` + `name: "<text>"` |
-| componentProperties has `data-testid` | `testid: <value>` |
-| Plain text leaf (outside interactive) | `text: "<content>"` |
-| Node name ends `Icon` | `role: img` + `name: "<accessible name>"` |
-
-Every provisional entry MUST carry:
-
-```
-# @needs-live-verify source=figma node_id=<id>
-```
-
-Provisional selectors feed `selectors.yaml` as candidates. `run-test` Phase 0 verifies them against the live page and overwrites incorrect entries.
-
----
-
-## Security
-
-- Never include the PAT in `spec_figma.md`, selectors, test data, or any committed file
-- Never log or echo the PAT in terminal output
-- Read only from `.sungen/figma-cache/` and screen directories — never from `.env`

package/src/orchestrator/templates/ai-instructions/github-skill-sungen-capture-figma.md

@@ -1,142 +0,0 @@
----
-name: sungen-capture-figma
-description: 'Fetch design context + PNG from a Figma frame URL via Figma Dev Mode MCP. Auto-loaded by create-test when user picks Figma as the visual source.'
-user-invocable: false
----
-
-## Purpose
-
-Pull **structured design data** (layout, typography, colors, component tree, design tokens) and a **PNG screenshot** from a Figma frame URL, so `sungen-tc-generation` can author Gherkin + test-data before a live domain exists.
-
-Use this when the project is pre-launch, or when Figma is the source of truth and the live build lags the design.
-
----
-
-## Prerequisites
-
-- **Figma MCP server** (`https://mcp.figma.com/mcp`, HTTP transport) connected in `.vscode/mcp.json` — `sungen init` scaffolds this automatically. On first use, VS Code / Copilot opens a browser for Figma OAuth. Official tools: `get_design_context`, `get_variable_defs`, `get_screenshot`.
-- Figma account signed in with access to the file. **Dev/Full seats** get per-minute rate limits; **Starter/View seats** get monthly tool-call limits.
-- A Figma URL with both **fileKey** and **nodeId** in it.
-
-If the MCP is not connected, **do not fail silently** — tell the user:
-> "Figma MCP not detected. Run `sungen init` to scaffold the config, or manually add `figma` with `url: https://mcp.figma.com/mcp` to `.vscode/mcp.json`. Then sign in when VS Code prompts."
-
-Then stop.
-
----
-
-## Steps
-
-### 1. Resolve Figma URL
-
-Prefer in this order:
-
-1. `Figma URL` field in `qa/screens/<screen>/requirements/spec.md` (Overview section)
-2. If empty or missing → ask the user: *"Paste the Figma frame URL"*
-
-Accept any of these URL shapes:
-
-```
-https://www.figma.com/file/<fileKey>/<title>?node-id=<nodeId>
-https://www.figma.com/design/<fileKey>/<title>?node-id=<nodeId>
-https://www.figma.com/proto/<fileKey>/<title>?node-id=<nodeId>
-```
-
-Parse:
-- `fileKey` = the segment after `/file/`, `/design/`, or `/proto/`
-- `nodeId` = the `node-id` query param (may use `-` or `:` — pass through as-is; MCP accepts both)
-
-If `node-id` is missing, ask the user to select a frame in Figma and copy the **frame URL** specifically (not the file root URL).
-
-### 2. Fetch design context
-
-Call **both** in parallel:
-
-```
-get_design_context({ fileKey, nodeId })
-get_variable_defs({ fileKey, nodeId })
-```
-
-`get_design_context` returns layout, typography, color values, component structure, spacing.
-`get_variable_defs` returns named design tokens (color/spacing/typography variables).
-
-### 3. Fetch screenshot
-
-```
-get_screenshot({ fileKey, nodeId })
-```
-
-Save the returned PNG to:
-
-```
-qa/screens/<screen>/requirements/ui/figma-<sanitized-nodeId>.png
-```
-
-Sanitize `nodeId` for filesystem: replace `:` and `-` with `_`. Example: `42-15` → `figma-42_15.png`.
-
-### 4. Write metadata dump
-
-Combine the design context + variables into a Markdown summary at:
-
-```
-qa/screens/<screen>/requirements/ui/figma-meta.md
-```
-
-Format:
-
-```markdown
-# Figma Capture — <nodeId>
-
-**Source:** <full Figma URL>
-**Captured:** <ISO date>
-
-## Components
-<hierarchical list of component names + variants from get_design_context>
-
-## Typography
-<font families, sizes, weights, line heights>
-
-## Colors
-<color tokens + raw hex values>
-
-## Spacing & Layout
-<spacing tokens, auto-layout specs>
-
-## Text Content
-<visible text strings from the frame — used by tc-generation to populate test-data>
-```
-
-This file is consumed by `sungen-tc-generation` as a secondary source alongside `spec.md`.
-
-### 5. Report back
-
-Output a short summary to the user:
-
-> Captured Figma frame `<nodeId>`:
-> - Components: N
-> - Text strings: M
-> - Design tokens: K
-> - Screenshot: `qa/screens/<screen>/requirements/ui/figma-<nodeId>.png`
-> - Metadata: `requirements/ui/figma-meta.md`
-
-Then hand back to the calling command.
-
----
-
-## Error handling
-
-| Error | Action |
-|---|---|
-| MCP tool not available | Print setup instructions, stop, do not fall back silently |
-| `fileKey` missing from URL | Ask user to paste a valid frame URL |
-| `nodeId` missing from URL | Ask user to right-click a frame in Figma → *Copy link to selection* |
-| `get_design_context` 403 | Ask user to check Dev Mode seat on that file |
-| `get_screenshot` returns no image | Continue with metadata only; warn user no PNG was captured |
-
----
-
-## What this skill does NOT do
-
-- Does not generate Gherkin (that's `sungen-tc-generation`)
-- Does not write `selectors.yaml` (that's `/sungen-run-test`)
-- Does not validate the design against live UI (future skill: `sungen-capture-live` can be run afterwards for cross-check)