@polymorphism-tech/morph-spec 4.21.0 → 4.22.0

package/framework/skills/level-1-workflows/morph-phase-implement/SKILL.md

@@ -5,7 +5,7 @@ argument-hint: "[feature-name]"
 context: fork
 agent: general-purpose
 user-invocable: false
-cliVersion: "4.21.0"
+cliVersion: "4.22.0"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion, Agent
 ---
 
@@ -204,6 +204,7 @@ Read: .morph/features/{feature}/4-tasks/tasks.md
     + Read: .morph/features/{feature}/2-design/contracts.cs  (or contracts.ts for TypeScript projects)
     + Read: .morph/config/config.json                       (→ architecture.style)
     + Read: .morph/features/{feature}/3-plan/plan.md
+    + Read: .morph/features/{feature}/1-ui/assets.md              (if exists — image asset specs)
 ```
 
 ### 2. Detect architecture style
@@ -221,6 +222,80 @@ Otherwise → go directly to the task loop.
 
 Structure: `Features/{Entity}Feature/{Op}/` with Handler (+ Request/Response records) + Validator + Endpoint per slice. Everything `sealed`. `Guid.CreateVersion7()`. `result.Match()` in endpoints. No Application Service layer — handler accesses IRepository directly. Auto-discovery via reflection: do not manually register in Program.cs.
 
+### 3. UI Reference Loading (Stitch HTML)
+
+> **Skip if:** `.morph/features/{feature}/1-ui/stitch-screen-map.json` does not exist.
+> This section is OPTIONAL — only applies when the UI/UX phase used Stitch MCP.
+
+If `stitch-screen-map.json` exists, this feature has Stitch HTML exports for visual fidelity:
+
+1. **Read the screen map and CSS mapping in parallel:**
+   ```
+   Read: .morph/features/{feature}/1-ui/stitch-screen-map.json
+   Read: .morph/features/{feature}/1-ui/stitch-html/stitch-css-map.json
+   ```
+
+2. **For each task that modifies a page/route:**
+   - Parse the task description for route references (e.g., `/dashboard`, `/settings`)
+   - Find the matching screen in `stitch-screen-map.json` by route
+   - Read the corresponding HTML file:
+     ```
+     Read: .morph/features/{feature}/1-ui/stitch-html/{screenId}.html
+     ```
+   - Include the HTML in the agent's context along with the CSS mapping
+
+3. **Translation rules for agents:**
+   When implementing from Stitch HTML, agents MUST:
+   - Replace Stitch inline color values with project CSS custom properties using `stitch-css-map.json`
+   - Preserve the **layout structure** (flex/grid hierarchy, element nesting) from Stitch HTML
+   - Preserve **typography hierarchy** (heading levels, font sizes, weights)
+   - Map Stitch HTML elements to the chosen UI library components (e.g., `<div class="card">` → shadcn `<Card>`)
+   - Respect the Stitch spacing proportions, mapping to project spacing tokens
+   - For unmapped values in `stitch-css-map.json`, add them as new tokens to `design-system.md`
+
+> **Source of truth hierarchy:** The Stitch HTML is the visual source of truth. `mockups.md` describes
+> behavior and states; the HTML describes exact visual structure. When they conflict, the HTML wins for
+> layout/visual, mockups.md wins for behavior/states.
+
+### 4. Image Asset Generation (Gemini Image MCP)
+
+> **Skip if:** `.morph/features/{feature}/1-ui/assets.md` does not exist.
+> **Skip if:** Gemini Image MCP is not available.
+> This section is OPTIONAL — only applies when the UI/UX phase created an assets.md spec.
+
+If `assets.md` exists, this feature has image assets to generate during implementation:
+
+1. **Read the assets spec:**
+   ```
+   Read: .morph/features/{feature}/1-ui/assets.md
+   ```
+
+2. **When a task involves a component listed in assets.md:**
+   - Find the matching IMG-NNN entry by component name or route
+   - Invoke `/morph-gemini-image` with the asset spec:
+     - Pass the `Prompt` field as the generation prompt
+     - Pass the `Aspect Ratio` field
+     - Pass the `Output Path` field
+   - If the image needs refinement, use `edit_image` or `continue_editing`
+
+3. **Integrate the generated image into the component:**
+   ```tsx
+   import Image from 'next/image';
+
+   <Image
+     src="/images/{feature}/{name}.png"
+     alt="{descriptive alt text}"
+     width={width}
+     height={height}
+     priority  // if above-the-fold
+   />
+   ```
+
+4. **Verify build compiles** after adding the image reference.
+
+> **Important:** Generate images DURING the task that builds the component, not as a separate step.
+> This keeps the image contextually linked to the component code.
+
 ---
 
 ## Workflow
@@ -252,6 +327,14 @@ Agent(subagent_type="morph-dotnet-senior", prompt="Implement tasks T001, T002 fo
 > **MANDATORY:** Use the exact `subagentType` value from `recommended`. Do NOT use `general-purpose` agents when a `subagentType` is available.
 >
 > The agent `.md` file contains the full expertise prompt, task routing, and key standards. No additional prompt injection needed — just provide the task assignment.
+>
+> **If Stitch HTML exists:** When dispatching frontend agents, read `stitch-screen-map.json` and include
+> the relevant screen HTML for each agent's assigned tasks. Populate the `{{STITCH_CONTEXT}}` placeholder
+> in `implementer-prompt.md` with the screen HTML and CSS mapping for the routes that agent is implementing.
+>
+> **If assets.md exists:** When dispatching frontend agents, read `assets.md` and include
+> the relevant IMG-NNN entries for each agent's assigned routes. Populate the `{{ASSETS_CONTEXT}}`
+> placeholder in `implementer-prompt.md` with the image specs for the routes that agent is implementing.
 
 5. After all subagents complete, validate integration: `morph-spec validate-feature $ARGUMENTS --phase implement`
 
@@ -361,6 +444,64 @@ await mcp__playwright__browser_console_messages({ level: 'error' });
 await mcp__playwright__browser_take_screenshot({ type: 'png' });
 ```
 
