@torka/claude-workflows 0.12.0 → 0.13.1

package/skills/designer-founder/steps/step-06-validate.md

@@ -0,0 +1,181 @@
+# Step 6: Validate & Finalize
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- NEVER skip the consistency checklist
+- CRITICAL: Auto-fix issues when possible, flag the rest
+- ALWAYS save designer state for session continuity
+- Goal: Quality gate before workflow completion
+
+---
+
+## CONTEXT FROM PREVIOUS STEPS
+
+You should have:
+- All artifacts created in `{planning_artifacts}/ux-design/`
+- Epic linking completed (or skipped) in Step 5
+- `theme`: Theme info (if used)
+- `design`: Full design state from Step 3
+- `scope`: What was designed
+- `linking_result`: Epic linking results from Step 5
+
+---
+
+## YOUR TASK
+
+Run a consistency check across all artifacts and product docs, fix issues, and finalize the workflow.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Design Consistency Check
+
+Validate all artifacts and product docs:
+
+```
+DESIGN CONSISTENCY CHECK
+
+1. [ ] No hardcoded hex/color values - all colors reference theme tokens
+2. [ ] shadcn install command is complete - every component in any artifact appears in the command
+3. [ ] All tokens referenced in component strategies exist in tokens.json (if theme provided)
+4. [ ] File paths use project naming conventions
+5. [ ] Artifact file names follow epic-{N}-{feature}- prefix pattern
+6. [ ] Epic links are valid (relative paths correct)
+7. [ ] All designed screens have corresponding epic references
+8. [ ] Design decisions and PRD/epics are consistent (no contradictions between specs)
+9. [ ] All referenced UI patterns have component definitions (toasts, loading states, error states)
+```
+
+Run each check against the actual files:
+
+**Check 1 (Theme tokens):** If theme was provided, scan artifact files for hex values like `#FF0000` or `rgb()`. All colors should reference CSS custom properties (`var(--primary)`) or Tailwind theme classes.
+
+**Check 2 (shadcn completeness):** Extract all shadcn component references from all artifacts. Compare against the install command in the component strategy. Flag any missing.
+
+**Check 3 (Token existence):** If `tokens.json` was provided, verify all token references in component strategies match actual keys in the tokens file.
+
+**Check 4 (Naming conventions):** Check if file names follow the project's established patterns.
+
+**Check 5 (Epic prefix):** Verify all UX artifact files start with `epic-{N}-{feature}-`.
+
+**Check 6 (Link validity):** Check all relative paths in epic files point to files that exist.
+
+**Check 7 (Screen coverage):** Compare designed screens against epic references. Flag any designed screens without epic references.
+
+**Check 8 (Spec consistency):** Check that design decisions documented in artifacts don't contradict PRD or epic requirements.
+
+**Check 9 (UI patterns):** If designs reference toasts, loading states, error states, or empty states, verify these are defined in the component strategy's interaction patterns section.
+
+---
+
+### 2. Report Results
+
+```
+CONSISTENCY CHECK RESULTS
+
+[pass/fail] No hardcoded colors: {details}
+[pass/fail] shadcn install complete: {details}
+[pass/fail] Token references valid: {details}
+[pass/fail] File naming conventions: {details}
+[pass/fail] Epic prefix pattern: {details}
+[pass/fail] Epic link validity: {details}
+[pass/fail] Screen-epic coverage: {details}
+[pass/fail] Spec consistency: {details}
+[pass/fail] UI pattern definitions: {details}
+
+Issues found: {count}
+
+[F] Fix all - Auto-correct issues
+[R] Review - Show details for each issue
+[S] Skip - Continue with known issues
+```
+
+**If F (Fix all):**
+- Auto-correct each issue (add missing components to install command, fix file paths, add missing epic references, etc.)
+- Report what was fixed
+- Re-run check to confirm
+
+**If R (Review):**
+- Show each issue with context
+- Allow user to fix, skip, or note each one
+- Proceed after review
+
+**If S (Skip):**
+- Note known issues in workflow output
+- Proceed to finalization
+
+---
+
+### 3. Save Designer State
+
+Write session state to `{planning_artifacts}/ux-design/.designer-state.yaml` for future workflow runs:
+
+```yaml
+last_run: "{timestamp}"
+tool_used: "{design.tool_used}"
+theme: "{theme.prompt_file or none}"
+mode: "{mode}"
+project_state: "{greenfield | existing}"
+tools_available:
+  superdesign: {true/false}
+  magicpatterns: {true/false}
+  stitch: {true/false}
+  shadcn_mcp: {true/false}
+scope_summary: "{brief description of what was designed}"
+artifacts_created:
+  - "{file1}"
+  - "{file2}"
+epic_linked: "{epic file path or none}"
+```
+
+---
+
+### 4. Workflow Complete
+
+```
+DESIGN WORKFLOW COMPLETE
+
+Summary:
+─────────────────────────────────────
+Mode: {mode}
+Tool: {design.tool_used}
+Theme: {theme.name or "None"}
+Prototype: {design.output_location}
+
+Artifacts:
+{list of created files with paths}
+
+Epic: {linked epic or "Not linked"}
+Consistency: {pass_count}/{total_count} checks passed
+─────────────────────────────────────
+
+Next Steps for Development:
+1. Install components:
+   {install_command}
+
+2. Review component strategy for custom builds
+
+3. Reference layouts during implementation
+
+{If related story exists:}
+This design supports: {story_reference}
+Ready for implementation via /dev-story workflow.
+─────────────────────────────────────
+
+[N] New Design - Start another design session
+[D] Done - Exit workflow
+```
+
+**Menu Handlers:**
+- **N**: Load `./step-01-context.md` (returning session detection will kick in)
+- **D**: Exit workflow
+
+---
+
+## SUCCESS CRITERIA
+
+- All 9 consistency checks executed
+- Issues identified and addressed (fixed, reviewed, or acknowledged)
+- Designer state saved for session continuity
+- Completion summary presented to user

