wogiflow 1.0.21 → 1.0.22

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

@@ -0,0 +1,173 @@
+# Guided Edit Mode
+
+Step-by-step guided editing for multi-file changes.
+
+---
+
+## Purpose
+
+Guided Edit solves the challenge of large refactors:
+- **Visibility**: See exactly which files will change
+- **Control**: Approve or reject each change individually
+- **Safety**: No bulk changes without review
+- **Persistence**: Resume interrupted sessions
+
+---
+
+## Quick Start
+
+```bash
+# Start a guided edit session
+/wogi-guided-edit "rename Button to BaseButton"
+
+# Review files one by one
+# Use: approve / reject / skip for each file
+```
+
+---
+
+## Use Cases
+
+### Large Refactors
+
+Rename a component across many files:
+
+```bash
+/wogi-guided-edit "rename UserService to UserManager"
+```
+
+### Library Upgrades
+
+Update imports everywhere:
+
+```bash
+/wogi-guided-edit "replace import { X } from 'old-lib' with import { X } from 'new-lib'"
+```
+
+### Code Cleanup
+
+Find and review deprecated patterns:
+
+```bash
+/wogi-guided-edit "find componentWillMount"
+```
+
+### Schema Changes
+
+After modifying an entity, find all usages:
+
+```bash
+/wogi-guided-edit "find UserEntity"
+```
+
+---
+
+## Session Commands
+
+Once a session starts:
+
+| Command | Shortcut | Action |
+|---------|----------|--------|
+| `next` | `n` | Show next file to review |
+| `approve` | `a`, `y` | Approve and apply changes |
+| `reject` | `r` | Reject file, skip changes |
+| `skip` | `s` | Skip for now |
+| `status` | - | Show progress |
+| `abort` | `q` | Cancel session |
+
+---
+
+## Workflow
+
+```
+1. Start Session
+   └── Analyze description (rename/replace/find)
+   └── Search codebase for matches
+   └── Show file list with match counts
+
+2. Review Loop
+   └── Show file with match locations
+   └── Show proposed diff (if replace)
+   └── Wait for: approve / reject / skip
+
+3. Complete
+   └── Show summary (approved/rejected/skipped)
+   └── Changes already applied to approved files
+```
+
+---
+
+## Configuration
+
+```json
+{
+  "guidedEdit": {
+    "enabled": true,
+    "sessionFile": ".workflow/state/guided-edit-session.json",
+    "extensions": ["ts", "tsx", "js", "jsx", "vue", "svelte"],
+    "srcDir": null  // null = auto-detect (src/ or project root)
+  }
+}
+```
+
+---
+
+## Session Persistence
+
+Progress is saved to `.workflow/state/guided-edit-session.json`:
+
+```json
+{
+  "id": "ge-1704729600000",
+  "description": "rename Button to BaseButton",
+  "type": "rename",
+  "search": "Button",
+  "replace": "BaseButton",
+  "files": [
+    { "path": "src/components/Button.tsx", "status": "approved" },
+    { "path": "src/pages/Home.tsx", "status": "pending" }
+  ],
+  "currentIndex": 1,
+  "stats": { "approved": 1, "rejected": 0, "skipped": 0 }
+}
+```
+
+You can:
+- Close Claude and resume later
+- Run `status` to see where you left off
+- Run `abort` to cancel and start fresh
+
+---
+
+## Pattern Recognition
+
+The tool recognizes common patterns:
+
+| Pattern | Type | Example |
+|---------|------|---------|
+| `rename X to Y` | rename | "rename Button to BaseButton" |
+| `replace X with Y` | replace | "replace console.log with logger.debug" |
+| `find X` | find | "find deprecated API" |
+| `update X` | update | "update imports from old-lib" |
+
+---
+
+## CLI Usage
+
+```bash
+# Via flow script
+node scripts/flow-guided-edit.js start "description"
+node scripts/flow-guided-edit.js next
+node scripts/flow-guided-edit.js approve
+node scripts/flow-guided-edit.js reject
+node scripts/flow-guided-edit.js status
+node scripts/flow-guided-edit.js abort
+```
+
+---
+
+## Related
+
+- [Code Traces](./code-traces.md) - Understanding code flow
+- [Task Execution](../02-task-execution/) - Task workflow
+- [Configuration](../configuration/all-options.md) - All options

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

