wogiflow 1.0.21 → 1.0.22

package/.claude/skills/figma-analyzer/knowledge/anti-patterns.md

@@ -0,0 +1,216 @@
+# Figma Analyzer Anti-Patterns
+
+Patterns to avoid when analyzing Figma designs and generating code.
+
+---
+
+## Analysis Anti-Patterns
+
+### Anti-Pattern: Regenerating Existing Components
+
+**Bad**:
+```
+Figma shows a "Button" → Generate new Button.tsx
+```
+
+**Good**:
+```
+Figma shows a "Button" → Check registry → Match to existing Button.tsx → Reuse or add variant
+```
+
+**Why it's bad**: Creates duplicate components, fragments design system, increases maintenance burden
+
+---
+
+### Anti-Pattern: Top-Down Monolithic Analysis
+
+**Bad**:
+```
+Analyze entire screen as one component → Generate single ScreenComponent.tsx
+```
+
+**Good**:
+```
+Break down: Screen → Organisms → Molecules → Atoms
+Match each level independently
+```
+
+**Why it's bad**: Misses reuse opportunities, creates unmaintainable code, violates atomic design principles
+
+---
+
+### Anti-Pattern: Ignoring Match Scores
+
+**Bad**:
+```
+Component has 85% match score → Create new component anyway
+```
+
+**Good**:
+```
+85% match → Use existing with minor adjustments
+68% match → Consider as variant
+45% match → Create new component
+```
+
+**Why it's bad**: Wastes development effort, creates unnecessary component proliferation
+
+---
+
+## Code Generation Anti-Patterns
+
+### Anti-Pattern: Hardcoding Figma Values
+
+**Bad**:
+```tsx
+const Button = styled.button`
+  background: #3B82F6;  /* Hardcoded Figma hex */
+  padding: 12px 24px;   /* Hardcoded Figma values */
+`;
+```
+
+**Good**:
+```tsx
+const Button = styled.button`
+  background: ${theme.colors.primary};
+  padding: ${theme.space[3]} ${theme.space[6]};
+`;
+```
+
+**Why it's bad**: Breaks design system consistency, makes theme changes impossible
+
+---
+
+### Anti-Pattern: Skipping Confirmation Step
+
+**Bad**:
+```
+Analyze → Generate code immediately
+```
+
+**Good**:
+```
+Analyze → Show matches → Get developer confirmation → Generate code
+```
+
+**Why it's bad**: Developers lose control, wrong decisions get implemented, requires rework
+
+---
+
+### Anti-Pattern: Flat Component Output
+
+**Bad**:
+```tsx
+// All components in one file
+export const Button = () => ...
+export const Card = () => ...
+export const Header = () => ...
+```
+
+**Good**:
+```
+// Structured output
+atoms/Button.tsx (import existing)
+molecules/Card.tsx (new variant)
+organisms/Header.tsx (adjustment)
+```
+
+**Why it's bad**: Doesn't integrate with existing codebase structure
+
+---
+
+## Matching Anti-Patterns
+
+### Anti-Pattern: Name-Only Matching
+
+**Bad**:
+```
+Figma "PrimaryButton" → Search for "PrimaryButton" → No match → Create new
+```
+
+**Good**:
+```
+Figma "PrimaryButton" → Search semantically:
+  - "Button" with variant "primary"
+  - "PrimaryButton"
+  - Components with similar props
+→ Found Button.tsx with primary variant
+```
+
+**Why it's bad**: Misses existing components due to naming differences
+
+---
+
+### Anti-Pattern: Ignoring Component Hierarchy
+
+**Bad**:
+```
+Match: Card component
+Skip: What's inside the Card (icons, text, buttons)
+```
+
+**Good**:
+```
+Match: Card component
+Also match: All nested components (Icon, Typography, Button)
+```
+
+**Why it's bad**: Nested components get regenerated, losing reuse opportunities
+
+---
+
+### Anti-Pattern: Binary Match Decisions
+
+**Bad**:
+```
+Match score < 100% → Create new component
+```
+
+**Good**:
+```
+95%+ → Use directly
+80-95% → Minor adjustments
+60-80% → Add as variant
+<60% → Create new
+```
+
+**Why it's bad**: Creates unnecessary components for minor differences
+
+---
+
+## Workflow Anti-Patterns
+
+### Anti-Pattern: Skipping Registry Scan
+
+**Bad**:
+```
+Receive Figma data → Start matching immediately
+```
+
+**Good**:
+```
+Receive Figma data → Ensure registry is current → Then match
+```
+
+**Why it's bad**: Matches against stale component data, misses recent additions
+
+---
+
+### Anti-Pattern: No Decision Persistence
+
+**Bad**:
+```
+Developer makes decisions → Generate code → Decisions lost
+```
+
+**Good**:
+```
+Developer makes decisions → Save to figma-decisions.json → Generate code
+Decisions available for future reference and audit
+```
+
+**Why it's bad**: No audit trail, can't review or adjust decisions later
+
+---
+
+_More anti-patterns will be added as they are discovered._

