@torka/claude-workflows 0.1.0 → 0.3.0

package/skills/designer-founder/steps/step-02-scope.md

@@ -0,0 +1,198 @@
+# Step 2: Scope & Inspiration
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER proceed without clear scope confirmation
+- 📖 CRITICAL: Pull relevant context from existing artifacts
+- ✅ ALWAYS confirm scope before design phase
+- 🎯 Goal: Define exactly what to design and gather visual references
+
+---
+
+## CONTEXT FROM PREVIOUS STEP
+
+You should have:
+- `mode`: production (otherwise this step is skipped)
+- `user_intent`: What user wants to design
+- `project_state`: greenfield or existing
+- `related_artifacts`: List of relevant files
+
+---
+
+## YOUR TASK
+
+Define the specific scope of design work and optionally gather visual inspiration.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Pull Existing Context (if available)
+
+**If existing project with artifacts:**
+
+Read relevant files to understand:
+- Existing design decisions (from UX specs)
+- Related user stories (from epics)
+- Current component patterns (from component inventory)
+- Design tokens already defined
+
+Present summary:
+```
+EXISTING CONTEXT
+
+From UX Specification:
+- [Key design decisions relevant to this work]
+
+From Epic/Stories:
+- [Related stories and their requirements]
+
+Current Design System:
+- Theme: [dark/light/both]
+- Primary components: [list]
+- Patterns established: [list]
+```
+
+**If greenfield:**
+```
+GREENFIELD PROJECT
+
+No existing design specs found. This design work will help establish:
+- Visual direction
+- Component patterns
+- Design tokens foundation
+```
+
+---
+
+### 2. Define Scope
+
+Based on user intent and context, propose specific scope:
+
+```
+PROPOSED SCOPE
+
+Based on "{user_intent}", here's what I recommend designing:
+
+1. [Specific page/flow/component]
+   - [What it needs to accomplish]
+   - [Key elements to include]
+
+2. [Another item if multi-part]
+   - [Details]
+
+Estimated outputs:
+- [ ] Design prototype ([tool])
+- [ ] Component strategy
+- [ ] Page layouts
+- [ ] User journey (if multi-step)
+```
+
+Ask for confirmation:
+```
+Does this scope look right? Want to add or remove anything?
+```
+
+---
+
+### 3. Gather Inspiration (Optional)
+
+After scope is confirmed, offer inspiration gathering:
+
+```
+INSPIRATION (Optional)
+
+Would you like to gather visual references before designing?
+
+[Y] Yes - I'll search for relevant examples
+[N] No - Let's proceed with design
+[U] I have URLs - I'll share specific references
+```
+
+**If Y (search for inspiration):**
+- Use web search to find 2-3 relevant design examples
+- Focus on the specific UI pattern being designed
+- Present findings with brief analysis:
+  ```
+  INSPIRATION FOUND
+
+  1. [Source/Company] - [URL if available]
+     What works: [specific element]
+     Relevant for: [how it applies to our design]
+
+  2. [Another example]
+     ...
+  ```
+
+**If U (user has URLs):**
+- Accept user's reference URLs
+- If Playwright available, offer to screenshot them
+- Note key elements to incorporate
+
+**If N:**
+- Proceed directly to design
+
+---
+
+### 4. Confirm Design Direction
+
+Summarize before proceeding:
+
+```
+DESIGN BRIEF
+
+Scope: [confirmed scope items]
+
+Inspiration:
+- [References gathered, or "None - proceeding with library defaults"]
+
+Design approach:
+- Primary tool: [based on availability and scope]
+- Target: [what we're creating]
+
+Ready to proceed to design phase.
+```
+
+---
+
+## COLLABORATION MENU
+
+```
+[A] Advanced - Deeper exploration of requirements
+[P] Party Mode - Get perspectives from PM, Dev, UX agents
+[C] Continue - Proceed to design phase
+```
+
+**Menu Handlers:**
+- **A**: Explore requirements more deeply, ask clarifying questions
+- **P**: Load party mode for multi-agent input on design direction
+- **C**: Proceed to Step 3
+
+---
+
+## STATE TO CARRY FORWARD
+
+Add to working memory:
+
+```yaml
+scope:
+  items:
+    - name: "[item 1]"
+      description: "[what it accomplishes]"
+      type: [page | flow | component]
+    - name: "[item 2]"
+      ...
+inspiration:
+  - source: "[name]"
+    url: "[url if available]"
+    takeaway: "[what to incorporate]"
+design_direction: "[summary of approach]"
+```
+
+---
+
+## NEXT STEP
+
+When user selects [C], load `./step-03-design.md`
+
+Remember: Do NOT proceed until user explicitly selects [C]

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