package/skills/designer-founder/templates/component-strategy.md

@@ -14,6 +14,8 @@ npx shadcn@latest add {shadcn_components}
 
 {extraction_table}
 
+{theme_integration_section}
+
 ## Component Mapping
 
 | UI Element | Source | Component | Variant/Props | Notes |
@@ -34,6 +36,8 @@ npx shadcn@latest add {shadcn_components}
 
 {what_not_to_do_section}
 
+{interaction_patterns_section}
+
 ## Implementation Notes
 
 {implementation_notes}

package/skills/designer-founder/tools/magicpatterns.md

@@ -5,7 +5,7 @@
 MagicPatterns is an AI design tool that generates React components directly. Requires MagicPatterns MCP to be configured.
 
 **Output:** React component code + hosted design URL
-**MCP Tools Used:** `create_design`, `get_design`, `read_files`, `update_design`
+**MCP Tools Available:** `create_design`, `get_design`, `read_files`, `update_design`
 
 ---
 
@@ -30,11 +30,32 @@ Alternative options:
 [D] Direct - Map to components directly
 ```
 
+### MCP Connection Recovery
+
+If MCP tools are available but a call fails with a connection error:
+1. Wait 10 seconds
+2. Retry the failed call once
+3. If still failing, ask user to run `/mcp` to reconnect
+
+**CRITICAL:** Do NOT proceed to artifact generation if `read_files` fails. The extracted React code is what makes component-strategy artifacts accurate. Wait for MCP reconnection rather than generating artifacts without extracted code.
+
 ---
 
 ## Execution Flow
 
-### 1. Frame Design Prompt
+### 1. Check Existing Designs
+
+Before creating new designs, check if the user already has relevant designs on MagicPatterns:
+
+```
+Tool: get_design
+Parameters:
+  url: "{any_known_project_url}"
+```
+
+If user has been working in MagicPatterns directly, they may have created variations. List available files/versions and let user choose before creating new designs.
+
+### 2. Frame Design Prompt
 
 Construct prompt from context:
 
@@ -47,13 +68,20 @@ Requirements:
 - Responsive design (mobile-first)
 - {additional_context_from_scope}
 
+{if theme provided}
+Theme:
+- Reference: {theme.prompt_file}
+- Tokens: {theme.tokens_file}
+- Follow theme design rules for colors, typography, spacing
+{/if}
+
 Style:
 - {inspiration_notes}
 - Clean, modern aesthetic
 - Consistent with shadcn/ui patterns
 ```
 