package/.claude/skills/figma-analyzer/knowledge/patterns.md

@@ -0,0 +1,144 @@
+# Figma Analyzer Patterns
+
+Patterns for analyzing Figma designs and matching against existing codebases.
+
+---
+
+## Matching Patterns
+
+### Pattern: Atomic Component Priority
+
+**Context**: When analyzing a Figma screen
+**Approach**:
+1. First identify atoms (buttons, inputs, icons, text)
+2. Then molecules (search bars, cards, nav items)
+3. Then organisms (headers, sidebars, forms)
+4. Finally templates/pages
+
+**Why it works**: Bottom-up analysis ensures foundational components are matched first
+
+---
+
+### Pattern: Match Score Thresholds
+
+| Score | Action | Example |
+|-------|--------|---------|
+| 95%+ | Use directly | Icon with same name and size |
+| 80-95% | Use with minor adjustments | Button with different padding |
+| 60-80% | Consider as variant | Card with new layout option |
+| <60% | Create new component | Novel component design |
+
+**Why it works**: Clear decision boundaries reduce developer cognitive load
+
+---
+
+### Pattern: Property-Based Matching
+
+**Context**: Calculating match scores
+**Approach**:
+```
+Score = (
+  nameMatch * 0.3 +
+  typeMatch * 0.2 +
+  propsMatch * 0.3 +
+  visualMatch * 0.2
+)
+```
+
+Components to compare:
+- Name similarity (case-insensitive, handle synonyms)
+- Component type (button, input, card)
+- Props overlap (size, variant, color)
+- Visual characteristics (dimensions, colors)
+
+---
+
+## Decision Patterns
+
+### Pattern: Variant vs New Component
+
+**When to add variant**:
+- Same base functionality
+- Similar props/API
+- Fits existing component architecture
+- Score 60-80%
+
+**When to create new**:
+- Different behavior/purpose
+- Would require breaking changes
+- Doesn't fit existing component patterns
+- Score <60%
+
+---
+
+### Pattern: Design Token Preservation
+
+**Context**: Maintaining design system consistency
+**Approach**:
+1. Map Figma colors to existing tokens first
+2. Only create new tokens if truly novel
+3. Prefer closest existing size/spacing tokens
+4. Document any new tokens needed
+
+Example mapping:
+```
+Figma #1F2937 → token: gray-800
+Figma 16px → token: text-base
+Figma 24px spacing → token: space-6
+```
+
+---
+
+## Output Patterns
+
+### Pattern: Structured Decision Format
+
+**Context**: Storing developer decisions
+**Format**:
+```json
+{
+  "figmaComponent": "Button/Primary",
+  "decision": "use" | "variant" | "new" | "skip",
+  "matchedTo": "Button.tsx",
+  "confidence": 0.92,
+  "differences": ["color", "size"],
+  "variantName": "large",
+  "notes": "Developer chose to add as variant"
+}
+```
+
+---
+
+### Pattern: Generated Code Structure
+
+**Context**: Code generation output
+**Include**:
+1. Import statements for existing components
+2. Variant definitions (what to add)
+3. New component skeletons
+4. Composition code showing assembly
+
+**Order**: Atoms → Molecules → Organisms → Page composition
+
+---
+
+## Anti-Patterns to Avoid
+
+### Anti-Pattern: Regenerating Existing Components
+
+**Bad**: Creating new Button.tsx when one exists
+**Good**: Identify match, offer variant or adjustment
+
+### Anti-Pattern: Missing Atomic Analysis
+
+**Bad**: Creating monolithic screen component
+**Good**: Break into reusable atoms/molecules first
+
+### Anti-Pattern: Ignoring Design Tokens
+
+**Bad**: Hardcoding Figma hex values
+**Good**: Map to existing token system
+
+---
+
+_More patterns will be added as they are discovered._