@@ -0,0 +1,168 @@
+# Step 3: Design Execution
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER proceed without user confirmation at each design iteration
+- 📖 CRITICAL: Load the appropriate tool file for detailed execution
+- ✅ ALWAYS show design results for review before moving on
+- 🎯 Goal: Create visual prototype using user's preferred tool
+
+---
+
+## CONTEXT FROM PREVIOUS STEPS
+
+You should have:
+- `mode`: quick_prototype or production
+- `user_intent`: What to design
+- `scope`: Specific items to design (if production mode)
+- `inspiration`: Visual references (if gathered)
+- `tools_available`: Which tools are configured
+
+---
+
+## YOUR TASK
+
+Execute design using the user's preferred tool, iterate until satisfied.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Present Tool Selection
+
+Based on available tools, present options:
+
+```
+DESIGN TOOL SELECTION
+
+Choose your design approach:
+
+[S] SuperDesign
+    → Quick HTML/CSS prototypes via VS Code
+    → Best for: Rapid visual exploration, custom styling
+
+[M] MagicPatterns {show availability status}
+    → AI-generated React components
+    → Best for: Direct React code, component variations
+
+[W] Wireframe Only
+    → ASCII or Excalidraw sketch
+    → Best for: Structure-first, discussing layout
+
+[D] Direct to Components
+    → Skip visuals, map directly to shadcn
+    → Best for: Standard patterns, known layouts
+
+Which approach? [S/M/W/D]
+```
+
+---
+
+### 2. Load Tool Execution File
+
+Based on user selection, load the corresponding tool file:
+
+| Selection | Tool File |
+|-----------|-----------|
+| S | `{installed_path}/tools/superdesign.md` |
+| M | `{installed_path}/tools/magicpatterns.md` |
+| W | `{installed_path}/tools/wireframe.md` |
+| D | `{installed_path}/tools/direct-mapping.md` |
+
+**CRITICAL:** Read the ENTIRE tool file and follow its instructions exactly.
+
+Pass context to tool execution:
+- `user_intent`
+- `scope` (if available)
+- `inspiration` (if gathered)
+
+---
+
+### 3. Tool Execution
+
+Execute the loaded tool file completely:
+- Follow all steps in the tool file
+- Handle user interactions as specified
+- Collect output state as defined in tool file
+
+---
+
+### 4. Offer Playwright Verification (Optional)
+
+If Playwright MCP is available AND user created a visual prototype (SuperDesign or MagicPatterns):
+
+```
+VISUAL VERIFICATION (Optional)
+
+Would you like me to capture screenshots of your design?
+
+[Y] Yes - Take screenshots (desktop + mobile)
+[N] No - Skip verification
+```
+
+If Y:
+- Use Playwright to navigate to design
+- Capture desktop screenshot
+- Resize viewport (375px width) and capture mobile screenshot
+- Present screenshots for review
+
+---
+
+### 5. Confirm Design Completion
+
+After tool execution completes:
+
+```
+DESIGN COMPLETE
+
+Tool used: {design.tool_used}
+Output: {design.output_location}
+```
+
+**If Quick Prototype mode:**
+```
+Prototype complete! Would you like to:
+
+[P] Production - Convert to dev-ready artifacts
+[D] Done - End workflow here
+```
+
+**If Production mode:**
+```
+Ready to create dev handover artifacts.
+```
+
+---
+
+## COLLABORATION MENU
+
+```
+[A] Advanced - Explore design alternatives
+[P] Party Mode - Get feedback from multiple perspectives
+[C] Continue - Proceed to next step
+```
+
+---
+
+## STATE AFTER COMPLETION
+
+Should have from tool execution:
+
+```yaml
+design:
+  tool_used: [superdesign | magicpatterns | wireframe | direct]
+  output_location: "{path or URL}"
+  output_format: [html | react | ascii | mapping]
+  needs_conversion: [true | false]
+  # Plus tool-specific state (components, code, etc.)
+```
+
+---
+
+## NEXT STEP
+
+- If `mode` = `quick_prototype` AND user selects [D]: End workflow
+- If `mode` = `quick_prototype` AND user selects [P]: Load `./step-04-artifacts.md`
+- If `mode` = `production` AND user selects [C]: Load `./step-04-artifacts.md`
+
+Remember: Do NOT proceed until user explicitly confirms.

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

