@torka/claude-workflows 0.10.0 → 0.12.0

package/.claude-plugin/plugin.json

@@ -34,6 +34,10 @@
     {
       "name": "agent-creator",
       "description": "Creates custom Claude Code sub-agents for project tasks"
+    },
+    {
+      "name": "product-architect",
+      "description": "Agent team that creates PRD + Architecture from product notes. PM and Architect collaborate, escalating only for key decisions."
     }
   ],
   "hooks": {

package/commands/dev-story-fullstack.md

@@ -41,11 +41,14 @@ Execute fullstack stories using a **hybrid approach** - applying design-first me
 
 ### 2.2 Optional MCPs (graceful degradation)
 
-| MCP | Purpose | Fallback |
-|-----|---------|----------|
+| MCP/Skill | Purpose | Fallback |
+|-----------|---------|----------|
 | Context7 | Library docs | Web search |
 | MagicPatterns | Design code fetch | Manual implementation |
+| Stitch | Design screen conversion | Manual implementation |
 | Serena | Codebase analysis | Manual Glob/Grep |
+| react-best-practices (skill) | React/Next.js performance | Standard implementation |
+| Stitch react-components (skill) | Converting Stitch designs to React code | Standard implementation |
 
 ### 2.3 Probe Execution
 
@@ -181,6 +184,7 @@ IF task type is UI:
 
 1. Design Analysis:
    - Check for MagicPatterns link
+   - Check for Stitch screen reference
    - Check for shadcn component mentions
    - Identify visual requirements
 
@@ -188,22 +192,32 @@ IF task type is UI:
    IF MagicPatterns link:
      - Fetch code via MCP
      - Adapt for project structure
+   IF Stitch screen :
+     * IF component already exists → Log: "using existing" → SKIP Stitch
+     * IF component NOT exists →
+         - Fetch via Stitch MCP
+         - Convert to React components using Stitch react-components skill
+         - Run validation scripts
    IF shadcn components:
      - ALWAYS call get_item_examples_from_registries FIRST
      - Review demo output
      - Implement with correct patterns
 
-3. Visual Validation:
+3. Apply Performance Patterns:
+   IF react-best-practices skill available:
+     - Apply skill guidance during implementation
+
+4. Visual Validation:
    - Navigate to affected page via Playwright
    - Take screenshot
    - Check console for errors
    - Fix and retry if issues (max 3 iterations)
 
-4. Add Tests (after visual validation):
+5. Add Tests (after visual validation):
    - E2E tests for user flows
    - Unit tests for component logic
 
-5. Run test suite and verify all pass
+6. Run test suite and verify all pass
 ```
 
 ### 6.3 Backend Task Execution (TDD)

package/commands/dev-story-ui.md

@@ -48,10 +48,13 @@ Scan story content (tasks, dev notes, acceptance criteria) for:
 
 ### 2.3 Optional MCPs (graceful degradation)
 
-| MCP | Purpose | Fallback |
-|-----|---------|----------|
+| MCP/Skill | Purpose | Fallback |
+|-----------|---------|----------|
 | Context7 | Library docs | Web search |
 | MagicPatterns | Design code fetch | Manual implementation from design |
+| Stitch | Design screen conversion | Manual implementation |
+| react-best-practices (skill) | React/Next.js performance | Standard implementation |
+| Stitch react-components (skill) | Converting Stitch designs to React code | Standard implementation |
 
 ### 2.4 Probe Execution
 
@@ -154,6 +157,7 @@ Dev Agent Record update:
 ```
 1. Extract design references from story:
    - MagicPatterns links
+   - Stitch screen references
    - Figma links
    - Screenshot paths
    - Component specifications in Dev Notes
@@ -162,16 +166,31 @@ Dev Agent Record update:
    - CRITICAL: Fetch code via MCP (NEVER build from scratch)
    - Adapt for project structure
 
-3. IF shadcn components needed:
+2. IF Stitch screen reference (stitch.new or stitch: prefix):
+   - Extract target component name from reference
+   - CHECK IF COMPONENT EXISTS:
+     * Look for: .stitch/{ComponentName}.tsx  
+     * Look for: src/components/{ComponentName}.tsx
+     * Look for: src/app/**/components/{ComponentName}.tsx
+   - IF component exists:
+     * Log: "Component {name} already exists - using existing"
+     * SKIP Stitch fetch
+   - IF component NOT exists AND Stitch MCP available:
+     * Fetch via Stitch MCP
+     * Run validation: npm run validate <file_path>
+   - IF Stitch MCP unavailable:
+     * Log: "Stitch MCP not configured - manual implementation"
+
+4. IF shadcn components needed:
    - Call mcp__shadcn__search_items_in_registries for relevant components
    - Note component names for implementation
 
-4. Document design decisions:
+5. Document design decisions:
    - Components to use
    - Styling approach
    - Layout patterns
 
-5. Log design analysis in Dev Agent Record
+6. Log design analysis in Dev Agent Record
 ```
 
 ---
@@ -214,6 +233,10 @@ IF using shadcn components:
 3. Use semantic HTML
 4. Apply consistent styling (Tailwind classes)
 5. Ensure accessibility basics (alt text, labels, ARIA)
+
+IF react-best-practices skill available:
+  - Apply skill guidance during implementation
+  - The skill provides built-in priority and "when to use" guidance
 ```
 
 ---

package/install.js

@@ -13,6 +13,11 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 
+// Files that should not be overwritten if user has customized them
+const PROTECTED_FILES = [
+  'vt-preferences.md',
+];
+
 // ANSI colors for output
 const colors = {
   green: '\x1b[32m',
@@ -44,6 +49,10 @@ function logSkip(message) {
   log(`  ○ ${message}`, 'yellow');
 }
 
+function logPreserve(message) {
+  log(`  ★ ${message}`, 'yellow');
+}
+
 function logError(message) {
   log(`  ✗ ${message}`, 'red');
 }
@@ -137,6 +146,13 @@ function copyDirRecursive(src, dest, stats) {
       copyDirRecursive(srcPath, destPath, stats);
     } else {
       if (fs.existsSync(destPath)) {
+        // Check if this is a protected user config file
+        if (PROTECTED_FILES.includes(entry.name)) {
+          stats.preserved.push(destPath);
+          logPreserve(`Preserved (user config): ${path.relative(stats.targetBase, destPath)}`);
+          continue;
+        }
+
         // File exists - check if content differs
         const srcContent = fs.readFileSync(srcPath);
         const destContent = fs.readFileSync(destPath);
@@ -198,6 +214,7 @@ function install() {
     'agents/desk-check-gate.md',
     'skills/agent-creator/',
     'skills/designer-founder/',
+    'skills/product-architect/',
     '*.backup',
   ];
   const addedCount = ensureGitignoreEntries(
@@ -214,6 +231,7 @@ function install() {
     updated: [],
     unchanged: [],
     backups: [],
+    preserved: [],
     targetBase,
   };
 
@@ -264,6 +282,7 @@ function install() {
     const bmadOutputGitignorePath = path.join(bmadOutputDir, '.gitignore');
     const bmadOutputEntries = [
       'epic-executions/',
+      'screenshots/',
     ];
     const outputAdded = ensureGitignoreEntries(
       bmadOutputGitignorePath,
@@ -280,6 +299,9 @@ function install() {
   log(`   Files copied (new): ${stats.copied.length}`, 'green');
   log(`   Files updated: ${stats.updated.length}`, 'cyan');
   log(`   Files unchanged: ${stats.unchanged.length}`, 'yellow');
+  if (stats.preserved.length > 0) {
+    log(`   Files preserved: ${stats.preserved.length} (user config)`, 'yellow');
+  }
   if (stats.backups.length > 0) {
     log(`   Backups created: ${stats.backups.length} (*.backup files)`, 'yellow');
   }
@@ -288,7 +310,8 @@ function install() {
   log('\n' + colors.bold + '📝 Next Steps' + colors.reset);
   log('   1. Run /git-cleanup-and-merge or /plan-parallelization to test');
   log('   2. Try /designer-founder for UI/UX design workflows');
-  log('   3. Use /dev-story-ui, /dev-story-backend, or /dev-story-fullstack for story execution\n');
+  log('   3. Try /product-architect for autonomous PRD + Architecture (requires Agent Teams)');
+  log('   4. Use /dev-story-ui, /dev-story-backend, or /dev-story-fullstack for story execution\n');
 
   // Note about BMAD dependencies
   log(colors.yellow + '⚠️  Note: Some components work better with BMAD Method installed:' + colors.reset);
@@ -301,12 +324,112 @@ function install() {
   log('   ✓ dev-story-ui, dev-story-backend, dev-story-fullstack');
   log('   ✓ agent-creator skill (with expertise profiles)');
   log('   ✓ designer-founder skill');
+  log('   ✓ product-architect skill (requires Agent Teams + BMAD)');
   log('   ✓ desk-check-gate agent\n');
 }
 
+/**
+ * Auto-install Vercel react-best-practices skill for performance optimization
+ * Provides 57 React/Next.js performance rules with built-in guidance
+ */
+async function installReactBestPractices(isGlobal) {
+  const { execSync } = require('child_process');
+
+  log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+  log(colors.bold + '  REACT BEST PRACTICES SETUP' + colors.reset);
+  log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+  log('\nInstalling Vercel react-best-practices skill (57 performance rules)...\n');
+
+  const globalFlag = isGlobal ? ' -g' : '';
+  const execOptions = {
+    stdio: 'inherit',
+    timeout: 90000,
+    cwd: isGlobal ? undefined : (process.env.INIT_CWD || process.cwd()),
+  };
+
+  try {
+    execSync(`npx skills add vercel-labs/agent-skills --skill react-best-practices${globalFlag} -a claude-code -y`, execOptions);
+
+    log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+    log(colors.green + colors.bold + '  ✓ REACT BEST PRACTICES INSTALLED' + colors.reset);
+    log('');
+    log('  The skill provides guidance for:');
+    log('  - Eliminating waterfalls (CRITICAL)');
+    log('  - Bundle size optimization (CRITICAL)');
+    log('  - Server-side performance (HIGH)');
+    log('  - Re-render optimization (MEDIUM)');
+    log('');
+    log('  To update: npx skills update');
+    log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset + '\n');
+
+  } catch (error) {
+    log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+    log(colors.yellow + colors.bold + '  ⚠ REACT BEST PRACTICES INSTALLATION SKIPPED' + colors.reset);
+    log('');
+    log('  To install manually:');
+    log('  npx skills add vercel-labs/agent-skills --skill react-best-practices -g -a claude-code');
+    log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset + '\n');
+  }
+}
+
+/**
+ * Auto-install Google's stitch-skills for Stitch integration
+ * These skills enhance the designer-founder workflow with Stitch support
+ */
+async function installStitchSkills(isGlobal) {
+  const { execSync } = require('child_process');
+
+  log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+  log(colors.bold + '  STITCH INTEGRATION SETUP' + colors.reset);
+  log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+  log('\nInstalling Google stitch-skills for Stitch design tool...\n');
+
+  const globalFlag = isGlobal ? ' -g' : '';
+  const execOptions = {
+    stdio: 'inherit',
+    timeout: 60000,
+    cwd: isGlobal ? undefined : (process.env.INIT_CWD || process.cwd()),
+  };
+
+  try {
+    // Install design-md skill (required for Stitch)
+    execSync(`npx skills add google-labs-code/stitch-skills --skill design-md${globalFlag} -a claude-code -y`, execOptions);
+
+    // Install react-components skill (for HTML→React conversion)
+    execSync(`npx skills add google-labs-code/stitch-skills --skill react-components${globalFlag} -a claude-code -y`, execOptions);
+
+    log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+    log(colors.green + colors.bold + '  ✓ STITCH SKILLS INSTALLED SUCCESSFULLY' + colors.reset);
+    log('');
+    log('  To use Stitch in designer-founder workflow:');
+    log('  1. Configure Stitch MCP server');
+    log('  2. Run /designer-founder and select [T] Stitch');
+    log('');
+    log('  To update skills later: npx skills update');
+    log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset + '\n');
+
+  } catch (error) {
+    log('\n' + colors.bold + '════════════════════════════════════════════════════════════' + colors.reset);
+    log(colors.yellow + colors.bold + '  ⚠ STITCH SKILLS INSTALLATION SKIPPED' + colors.reset);
+    log('');
+    log('  Could not auto-install stitch-skills.');
+    log('  This may be due to network issues or missing dependencies.');
+    log('');
+    log('  To install manually later:');
+    log('  npx skills add google-labs-code/stitch-skills -g -a claude-code');
+    log('');
+    log('  You can still use other design tools (SuperDesign, MagicPatterns).');
+    log(colors.bold + '════════════════════════════════════════════════════════════' + colors.reset + '\n');
+  }
+}
+
 // Run installation
 try {
+  const isGlobal = process.env.npm_config_global === 'true';
   install();
+  // Attempt to install external skills (non-blocking)
+  installReactBestPractices(isGlobal);
+  installStitchSkills(isGlobal);
 } catch (error) {
   logError(`Installation failed: ${error.message}`);
   // Don't exit with error code - allow npm install to complete

package/package.json

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

package/skills/designer-founder/SKILL.md

@@ -73,6 +73,8 @@ MagicPatterns MCP: [check if mcp__magicpatterns tools available]
 shadcn MCP: [check if mcp__shadcn tools available]
 Playwright MCP: [check if mcp__playwright tools available]
 SuperDesign: [check if .superdesign/ folder and instructions exist]
+Stitch MCP: [check if mcp__stitch* or stitch* tools available]
+Stitch Skills: [check if design-md skill installed via `npx skills list`]
 ```
 
 Adjust tool menus based on availability. Tools marked as unavailable should show "(not configured)" in menus.

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

@@ -41,6 +41,11 @@ Choose your design approach:
     → Quick HTML/CSS prototypes via VS Code
     → Best for: Rapid visual exploration, custom styling
 
+[T] Stitch (Google AI Design) {show availability status}
+    → AI-generated complete page designs
+    → Best for: Full page layouts, design system consistency
+    → Requires: Stitch MCP + Google's stitch-skills installed
+
 [M] MagicPatterns {show availability status}
     → AI-generated React components
     → Best for: Direct React code, component variations
@@ -53,7 +58,7 @@ Choose your design approach:
     → Skip visuals, map directly to shadcn
     → Best for: Standard patterns, known layouts
 
-Which approach? [S/M/W/D]
+Which approach? [S/T/M/W/D]
 ```
 
 ---
@@ -65,6 +70,7 @@ Based on user selection, load the corresponding tool file:
 | Selection | Tool File |
 |-----------|-----------|
 | S | `{installed_path}/tools/superdesign.md` |
+| T | `{installed_path}/tools/stitch.md` |
 | M | `{installed_path}/tools/magicpatterns.md` |
 | W | `{installed_path}/tools/wireframe.md` |
 | D | `{installed_path}/tools/direct-mapping.md` |

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

@@ -30,7 +30,7 @@ Convert design output to dev-ready artifacts and save to `{planning_artifacts}/u
 
 ### 1. Conversion (if needed)
 
-**If `design.needs_conversion` = true (SuperDesign or Wireframe):**
+**If `design.needs_conversion` = true (SuperDesign, Stitch, or Wireframe):**
 
 Load and execute: `{installed_path}/tools/conversion.md`
 
@@ -119,6 +119,8 @@ Populate 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."
+  - **Stitch (with react-components):** "React/TypeScript components generated via Google's react-components skill. AST-validated, includes hooks extraction and data decoupling."
+  - **Stitch (quick mapping):** "HTML/CSS prototype converted via shadcn component mapping."
   - **Wireframe:** "Structure reference only. Build components from scratch."
   - **Direct:** "Component mapping provided. No visual prototype created."
 

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

@@ -0,0 +1,180 @@
+# Design System: {project_name}
+
+**Stitch Project ID:** {stitch_project_id}
+**Generated:** {date}
+**Last Updated:** {date}
+
+---
+
+## 1. Visual Theme & Atmosphere
+
+### Overall Feel
+{describe the overall visual feel - e.g., "Modern and minimalist with soft edges and subtle depth"}
+
+### Design Principles
+- {principle_1}
+- {principle_2}
+- {principle_3}
+
+---
+
+## 2. Color Palette & Roles
+
+### Primary Colors
+| Name | Value | Usage |
+|------|-------|-------|
+| Primary | `{color}` | Main CTAs, active states |
+| Primary Hover | `{color}` | Hover state for primary |
+| Primary Foreground | `{color}` | Text on primary backgrounds |
+
+### Secondary Colors
+| Name | Value | Usage |
+|------|-------|-------|
+| Secondary | `{color}` | Secondary actions |
+| Secondary Hover | `{color}` | Hover state for secondary |
+| Secondary Foreground | `{color}` | Text on secondary backgrounds |
+
+### Neutral Colors
+| Name | Value | Usage |
+|------|-------|-------|
+| Background | `{color}` | Page background |
+| Foreground | `{color}` | Primary text |
+| Muted | `{color}` | Subtle backgrounds |
+| Muted Foreground | `{color}` | Secondary text |
+| Border | `{color}` | Borders and dividers |
+
+### Semantic Colors
+| Name | Value | Usage |
+|------|-------|-------|
+| Destructive | `{color}` | Errors, delete actions |
+| Success | `{color}` | Success states |
+| Warning | `{color}` | Warning states |
+
+### Dark Mode Variants
+{if dark_mode_supported}
+| Light Mode | Dark Mode | Usage |
+|------------|-----------|-------|
+| `{light}` | `{dark}` | Background |
+| `{light}` | `{dark}` | Foreground |
+{/if}
+
+---
+
+## 3. Typography Rules
+
+### Font Family
+- **Sans:** `{font_family}` (e.g., Inter, system-ui)
+- **Mono:** `{mono_family}` (e.g., JetBrains Mono, monospace)
+
+### Scale
+| Name | Size | Weight | Line Height | Usage |
+|------|------|--------|-------------|-------|
+| H1 | `{size}` | `{weight}` | `{lh}` | Page titles |
+| H2 | `{size}` | `{weight}` | `{lh}` | Section headers |
+| H3 | `{size}` | `{weight}` | `{lh}` | Subsections |
+| Body | `{size}` | `{weight}` | `{lh}` | Default text |
+| Small | `{size}` | `{weight}` | `{lh}` | Captions, labels |
+
+### Text Colors
+- Primary: `foreground`
+- Secondary: `muted-foreground`
+- Links: `primary`
+- Disabled: `muted-foreground` with 50% opacity
+
+---
+
+## 4. Component Stylings
+
+### Buttons
+| Variant | Background | Text | Border | Hover |
+|---------|------------|------|--------|-------|
+| Default | `primary` | `primary-foreground` | none | `primary/90` |
+| Secondary | `secondary` | `secondary-foreground` | none | `secondary/80` |
+| Outline | transparent | `foreground` | `border` | `muted` |
+| Ghost | transparent | `foreground` | none | `muted` |
+| Destructive | `destructive` | `destructive-foreground` | none | `destructive/90` |
+
+### Border Radius
+| Element | Radius |
+|---------|--------|
+| Buttons | `{radius}` |
+| Cards | `{radius}` |
+| Inputs | `{radius}` |
+| Modals | `{radius}` |
+
+### Shadows
+| Name | Value | Usage |
+|------|-------|-------|
+| sm | `{shadow}` | Subtle elevation |
+| md | `{shadow}` | Cards, dropdowns |
+| lg | `{shadow}` | Modals, popovers |
+
+### Spacing Scale
+Base unit: `{base}` (e.g., 4px)
+
+| Name | Value | Usage |
+|------|-------|-------|
+| xs | `{value}` | Tight spacing |
+| sm | `{value}` | Compact elements |
+| md | `{value}` | Default spacing |
+| lg | `{value}` | Section spacing |
+| xl | `{value}` | Large gaps |
+
+---
+
+## 5. Layout Principles
+
+### Grid System
+- **Container max-width:** `{width}` (e.g., 1280px)
+- **Columns:** {columns} (e.g., 12)
+- **Gutter:** `{gutter}` (e.g., 24px)
+
+### Breakpoints
+| Name | Width | Notes |
+|------|-------|-------|
+| sm | `{width}` | Mobile landscape |
+| md | `{width}` | Tablet |
+| lg | `{width}` | Desktop |
+| xl | `{width}` | Large desktop |
+
+### Content Widths
+- **Prose:** max-width `{width}` for readable text
+- **Forms:** max-width `{width}` for form containers
+- **Full:** 100% width containers
+
+---
+
+## 6. Animation & Motion
+
+### Transitions
+| Property | Duration | Easing |
+|----------|----------|--------|
+| Colors | `{duration}` | `{easing}` |
+| Transform | `{duration}` | `{easing}` |
+| Opacity | `{duration}` | `{easing}` |
+
+### Micro-interactions
+- **Hover:** {describe hover behavior}
+- **Focus:** {describe focus behavior}
+- **Active:** {describe active state}
+
+---
+
+## Notes for Stitch
+
+When generating screens with Stitch, reference this document to maintain consistency:
+
+1. **Include design system context** in prompts
+2. **Reference color names** (e.g., "primary", "muted") not hex values
+3. **Use typography scale names** for consistent sizing
+4. **Apply spacing scale** for consistent rhythm
+
+### Example Stitch Prompt Addition
+
+```
+Use the design system:
+- Primary color for CTAs
+- Border radius: {radius}
+- Font: {font_family}
+- Spacing: 4px base unit
+```