-### 2. Create Design
+### 3. Create Design
 
 Use MCP tool:
 ```
@@ -63,7 +91,7 @@ Parameters:
   imageUrls: [{inspiration_image_urls}]  // optional
 ```
 
-### 2.5 Handle Empty Response
+### 3.5 Handle Empty Response
 
 If `create_design` returns no URL or empty response:
 
@@ -82,35 +110,38 @@ Options:
 - Accept URL from user
 - Validate format (must contain `magicpatterns.com/c/` or `magicpatterns.app`)
 - Call `get_design` to verify design exists
-- If valid, continue to step 3
+- If valid, continue to step 4
 - If invalid, show error and return to options
 
 **If R (Retry):**
-- Re-execute step 2 with same parameters
+- Re-execute step 3 with same parameters
 - If fails again, suggest P or S options
 
 **If S (Switch):**
 - Return to tool selection in step-03-design.md
 - Mark current design attempt as abandoned
 
-### 3. Present Result
+### 4. Present Result
+
+After design is created, show the URL and let user validate directly on MagicPatterns:
 
 ```
 DESIGN CREATED
 
-Preview URL: {preview_url}
-Editor URL: {editor_url}
+URL: {design_url}
 
-Please review the design in MagicPatterns.
+Please review the design on MagicPatterns.
 
 Options:
-[U] Update - Request changes
+[U] Update - Request changes (uses update_design MCP tool)
 [R] Read Code - Extract React component code
 [V] View Files - List available files
 [C] Continue - Design is approved
 ```
 
-### 4. Handle User Selection
+**IMPORTANT:** Do NOT take Playwright screenshots of MagicPatterns designs. MagicPatterns renders in a cross-origin iframe that produces unusable screenshots. Direct the user to review on the MagicPatterns platform instead.
+
+### 5. Handle User Selection
 
 **If U (Update):**
 
@@ -119,7 +150,7 @@ Ask what changes are needed:
 What changes would you like to make?
 ```
 
-Use MCP tool:
+Use `update_design` for iteration instead of creating new designs:
 ```
 Tool: update_design
 Parameters:
@@ -127,7 +158,7 @@ Parameters:
   prompt: "{user_change_request}"
 ```
 
-Return to step 3 after update completes.
+Return to step 4 after update completes.
 
 **If V (View Files):**
 
@@ -165,6 +196,8 @@ Parameters:
   fileNames: [{selected_files}]
 ```
 
+**CRITICAL:** If `read_files` fails, do NOT proceed to artifact generation. Wait for MCP reconnection (see "MCP Connection Recovery" above). The extracted code is essential for accurate component-strategy artifacts.
+
 Present code:
 ```
 REACT CODE EXTRACTED
@@ -220,7 +253,7 @@ Parameters:
   imageUrls: [{screenshot_of_html_design}]  // if available
 ```
 
-This is useful in the conversion step when the user chooses MagicPatterns for HTML→React conversion.
+This is useful in the conversion step when the user chooses MagicPatterns for HTML->React conversion.
 
 ---
 
@@ -246,7 +279,7 @@ After each design is created or approved, show progress:
 DESIGN PROGRESS: {completed} of {total} complete
 
 {foreach design in designs}