package/.claude/skills/figma-analyzer/skill.md

@@ -0,0 +1,236 @@
+---
+name: figma-analyzer
+version: 1.0.0
+description: Analyze Figma designs and match components against existing codebase
+scope: project
+user-invocable: true
+context: inline
+agent: developer
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Edit
+  - Write
+  - Bash(./scripts/flow figma *)
+  - mcp__figma__*
+lastUpdated: 2026-01-11
+learningCount: 0
+successRate: 0
+---
+
+# Figma Component Analyzer Skill
+
+## Overview
+
+This skill helps you analyze Figma designs and match components against the existing codebase. Instead of generating all new code, it identifies what can be reused and guides developers through an interactive confirmation process.
+
+## When to Use
+
+Use this skill when:
+- A developer shares a Figma link and asks to implement a screen
+- Converting Figma designs to code
+- Adding new screens/features from Figma designs
+- Working with Figma MCP to generate code
+
+## Triggers
+
+- keywords: ["figma", "figma-link", "design-file", "design-system", "design-tokens", "mockup", "wireframe", "figma-mcp", "frame", "artboard"]
+- filePatterns: []
+- taskTypes: ["feature"]
+- categories: ["design", "design-to-code"]
+
+## Workflow
+
+### Step 1: Index the Codebase (First Time)
+
+Before analyzing Figma designs, index the codebase:
+
+```bash
+./scripts/flow figma scan
+```
+
+This creates `.workflow/state/component-registry.json` with all existing components.
+
+### Step 2: Get Figma Data via MCP
+
+When the developer provides a Figma link, use the Figma MCP to get design data:
+
+```
+# Use Figma MCP to get design context
+figma.get_file_nodes(file_key="...", node_ids=["..."])
+```
+
+### Step 3: Analyze and Match
+
+Use the Wogi Figma tools to analyze:
+
+```bash
+# Extract components from Figma data
+echo '<figma_mcp_response>' | ./scripts/flow-figma-extract.js --stdin > /tmp/figma-components.json
+
+# Match against registry
+./scripts/flow-figma-match.js /tmp/figma-components.json > /tmp/figma-matches.json
+```
+
+Or use the MCP server tools directly:
+- `wogi_figma_analyze` - Full analysis pipeline
+- `wogi_figma_match` - Match single component
+
+### Step 4: Present Results to Developer
+
+Display the analysis results in a clear format:
+
+```
+═══════════════════════════════════════════════════════════════════
+                 FIGMA COMPONENT ANALYSIS
+═══════════════════════════════════════════════════════════════════
+
+📊 Found 12 components, 8 potential matches
+
+ATOMS (5):
+├─ Icon (settings)    → 95% match → Icon.tsx           ✅ USE
+├─ Text (heading)     → 100% match → Typography.tsx    ✅ USE
+├─ Button (primary)   → 88% match → Button.tsx         ⚠️ ADJUST
+├─ Input (outlined)   → 72% match → Input.tsx          ➕ VARIANT?
+└─ Avatar (new)       → 45% match → Avatar.tsx         🆕 NEW
+
+MOLECULES (4):
+├─ SearchBar          → 92% match → SearchBar.tsx      ✅ USE
+├─ Card (stats)       → 85% match → Card.tsx           ⚠️ ADJUST
+├─ NavItem            → 78% match → NavItem.tsx        ➕ VARIANT?
+└─ UserMenu           → 35% match → (none)             🆕 NEW
+
+ORGANISMS (3):
+├─ Header             → 82% match → Header.tsx         ⚠️ ADJUST
+├─ Sidebar            → 68% match → Sidebar.tsx        ➕ VARIANT?
+└─ Dashboard          → 0% match → (none)              🆕 NEW
+```
+
+### Step 5: Interactive Confirmation
+
+For each component, ask the developer to confirm:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Sidebar (nav) - 68% match to Sidebar.tsx
+
+Differences:
+  • Width: 280px (existing: 240px)
+  • Background: #1F2937 (existing: #111827)
+  • Has collapse button (existing: doesn't)
+
+Options:
+  [1] ✅ Use existing Sidebar.tsx (ignore differences)
+  [2] ➕ Add as variant "collapsible" to Sidebar.tsx
+  [3] 🆕 Create new component: CollapsibleSidebar.tsx
+  [4] ⏭️ Skip - I'll handle manually
+
+Developer choice:
+```
+
+### Step 6: Generate Code
+
+After all confirmations, generate the appropriate code:
+
+```bash
+./scripts/flow figma generate
+```
+
+Output includes:
+- Import statements for existing components
+- Variant additions (what to add to existing components)
+- New component prompts for Claude to generate
+- Composition code showing how everything fits together
+
+## Key Principles
+
+1. **Never regenerate existing components** - Always check registry first
+2. **Break screens into atoms first** - Work bottom-up
+3. **80% threshold for reuse** - Below 80% match, consider creating new
+4. **Confirm before creating** - Let developer decide use/variant/new
+5. **Preserve design system** - Match existing patterns and tokens
+
+## Thresholds
+
+| Score | Suggestion |
+|-------|------------|
+| 95%+ | Use directly |
+| 80-95% | Use with minor adjustments |
+| 60-80% | Consider as variant |
+| <60% | Create new component |
+
+## Files Created
+
+- `.workflow/state/component-registry.json` - Codebase component index
+- `.workflow/state/figma-decisions.json` - Developer decisions
+- `.workflow/state/figma-output.json` - Generated output
+
+## CLI Commands
+
+```bash
+./scripts/flow figma scan              # Scan codebase for components
+./scripts/flow figma show [name]       # Show component details
+./scripts/flow figma extract <file>    # Extract from Figma data
+./scripts/flow figma match <file>      # Match against registry
+./scripts/flow figma confirm <file>    # Interactive confirmation
+./scripts/flow figma generate          # Generate code from decisions
+./scripts/flow figma server            # Start MCP server
+```
+
+## MCP Server
+
+Start the MCP server for use with Claude Desktop or other MCP clients:
+
+```bash
+./scripts/flow figma server
+```
+
+Add to Claude Desktop config:
+```json
+{
+  "mcpServers": {
+    "wogi-figma": {
+      "command": "node",
+      "args": ["/path/to/wogi-flow/scripts/flow-figma-mcp-server.js"]
+    }
+  }
+}
+```
+
+## Example Prompt
+
+When a developer says "implement this Figma screen", respond:
+
+"I'll analyze this design and match it against your existing components. Let me:
+
+1. First, check your component registry (or scan if needed)
+2. Extract all components from the Figma design
+3. Match each against your codebase
+4. Walk you through what to reuse vs. create new
+
+This ensures we maintain your design system and don't duplicate components."
+
+## Setting Up Figma MCP
+
+To use Figma designs with Claude:
+
+1. Get a Figma Personal Access Token from https://www.figma.com/developers/api#access-tokens
+2. Add the Figma MCP server to your Claude config:
+
+```json
+{
+  "mcpServers": {
+    "figma": {
+      "command": "npx",
+      "args": ["-y", "@anthropic/mcp-server-figma"],
+      "env": {
+        "FIGMA_PERSONAL_ACCESS_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+3. Now you can use `figma.get_file_nodes()` to fetch design data

package/lib/installer.js

@@ -338,11 +338,47 @@ function createCLIConfig(projectRoot, cliKey, config) {
   const cliDir = path.join(projectRoot, cli.dir);
   fs.mkdirSync(cliDir, { recursive: true });
 
-  // Create CLI-specific config file
+  // Create CLI-specific config file and copy resources
   if (cliKey === 'claude') {
-    const claudeMd = `# Project Instructions
+    // Copy commands from package
+    const packageCommands = path.join(PACKAGE_ROOT, '.claude', 'commands');
+    const projectCommands = path.join(cliDir, 'commands');
+    if (fs.existsSync(packageCommands)) {
+      copyDir(packageCommands, projectCommands);
+      console.log('  Copied .claude/commands/ (slash commands)');
+    }
+
+    // Copy docs from package
+    const packageDocs = path.join(PACKAGE_ROOT, '.claude', 'docs');
+    const projectDocs = path.join(cliDir, 'docs');
+    if (fs.existsSync(packageDocs)) {
+      copyDir(packageDocs, projectDocs);
+      console.log('  Copied .claude/docs/ (documentation)');
+    }
+
+    // Copy rules from package
+    const packageRules = path.join(PACKAGE_ROOT, '.claude', 'rules');
+    const projectRules = path.join(cliDir, 'rules');
+    if (fs.existsSync(packageRules)) {
+      copyDir(packageRules, projectRules);
+      console.log('  Copied .claude/rules/ (coding rules)');
+    }
+
+    // Copy skills from package (base skills only)
+    const packageSkills = path.join(PACKAGE_ROOT, '.claude', 'skills');
+    const projectSkills = path.join(cliDir, 'skills');
+    if (fs.existsSync(packageSkills)) {
+      copyDir(packageSkills, projectSkills);
+      console.log('  Copied .claude/skills/ (base skills)');
+    }
 
-You are an AI development assistant using the Wogi Flow methodology.
+    // Generate CLAUDE.md from template
+    const claudeMdTemplate = path.join(PACKAGE_ROOT, '.workflow', 'templates', 'claude-md.hbs');
+    if (fs.existsSync(claudeMdTemplate)) {
+      // For now, create a simple CLAUDE.md - the bridge will regenerate with full template
+      const claudeMd = `# Project Instructions
+
+You are an AI development assistant using the WogiFlow methodology v1.0.
 
 ## Quick Start
 
@@ -356,22 +392,16 @@ cat .workflow/state/ready.json # Check tasks
 - \`/wogi-ready\` - Show available tasks
 - \`/wogi-start TASK-X\` - Start a task
 - \`/wogi-status\` - Project overview
+- \`/wogi-health\` - Check workflow health
 
 Generated by Wogi Flow v${config.version}
 `;
-    fs.writeFileSync(path.join(cliDir, 'CLAUDE.md'), claudeMd);
-
-    // Create skills directory
-    fs.mkdirSync(path.join(cliDir, 'skills'), { recursive: true });
-
-    // Create docs directory
-    fs.mkdirSync(path.join(cliDir, 'docs'), { recursive: true });
-
-    // Create rules directory
-    fs.mkdirSync(path.join(cliDir, 'rules'), { recursive: true });
+      fs.writeFileSync(path.join(projectRoot, 'CLAUDE.md'), claudeMd);
+      console.log('  Created CLAUDE.md');
+    }
   }
 
-  console.log(`  Created ${cli.dir}/ for ${cli.name}`);
+  console.log(`  Configured ${cli.name}`);
 }
 
 /**
@@ -458,7 +488,9 @@ async function init(args) {
       console.log('');
     } catch (err) {
       rl.close();
-      throw err;
+      console.error(`\nSetup prompt failed: ${err.message}`);
+      console.log('Run "flow init --basic" to skip the AI recommendation.\n');
+      process.exit(1);
     }
   }
 
@@ -468,13 +500,20 @@ async function init(args) {
 
   // Detect project name from package.json or directory name
   const packageJsonPath = path.join(projectRoot, 'package.json');
-  const pkg = safeReadJson(packageJsonPath);
-  if (pkg && pkg.name) {
-    config.projectName = pkg.name;
+  const projectPkg = safeReadJson(packageJsonPath);
+  if (projectPkg && projectPkg.name) {
+    config.projectName = projectPkg.name;
   } else {
     config.projectName = path.basename(projectRoot);
   }
 
+  // Validate CLI option early (before interactive mode)
+  if (options.cli && !SUPPORTED_CLIS[options.cli]) {
+    console.error(`Unknown CLI: ${options.cli}`);
+    console.log(`Supported CLIs: ${Object.keys(SUPPORTED_CLIS).join(', ')}`);
+    process.exit(1);
+  }
+
   // Interactive or quick mode
   if (options.yes) {
     // Use defaults and CLI option if provided
@@ -519,7 +558,8 @@ async function init(args) {
       rl.close();
     } catch (err) {
       rl.close();
-      throw err;
+      console.error(`\nSetup failed: ${err.message}`);
+      process.exit(1);
     }
   }