@@ -0,0 +1,292 @@
+# Step 4: Convert & Create Artifacts
+
+## MANDATORY EXECUTION RULES (READ FIRST)
+
+- 🛑 NEVER generate artifacts without user approval of content
+- 📖 CRITICAL: Use templates from `{installed_path}/templates/`
+- ✅ ALWAYS create artifacts in the designated output folder
+- 🎯 Goal: Transform design into dev-ready documentation
+
+---
+
+## CONTEXT FROM PREVIOUS STEPS
+
+You should have:
+- `mode`: production (or quick_prototype converting to production)
+- `scope`: What was designed
+- `design.tool_used`: Which tool created the design
+- `design.output_location`: Where the design lives
+- `design.needs_conversion`: Whether HTML→React conversion is needed
+
+---
+
+## YOUR TASK
+
+Convert design output to dev-ready artifacts and save to `{planning_artifacts}/ux-design/`.
+
+---
+
+## TASK SEQUENCE
+
+### 1. Conversion (if needed)
+
+**If `design.needs_conversion` = true (SuperDesign or Wireframe):**
+
+Load and execute: `{installed_path}/tools/conversion.md`
+
+This handles HTML→React conversion with strategies:
+- Component Mapping (shadcn)
+- MagicPatterns Conversion
+- Hybrid
+
+**If `design.needs_conversion` = false (MagicPatterns or Direct):**
+
+Skip conversion, proceed to artifact generation.
+
+---
+
+### 2. Prepare Artifact Data
+
+Collect all data needed for templates:
+
+```yaml
+artifact_data:
+  feature_name: "{from scope or user_intent}"
+  date: "{current date}"
+
+  # From design phase
+  tool_used: "{design.tool_used}"
+  output_location: "{design.output_location}"
+
+  # From conversion (if applicable)
+  shadcn_components: [list]
+  custom_components: [list]
+  install_command: "{npx shadcn command}"
+
+  # Design details
+  visual_direction: "{from inspiration/scope}"
+  inspiration_sources: [list]
+```
+
+---
+
+### 3. Determine Artifacts to Create
+
+Based on scope and design:
+
+```
+ARTIFACTS TO GENERATE
+
+Required:
+✓ Design Brief - Overview and decisions
+✓ Component Strategy - What to install and build
+
+Conditional:
+{✓/✗} Layouts - {if page/screen design, not just component}
+{✓/✗} User Journeys - {if multi-step flow}
+
+Output folder: {planning_artifacts}/ux-design/
+File prefix: {feature_name_kebab_case}-
+```
+
+Confirm with user:
+```
+Generate these artifacts? [Y/N]
+```
+
+---
+
+### 4. Generate Artifacts
+
+For each artifact, load template and populate:
+
+#### Design Brief
+
+**Template:** `{installed_path}/templates/design-brief.md`
+
+Populate placeholders:
+- `{feature_name}` → Scope item name
+- `{overview_description}` → What was designed and why
+- `{design_decisions}` → Key choices made
+- `{tool_used}` → Design tool
+- `{output_location}` → Prototype location
+- `{visual_direction}` → Style notes
+- `{inspiration_sources}` → References used
+- `{date}` → Current date
+
+**Save to:** `{planning_artifacts}/ux-design/{prefix}design-brief.md`
+
+---
+
+#### Component Strategy
+
+**Template:** `{installed_path}/templates/component-strategy.md`
+
+Populate placeholders:
+- `{feature_name}` → Scope item name
+- `{shadcn_components}` → Installation command components
+- `{component_mapping_rows}` → Table rows of element→component mapping
+- `{shadcn_component_details}` → Details for each shadcn component
+- `{custom_component_details}` → Build approach for custom components
+- `{magicpatterns_section}` → URLs and extraction instructions (if used)
+- `{implementation_notes}` → Any special considerations
+- `{date}` → Current date
+
+**Save to:** `{planning_artifacts}/ux-design/{prefix}component-strategy.md`
+
+---
+
+#### Layouts (if applicable)
+
+**Template:** `{installed_path}/templates/layouts.md`
+
+Only generate if designing pages/screens (not standalone components).
+
+Populate placeholders:
+- `{feature_name}` → Scope item name
+- `{desktop_layout_ascii}` → Desktop wireframe
+- `{desktop_notes}` → Layout notes
+- `{tablet_layout_ascii}` → Tablet wireframe
+- `{tablet_changes}` → What changes
+- `{mobile_layout_ascii}` → Mobile wireframe
+- `{mobile_changes}` → What changes
+- `{responsive_summary_rows}` → Table of element behavior
+- `{date}` → Current date
+
+**Save to:** `{planning_artifacts}/ux-design/{prefix}layouts.md`
+
+---
+
+#### User Journeys (if applicable)
+
+**Template:** `{installed_path}/templates/user-journeys.md`
+
+Only generate if multi-step flow (wizard, checkout, onboarding, etc.).
+
+Populate placeholders:
+- `{feature_name}` → Scope item name
+- `{journey_name}` → Name of the flow
+- `{journey_trigger}` → What starts the journey
+- `{journey_goal}` → What user accomplishes
+- `{mermaid_flowchart}` → Flow diagram in Mermaid syntax
+- `{journey_steps}` → Detailed step descriptions
+- `{alternative_flows}` → Other paths
+- `{edge_cases}` → Edge case handling
+- `{error_states}` → Error handling
+- `{date}` → Current date
+
+**Save to:** `{planning_artifacts}/ux-design/{prefix}user-journeys.md`
+
+---
+
+### 5. Present Artifacts for Review
+
+```
+ARTIFACTS CREATED
+
+Location: {planning_artifacts}/ux-design/
+
+Files:
+✓ {prefix}design-brief.md
+✓ {prefix}component-strategy.md
+{✓ {prefix}layouts.md}
+{✓ {prefix}user-journeys.md}
+
+Options:
+[R] Review - Show artifact contents
+[E] Edit - Make changes to an artifact
+[C] Complete - Finalize workflow
+```
+
+**If R (Review):**
+- Ask which artifact to show
+- Display contents
+- Return to options
+
+**If E (Edit):**
+- Ask which artifact and what changes
+- Update the file
+- Return to options
+
+---
+
+### 6. Workflow Complete
+
+```
+DESIGN WORKFLOW COMPLETE ✓
+
+Summary:
+─────────────────────────────────────
+Mode: {mode}
+Tool: {design.tool_used}
+Prototype: {design.output_location}
+
+Artifacts:
+{list of created files with paths}
+
+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
+```
+
+---
+
+## OUTPUT FOLDER MANAGEMENT
+
+**If folder doesn't exist:**
+- Create `{planning_artifacts}/ux-design/`
+
+**If files already exist:**
+```
+Files already exist:
+- {existing_file_1}
+- {existing_file_2}
+
+Options:
+[O] Overwrite - Replace existing files
+[V] Version - Create {prefix}v2-*.md files
+[M] Merge - Add to existing files with changelog
+```
+
+**If Merge selected:**
+- Append new content with section header:
+  ```markdown
+  ---
+
+  ## Update: {date}
+
+  {new_content}
+  ```
+
+---
+
+## COLLABORATION MENU
+
+```
+[A] Advanced - Refine artifacts further
+[P] Party Mode - Get dev/PM review of artifacts
+[C] Complete - Finish workflow
+```
+
+---
+
+## SUCCESS CRITERIA
+
+✅ Design converted to component mapping (if needed)
+✅ All applicable artifacts created
+✅ Files saved to correct location
+✅ shadcn installation command provided
+✅ Custom components identified with build approach

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

@@ -0,0 +1,35 @@
+# {feature_name} Component Strategy
+
+## Quick Reference
+
+### Installation Command
+
+```bash
+npx shadcn@latest add {shadcn_components}
+```
+
+## Component Mapping
+
+| UI Element | Source | Component | Variant/Props | Notes |
+|------------|--------|-----------|---------------|-------|
+{component_mapping_rows}
+
+## shadcn Components
+
+{shadcn_component_details}
+
+## Custom Components
+
+{custom_component_details}
+
+## MagicPatterns Designs
+
+{magicpatterns_section}
+
+## Implementation Notes
+
+{implementation_notes}
+
+---
+
+*Generated by designer-founder workflow on {date}*

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

@@ -0,0 +1,26 @@
+# {feature_name} Design Brief
+
+## Overview
+
+{overview_description}
+
+## Design Decisions
+
+{design_decisions}
+
+## Prototype Location
+
+- **Tool:** {tool_used}
+- **File:** {output_location}
+
+## Visual Direction
+
+{visual_direction}
+
+## Inspiration Sources
+
+{inspiration_sources}
+
+---
+
+*Generated by designer-founder workflow on {date}*