agentic-qe 1.0.0

package/.claude/commands/hooks/overview.md

@@ -0,0 +1,132 @@
+# Claude Code Hooks for claude-flow
+
+## Purpose
+Automatically coordinate, format, and learn from Claude Code operations using hooks with MCP tool integration.
+
+## Available Hooks
+
+### Pre-Operation Hooks
+- **pre-edit**: Validate and assign agents before file modifications
+- **pre-bash**: Check command safety and resource requirements  
+- **pre-task**: Auto-spawn agents for complex tasks
+
+### Post-Operation Hooks
+- **post-edit**: Auto-format code, train neural patterns, update memory
+- **post-bash**: Log execution and update metrics
+- **post-search**: Cache results and improve search patterns
+
+### MCP Integration Hooks
+- **mcp-initialized**: Persist swarm configuration
+- **agent-spawned**: Update agent roster and memory
+- **task-orchestrated**: Monitor task progress through memory
+- **neural-trained**: Save pattern improvements
+
+### Memory Coordination Hooks
+- **memory-write**: Triggered when agents write to coordination memory
+- **memory-read**: Triggered when agents read from coordination memory
+- **memory-sync**: Synchronize memory across swarm agents
+
+### Session Hooks
+- **notify**: Custom notifications with swarm status
+- **session-end**: Generate summary and save state
+- **session-restore**: Load previous session state
+
+## Configuration
+Hooks are configured in `.claude/settings.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx claude-flow hook pre-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/current'"
+        }]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "^(Write|Edit|MultiEdit)$",
+        "hooks": [{
+          "type": "command",
+          "command": "npx claude-flow hook post-edit --file '${tool.params.file_path}' --memory-key 'swarm/editor/complete'"
+        }]
+      }
+    ]
+  }
+}
+```
+
+## MCP Tool Integration in Hooks
+
+Hooks automatically trigger MCP tools for coordination:
+
+```javascript
+// Pre-task hook spawns agents
+npx claude-flow hook pre-task --description "[task]"
+// Internally calls:
+mcp__claude-flow__agent_spawn { type: "appropriate-agent" }
+
+// Post-edit hook updates memory
+npx claude-flow hook post-edit --file "[file]"
+// Internally calls:
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/editor/[file]",
+  namespace: "coordination",
+  value: JSON.stringify({ file, changes, timestamp })
+}
+
+// Session-end hook persists state
+npx claude-flow hook session-end
+// Internally calls:
+mcp__claude-flow__memory_persist { sessionId: "[session-id]" }
+```
+
+## Memory Coordination Protocol
+
+All hooks follow the mandatory memory write pattern:
+
+```javascript
+// 1. STATUS - Hook starts
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/status",
+  namespace: "coordination",
+  value: JSON.stringify({ status: "running", hook: "[name]" })
+}
+
+// 2. PROGRESS - Hook processes
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/progress",
+  namespace: "coordination",
+  value: JSON.stringify({ progress: 50, action: "processing" })
+}
+
+// 3. COMPLETE - Hook finishes
+mcp__claude-flow__memory_usage {
+  action: "store",
+  key: "swarm/hooks/[hook-name]/complete",
+  namespace: "coordination",
+  value: JSON.stringify({ status: "complete", result: "success" })
+}
+```
+
+## Benefits
+- 🤖 Automatic agent assignment based on file type
+- 🎨 Consistent code formatting
+- 🧠 Continuous neural pattern improvement  
+- 💾 Cross-session memory persistence via MCP tools
+- 📊 Performance metrics tracking through memory
+- 🔄 Automatic memory coordination between agents
+- 🎯 Smart agent spawning based on task analysis
+
+## See Also
+- [Pre-Edit Hook](./pre-edit.md)
+- [Post-Edit Hook](./post-edit.md)
+- [Session End Hook](./session-end.md)
+- [Memory Usage](../memory/memory-usage.md)
+- [Agent Spawning](../agents/agent-spawning.md)

package/.claude/commands/hooks/post-edit.md