-{if status = approved}✓{/if}{if status = created}◐{/if}{if status = pending}○{/if} {name} - {status}{if url} ({url}){/if}
+{if status = approved}[done]{/if}{if status = created}[review]{/if}{if status = pending}[pending]{/if} {name} - {status}{if url} ({url}){/if}
 {/foreach}
 
 Options:
@@ -264,7 +297,7 @@ When scope has multiple items:
    DESIGNS TO CREATE ({count} items)
 
    {foreach scope_item}
-   ○ {item_name}
+   [ ] {item_name}
    {/foreach}
 
    Options:
@@ -272,10 +305,10 @@ When scope has multiple items:
    [B] Batch - Create all designs, then review together
    ```
 
-2. **If One-by-one:** Execute steps 1-4 for each item, updating registry after each
+2. **If One-by-one:** Execute steps 1-5 for each item, updating registry after each
 
 3. **If Batch:**
-   - Create all designs (steps 1-3) without waiting for approval
+   - Create all designs (steps 1-4) without waiting for approval
    - Present all designs for bulk review
    - Allow individual updates before final approval
 

package/skills/designer-founder/tools/stitch.md

@@ -3,12 +3,11 @@
 ## Overview
 
 Stitch is Google's AI design tool that generates web UI screens from text prompts.
-This tool requires both Stitch MCP and Google's stitch-skills to be installed.
+This tool requires Stitch MCP to be configured.
 
 **Output Location:** `.stitch/screens/`
 **Output Format:** HTML + CSS files + screenshots
-**MCP Tools Used:** `generate_screen_from_text`, `get_screen`, `list_projects`, `create_project`
-**Dependencies:** Google's stitch-skills (design-md skill at minimum)
+**MCP Tools Available:** `generate_screen_from_text`, `get_screen`, `list_screens`, `list_projects`, `get_project`, `create_project`, `edit_screens`, `generate_variants`
 
 ---
 
@@ -18,7 +17,7 @@ Check availability before proceeding:
 
 ```
 Stitch MCP: [check if mcp__stitch* or stitch* tools available]
-Stitch Skills: [check if design-md skill installed]
+react-components skill: [check if installed via `npx skills list`]
 ```
 
 ### If Stitch MCP not available:
@@ -38,66 +37,40 @@ Alternative options:
 [B] Back to tool selection
 ```
 
-### If Stitch Skills not installed:
+### If react-components skill not installed:
 
 ```
-STITCH SKILLS REQUIRED
+STITCH SKILL RECOMMENDED
 
-Google's stitch-skills are required for Stitch integration.
+Google's react-components skill enhances HTML->React conversion.
 
 Install with:
-npx skills add google-labs-code/stitch-skills --skill design-md -g -a claude-code -y
 npx skills add google-labs-code/stitch-skills --skill react-components -g -a claude-code -y
 
 Then restart Claude Code and try again.
 
+[C] Continue without skill - Use standard conversion
 [B] Back to tool selection
 ```
 
 ---
 
-## Execution Flow
-
-### 1. Check for DESIGN.md
+## Content Limitations
 
-```
-STITCH PROJECT SETUP
+Stitch works best for **full-page layouts** (landing pages, dashboards, settings screens, forms).
 
-Checking for design system documentation...
-```
-
-**If DESIGN.md exists in project root:**
-
-```
-Found: DESIGN.md
-Design system will be used for prompt consistency.
+Stitch is NOT suitable for:
+- Component showcases or design system pages
+- Individual component generation (use MagicPatterns instead)
+- Design token documentation
 
-[C] Continue with existing design system
-[U] Update design system first (uses design-md skill)
-```
-
-**If DESIGN.md doesn't exist:**
-
-```
-No DESIGN.md found.
-
-DESIGN.md helps Stitch generate consistent designs by documenting
-your color palette, typography, and component styles.
+---
 
-Options:
-[G] Generate DESIGN.md (Recommended)
-    → Uses design-md skill to create semantic design documentation
-    → Best for: New projects, establishing design consistency
+## Execution Flow
 
-[S] Skip - proceed without design system
-    → Stitch will use default styling
-    → Fine for: Quick prototypes, one-off designs
-```
+### 1. Theme Reference
 