@@ -0,0 +1,286 @@
+# MCP Integrations
+
+<!-- PINS: overview, figma-integration, context7-docs, lsp-integration, custom-servers, auto-search, troubleshooting -->
+
+Connect external tools via Model Context Protocol servers.
+
+---
+
+## Overview
+<!-- PIN: overview -->
+
+MCP (Model Context Protocol) allows WogiFlow to:
+- Connect to external services
+- Access additional tools
+- Extend functionality
+- Integrate with IDEs
+
+---
+
+## Available Integrations
+
+### Figma MCP
+
+Design-to-code integration:
+
+```json
+{
+  "figmaAnalyzer": {
+    "mcpServer": {
+      "port": 3847,
+      "autoStart": false
+    }
+  }
+}
+```
+
+### Context7 Documentation
+
+Library documentation lookup:
+
+```bash
+# Find library ID
+mcp-find "react hooks"
+
+# Get documentation
+mcp-get-library-docs "/vercel/next.js" --topic "routing"
+```
+
+### Custom Servers
+
+Configure additional MCP servers in Claude settings.
+
+---
+
+## Using MCP Tools
+
+### List Available Tools
+
+```bash
+mcp-find "search query"
+```
+
+### Add a Server
+
+```bash
+mcp-add server-name
+```
+
+### Enable/Disable Servers
+
+Use Claude Code's MCP commands to manage servers:
+
+```bash
+# Enable a server
+/mcp enable <server-name>
+
+# Disable a server
+/mcp disable <server-name>
+
+# List all servers
+/mcp list
+```
+
+> **Note**: The @-mention syntax for enabling/disabling MCP servers has been removed. Use `/mcp enable <name>` instead.
+
+### MCP Tool Auto-Search Mode (Claude Code 2.1.7+)
+<!-- PIN: auto-search -->
+
+Claude Code automatically manages MCP tools to optimize context usage:
+
+- **When enabled**: If MCP tool descriptions exceed 10% of the context window, tools are automatically deferred
+- **Discovery**: Deferred tools are discovered via the `MCPSearch` tool instead of being loaded upfront
+- **Default**: Enabled by default for all users
+
+**Implications for WogiFlow users:**
+- Keep tool descriptions concise (under 100 words recommended)
+- Tools with verbose descriptions may not appear in initial tool list
+- Use `MCPSearch` to find deferred tools when needed
+
+**To disable** (not recommended):
+```json
+// In Claude Code settings
+{
+  "disallowedTools": ["MCPSearch"]
+}
+```
+
+**Best practice**: Design MCP tool descriptions to be concise and searchable. Front-load the most important keywords.
+
+### Configure Server
+
+```bash
+mcp-config-set server-name {config}
+```
+
+---
+
+## Figma Integration
+<!-- PIN: figma-integration -->
+
+### Setup
+
+1. Configure MCP server:
+   ```json
+   {
+     "figmaAnalyzer": {
+       "mcpServer": {
+         "port": 3847,
+         "autoStart": true
+       }
+     }
+   }
+   ```
+
+2. Install Figma plugin (if available)
+
+3. Connect to server
+
+### Commands
+
+| Command | Purpose |
+|---------|---------|
+| `figma-analyze` | Analyze frame |
+| `figma-export` | Export assets |
+| `figma-compare` | Compare to code |
+
+---
+
+## Documentation Integration
+<!-- PIN: context7-docs -->
+
+### Context7 Lookup
+
+```bash
+# Find library
+mcp-resolve-library-id "react"
+
+# Get docs
+mcp-get-library-docs "/facebook/react" --topic "hooks"
+```
+
+### Automatic Docs
+
+With `skillLearning.fetchOfficialDocs`:
+
+```json
+{
+  "skillLearning": {
+    "fetchOfficialDocs": true,
+    "officialDocsUrls": {
+      "react": "https://react.dev"
+    }
+  }
+}
+```
+
+---
+
+## LSP Integration
+<!-- PIN: lsp-integration -->
+
+Language Server Protocol for type information:
+
+```json
+{
+  "lsp": {
+    "enabled": true,
+    "server": "typescript-language-server",
+    "timeout": 5000,
+    "cacheTypes": true
+  }
+}
+```
+
+### Benefits
+
+- Type-aware completions
+- Import suggestions
+- Error detection
+- Go-to-definition
+
+---
+
+## Building Custom MCP Servers
+<!-- PIN: custom-servers -->
+
+### Code Mode
+
+Create JavaScript tools combining multiple servers:
+
+```bash
+mcp-code-mode --servers "figma,context7" --name "design-docs"
+```
+
+### Server Structure
+
+```javascript
+// Custom MCP server
+module.exports = {
+  name: "my-server",
+  tools: {
+    "my-tool": {
+      description: "Does something useful",
+      parameters: {...},
+      handler: async (params) => {
+        // Implementation
+      }
+    }
+  }
+};
+```
+
+---
+
+## Resource Access
+
+Read resources from MCP servers:
+
+```bash
+# List resources
+mcp-list-resources
+
+# Read resource
+mcp-read-resource "server-name" "resource://path"
+```
+
+---
+
+## Best Practices
+
+1. **Start with Built-in**: Use provided integrations first
+2. **Configure Once**: Set up profiles for common configs
+3. **Check Availability**: Verify server is running
+4. **Cache Wisely**: Enable caching for slow services
+5. **Security**: Don't expose sensitive servers publicly
+
+---
+
+## Troubleshooting
+<!-- PIN: troubleshooting -->
+
+### Server Not Responding
+
+- Check server is running
+- Verify port is correct
+- Check firewall settings
+
+### Tool Not Found
+
+- Ensure server is added
+- Check tool name spelling
+- Verify server supports the tool
+
+### Timeout Errors
+
+- Increase timeout settings
+- Check network connectivity
+- Verify server performance
+
+---
+
+## Related
+
+- [Figma Analyzer](./figma-analyzer.md) - Design integration
+- [Configuration](../configuration/all-options.md) - All settings
+- [Hybrid Mode](../02-task-execution/02-execution-loop.md#hybrid-mode) - Local LLM execution

package/.claude/docs/knowledge-base/06-safety-guardrails/README.md

@@ -0,0 +1,153 @@
+# Safety & Guardrails
+
+Protecting your codebase from mistakes.
+
+---
+
+## Overview
+
+Safety features prevent:
+- Accidental destructive changes
+- Security vulnerabilities
+- Lost work
+- Unreviewed commits
+
+---
+
+## Features
+
+| Feature | Purpose |
+|---------|---------|
+| [Damage Control](./damage-control.md) | Pattern-based protection |
+| [Security Scanning](./security-scanning.md) | Pre-commit security checks |
+| [Checkpoint/Rollback](./checkpoint-rollback.md) | Recovery system |
+| [Commit Gates](./commit-gates.md) | Approval workflow |
+
+---
+
+## Quick Start
+
+### Enable Damage Control
+
+```json
+{
+  "damageControl": {
+    "enabled": true,
+    "onBlock": "error"
+  }
+}
+```
+
+### Enable Security Scanning
+
+```json
+{
+  "security": {
+    "scanBeforeCommit": true,
+    "blockOnHigh": true
+  }
+}
+```
+
+### Enable Checkpoints
+
+```json
+{
+  "checkpoint": {
+    "enabled": true,
+    "interval": 5
+  }
+}
+```
+
+---
+
+## Key Configuration
+
+```json
+{
+  "damageControl": {
+    "enabled": false,
+    "patternsFile": ".workflow/damage-control.yaml",
+    "onBlock": "error",
+    "onAsk": "prompt",
+    "logging": true
+  },
+  "security": {
+    "scanBeforeCommit": true,
+    "blockOnHigh": true,
+    "checkPatterns": {
+      "secrets": true,
+      "injection": true,
+      "npmAudit": true
+    }
+  },
+  "checkpoint": {
+    "enabled": true,
+    "interval": 5,
+    "maxCheckpoints": 20,
+    "autoCommit": true
+  }
+}
+```
+
+---
+
+## Protection Layers
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PROTECTION LAYERS                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│   Layer 1: Damage Control                                   │
+│   ├── Block destructive commands                           │
+│   ├── Require approval for risky ops                       │
+│   └── Log suspicious activity                              │
+│                                                             │
+│   Layer 2: Security Scanning                                │
+│   ├── Detect secrets in code                               │
+│   ├── Find injection vulnerabilities                       │
+│   └── Check npm audit                                      │
+│                                                             │
+│   Layer 3: Checkpoints                                      │
+│   ├── Periodic snapshots                                   │
+│   ├── Git commits                                          │
+│   └── State backups                                        │
+│                                                             │
+│   Layer 4: Commit Gates                                     │
+│   ├── Approval workflow                                    │
+│   ├── Quality gates                                        │
+│   └── Review requirements                                  │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `flow checkpoint create` | Manual checkpoint |
+| `flow checkpoint rollback` | Restore checkpoint |
+| `flow checkpoint list` | View checkpoints |
+| `flow security scan` | Manual security scan |
+
+---
+
+## Best Practices
+
+1. **Enable Damage Control**: For production projects
+2. **Regular Checkpoints**: Before risky operations
+3. **Security Scan Always**: Block high-severity issues
+4. **Review Before Commit**: Use approval workflow
+5. **Keep Backup Checkpoints**: Don't rely on just git
+
+---
+
+## Related
+
+- [Task Execution](../02-task-execution/) - Where gates apply
+- [Verification](../02-task-execution/03-verification.md) - Quality gates
+- [Configuration](../configuration/all-options.md) - All settings