@@ -0,0 +1,117 @@
+# hook post-edit
+
+Execute post-edit processing including formatting, validation, and memory updates.
+
+## Usage
+
+```bash
+npx claude-flow hook post-edit [options]
+```
+
+## Options
+
+- `--file, -f <path>` - File path that was edited
+- `--auto-format` - Automatically format code (default: true)
+- `--memory-key, -m <key>` - Store edit context in memory
+- `--train-patterns` - Train neural patterns from edit
+- `--validate-output` - Validate edited file
+
+## Examples
+
+### Basic post-edit hook
+
+```bash
+npx claude-flow hook post-edit --file "src/components/Button.jsx"
+```
+
+### With memory storage
+
+```bash
+npx claude-flow hook post-edit -f "api/auth.js" --memory-key "auth/login-implementation"
+```
+
+### Format and validate
+
+```bash
+npx claude-flow hook post-edit -f "config/webpack.js" --auto-format --validate-output
+```
+
+### Neural training
+
+```bash
+npx claude-flow hook post-edit -f "utils/helpers.ts" --train-patterns --memory-key "utils/refactor"
+```
+
+## Features
+
+### Auto Formatting
+
+- Language-specific formatters
+- Prettier for JS/TS/JSON
+- Black for Python
+- gofmt for Go
+- Maintains consistency
+
+### Memory Storage
+
+- Saves edit context
+- Records decisions made
+- Tracks implementation details
+- Enables knowledge sharing
+
+### Pattern Training
+
+- Learns from successful edits
+- Improves future suggestions
+- Adapts to coding style
+- Enhances coordination
+
+### Output Validation
+
+- Checks syntax correctness
+- Runs linting rules
+- Validates formatting
+- Ensures quality
+
+## Integration
+
+This hook is automatically called by Claude Code when:
+
+- After Edit tool completes
+- Following MultiEdit operations
+- During file saves
+- After code generation
+
+Manual usage in agents:
+
+```bash
+# After editing files
+npx claude-flow hook post-edit --file "path/to/edited.js" --memory-key "feature/step1"
+```
+
+## Output
+
+Returns JSON with:
+
+```json
+{
+  "file": "src/components/Button.jsx",
+  "formatted": true,
+  "formatterUsed": "prettier",
+  "lintPassed": true,
+  "memorySaved": "component/button-refactor",
+  "patternsTrained": 3,
+  "warnings": [],
+  "stats": {
+    "linesChanged": 45,
+    "charactersAdded": 234
+  }
+}
+```
+
+## See Also
+
+- `hook pre-edit` - Pre-edit preparation
+- `Edit` - File editing tool
+- `memory usage` - Memory management
+- `neural train` - Pattern training

package/.claude/commands/hooks/post-task.md

@@ -0,0 +1,112 @@
+# hook post-task
+
+Execute post-task cleanup, performance analysis, and memory storage.
+
+## Usage
+
+```bash
+npx claude-flow hook post-task [options]
+```
+
+## Options
+
+- `--task-id, -t <id>` - Task identifier for tracking
+- `--analyze-performance` - Generate performance metrics (default: true)
+- `--store-decisions` - Save task decisions to memory
+- `--export-learnings` - Export neural pattern learnings
+- `--generate-report` - Create task completion report
+
+## Examples
+
+### Basic post-task hook
+
+```bash
+npx claude-flow hook post-task --task-id "auth-implementation"
+```
+
+### With full analysis
+
+```bash
+npx claude-flow hook post-task -t "api-refactor" --analyze-performance --generate-report
+```
+
+### Memory storage
+
+```bash
+npx claude-flow hook post-task -t "bug-fix-123" --store-decisions --export-learnings
+```
+
+### Quick cleanup
+
+```bash
+npx claude-flow hook post-task -t "minor-update" --analyze-performance false
+```
+
+## Features
+
+### Performance Analysis
+
+- Measures execution time
+- Tracks token usage
+- Identifies bottlenecks
+- Suggests optimizations
+
+### Decision Storage
+
+- Saves key decisions made
+- Records implementation choices
+- Stores error resolutions
+- Maintains knowledge base
+
+### Neural Learning
+
+- Exports successful patterns
+- Updates coordination models
+- Improves future performance
+- Trains on task outcomes
+
+### Report Generation
+
+- Creates completion summary
+- Documents changes made
+- Lists files modified
+- Tracks metrics achieved
+
+## Integration
+
+This hook is automatically called by Claude Code when:
+
+- Completing a task
+- Switching to a new task
+- Ending a work session
+- After major milestones
+
+Manual usage in agents:
+
+```bash
+# In agent coordination
+npx claude-flow hook post-task --task-id "your-task-id" --analyze-performance true
+```
+
+## Output
+
+Returns JSON with:
+
+```json
+{
+  "taskId": "auth-implementation",
+  "duration": 1800000,
+  "tokensUsed": 45000,
+  "filesModified": 12,
+  "performanceScore": 0.92,
+  "learningsExported": true,
+  "reportPath": "/reports/task-auth-implementation.md"
+}
+```
+
+## See Also
+
+- `hook pre-task` - Pre-task setup
+- `performance report` - Detailed metrics
+- `memory usage` - Memory management
+- `neural patterns` - Pattern analysis