-**If G (Generate):**
-- Invoke the design-md skill: `/design-md`
-- Wait for user to complete the skill workflow
-- Continue to design generation after DESIGN.md is created
+Theme tokens should be established before design. If a theme was provided in Step 1, reference it in the design prompt. If no theme was provided, proceed with tool defaults.
 
 ---
 
@@ -119,9 +92,10 @@ Requirements:
 - Tailwind CSS classes
 - {additional_context_from_scope}
 
-{if DESIGN.md exists}
-DESIGN SYSTEM:
-[Include relevant sections from DESIGN.md - colors, typography, component styles]
+{if theme provided}
+THEME:
+[Include relevant sections from theme.prompt.md - colors, typography, component styles]
+[Reference token values from theme.tokens.json for precise color matching]
 {/if}
 
 Style Direction:
@@ -178,7 +152,7 @@ GENERATING DESIGN
 Feature: {user_intent}
 Project: {project_name}
 
-Please wait while Stitch generates your design...
+Generating screen (this takes 1-3 minutes)...
 ```
 
 ```
@@ -187,7 +161,25 @@ Parameters:
   projectId: "{projectId}"
   prompt: "{constructed_prompt}"
   deviceType: "DESKTOP"
+  modelId: "GEMINI_3_PRO"
+```
+
+**IMPORTANT:** Always use `modelId: "GEMINI_3_PRO"` for higher quality output (not Flash).
+
+### Generation Timing
+
+Screens take **1-3 minutes** to generate (per Stitch MCP documentation).
+
+**DO NOT RETRY** if the tool call appears slow. The built-in Stitch MCP docs explicitly state: "This action can take a few minutes. DO NOT RETRY."
+
+After firing the generation request:
 ```
+Screen is generating (1-3 min). I'll check the result shortly.
+```
+
+- `list_screens` will NOT show the screen until generation completes
+- Wait at least 90 seconds before assuming failure
+- If the tool call fails with a connection error, the generation may still succeed server-side -- try `get_screen` or `list_screens` later to check
 
 ---
 
@@ -208,8 +200,10 @@ mkdir -p .stitch/screens/
 ```
 
 Download and save assets:
-- **HTML:** `htmlCode.downloadUrl` → save to `.stitch/screens/{page}.html`
-- **Screenshot:** `screenshot.downloadUrl` → save to `.stitch/screens/{page}.png`
+- **HTML:** `htmlCode.downloadUrl` -> save to `.stitch/screens/{page}.html`
+- **Screenshot:** `screenshot.downloadUrl` -> save to `.stitch/screens/{page}.png`
+
+**IMPORTANT:** Do NOT download/export HTML until the user has reviewed and approved the design on the Stitch platform.
 
 ---
 
@@ -225,10 +219,12 @@ Files saved:
 - HTML: .stitch/screens/{page}.html
 - Preview: .stitch/screens/{page}.png
 
+Please review the design on the Stitch platform.
+
 Options:
 [V] View - Display screenshot
-[P] Playwright - Capture live rendering (desktop + mobile)
-[U] Update - Request changes via Stitch
+[E] Edit - Request changes via edit_screens
+[A] Alternatives - Generate design variants
 [C] Continue - Design approved, proceed to next step
 ```
 
@@ -238,22 +234,55 @@ Options:
 - Display the screenshot image from `.stitch/screens/{page}.png`
 - Return to options
 
-**If P (Playwright) and Playwright available:**
-- Navigate to `file://{absolute_path}/.stitch/screens/{page}.html`
-- Capture desktop screenshot (1280px width)
-- Resize viewport (375px width) and capture mobile screenshot
-- Present both screenshots for comparison
-- Return to options
-
-**If U (Update):**
+**If E (Edit):**
+Use `edit_screens` for iteration instead of regenerating from scratch:
 ```
 What changes would you like to make?
+```
+
+```
+Tool: edit_screens
+Parameters:
+  projectId: "{projectId}"
+  screenId: "{screenId}"
+  prompt: "{user_change_request}"
+```
+
+Wait for edit to complete (same timing rules as generation), then retrieve updated assets.
+Return to step 6.
+
+**If A (Alternatives):**
+Offer variant generation when user wants to explore alternatives:
 
