wogiflow 1.0.21 → 1.0.22

package/.claude/docs/knowledge-base/05-development-tools/README.md

@@ -0,0 +1,84 @@
+# Development Tools
+
+Features that accelerate specific development workflows.
+
+---
+
+## Overview
+
+These tools speed up common tasks:
+- Design-to-code with Figma
+- Understanding codebases with traces
+- Step-by-step multi-file editing
+- MCP server integrations
+
+---
+
+## Features
+
+| Feature | Purpose |
+|---------|---------|
+| [Figma Analyzer](./figma-analyzer.md) | Design-to-code component matching |
+| [Code Traces](./code-traces.md) | Understand code flow for features |
+| [Guided Edit](./guided-edit.md) | Step-by-step multi-file changes |
+| [MCP Integrations](./mcp-integrations.md) | External tool connections |
+
+---
+
+## Quick Start
+
+### Figma Analysis
+
+```bash
+/wogi-figma analyze LoginScreen
+```
+
+### Code Trace
+
+```bash
+/wogi-trace "user authentication flow"
+```
+
+### Guided Edit
+
+```bash
+/wogi-guided-edit "rename Button to BaseButton"
+```
+
+---
+
+## Key Configuration
+
+```json
+{
+  "figmaAnalyzer": {
+    "enabled": true,
+    "thresholds": {
+      "exactMatch": 95,
+      "strongMatch": 80
+    }
+  },
+  "traces": {
+    "saveTo": ".workflow/traces",
+    "generateDiagrams": true
+  }
+}
+```
+
+---
+
+## Integration Points
+
+These tools integrate with:
+- Task execution (auto-context)
+- Component indexing
+- App-map registry
+- Hybrid mode
+
+---
+
+## Related
+
+- [Task Execution](../02-task-execution/) - Core workflow
+- [Setup](../01-setup-onboarding/) - Component indexing
+- [Configuration](../configuration/all-options.md) - All settings

package/.claude/docs/knowledge-base/05-development-tools/code-traces.md