package/.claude/commands/hooks/pre-edit.md

@@ -0,0 +1,113 @@
+# hook pre-edit
+
+Execute pre-edit validations and agent assignment before file modifications.
+
+## Usage
+
+```bash
+npx claude-flow hook pre-edit [options]
+```
+
+## Options
+
+- `--file, -f <path>` - File path to be edited
+- `--auto-assign-agent` - Automatically assign best agent (default: true)
+- `--validate-syntax` - Pre-validate syntax before edit
+- `--check-conflicts` - Check for merge conflicts
+- `--backup-file` - Create backup before editing
+
+## Examples
+
+### Basic pre-edit hook
+
+```bash
+npx claude-flow hook pre-edit --file "src/auth/login.js"
+```
+
+### With validation
+
+```bash
+npx claude-flow hook pre-edit -f "config/database.js" --validate-syntax
+```
+
+### Manual agent assignment
+
+```bash
+npx claude-flow hook pre-edit -f "api/users.ts" --auto-assign-agent false
+```
+
+### Safe editing with backup
+
+```bash
+npx claude-flow hook pre-edit -f "production.env" --backup-file --check-conflicts
+```
+
+## Features
+
+### Auto Agent Assignment
+
+- Analyzes file type and content
+- Assigns specialist agents
+- TypeScript → TypeScript expert
+- Database → Data specialist
+- Tests → QA engineer
+
+### Syntax Validation
+
+- Pre-checks syntax validity
+- Identifies potential errors
+- Suggests corrections
+- Prevents broken code
+
+### Conflict Detection
+
+- Checks for git conflicts
+- Identifies concurrent edits
+- Warns about stale files
+- Suggests merge strategies
+
+### File Backup
+
+- Creates safety backups
+- Enables quick rollback
+- Tracks edit history
+- Preserves originals
+
+## Integration
+
+This hook is automatically called by Claude Code when:
+
+- Using Edit or MultiEdit tools
+- Before file modifications
+- During refactoring operations
+- When updating critical files
+
+Manual usage in agents:
+
+```bash
+# Before editing files
+npx claude-flow hook pre-edit --file "path/to/file.js" --validate-syntax
+```
+
+## Output
+
+Returns JSON with:
+
+```json
+{
+  "continue": true,
+  "file": "src/auth/login.js",
+  "assignedAgent": "auth-specialist",
+  "syntaxValid": true,
+  "conflicts": false,
+  "backupPath": ".backups/login.js.bak",
+  "warnings": []
+}
+```
+
+## See Also
+
+- `hook post-edit` - Post-edit processing
+- `Edit` - File editing tool
+- `MultiEdit` - Multiple edits tool
+- `agent spawn` - Manual agent creation

package/.claude/commands/hooks/pre-task.md