-Describe the changes and I'll generate an updated design.
 ```
-- Append change request to prompt
-- Generate new screen with updated prompt
-- Return to step 5
+GENERATE VARIANTS
+
+How different should the variants be?
+
+[R] Refine - Subtle variations (same structure, minor tweaks)
+[E] Explore - Moderate changes (layout shifts, style changes)
+[I] Reimagine - Significantly different approaches
+
+How many variants? [1-5, default: 3]
+
+What aspects to vary?
+[L] Layout
+[C] Color scheme
+[T] Typography
+[A] All aspects
+```
+
+```
+Tool: generate_variants
+Parameters:
+  projectId: "{projectId}"
+  screenId: "{screenId}"
+  creativeRange: "[REFINE | EXPLORE | REIMAGINE]"
+  aspects: ["LAYOUT", "COLOR_SCHEME", ...]
+  variantCount: {count}
+```
+
+Present variants for comparison and selection. Selected variant becomes the active design.
 
 **If C (Continue):**
 - Store design state
@@ -274,7 +303,6 @@ design:
   screenshot: ".stitch/screens/{page}.png"
   stitch_project_id: "{projectId}"
   stitch_screen_id: "{screenId}"
-  design_md_used: true/false
 ```
 
 ---
@@ -312,7 +340,7 @@ Which approach? [A/O]
 ```
 
 **If A (All at once):**
-- Generate each design in sequence
+- Generate each design in sequence (DO NOT fire multiple generations simultaneously)
 - Track status in design registry
 - Present all for review at end
 
@@ -344,4 +372,6 @@ Both are presented in Step 4 when `design.tool_used` = `stitch`.
 | `create_project` | Create new project |
 | `list_screens` | Get all screens in project |
 | `get_screen` | Get screen details + download URLs |
-| `generate_screen_from_text` | Generate new screen from prompt |
+| `generate_screen_from_text` | Generate new screen from prompt (use `modelId: "GEMINI_3_PRO"`) |
+| `edit_screens` | Edit existing screens via prompt (use for iteration) |
+| `generate_variants` | Create design variations with creative range control |

package/uninstall.js

@@ -43,6 +43,7 @@ const INSTALLED_FILES = {
     'dev-story-backend.md',
     'dev-story-fullstack.md',
     'dev-story-ui.md',
+    'deep-audit.md',
   ],
   agents: [
     'principal-code-reviewer.md',
@@ -103,6 +104,24 @@ const INSTALLED_FILES = {
     'generate-theme.ts',
     'superdesign-agent-instructions.md',
   ],
+  'skills/deep-audit': [
+    'SKILL.md',
+    'INSPIRATIONS.md',
+  ],
+  'skills/deep-audit/agents': [
+    'security-and-error-handling.md',
+    'architecture-and-complexity.md',
+    'code-health.md',
+    'performance-profiler.md',
+    'test-coverage-analyst.md',
+    'type-design-analyzer.md',
+    'data-layer-reviewer.md',
+    'api-contract-reviewer.md',
+    'seo-accessibility-auditor.md',
+  ],
+  'skills/deep-audit/templates': [
+    'report-template.md',
+  ],
 };
 
 /**
@@ -279,6 +298,9 @@ function uninstall() {
     'skills/product-architect',
     'skills/agent-creator/expertise',
     'skills/agent-creator',
+    'skills/deep-audit/templates',
+    'skills/deep-audit/agents',
+    'skills/deep-audit',
   ];
   for (const skillSubDir of skillDirs) {
     const dirPath = path.join(targetBase, skillSubDir);