@torka/claude-workflows 0.6.1 → 0.6.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@torka/claude-workflows",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Claude Code workflow helpers: epic automation, git cleanup, agents, and design workflows",
   "keywords": [
     "claude-code",

package/skills/designer-founder/SKILL.md

@@ -33,7 +33,7 @@ You are an expert UI/UX designer and visual design specialist who:
 
 ## WORKFLOW ARCHITECTURE
 
-This uses **micro-file architecture** with 4 core steps:
+This uses **micro-file architecture** with 5 core steps:
 
 | Step | Name | Purpose |
 |------|------|---------|
@@ -41,9 +41,10 @@ This uses **micro-file architecture** with 4 core steps:
 | 2 | Scope & Inspiration | Define what to design, gather references |
 | 3 | Design | Execute design using selected tool |
 | 4 | Convert & Artifacts | Transform to dev-ready output |
+| 5 | Epic Linking | Connect designs to implementation plans (optional) |
 
 **Quick Prototype Mode:** Steps 1 → 3 (skip detailed artifacts)
-**Production Mode:** Steps 1 → 2 → 3 → 4 (full flow)
+**Production Mode:** Steps 1 → 2 → 3 → 4 → 5 (optional) (full flow)
 
 ---
 

package/skills/designer-founder/steps/step-03-design.md

@@ -134,6 +134,66 @@ Ready to create dev handover artifacts.
 
 ---
 
+### 5.5 Validate All Designs (Before Step 4)
+
+**When scope has multiple items**, validate coverage before proceeding to artifacts:
+
+```
+DESIGN VALIDATION
+
+Checking scope coverage:
+{foreach scope_item}
+[✓/✗] {item_name}: {url_or_missing}
+{/foreach}
+
+─────────────────────────────────────
+Coverage: {completed_count} of {total_count} scope items
+```
+
+**If any items missing:**
+```
+Some designs are incomplete.
+
+Missing:
+{foreach missing_item}
+- {item_name}
+{/foreach}
+
+Options:
+[C] Create missing - Generate remaining designs now
+[S] Skip - Proceed with partial coverage (will note gaps in artifacts)
+[R] Revise scope - Remove items that don't need designs
+```
+
+**If C (Create missing):**
+- Return to step 2 for each missing item
+- Update design registry after each creation
+- Return to validation after all created
+
+**If S (Skip):**
+- Mark skipped items in design state
+- Add "NOT DESIGNED" note to artifact generation
+- Proceed to step 4 with partial coverage
+
+**If R (Revise scope):**
+- Show current scope items
+- Allow removal of items
+- Recalculate coverage
+- Return to validation
+
+**If all items covered:**
+```
+VALIDATION PASSED ✓
+
+All {total_count} scope items have approved designs.
+Ready for artifact generation.
+
+[C] Continue to artifacts
+[R] Review designs before continuing
+```
+
+---
+
 ## COLLABORATION MENU
 
 ```

package/skills/designer-founder/steps/step-04-artifacts.md

@@ -114,6 +114,22 @@ Populate placeholders:
 - `{inspiration_sources}` → References used
 - `{date}` → Current date
 
+**Tool-specific placeholders:**
+
+- `{tool_specific_notes}` → Generate based on tool used:
+  - **MagicPatterns:** "React/TypeScript code ready for extraction. Use `read_files` MCP tool to access."
+  - **SuperDesign:** "HTML/CSS prototype. Requires conversion to React components."
+  - **Wireframe:** "Structure reference only. Build components from scratch."
+  - **Direct:** "Component mapping provided. No visual prototype created."
+
+- `{implementation_source_section}` → When MagicPatterns used:
+  ```markdown
+  | Component | Source URL | Files to Extract |
+  |-----------|------------|------------------|
+  | {component_name} | [{design_name}]({url}) | {file_list} |
+  ```
+  For other tools: "See Component Strategy for implementation details."
+
 **Save to:** `{planning_artifacts}/ux-design/{prefix}design-brief.md`
 
 ---
@@ -132,6 +148,42 @@ Populate placeholders:
 - `{implementation_notes}` → Any special considerations
 - `{date}` → Current date
 
+**MagicPatterns-specific placeholders (when `design.tool_used` = magicpatterns):**
+
+- `{magicpatterns_extraction_warning}` → Include this warning block:
+  ```markdown
+  > **CRITICAL: EXTRACT CODE, DO NOT REBUILD**
+  >
+  > MagicPatterns designs contain **production-ready React/TypeScript**.
+  > Use `mcp__magic-patterns__read_files` to extract code directly.
+  > Only adapt for project patterns (Supabase auth, react-hook-form, etc.)
+  ```
+
+- `{extraction_table}` → Generate extraction guide from design registry:
+  ```markdown
+  | Design | MagicPatterns URL | Primary File | Key Elements |
+  |--------|-------------------|--------------|--------------|
+  | Sign In | [View](url) | SignInForm.tsx | Form, validation, social buttons |
+  | Sign Up | [View](url) | SignUpForm.tsx | Multi-step form, password strength |
+  ```
+
+- `{what_not_to_do_section}` → Include this section:
+  ```markdown
+  ## What NOT to Do
+
+  | Don't | Instead |
+  |-------|---------|
+  | Build layouts from scratch | Extract from MagicPatterns designs |
+  | Create custom form components | Extract existing form patterns |
+  | Write CSS for auth cards | Extract Tailwind classes from designs |
+  | Guess component structure | Read files with `read_files` tool first |
+  ```
+
+**For non-MagicPatterns tools:**
+- `{magicpatterns_extraction_warning}` → Empty string
+- `{extraction_table}` → Empty string or "N/A - Design created with {tool_used}"
+- `{what_not_to_do_section}` → Empty string
+
 **Save to:** `{planning_artifacts}/ux-design/{prefix}component-strategy.md`
 
 ---
@@ -153,6 +205,20 @@ Populate placeholders:
 - `{responsive_summary_rows}` → Table of element behavior
 - `{date}` → Current date
 
+**Implementation note placeholder:**
+
+- `{layout_implementation_note}` → When MagicPatterns used:
+  ```markdown
+  > **NOTE: Layouts Already Implemented**
+  >
+  > These layouts are reference documentation. The actual responsive layouts
+  > are already built into the MagicPatterns designs. Extract the Tailwind
+  > responsive classes directly from the design files rather than rebuilding.
+  >
+  > **Source:** Extract from [{design_name}]({url}) using `read_files` tool.
+  ```
+  For other tools: Empty string or omit placeholder
+
 **Save to:** `{planning_artifacts}/ux-design/{prefix}layouts.md`
 
 ---
@@ -175,6 +241,18 @@ Populate placeholders:
 - `{error_states}` → Error handling
 - `{date}` → Current date
 
+**Implementation source placeholder:**
+
+- `{journey_implementation_sources}` → Link each journey step to its design source:
+  ```markdown
+  | Step | Design Source | Primary File | Key Feature |
+  |------|---------------|--------------|-------------|
+  | 1. Enter email | [Sign In]({url}) | SignInForm.tsx | Email input with validation |
+  | 2. Enter password | [Sign In]({url}) | SignInForm.tsx | Password field with show/hide |
+  | 3. Submit | [Sign In]({url}) | SignInForm.tsx | Loading state, error handling |
+  ```
+  For non-MagicPatterns: "Reference {tool_used} prototype at {output_location}"
+
 **Save to:** `{planning_artifacts}/ux-design/{prefix}user-journeys.md`
 
 ---
@@ -238,10 +316,16 @@ This design supports: {story_reference}
 Ready for implementation via /dev-story workflow.
 ─────────────────────────────────────
 
+[L] Link to Epics - Update implementation plans with UX references
 [N] New Design - Start another design session
 [D] Done - Exit workflow
 ```
 
+**Menu Handlers:**
+- **L**: Load `./step-05-epic-linking.md` to cross-reference designs in epic files
+- **N**: Restart workflow from Step 1
+- **D**: Exit workflow
+
 ---
 
 ## OUTPUT FOLDER MANAGEMENT

package/skills/designer-founder/steps/step-05-epic-linking.md

@@ -0,0 +1,370 @@
+# Step 5: Epic Linking
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER modify epic files without user approval
+- 📖 CRITICAL: Preview all changes before applying
+- ✅ ALWAYS preserve existing epic content (targeted edits only)
+- 🎯 Goal: Cross-reference UX designs in implementation plans
+
+---
+
+## CONTEXT FROM PREVIOUS STEPS
+
+You should have from Step 4:
+- `artifact_data.feature_name`: What was designed
+- `artifact_data.date`: Current date
+- `design.tool_used`: Which tool created the design (magicpatterns, superdesign, wireframe, direct)
+- `design.output_location`: Where the design lives (URL or folder path)
+- Files created in `{planning_artifacts}/ux-design/` with prefix like `epic-3-onboarding-*`
+
+---
+
+## YOUR TASK
+
+Connect UX design artifacts to epic files so developers can find designs during implementation.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Detect Related Epics
+
+Extract epic number from artifact prefix:
+
+**Pattern:** `{prefix}design-brief.md` where prefix = `epic-{N}-{feature-name}-`
+
+```
+SCANNING FOR RELATED EPICS
+─────────────────────────────────────
+
+Artifact prefix: {prefix}
+Detected epic: Epic {N}
+
+Searching: {planning_artifacts}/epics/
+```
+
+**Search logic:**
+1. Parse artifact filename prefix (e.g., `epic-3-onboarding-` → Epic 3)
+2. Find epic file: `epic-{N}-*.md` in `{planning_artifacts}/epics/`
+3. If multiple matches, list all and ask user to select
+
+**If no epic found:**
+```
+No matching epic file found for "{prefix}".
+
+Options:
+[P] Provide path - Enter epic file path manually
+[S] Skip - Continue without linking
+```
+
+---
+
+### 2. Analyze Epic Structure
+
+Read the epic file and identify:
+
+```yaml
+epic_analysis:
+  file_path: "{epic_file_path}"
+  title: "{Epic N: Title}"
+  has_ux_section: [true/false]
+  stories:
+    - number: "3.1"
+      title: "Story title"
+      has_ux_design: [true/false]
+    - number: "3.2"
+      ...
+```
+
+**Report to user:**
+```
+EPIC ANALYSIS
+─────────────────────────────────────
+
+Found: {Epic N: Title}
+Location: {epic_file_path}
+
+Current UX Design references:
+- Epic level: {Yes/No}
+- Stories with UX Design section: {count}/{total}
+
+Artifacts to link:
+- {prefix}design-brief.md
+- {prefix}component-strategy.md
+{- {prefix}layouts.md}
+{- {prefix}user-journeys.md}
+```
+
+---
+
+### 3. Prepare Epic-Level Link
+
+**If epic does NOT have UX Design section:**
+
+Generate section to insert after **Goal:** line:
+
+```markdown
+**UX Design Artifacts:**
+- [Design Brief](../ux-design/{prefix}design-brief.md)
+- [Component Strategy](../ux-design/{prefix}component-strategy.md)
+{- [Layouts](../ux-design/{prefix}layouts.md)}
+{- [User Journeys](../ux-design/{prefix}user-journeys.md)}
+```
+
+**If epic already has UX Design section:**
+
+```
+Epic already has UX Design Artifacts section.
+
+Options:
+[U] Update - Replace with new links
+[M] Merge - Add new links to existing
+[K] Keep - Leave epic-level unchanged
+```
+
+---
+
+### 4. Prepare Story-Level Links
+
+For each story, determine if there's a matching design:
+
+**Matching logic:**
+- Check if `design.output_location` contains story-specific designs
+- For MagicPatterns: Check design registry from Step 3 for story-matched URLs
+- For other tools: Match by feature name similarity
+
+**Story-level UX Design format varies by tool:**
+
+**MagicPatterns:**
+```markdown
+**UX Design:**
+- **Prototype:** [Story Title]({magicpatterns_url})
+- **Components:** `ComponentA.tsx`, `ComponentB.tsx`
+```
+
+**SuperDesign:**
+```markdown
+**UX Design:**
+- **Prototype:** `.superdesign/design_iterations/{feature}/`
+- **Components:** shadcn `Button`, custom `FeatureCard`
+```
+
+**Direct Mapping (shadcn research):**
+```markdown
+**UX Design:**
+- **Components:** shadcn `Card`, shadcn `Form`, custom `UserCard`
+- **See:** [Component Strategy](../ux-design/{prefix}component-strategy.md)
+```
+
+**Wireframe:**
+```markdown
+**UX Design:**
+- **Wireframe:** See [Layouts](../ux-design/{prefix}layouts.md)
+- **Components:** shadcn `Card`, custom `WizardStep`
+```
+
+---
+
+### 5. Preview Changes
+
+Present all changes before applying:
+
+```
+PROPOSED CHANGES
+─────────────────────────────────────
+
+Epic: {Epic N: Title}
+File: {epic_file_path}
+
+EPIC-LEVEL (after Goal line):
++ **UX Design Artifacts:**
++ - [Design Brief](../ux-design/{prefix}design-brief.md)
++ - [Component Strategy](../ux-design/{prefix}component-strategy.md)
++ - [User Journeys](../ux-design/{prefix}user-journeys.md)
+
+STORY-LEVEL:
+○ Story {N.1}: {title}
+  + **UX Design:**
+  + - **Prototype:** [{title}]({url})
+  + - **Components:** `Component.tsx`
+
+○ Story {N.2}: {title}
+  (no matching design found - skipping)
+
+○ Story {N.3}: {title}
+  + **UX Design:**
+  + - **Prototype:** [{title}]({url})
+  + - **Components:** shadcn `Select`, `Preferences.tsx`
+
+─────────────────────────────────────
+
+Options:
+[A] Apply all - Add all UX references
+[E] Epic only - Only add epic-level section
+[S] Select - Choose which stories to update
+[X] Cancel - Return without changes
+```
+
+---
+
+### 6. Apply Changes
+
+**If user approves:**
+
+Execute targeted edits:
+
+1. **Epic-level:** Insert after the line containing `**Goal:**`
+   - Find: `**Goal:**.*\n`
+   - Insert after match: UX Design Artifacts section + blank line
+
+2. **Story-level:** Insert after `**Acceptance Criteria:**` section, before `---`
+   - Find: Story heading → Acceptance Criteria → last criterion line
+   - Insert before `---`: UX Design section + blank line
+
+**Use Edit tool for each change:**
+```
+Editing: {epic_file_path}
+- Adding epic-level UX references...
+- Adding Story {N.1} UX references...
+- Adding Story {N.3} UX references...
+```
+
+**After all edits:**
+```
+EPIC LINKING COMPLETE ✓
+
+Updated: {epic_file_path}
+
+Changes made:
+✓ Epic-level UX Design Artifacts section
+✓ Story {N.1} UX Design reference
+✓ Story {N.3} UX Design reference
+
+Stories skipped (no matching design):
+- Story {N.2}
+```
+
+---
+
+### 7. Return to Completion Menu
+
+```
+─────────────────────────────────────
+
+[L] Link more - Link to additional epics
+[N] New Design - Start another design session
+[D] Done - Exit workflow
+```
+
+**Menu Handlers:**
+- **L**: Restart from Section 1 (epic detection)
+- **N**: Load `./step-01-context.md`
+- **D**: Exit workflow
+
+---
+
+## EDGE CASE HANDLING
+
+### No Related Epic Found
+
+```
+No epic file found matching artifact prefix "{prefix}".
+
+This may happen when:
+- Design is for a feature without a defined epic
+- Artifact naming doesn't follow epic-{N}- pattern
+- Epic files are in a different location
+
+Options:
+[P] Provide path - Enter epic file path manually
+[C] Create reference - Just show the links to copy manually
+[S] Skip - Continue without linking
+```
+
+**If P:**
+- Prompt for epic file path
+- Validate file exists
+- Continue with linking flow
+
+**If C:**
+- Display formatted markdown sections for user to copy
+- Return to completion menu
+
+### Epic Already Has Complete UX Section
+
+```
+Epic {N} already has UX Design references:
+
+Epic-level: ✓ Present
+Stories with UX: 5/5
+
+Options:
+[R] Review current - Show existing UX sections
+[U] Update anyway - Replace with current design references
+[S] Skip - Keep existing references
+```
+
+### Multiple Epics Match
+
+If artifact prefix is ambiguous or design spans epics:
+
+```
+Multiple related epics detected:
+
+[1] Epic 2: Authentication Experience
+[2] Epic 3: User Onboarding & Welcome
+
+Select which to update (comma-separated, or A for all):
+```
+
+### Story-Design Mismatch
+
+When design doesn't map cleanly to stories:
+
+```
+DESIGN-TO-STORY MAPPING
+─────────────────────────────────────
+
+Design: {feature_name}
+Stories in Epic {N}: 7
+
+Auto-matched:
+✓ Story 3.1 → Onboarding Step 1 design
+✓ Story 3.3 → Preferences design
+
+Unmatched stories (manual mapping needed):
+? Story 3.2 - Feature Tour
+? Story 3.4 - Progress & Skip
+
+Unmatched designs:
+? Dashboard Welcome component
+
+Options:
+[M] Manual map - Match designs to stories manually
+[A] Auto only - Only link matched stories
+[S] Skip stories - Only add epic-level links
+```
+
+---
+
+## STATE TO CARRY FORWARD
+
+```yaml
+linking_result:
+  epic_file: "{path}"
+  epic_level_added: true
+  stories_linked: ["3.1", "3.3", "3.5"]
+  stories_skipped: ["3.2", "3.4"]
+```
+
+---
+
+## SUCCESS CRITERIA
+
+✅ Related epic file identified (or user provided path)
+✅ Changes previewed before applying
+✅ Epic-level UX Design Artifacts section added
+✅ Story-level UX Design sections added where applicable
+✅ Existing epic content preserved
+✅ Relative paths correct (`../ux-design/...`)

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

@@ -1,13 +1,19 @@
 # {feature_name} Component Strategy
 
+{magicpatterns_extraction_warning}
+
 ## Quick Reference
 
-### Installation Command
+### 1. Install shadcn Components
 
 ```bash
 npx shadcn@latest add {shadcn_components}
 ```
 
+### 2. Extract Code from MagicPatterns
+
+{extraction_table}
+
 ## Component Mapping
 
 | UI Element | Source | Component | Variant/Props | Notes |
@@ -26,6 +32,8 @@ npx shadcn@latest add {shadcn_components}
 
 {magicpatterns_section}
 
+{what_not_to_do_section}
+
 ## Implementation Notes
 
 {implementation_notes}

package/skills/designer-founder/templates/design-brief.md

@@ -11,7 +11,9 @@
 ## Prototype Location
 
 - **Tool:** {tool_used}
-- **File:** {output_location}
+- **Location:** {output_location}
+
+{tool_specific_notes}
 
 ## Visual Direction
 
@@ -21,6 +23,10 @@
 
 {inspiration_sources}
 
+## Implementation Source
+
+{implementation_source_section}
+
 ---
 
 *Generated by designer-founder workflow on {date}*

package/skills/designer-founder/templates/layouts.md

@@ -1,5 +1,7 @@
 # {feature_name} Layouts
 
+{layout_implementation_note}
+
 ## Desktop (lg: 1024px+)
 
 ```

package/skills/designer-founder/templates/user-journeys.md

@@ -15,6 +15,10 @@
 
 {journey_steps}
 
+### Implementation Sources
+
+{journey_implementation_sources}
+
 ## Alternative Flows
 
 {alternative_flows}

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

@@ -63,6 +63,36 @@ Parameters:
   imageUrls: [{inspiration_image_urls}]  // optional
 ```
 
+### 2.5 Handle Empty Response
+
+If `create_design` returns no URL or empty response:
+
+```
+DESIGN CREATION ISSUE
+
+The design may have been created but the URL wasn't returned.
+
+Options:
+[P] Paste URL - I'll provide the URL from MagicPatterns browser
+[R] Retry - Try creating the design again
+[S] Switch - Use a different design tool
+```
+
+**If P (Paste URL):**
+- 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 invalid, show error and return to options
+
+**If R (Retry):**
+- Re-execute step 2 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
 
 ```
@@ -191,3 +221,83 @@ Parameters:
 ```
 
 This is useful in the conversion step when the user chooses MagicPatterns for HTML→React conversion.
+
+---
+
+## Design Registry Pattern
+
+When creating multiple designs (e.g., auth flows with 6 screens), maintain a registry to track progress:
+
+### Registry Structure
+
+```yaml
+designs:
+  - name: "{scope_item_name}"
+    url: "{url_or_pending}"
+    status: [pending | created | approved]
+    files: [list from get_design]
+```
+
+### Progress Display
+
+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}
+{/foreach}
+
+Options:
+[N] Next - Create next pending design
+[R] Review - Review a specific design
+[C] Continue - Proceed to artifacts (if all approved)
+```
+
+### Batch Creation Flow
+
+When scope has multiple items:
+
+1. **Show scope overview:**
+   ```
+   DESIGNS TO CREATE ({count} items)
+
+   {foreach scope_item}
+   ○ {item_name}
+   {/foreach}
+
+   Options:
+   [O] One-by-one - Create and approve each design individually
+   [B] Batch - Create all designs, then review together
+   ```
+
+2. **If One-by-one:** Execute steps 1-4 for each item, updating registry after each
+
+3. **If Batch:**
+   - Create all designs (steps 1-3) without waiting for approval
+   - Present all designs for bulk review
+   - Allow individual updates before final approval
+
+### Registry State
+
+Store in workflow context:
+
+```yaml
+design_registry:
+  total_items: {count}
+  completed: {approved_count}
+  designs:
+    - name: "Sign In"
+      url: "https://magicpatterns.com/c/abc123"
+      status: approved
+      files: ["SignInForm.tsx", "styles.css"]
+    - name: "Sign Up"
+      url: "https://magicpatterns.com/c/def456"
+      status: created
+      files: ["SignUpForm.tsx"]
+    - name: "Forgot Password"
+      url: null
+      status: pending
+      files: []
+```