+### Step 5.5: Visual Verification against Stitch (Optional)
+
+> **Skip if:** `.morph/features/$ARGUMENTS/1-ui/stitch-screen-map.json` does not exist.
+> **Skip if:** Playwright MCP is not available.
+> **Skip if:** Dev server is not running.
+> This step is strongly recommended but not blocking — consistent with fail-open philosophy.
+
+After implementing visual components, compare against the Stitch reference:
+
+1. **Load screen map:**
+   ```
+   Read: .morph/features/$ARGUMENTS/1-ui/stitch-screen-map.json
+   ```
+
+2. **For each screen that was implemented in the current task batch:**
+
+   a. **Screenshot the implemented page:**
+      ```
+      mcp__plugin_playwright_playwright__browser_navigate({ url: '{devServerUrl}{route}' })
+      mcp__plugin_playwright_playwright__browser_resize({ width: 1440, height: 900 })
+      mcp__plugin_playwright_playwright__browser_take_screenshot({})
+      ```
+
+   b. **Read the original Stitch screenshot:**
+      ```
+      Read: .morph/features/$ARGUMENTS/1-ui/stitch-screen-{index}.png
+      ```
+
+   c. **Compare visually** (multimodal comparison of both images):
+      - **Layout:** Grid/flex structure matching? Sections in correct positions?
+      - **Typography:** Heading sizes, weights, font families consistent?
+      - **Colors:** Mapped CSS tokens producing visually similar colors?
+      - **Spacing:** Margins and paddings proportionally similar?
+      - **Interactive elements:** Buttons, inputs, cards styled similarly?
+
+   d. **Document results** in `.morph/features/$ARGUMENTS/5-implement/visual-verification.md`:
+      ```markdown
+      # Visual Verification — {feature}
+
+      ## Screen: {title} ({route})
+
+      | Aspect | Match | Notes |
+      |--------|-------|-------|
+      | Layout | ✓/✗ | {notes} |
+      | Typography | ✓/✗ | {notes} |
+      | Colors | ✓/✗ | {notes} |
+      | Spacing | ✓/✗ | {notes} |
+      | Interactive | ✓/✗ | {notes} |
+
+      **Overall:** {PASS/NEEDS_WORK}
+      ```
+
+   e. **If NEEDS_WORK:** Fix the most impactful discrepancies (layout first, then colors,
+      then typography). Re-screenshot and re-compare. Maximum 2 iteration rounds to avoid
+      infinite loops.
+
+3. **Skip gracefully** if any prerequisite is missing (log warning, continue to Step 6).
+
 ### Step 6: Generate `recap.md`
 
 After ALL tasks completed:
@@ -471,10 +612,10 @@ Agent(subagent_type=morph-standards-architect, prompt=<filled prompts/code-quali
 
 ## Phase Outputs
 
-<!-- morph-outputs:implement -->
-| Output | Caminho |
-|--------|---------|
-| `recap` | `.morph/features/{feature}/5-implement/recap.md` |
+<!-- morph-outputs:implement -->
+| Output | Caminho |
+|--------|---------|
+| `recap` | `.morph/features/{feature}/5-implement/recap.md` |
 <!-- /morph-outputs -->
 
 ---

package/framework/skills/level-1-workflows/morph-phase-implement/prompts/implementer-prompt.md

@@ -10,6 +10,14 @@ You are implementing tasks for the feature '{{FEATURE_NAME}}' as agent '{{AGENT_
 **Standards:** Read relevant files in `.morph/framework/standards/`
 **Code Templates:** Read `.morph/framework/templates/code/dotnet/feature/` (endpoint, handler, validator) — follow these patterns exactly
 
+## UI Reference (Stitch HTML)
+
+{{STITCH_CONTEXT}}
+
+## Image Assets
+
+{{ASSETS_CONTEXT}}
+
 ## Agent Briefing
 
 {{AGENT_BRIEFING}}

package/framework/skills/level-1-workflows/morph-phase-plan/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 3 (Plan). Generates a detailed implementation plan
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
+cliVersion: "4.22.0"
 ---
 
 # MORPH Plan — Phase 3

package/framework/skills/level-1-workflows/morph-phase-tasks/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 4 (Tasks). Breaks approved spec into bottom-up ord
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
+cliVersion: "4.22.0"
 ---
 
 # MORPH Tasks — Phase 4

package/framework/skills/level-1-workflows/morph-phase-uiux/SKILL.md

@@ -4,7 +4,7 @@ description: MORPH-SPEC Phase 2 (UI/UX). Creates design-system.md, mockups.md, c
 argument-hint: "[feature-name]"
 user-invocable: false
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
+cliVersion: "4.22.0"
 ---
 
 # MORPH UI/UX Design - Phase 2
@@ -45,6 +45,7 @@ Conditional phase for features with front-end. Collects UI/UX requirements, gene
 | Trend research | **Context7 MCP** / **WebSearch** | — |
 | Generate AI screen designs | **Stitch MCP** `generate_screen_from_text()` + `fetch_screen_image()` | HTML mockup + Playwright (Step 3.5) |
 | Export design tokens from Stitch | **Stitch MCP** `fetch_screen_code()` | Manual design-system.md creation |
+| Download Stitch HTML exports | **Stitch MCP** `fetch_screen_code()` → save to `stitch-html/` | Step 3.5.0.5 |
 
 **MCPs for this phase:** Playwright (preview, inspection, responsiveness), Context7 (component docs), Stitch (optional: AI screen generation, design.md export).
 
@@ -517,6 +518,109 @@ If Stitch MCP is available, present the user with a choice:
 > receives the actual component structure, CSS properties, and design tokens — not pixel approximations.
 > Use `react-components` or `shadcn-ui` companion skills to convert Stitch HTML into production React components.
 
+#### 3.5.0.5 — Download Stitch HTML Exports (after screen approval)
+
+> **Purpose:** Save the actual HTML/CSS from each Stitch screen so implementation agents can reference
+> real structure and styles instead of relying solely on text descriptions in mockups.md.
+> **Skip if:** Stitch path was not chosen, or no screens were approved.
+
+1. **Create stitch-html directory:**
+   ```bash
+   mkdir -p .morph/features/$ARGUMENTS/1-ui/stitch-html/
+   ```
+
+2. **For each approved screen**, fetch the full HTML:
+   ```
+   stitch__fetch_screen_code({ screenId: approvedScreenId })
+   ```
+   Save the returned HTML content to:
+   `.morph/features/$ARGUMENTS/1-ui/stitch-html/{screenId}.html`
+
+   > If `fetch_screen_code()` returns a structured object, extract the `.html` or `.code` field.
+
+3. **Auto-generate CSS mapping from design-system.md:**
+   Read `.morph/context/design-system.md` and extract all CSS custom properties (`--color-*`, `--font-*`, `--space-*`).
+   Scan each downloaded HTML file's `<style>` block for color literals, font families, and spacing values.
+   Produce a best-effort mapping file at `.morph/features/$ARGUMENTS/1-ui/stitch-html/stitch-css-map.json`:
+
+   ```json
+   {
+     "mappings": [
+       { "stitchValue": "#6366f1", "projectToken": "var(--color-primary)", "type": "color" },
+       { "stitchValue": "Inter", "projectToken": "var(--font-body)", "type": "font" }
+     ],
+     "unmapped": ["#ff0000"],
+     "source": ".morph/context/design-system.md"
+   }
+   ```
+
+   If no `design-system.md` exists, create the file with empty mappings:
+   ```json
+   { "mappings": [], "unmapped": [], "source": null, "note": "No design system found — use Stitch values directly" }
+   ```
+
+4. **Ask user for screen-to-route mapping:**
+   Use `AskUserQuestion` to map each screen to an app route. Present all screens in one call (up to 4 per call):
+
+   ```json
+   {
+     "questions": [{
+       "header": "Route Map",
+       "question": "Which app route does screen '{screenTitle}' correspond to?",
+       "multiSelect": false,
+       "options": [
+         { "label": "/{screenTitleLower}", "description": "Inferred from screen title" },
+         { "label": "/", "description": "Home/landing page" },
+         { "label": "Skip", "description": "This screen has no direct route" }
+       ]
+     }]
+   }
+   ```
+
+   For more than 4 screens, make sequential `AskUserQuestion` calls.
+
+5. **Create `stitch-screen-map.json`:**
+   Save to `.morph/features/$ARGUMENTS/1-ui/stitch-screen-map.json`:
+   ```json
+   {
+     "version": "1.0.0",
+     "projectId": "{stitchProjectId}",
+     "generatedAt": "{ISO timestamp}",
+     "screens": [
+       {
+         "screenId": "{screenId}",
+         "title": "{screenTitle}",
+         "route": "/dashboard",
+         "htmlFile": "stitch-html/{screenId}.html",
+         "screenshotFile": "stitch-screen-{index}.png",
+         "device": "desktop"
+       }
+     ],
+     "cssMapFile": "stitch-html/stitch-css-map.json"
+   }
+   ```
+
+6. **Update mockups.md** to reference downloaded HTML files.
+   Add a section at the top of `mockups.md`:
+
+   ```markdown
+   ## Stitch HTML Reference
+
+   This feature has Stitch HTML exports for implementation fidelity.
+   See `stitch-screen-map.json` for the full screen-to-route mapping.
+
+   | Screen | Route | HTML File |
+   |--------|-------|-----------|
+   | {title} | {route} | `stitch-html/{screenId}.html` |
+   ```
+
+7. **Mark output:**
+   ```bash
+   morph-spec state mark-output $ARGUMENTS stitchHtml
+   ```
+
+---
+
 **If "Use HTML mockup" selected:**
 → Proceed to 3.5.1 (existing workflow, unchanged)
 
@@ -682,7 +786,107 @@ Complete user flows:
 → Go back and complete the missing deliverable
 
 **If ALL checkboxes are checked:**
-→ Proceed to accessibility validation
+→ Proceed to image assets spec (Step 4.5) or accessibility validation (Step 5)
+
+---
+
+### Step 4.5: Generate Image Assets Spec (`assets.md`)
+
+> **Skip if:** Feature has no UI components, no mockups, no Stitch screens.
+> **Skip if:** No images needed (pure data/form UI with no visual assets).
+> **MCP:** Gemini Image MCP (optional — used for preview generation only).
+> **Standard:** `frontend/design-system/ai-image-generation.md`
+
+When the feature has UI components that need images (hero sections, brand panels, illustrations, empty states):
+
+1. **Identify image requirements:**
+   Scan these sources for image references:
+   - `mockups.md` — look for image placeholders, illustrations, photos
+   - `stitch-screen-map.json` (if exists) — Stitch designs reference Google-hosted images that need production replacements
+   - `components.md` — components listing image props or visual areas
+
+2. **Read design system context:**
+   ```
+   Read: .morph/context/design-system.md
+   ```
+   Extract: aesthetic direction, primary/accent/background colors, font pair.
+
+3. **Ask user to confirm image requirements:**
+
+   ```json
+   {
+     "questions": [{
+       "header": "Image Assets",
+       "question": "I identified these images needed for the feature. Which should we include in assets.md?",
+       "multiSelect": true,
+       "options": [
+         { "label": "{image1 purpose}", "description": "{route} — {aspect ratio}" },
+         { "label": "{image2 purpose}", "description": "{route} — {aspect ratio}" },
+         { "label": "None needed", "description": "Skip image asset generation entirely" }
+       ]
+     }]
+   }
+   ```
+
+4. **For each confirmed image**, ask for prompt refinement:
+
+   ```json
+   {
+     "questions": [{
+       "header": "IMG-001",
+       "question": "Prompt for {purpose}: '{auto-generated prompt based on design context}'. Adjust?",
+       "multiSelect": false,
+       "options": [
+         { "label": "Use as-is", "description": "The prompt looks good" },
+         { "label": "Adjust", "description": "I want to refine the prompt (Other)" }
+       ]
+     }]
+   }
+   ```
+
+5. **Generate `assets.md`:**
+   Write to `.morph/features/$ARGUMENTS/1-ui/assets.md`:
+
+   ```markdown
+   # Image Assets — {feature}
+
+   ## Design Context
+   - Aesthetic: {from design-system.md}
+   - Primary: {--color-primary value}
+   - Background: {--color-background value}
+   - Accent: {--color-accent value}
+   - Font pair: {display + body fonts}
+
+   ## Assets
+
+   ### IMG-001: {Descriptive Name}
+   - **Purpose:** {What this image represents in the UI}
+   - **Route:** {App route where it appears}
+   - **Component:** {React component name}
+   - **Aspect Ratio:** {1:1 | 3:2 | 16:9 | etc.}
+   - **Output Path:** `public/images/{feature}/{kebab-name}.png`
+   - **Prompt:** "{Narrative prompt with design system colors and aesthetic direction injected}"
+   - **Priority:** {high | medium | low}
+   ```
+
+6. **Optional — Generate preview images:**
+   If Gemini Image MCP is available, offer to generate preview images for user approval:
+
+   ```json
+   {
+     "questions": [{
+       "header": "Previews",
+       "question": "Gemini Image MCP is available. Want to generate preview images now for approval?",
+       "multiSelect": false,
+       "options": [
+         { "label": "Yes, generate previews", "description": "Generate images now for visual approval before implement phase" },
+         { "label": "Skip previews", "description": "Generate during implement phase instead" }
+       ]
+     }]
+   }
+   ```
+
+   If yes: invoke `/morph-gemini-image` for each asset, save previews to `1-ui/asset-previews/`, show to user for feedback. Iterate prompts if needed.
 
 ---
 
@@ -705,6 +909,8 @@ morph-spec state mark-output $ARGUMENTS ui-design-system
 morph-spec state mark-output $ARGUMENTS ui-mockups
 morph-spec state mark-output $ARGUMENTS ui-components
 morph-spec state mark-output $ARGUMENTS ui-flows
+# Only if Stitch path was used (stitch-screen-map.json exists):
+morph-spec state mark-output $ARGUMENTS stitchHtml
 ```
 
 > **Format note:** The `mark-output` commands accept BOTH kebab-case (`ui-design-system`)
@@ -774,13 +980,14 @@ Use `AskUserQuestion` to capture explicit approval before advancing:
 
 ## Phase Outputs
 
-<!-- morph-outputs:uiux -->
-| Output | Caminho |
-|--------|---------|
-| `uiDesignSystem` | `.morph/features/{feature}/1-ui/design-system.md` |
-| `uiMockups` | `.morph/features/{feature}/1-ui/mockups.md` |
-| `uiComponents` | `.morph/features/{feature}/1-ui/components.md` |
-| `uiFlows` | `.morph/features/{feature}/1-ui/flows.md` |
+<!-- morph-outputs:uiux -->
+| Output | Caminho |
+|--------|---------|
+| `uiDesignSystem` | `.morph/features/{feature}/1-ui/design-system.md` |
+| `uiMockups` | `.morph/features/{feature}/1-ui/mockups.md` |
+| `uiComponents` | `.morph/features/{feature}/1-ui/components.md` |
+| `uiFlows` | `.morph/features/{feature}/1-ui/flows.md` |
+| `stitchHtml` | `.morph/features/{feature}/1-ui/stitch-screen-map.json` |
 <!-- /morph-outputs -->
 
 ---

package/framework/skills/level-1-workflows/morph-scope-escalation/SKILL.md

@@ -4,7 +4,7 @@ description: Guided workflow for mid-implementation scope escalation — analyze
 user-invocable: true
 argument-hint: "[feature-name]"
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
-cliVersion: "4.21.0"
+cliVersion: "4.22.0"
 ---
 
 # Scope Escalation Workflow

package/framework/standards/STANDARDS.json

@@ -1097,6 +1097,38 @@
       "stacks": [
         "*"
       ]
+    },
+    {
+      "id": "frontend-design-system-ai-image-generation",
+      "name": "AI Image Generation",
+      "path": "frontend/design-system/ai-image-generation.md",
+      "category": "frontend",
+      "subcategory": "design-system",
+      "tags": [
+        "image",
+        "gemini",
+        "asset",
+        "ai-generation",
+        "placeholder",
+        "mcp"
+      ],
+      "aliases": [
+        "Image Generation",
+        "AI Assets",
+        "Gemini Images"
+      ],
+      "anchors": {
+        "when-to-use": "#when-to-use-ai-generated-images",
+        "prompt-patterns": "#prompt-engineering-patterns",
+        "aspect-ratios": "#aspect-ratio-guide",
+        "assets-md": "#assetsmd-format",
+        "edit-workflows": "#iterative-editing-workflows"
+      },
+      "digest": "Guidelines for generating project images with Gemini Image MCP — prompt patterns, aspect ratios, design-system-aware prompts, iterative editing, and assets.md format.",
+      "stacks": [
+        "nextjs",
+        "next"
+      ]
     }
   ]
 }