@@ -0,0 +1,278 @@
+# Code Traces
+
+Understand how code flows for specific features or behaviors.
+
+---
+
+## Purpose
+
+Code traces help you:
+- Understand how features work
+- Find all files involved in a flow
+- Create diagrams of code paths
+- Document architecture
+
+---
+
+## Configuration
+
+```json
+{
+  "traces": {
+    "saveTo": ".workflow/traces",
+    "generateDiagrams": true
+  }
+}
+```
+
+---
+
+## Usage
+
+### Generate a Trace
+
+```bash
+/wogi-trace "user authentication flow"
+```
+
+### Output
+
+```
+🔍 Code Trace: User Authentication Flow
+
+Entry Points:
+  → src/pages/login.tsx
+  → src/components/LoginForm.tsx
+
+Flow:
+  1. LoginForm.tsx
+     ├── Renders form with email/password
+     ├── Calls: useAuth hook
+     └── On submit: authService.login()
+
+  2. src/hooks/useAuth.ts
+     ├── Manages auth state (Zustand)
+     ├── Calls: authService methods
+     └── Returns: user, login, logout
+
+  3. src/services/authService.ts
+     ├── login(email, password)
+     │   └── POST /api/auth/login
+     ├── logout()
+     │   └── DELETE /api/auth/session
+     └── refreshToken()
+         └── POST /api/auth/refresh
+
+  4. src/pages/api/auth/login.ts
+     ├── Validates credentials
+     ├── Creates JWT token
+     └── Sets httpOnly cookie
+
+Files Involved: 7
+Total Lines: ~450
+
+Diagram saved: .workflow/traces/auth-flow.md
+```
+
+---
+
+## Trace Types
+
+### Feature Trace
+
+```bash
+/wogi-trace "checkout process"
+```
+
+Traces a complete user feature.
+
+### Component Trace
+
+```bash
+/wogi-trace component Button
+```
+
+Traces where a component is used.
+
+### API Trace
+
+```bash
+/wogi-trace api "/api/users"
+```
+
+Traces an API endpoint's flow.
+
+---
+
+## Diagram Generation
+
+When `generateDiagrams` is enabled:
+
+```markdown
+# Auth Flow Diagram
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant LF as LoginForm
+    participant AS as AuthService
+    participant API as /api/auth
+    participant DB as Database
+
+    U->>LF: Enter credentials
+    LF->>AS: login(email, pass)
+    AS->>API: POST /login
+    API->>DB: Find user
+    DB-->>API: User record
+    API->>API: Verify password
+    API->>API: Create JWT
+    API-->>AS: Token + User
+    AS->>AS: Store in state
+    AS-->>LF: Success
+    LF-->>U: Redirect to dashboard
+```
+```
+
+---
+
+## Trace Files
+
+Saved to `.workflow/traces/`:
+
+```
+.workflow/traces/
+├── auth-flow.md
+├── checkout-process.md
+├── button-usage.md
+└── api-users.md
+```
+
+### Trace File Format
+
+```markdown
+# Trace: User Authentication Flow
+
+Generated: 2024-01-15 10:30
+
+## Summary
+Authentication flow from login form to API to database.
+
+## Entry Points
+- src/pages/login.tsx
+- src/components/LoginForm.tsx
+
+## Files
+| File | Role | Lines |
+|------|------|-------|
+| LoginForm.tsx | UI | 45 |
+| useAuth.ts | State | 62 |
+| authService.ts | Service | 85 |
+| login.ts | API | 120 |
+
+## Flow Diagram
+[Mermaid diagram]
+
+## Key Functions
+- `login(email, password)` - Main auth entry
+- `createToken(user)` - JWT generation
+- `validatePassword(input, hash)` - Verification
+
+## Notes
+- Uses JWT with 1hr expiry
+- Refresh token in httpOnly cookie
+- Rate limited to 5 attempts/minute
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wogi-trace "<description>"` | Create feature trace |
+| `/wogi-trace component <name>` | Trace component usage |
+| `/wogi-trace api "<endpoint>"` | Trace API endpoint |
+
+---
+
+## Use Cases
+
+### Understanding Legacy Code
+
+```bash
+/wogi-trace "how does the payment system work"
+```
+
+### Onboarding New Developer
+
+```bash
+/wogi-trace "main application flow"
+```
+
+### Debugging
+
+```bash
+/wogi-trace "error handling in API"
+```
+
+### Documentation
+
+```bash
+/wogi-trace "data sync process" --save
+```
+
+---
+
+## Integration with Tasks
+
+Traces can feed into task planning:
+
+```
+1. Generate trace
+2. Identify all files involved
+3. Create task with file list
+4. Use trace for context during implementation
+```
+
+---
+
+## Best Practices
+
+1. **Start Broad**: Use general descriptions first
+2. **Refine**: Add specifics if trace is too large
+3. **Save Important Traces**: Good for documentation
+4. **Update After Changes**: Regenerate stale traces
+5. **Use for Planning**: Understand before modifying
+
+---
+
+## Troubleshooting
+
+### Trace Too Large
+
+Be more specific:
+```bash
+# Too broad
+/wogi-trace "user management"
+
+# Better
+/wogi-trace "user password reset flow"
+```
+
+### Missing Files
+
+- Check if files are in indexed directories
+- Ensure file extensions are supported
+- Verify imports are standard format
+
+### Diagrams Not Generating
+
+Check `generateDiagrams` is true and Mermaid syntax is valid.
+
+---
+
+## Related
+
+- [Task Planning](../02-task-execution/01-task-planning.md) - Using traces for planning
+- [Component Indexing](../01-setup-onboarding/component-indexing.md) - File discovery
+- [Configuration](../configuration/all-options.md) - All settings

package/.claude/docs/knowledge-base/05-development-tools/figma-analyzer.md

@@ -0,0 +1,253 @@
+# Figma Analyzer
+
+Match Figma designs to existing components for faster design-to-code.
+
+---
+
+## Purpose
+
+When implementing designs:
+1. **Find Existing Components**: Don't recreate what exists
+2. **Identify Variants**: Suggest variants over new components
+3. **Generate Prompts**: Create implementation prompts
+
+---
+
+## Configuration
+
+```json
+{
+  "figmaAnalyzer": {
+    "enabled": true,
+    "thresholds": {
+      "exactMatch": 95,          // Score for "use as-is"
+      "strongMatch": 80,         // Score for "good match"
+      "variantCandidate": 60     // Score for "add variant"
+    },
+    "componentDirs": [
+      "src/components",
+      "components",
+      "src/ui",
+      "ui"
+    ],
+    "mcpServer": {
+      "port": 3847,
+      "autoStart": false
+    },
+    "autoScanOnAnalyze": true,
+    "generatePrompts": true
+  }
+}
+```
+
+---
+
+## How It Works
+
+```
+Figma Design
+      ↓
+┌─────────────────────────────────────────┐
+│ 1. Extract design metadata              │
+│    - Component names                    │
+│    - Props/variants                     │
+│    - Styles                            │
+├─────────────────────────────────────────┤
+│ 2. Match against codebase              │
+│    - Name similarity                   │
+│    - Prop compatibility                │
+│    - Style matching                    │
+├─────────────────────────────────────────┤
+│ 3. Score matches                       │
+│    - Exact: 95+                        │
+│    - Strong: 80-95                     │
+│    - Variant: 60-80                    │
+│    - New: <60                          │
+├─────────────────────────────────────────┤
+│ 4. Generate recommendations            │
+│    - Use existing                      │
+│    - Add variant                       │
+│    - Create new                        │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## Usage
+
+### Analyze a Frame
+
+```bash
+/wogi-figma analyze "Login Screen"
+```
+
+### Output
+
+```
+📐 Figma Analysis: Login Screen
+
+Found 8 components in design:
+
+1. Button "Submit"
+   ✅ EXACT MATCH (97%)
+   → Use: src/components/Button.tsx
+   → Props: variant="primary", size="lg"
+
+2. Input "Email"
+   🔶 STRONG MATCH (85%)
+   → Use: src/components/Input.tsx
+   → Note: Add "email" variant for icon
+
+3. Card "Login Container"
+   🔶 VARIANT CANDIDATE (72%)
+   → Base: src/components/Card.tsx
+   → Suggestion: Add "auth" variant
+
+4. Logo "AppLogo"
+   ❌ NO MATCH
+   → Create: src/components/AppLogo.tsx
+
+Implementation prompt generated.
+```
+
+---
+
+## Match Scores
+
+| Score | Classification | Action |
+|-------|---------------|--------|
+| 95+ | Exact Match | Use as-is |
+| 80-95 | Strong Match | Minor tweaks needed |
+| 60-80 | Variant Candidate | Add variant |
+| <60 | No Match | Create new |
+
+---
+
+## Prompt Generation
+
+When `generatePrompts` is enabled:
+
+```markdown
+# Implementation Prompt: Login Screen
+
+## Components to Use
+
+### Button
+Path: src/components/Button.tsx
+Props: variant="primary", size="lg", onClick={handleSubmit}
+
+### Input
+Path: src/components/Input.tsx
+Props: type="email", placeholder="Email"
+Note: Consider adding email icon variant
+
+## Components to Create
+
+### AppLogo
+Create at: src/components/AppLogo.tsx
+From Figma: AppLogo frame
+Specs:
+  - Width: 120px
+  - Height: 40px
+  - SVG export available
+
+## Layout
+- Use flex column with gap-4
+- Card wrapper with padding-6
+- Center aligned, max-width 400px
+```
+
+---
+
+## MCP Server Mode
+
+For real-time Figma integration:
+
+```json
+{
+  "figmaAnalyzer": {
+    "mcpServer": {
+      "port": 3847,
+      "autoStart": true
+    }
+  }
+}
+```
+
+### Start Server
+
+```bash
+./scripts/flow figma-server start
+```
+
+### Connect from Figma
+
+Use the Figma MCP plugin to connect to the running server.
+
+---
+
+## Component Indexing
+
+Figma analyzer uses component index:
+
+```bash
+# Ensure index is current
+/wogi-map-index scan
+```
+
+### What's Indexed
+
+- Component names
+- Exported props
+- Variants available
+- File locations
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/wogi-figma analyze <frame>` | Analyze Figma frame |
+| `/wogi-figma compare` | Compare design to code |
+| `/wogi-figma prompt <frame>` | Generate impl prompt |
+
+---
+
+## Best Practices
+
+1. **Index First**: Run `/wogi-map-index scan` before analysis
+2. **Name Consistency**: Use same names in Figma and code
+3. **Use Variants**: Add variants instead of new components
+4. **Review Matches**: Don't blindly trust scores
+5. **Update App-Map**: Register new components
+
+---
+
+## Troubleshooting
+
+### Low Match Scores
+
+- Check naming consistency
+- Verify component index is current
+- Review threshold settings
+
+### Components Not Found
+
+- Verify `componentDirs` includes your paths
+- Run component index scan
+- Check file extensions match
+
+### MCP Server Issues
+
+- Check port availability
+- Verify Figma plugin installed
+- Check firewall settings
+
+---
+
+## Related
+
+- [Component Indexing](../01-setup-onboarding/component-indexing.md)
+- [Task Execution](../02-task-execution/) - Using prompts
+- [Configuration](../configuration/all-options.md) - All settings