@@ -0,0 +1,111 @@
+# hook pre-task
+
+Execute pre-task preparations and context loading.
+
+## Usage
+
+```bash
+npx claude-flow hook pre-task [options]
+```
+
+## Options
+
+- `--description, -d <text>` - Task description for context
+- `--auto-spawn-agents` - Automatically spawn required agents (default: true)
+- `--load-memory` - Load relevant memory from previous sessions
+- `--optimize-topology` - Select optimal swarm topology
+- `--estimate-complexity` - Analyze task complexity
+
+## Examples
+
+### Basic pre-task hook
+
+```bash
+npx claude-flow hook pre-task --description "Implement user authentication"
+```
+
+### With memory loading
+
+```bash
+npx claude-flow hook pre-task -d "Continue API development" --load-memory
+```
+
+### Manual agent control
+
+```bash
+npx claude-flow hook pre-task -d "Debug issue #123" --auto-spawn-agents false
+```
+
+### Full optimization
+
+```bash
+npx claude-flow hook pre-task -d "Refactor codebase" --optimize-topology --estimate-complexity
+```
+
+## Features
+
+### Auto Agent Assignment
+
+- Analyzes task requirements
+- Determines needed agent types
+- Spawns agents automatically
+- Configures agent parameters
+
+### Memory Loading
+
+- Retrieves relevant past decisions
+- Loads previous task contexts
+- Restores agent configurations
+- Maintains continuity
+
+### Topology Optimization
+
+- Analyzes task structure
+- Selects best swarm topology
+- Configures communication patterns
+- Optimizes for performance
+
+### Complexity Estimation
+
+- Evaluates task difficulty
+- Estimates time requirements
+- Suggests agent count
+- Identifies dependencies
+
+## Integration
+
+This hook is automatically called by Claude Code when:
+
+- Starting a new task
+- Resuming work after a break
+- Switching between projects
+- Beginning complex operations
+
+Manual usage in agents:
+
+```bash
+# In agent coordination
+npx claude-flow hook pre-task --description "Your task here"
+```
+
+## Output
+
+Returns JSON with:
+
+```json
+{
+  "continue": true,
+  "topology": "hierarchical",
+  "agentsSpawned": 5,
+  "complexity": "medium",
+  "estimatedMinutes": 30,
+  "memoryLoaded": true
+}
+```
+
+## See Also
+
+- `hook post-task` - Post-task cleanup
+- `agent spawn` - Manual agent creation
+- `memory usage` - Memory management
+- `swarm init` - Swarm initialization

package/.claude/commands/hooks/session-end.md

@@ -0,0 +1,118 @@
+# hook session-end
+
+Cleanup and persist session state before ending work.
+
+## Usage
+
+```bash
+npx claude-flow hook session-end [options]
+```
+
+## Options
+
+- `--session-id, -s <id>` - Session identifier to end
+- `--save-state` - Save current session state (default: true)
+- `--export-metrics` - Export session metrics
+- `--generate-summary` - Create session summary
+- `--cleanup-temp` - Remove temporary files
+
+## Examples
+
+### Basic session end
+
+```bash
+npx claude-flow hook session-end --session-id "dev-session-2024"
+```
+
+### With full export
+
+```bash
+npx claude-flow hook session-end -s "feature-auth" --export-metrics --generate-summary
+```
+
+### Quick close
+
+```bash
+npx claude-flow hook session-end -s "quick-fix" --save-state false --cleanup-temp
+```
+
+### Complete persistence
+
+```bash
+npx claude-flow hook session-end -s "major-refactor" --save-state --export-metrics --generate-summary
+```
+
+## Features
+
+### State Persistence
+
+- Saves current context
+- Stores open files
+- Preserves task progress
+- Maintains decisions
+
+### Metric Export
+
+- Session duration
+- Commands executed
+- Files modified
+- Tokens consumed
+- Performance data
+
+### Summary Generation
+
+- Work accomplished
+- Key decisions made
+- Problems solved
+- Next steps identified
+
+### Cleanup Operations
+
+- Removes temp files
+- Clears caches
+- Frees resources
+- Optimizes storage
+
+## Integration
+
+This hook is automatically called by Claude Code when:
+
+- Ending a conversation
+- Closing work session
+- Before shutdown
+- Switching contexts
+
+Manual usage in agents:
+
+```bash
+# At session end
+npx claude-flow hook session-end --session-id "your-session" --generate-summary
+```
+
+## Output
+
+Returns JSON with:
+
+```json
+{
+  "sessionId": "dev-session-2024",
+  "duration": 7200000,
+  "saved": true,
+  "metrics": {
+    "commandsRun": 145,
+    "filesModified": 23,
+    "tokensUsed": 85000,
+    "tasksCompleted": 8
+  },
+  "summaryPath": "/sessions/dev-session-2024-summary.md",
+  "cleanedUp": true,
+  "nextSession": "dev-session-2025"
+}
+```
+
+## See Also
+
+- `hook session-start` - Session initialization
+- `hook session-restore` - Session restoration
+- `performance report` - Detailed metrics
+- `memory backup` - State backup