@agentic-qe/v3 3.0.0-alpha.6 → 3.0.0-alpha.8

package/assets/skills/pair-programming/SKILL.md

@@ -0,0 +1,1202 @@
+---
+name: Pair Programming
+description: AI-assisted pair programming with multiple modes (driver/navigator/switch), real-time verification, quality monitoring, and comprehensive testing. Supports TDD, debugging, refactoring, and learning sessions. Features automatic role switching, continuous code review, security scanning, and performance optimization with truth-score verification.
+---
+
+# Pair Programming
+
+Collaborative AI pair programming with intelligent role management, real-time quality monitoring, and comprehensive development workflows.
+
+## What This Skill Does
+
+This skill provides professional pair programming capabilities with AI assistance, supporting multiple collaboration modes, continuous verification, and integrated testing. It manages driver/navigator roles, performs real-time code review, tracks quality metrics, and ensures high standards through truth-score verification.
+
+**Key Capabilities:**
+- **Multiple Modes**: Driver, Navigator, Switch, TDD, Review, Mentor, Debug
+- **Real-Time Verification**: Automatic quality scoring with rollback on failures
+- **Role Management**: Seamless switching between driver/navigator roles
+- **Testing Integration**: Auto-generate tests, track coverage, continuous testing
+- **Code Review**: Security scanning, performance analysis, best practice enforcement
+- **Session Persistence**: Auto-save, recovery, export, and sharing
+
+## Prerequisites
+
+**Required:**
+- Claude Flow CLI installed (`npm install -g claude-flow@alpha`)
+- Git repository (optional but recommended)
+
+**Recommended:**
+- Testing framework (Jest, pytest, etc.)
+- Linter configured (ESLint, pylint, etc.)
+- Code formatter (Prettier, Black, etc.)
+
+## Quick Start
+
+### Basic Session
+```bash
+# Start simple pair programming
+claude-flow pair --start
+```
+
+### TDD Session
+```bash
+# Test-driven development
+claude-flow pair --start \
+  --mode tdd \
+  --test-first \
+  --coverage 90
+```
+
+---
+
+## Complete Guide
+
+### Session Control Commands
+
+#### Starting Sessions
+```bash
+# Basic start
+claude-flow pair --start
+
+# Expert refactoring session
+claude-flow pair --start \
+  --agent senior-dev \
+  --focus refactor \
+  --verify \
+  --threshold 0.98
+
+# Debugging session
+claude-flow pair --start \
+  --agent debugger-expert \
+  --focus debug \
+  --review
+
+# Learning session
+claude-flow pair --start \
+  --mode mentor \
+  --pace slow \
+  --examples
+```
+
+#### Session Management
+```bash
+# Check status
+claude-flow pair --status
+
+# View history
+claude-flow pair --history
+
+# Pause session
+/pause [--reason <reason>]
+
+# Resume session
+/resume
+
+# End session
+claude-flow pair --end [--save] [--report]
+```
+
+### Available Modes
+
+#### Driver Mode
+You write code while AI provides guidance.
+
+```bash
+claude-flow pair --start --mode driver
+```
+
+**Your Responsibilities:**
+- Write actual code
+- Implement solutions
+- Make immediate decisions
+- Handle syntax and structure
+
+**AI Navigator:**
+- Strategic guidance
+- Spot potential issues
+- Suggest improvements
+- Real-time review
+- Track overall direction
+
+**Best For:**
+- Learning new patterns
+- Implementing familiar features
+- Quick iterations
+- Hands-on debugging
+
+**Commands:**
+```
+/suggest     - Get implementation suggestions
+/review      - Request code review
+/explain     - Ask for explanations
+/optimize    - Request optimization ideas
+/patterns    - Get pattern recommendations
+```
+
+#### Navigator Mode
+AI writes code while you provide direction.
+
+```bash
+claude-flow pair --start --mode navigator
+```
+
+**Your Responsibilities:**
+- Provide high-level direction
+- Review generated code
+- Make architectural decisions
+- Ensure business requirements
+
+**AI Driver:**
+- Write implementation code
+- Handle syntax details
+- Implement your guidance
+- Manage boilerplate
+- Execute refactoring
+
+**Best For:**
+- Rapid prototyping
+- Boilerplate generation
+- Learning from AI patterns
+- Exploring solutions
+
+**Commands:**
+```
+/implement   - Direct implementation
+/refactor    - Request refactoring
+/test        - Generate tests
+/document    - Add documentation
+/alternate   - See alternative approaches
+```
+
+#### Switch Mode
+Automatically alternates roles at intervals.
+
+```bash
+# Default 10-minute intervals
+claude-flow pair --start --mode switch
+
+# 5-minute intervals (rapid)
+claude-flow pair --start --mode switch --interval 5m
+
+# 15-minute intervals (deep focus)
+claude-flow pair --start --mode switch --interval 15m
+```
+
+**Handoff Process:**
+1. 30-second warning before switch
+2. Current driver completes thought
+3. Context summary generated
+4. Roles swap smoothly
+5. New driver continues
+
+**Best For:**
+- Balanced collaboration
+- Knowledge sharing
+- Complex features
+- Extended sessions
+
+#### Specialized Modes
+
+**TDD Mode** - Test-Driven Development:
+```bash
+claude-flow pair --start \
+  --mode tdd \
+  --test-first \
+  --coverage 100
+```
+Workflow: Write failing test → Implement → Refactor → Repeat
+
+**Review Mode** - Continuous code review:
+```bash
+claude-flow pair --start \
+  --mode review \
+  --strict \
+  --security
+```
+Features: Real-time feedback, security scanning, performance analysis
+
+**Mentor Mode** - Learning-focused:
+```bash
+claude-flow pair --start \
+  --mode mentor \
+  --explain-all \
+  --pace slow
+```
+Features: Detailed explanations, step-by-step guidance, pattern teaching
+
+**Debug Mode** - Problem-solving:
+```bash
+claude-flow pair --start \
+  --mode debug \
+  --verbose \
+  --trace
+```
+Features: Issue identification, root cause analysis, fix suggestions
+
+### In-Session Commands
+
+#### Code Commands
+```
+/explain [--level basic|detailed|expert]
+  Explain the current code or selection
+
+/suggest [--type refactor|optimize|security|style]
+  Get improvement suggestions
+
+/implement <description>
+  Request implementation (navigator mode)
+
+/refactor [--pattern <pattern>] [--scope function|file|module]
+  Refactor selected code
+
+/optimize [--target speed|memory|both]
+  Optimize code for performance
+
+/document [--format jsdoc|markdown|inline]
+  Add documentation to code
+
+/comment [--verbose]
+  Add inline comments
+
+/pattern <pattern-name> [--example]
+  Apply a design pattern
+```
+
+#### Testing Commands
+```
+/test [--watch] [--coverage] [--only <pattern>]
+  Run test suite
+
+/test-gen [--type unit|integration|e2e]
+  Generate tests for current code
+
+/coverage [--report html|json|terminal]
+  Check test coverage
+
+/mock <target> [--realistic]
+  Generate mock data or functions
+
+/test-watch [--on-save]
+  Enable test watching
+
+/snapshot [--update]
+  Create test snapshots
+```
+
+#### Review Commands
+```
+/review [--scope current|file|changes] [--strict]
+  Perform code review
+
+/security [--deep] [--fix]
+  Security analysis
+
+/perf [--profile] [--suggestions]
+  Performance analysis
+
+/quality [--detailed]
+  Check code quality metrics
+
+/lint [--fix] [--config <config>]
+  Run linters
+
+/complexity [--threshold <value>]
+  Analyze code complexity
+```
+
+#### Navigation Commands
+```
+/goto <file>[:line[:column]]
+  Navigate to file or location
+
+/find <pattern> [--regex] [--case-sensitive]
+  Search in project
+
+/recent [--limit <n>]
+  Show recent files
+
+/bookmark [add|list|goto|remove] [<name>]
+  Manage bookmarks
+
+/history [--limit <n>] [--filter <pattern>]
+  Show command history
+
+/tree [--depth <n>] [--filter <pattern>]
+  Show project structure
+```
+
+#### Git Commands
+```
+/diff [--staged] [--file <file>]
+  Show git diff
+
+/commit [--message <msg>] [--amend]
+  Commit with verification
+
+/branch [create|switch|delete|list] [<name>]
+  Branch operations
+
+/stash [save|pop|list|apply] [<message>]
+  Stash operations
+
+/log [--oneline] [--limit <n>]
+  View git log
+
+/blame [<file>]
+  Show git blame
+```
+
+#### AI Partner Commands
+```
+/agent [switch|info|config] [<agent-name>]
+  Manage AI agent
+
+/teach <preference>
+  Teach the AI your preferences
+
+/feedback [positive|negative] <message>
+  Provide feedback to AI
+
+/personality [professional|friendly|concise|verbose]
+  Adjust AI personality
+
+/expertise [add|remove|list] [<domain>]
+  Set AI expertise focus
+```
+
+#### Metrics Commands
+```
+/metrics [--period today|session|week|all]
+  Show session metrics
+
+/score [--breakdown]
+  Show quality scores
+
+/productivity [--chart]
+  Show productivity metrics
+
+/leaderboard [--personal|team]
+  Show improvement leaderboard
+```
+
+#### Role & Mode Commands
+```
+/switch [--immediate]
+  Switch driver/navigator roles
+
+/mode <type>
+  Change mode (driver|navigator|switch|tdd|review|mentor|debug)
+
+/role
+  Show current role
+
+/handoff
+  Prepare role handoff
+```
+
+### Command Shortcuts
+
+| Alias | Full Command |
+|-------|-------------|
+| `/s` | `/suggest` |
+| `/e` | `/explain` |
+| `/t` | `/test` |
+| `/r` | `/review` |
+| `/c` | `/commit` |
+| `/g` | `/goto` |
+| `/f` | `/find` |
+| `/h` | `/help` |
+| `/sw` | `/switch` |
+| `/st` | `/status` |
+
+### Configuration
+
+#### Basic Configuration
+Create `.claude-flow/pair-config.json`:
+
+```json
+{
+  "pair": {
+    "enabled": true,
+    "defaultMode": "switch",
+    "defaultAgent": "auto",
+    "autoStart": false,
+    "theme": "professional"
+  }
+}
+```
+
+#### Complete Configuration
+
+```json
+{
+  "pair": {
+    "general": {
+      "enabled": true,
+      "defaultMode": "switch",
+      "defaultAgent": "senior-dev",
+      "language": "javascript",
+      "timezone": "UTC"
+    },
+
+    "modes": {
+      "driver": {
+        "enabled": true,
+        "suggestions": true,
+        "realTimeReview": true,
+        "autoComplete": false
+      },
+      "navigator": {
+        "enabled": true,
+        "codeGeneration": true,
+        "explanations": true,
+        "alternatives": true
+      },
+      "switch": {
+        "enabled": true,
+        "interval": "10m",
+        "warning": "30s",
+        "autoSwitch": true,
+        "pauseOnIdle": true
+      }
+    },
+
+    "verification": {
+      "enabled": true,
+      "threshold": 0.95,
+      "autoRollback": true,
+      "preCommitCheck": true,
+      "continuousMonitoring": true,
+      "blockOnFailure": true
+    },
+
+    "testing": {
+      "enabled": true,
+      "autoRun": true,
+      "framework": "jest",
+      "onSave": true,
+      "coverage": {
+        "enabled": true,
+        "minimum": 80,
+        "enforce": true,
+        "reportFormat": "html"
+      }
+    },
+
+    "review": {
+      "enabled": true,
+      "continuous": true,
+      "preCommit": true,
+      "security": true,
+      "performance": true,
+      "style": true,
+      "complexity": {
+        "maxComplexity": 10,
+        "maxDepth": 4,
+        "maxLines": 100
+      }
+    },
+
+    "git": {
+      "enabled": true,
+      "autoCommit": false,
+      "commitTemplate": "feat: {message}",
+      "signCommits": false,
+      "pushOnEnd": false,
+      "branchProtection": true
+    },
+
+    "session": {
+      "autoSave": true,
+      "saveInterval": "5m",
+      "maxDuration": "4h",
+      "idleTimeout": "15m",
+      "breakReminder": "45m",
+      "metricsInterval": "1m"
+    },
+
+    "ai": {
+      "model": "advanced",
+      "temperature": 0.7,
+      "maxTokens": 4000,
+      "personality": "professional",
+      "expertise": ["backend", "testing", "security"],
+      "learningEnabled": true
+    }
+  }
+}
+```
+
+#### Built-in Agents
+
+```json
+{
+  "agents": {
+    "senior-dev": {
+      "expertise": ["architecture", "patterns", "optimization"],
+      "style": "thorough",
+      "reviewLevel": "strict"
+    },
+    "tdd-specialist": {
+      "expertise": ["testing", "mocks", "coverage"],
+      "style": "test-first",
+      "reviewLevel": "comprehensive"
+    },
+    "debugger-expert": {
+      "expertise": ["debugging", "profiling", "tracing"],
+      "style": "analytical",
+      "reviewLevel": "focused"
+    },
+    "junior-dev": {
+      "expertise": ["learning", "basics", "documentation"],
+      "style": "questioning",
+      "reviewLevel": "educational"
+    }
+  }
+}
+```
+
+#### CLI Configuration
+```bash
+# Set configuration
+claude-flow pair config set defaultMode switch
+claude-flow pair config set verification.threshold 0.98
+
+# Get configuration
+claude-flow pair config get
+claude-flow pair config get defaultMode
+
+# Export/Import
+claude-flow pair config export > config.json
+claude-flow pair config import config.json
+
+# Reset
+claude-flow pair config reset
+```
+
+#### Profile Management
+
+Create reusable profiles:
+
+```bash
+# Create profile
+claude-flow pair profile create refactoring \
+  --mode driver \
+  --verify true \
+  --threshold 0.98 \
+  --focus refactor
+
+# Use profile
+claude-flow pair --start --profile refactoring
+
+# List profiles
+claude-flow pair profile list
+```
+
+Profile configuration:
+```json
+{
+  "profiles": {
+    "refactoring": {
+      "mode": "driver",
+      "verification": {
+        "enabled": true,
+        "threshold": 0.98
+      },
+      "focus": "refactor"
+    },
+    "debugging": {
+      "mode": "navigator",
+      "agent": "debugger-expert",
+      "trace": true,
+      "verbose": true
+    },
+    "learning": {
+      "mode": "mentor",
+      "pace": "slow",
+      "explanations": "detailed",
+      "examples": true
+    }
+  }
+}
+```
+
+### Real-World Examples
+
+#### Example 1: Feature Implementation
+
+Implementing user authentication with JWT tokens:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode switch \
+  --agent senior-dev \
+  --focus implement \
+  --verify \
+  --test
+```
+
+**Session Flow:**
+```
+👥 Starting pair programming for authentication feature...
+
+[DRIVER: You - 10 minutes]
+/explain JWT authentication flow
+> AI explains JWT concepts and best practices
+
+/suggest implementation approach
+> AI suggests using middleware pattern with refresh tokens
+
+# You write the basic auth middleware structure
+
+[SWITCH TO NAVIGATOR]
+
+[NAVIGATOR: AI - 10 minutes]
+/implement JWT token generation with refresh tokens
+> AI generates secure token implementation
+
+/test-gen
+> AI creates comprehensive test suite
+
+[SWITCH TO DRIVER]
+
+[DRIVER: You - 10 minutes]
+# You refine the implementation
+/review --security
+> AI performs security review, suggests improvements
+
+/commit --message "feat: JWT authentication with refresh tokens"
+✅ Truth Score: 0.98 - Committed successfully
+```
+
+#### Example 2: Bug Fixing
+
+Debugging a memory leak in Node.js:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode navigator \
+  --agent debugger-expert \
+  --focus debug \
+  --trace
+```
+
+**Session Flow:**
+```
+👥 Starting debugging session...
+
+/status
+> Analyzing application for memory issues...
+
+/perf --profile
+> Memory usage growing: 150MB → 450MB over 10 minutes
+
+/find "new EventEmitter" --regex
+> Found 3 instances of EventEmitter creation
+
+/inspect eventEmitters --deep
+> Discovering listeners not being removed
+
+/suggest fix for memory leak
+> AI suggests: "Add removeListener in cleanup functions"
+
+/implement cleanup functions for all event emitters
+> AI generates proper cleanup code
+
+/test
+> Memory stable at 150MB ✅
+
+/commit --message "fix: memory leak in event emitters"
+```
+
+#### Example 3: TDD Session
+
+Building shopping cart with test-driven development:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode tdd \
+  --agent tdd-specialist \
+  --test-first
+```
+
+**Session Flow:**
+```
+👥 TDD Session: Shopping Cart Feature
+
+[RED PHASE]
+/test-gen "add item to cart"
+> AI writes failing test:
+  ✗ should add item to cart
+  ✗ should update quantity for existing item
+  ✗ should calculate total price
+
+[GREEN PHASE]
+/implement minimal cart functionality
+> You write just enough code to pass tests
+
+/test
+> Tests passing: 3/3 ✅
+
+[REFACTOR PHASE]
+/refactor --pattern repository
+> AI refactors to repository pattern
+
+/test
+> Tests still passing: 3/3 ✅
+
+[NEXT CYCLE]
+/test-gen "remove item from cart"
+> AI writes new failing tests...
+```
+
+#### Example 4: Code Refactoring
+
+Modernizing legacy code:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode driver \
+  --focus refactor \
+  --verify \
+  --threshold 0.98
+```
+
+**Session Flow:**
+```
+👥 Refactoring Session: Modernizing UserService
+
+/analyze UserService.js
+> AI identifies:
+  - Callback hell (5 levels deep)
+  - No error handling
+  - Tight coupling
+  - No tests
+
+/suggest refactoring plan
+> AI suggests:
+  1. Convert callbacks to async/await
+  2. Add error boundaries
+  3. Extract dependencies
+  4. Add unit tests
+
+/test-gen --before-refactor
+> AI generates tests for current behavior
+
+/refactor callbacks to async/await
+# You refactor with AI guidance
+
+/test
+> All tests passing ✅
+
+/review --compare
+> AI shows before/after comparison
+> Code complexity: 35 → 12
+> Truth score: 0.99 ✅
+
+/commit --message "refactor: modernize UserService with async/await"
+```
+
+#### Example 5: Performance Optimization
+
+Optimizing slow React application:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode switch \
+  --agent performance-expert \
+  --focus optimize \
+  --profile
+```
+
+**Session Flow:**
+```
+👥 Performance Optimization Session
+
+/perf --profile
+> React DevTools Profiler Results:
+  - ProductList: 450ms render
+  - CartSummary: 200ms render
+  - Unnecessary re-renders: 15
+
+/suggest optimizations for ProductList
+> AI suggests:
+  1. Add React.memo
+  2. Use useMemo for expensive calculations
+  3. Implement virtualization for long lists
+
+/implement React.memo and useMemo
+# You implement with AI guidance
+
+/perf --profile
+> ProductList: 45ms render (90% improvement!) ✅
+
+/implement virtualization with react-window
+> AI implements virtual scrolling
+
+/perf --profile
+> ProductList: 12ms render (97% improvement!) ✅
+> FPS: 60 stable ✅
+
+/commit --message "perf: optimize ProductList with memoization and virtualization"
+```
+
+#### Example 6: API Development
+
+Building RESTful API with Express:
+
+```bash
+# Session setup
+claude-flow pair --start \
+  --mode navigator \
+  --agent backend-expert \
+  --focus implement \
+  --test
+```
+
+**Session Flow:**
+```
+👥 API Development Session
+
+/design REST API for blog platform
+> AI designs endpoints:
+  POST   /api/posts
+  GET    /api/posts
+  GET    /api/posts/:id
+  PUT    /api/posts/:id
+  DELETE /api/posts/:id
+
+/implement CRUD endpoints with validation
+> AI implements with Express + Joi validation
+
+/test-gen --integration
+> AI generates integration tests
+
+/security --api
+> AI adds:
+  - Rate limiting
+  - Input sanitization
+  - JWT authentication
+  - CORS configuration
+
+/document --openapi
+> AI generates OpenAPI documentation
+
+/test --integration
+> All endpoints tested: 15/15 ✅
+```
+
+### Session Templates
+
+#### Quick Start Templates
+
+```bash
+# Refactoring template
+claude-flow pair --template refactor
+# Focus: Code improvement
+# Verification: High (0.98)
+# Testing: After each change
+# Review: Continuous
+
+# Feature template
+claude-flow pair --template feature
+# Focus: Implementation
+# Verification: Standard (0.95)
+# Testing: On completion
+# Review: Pre-commit
+
+# Debug template
+claude-flow pair --template debug
+# Focus: Problem solving
+# Verification: Moderate (0.90)
+# Testing: Regression tests
+# Review: Root cause
+
+# Learning template
+claude-flow pair --template learn
+# Mode: Mentor
+# Pace: Slow
+# Explanations: Detailed
+# Examples: Many
+```
+
+### Session Management
+
+#### Session Status
+
+```bash
+claude-flow pair --status
+```
+
+**Output:**
+```
+👥 Pair Programming Session
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Session ID: pair_1755021234567
+Duration: 45 minutes
+Status: Active
+
+Partner: senior-dev
+Current Role: DRIVER (you)
+Mode: Switch (10m intervals)
+Next Switch: in 3 minutes
+
+📊 Metrics:
+├── Truth Score: 0.982 ✅
+├── Lines Changed: 234
+├── Files Modified: 5
+├── Tests Added: 12
+├── Coverage: 87% ↑3%
+└── Commits: 3
+
+🎯 Focus: Implementation
+📝 Current File: src/auth/login.js
+```
+
+#### Session History
+
+```bash
+claude-flow pair --history
+```
+
+**Output:**
+```
+📚 Session History
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+1. 2024-01-15 14:30 - 16:45 (2h 15m)
+   Partner: expert-coder
+   Focus: Refactoring
+   Truth Score: 0.975
+   Changes: +340 -125 lines
+
+2. 2024-01-14 10:00 - 11:30 (1h 30m)
+   Partner: tdd-specialist
+   Focus: Testing
+   Truth Score: 0.991
+   Tests Added: 24
+
+3. 2024-01-13 15:00 - 17:00 (2h)
+   Partner: debugger-expert
+   Focus: Bug Fixing
+   Truth Score: 0.968
+   Issues Fixed: 5
+```
+
+#### Session Persistence
+
+```bash
+# Save session
+claude-flow pair --save [--name <name>]
+
+# Load session
+claude-flow pair --load <session-id>
+
+# Export session
+claude-flow pair --export <session-id> [--format json|md]
+
+# Generate report
+claude-flow pair --report <session-id>
+```
+
+#### Background Sessions
+
+```bash
+# Start in background
+claude-flow pair --start --background
+
+# Monitor background session
+claude-flow pair --monitor
+
+# Attach to background session
+claude-flow pair --attach <session-id>
+
+# End background session
+claude-flow pair --end <session-id>
+```
+
+### Advanced Features
+
+#### Custom Commands
+
+Define in configuration:
+
+```json
+{
+  "customCommands": {
+    "tdd": "/test-gen && /test --watch",
+    "full-review": "/lint --fix && /test && /review --strict",
+    "quick-fix": "/suggest --type fix && /implement && /test"
+  }
+}
+```
+
+Use custom commands:
+```
+/custom tdd
+/custom full-review
+```
+
+#### Command Chaining
+
+```
+/test && /commit && /push
+/lint --fix && /test && /review --strict
+```
+
+#### Session Recording
+
+```bash
+# Start with recording
+claude-flow pair --start --record
+
+# Replay session
+claude-flow pair --replay <session-id>
+
+# Session analytics
+claude-flow pair --analytics <session-id>
+```
+
+#### Integration Options
+
+**With Git:**
+```bash
+claude-flow pair --start --git --auto-commit
+```
+
+**With CI/CD:**
+```bash
+claude-flow pair --start --ci --non-interactive
+```
+
+**With IDE:**
+```bash
+claude-flow pair --start --ide vscode
+```
+
+### Best Practices
+
+#### Session Practices
+1. **Clear Goals** - Define session objectives upfront
+2. **Appropriate Mode** - Choose based on task type
+3. **Enable Verification** - For critical code paths
+4. **Regular Testing** - Maintain quality continuously
+5. **Session Notes** - Document important decisions
+6. **Regular Breaks** - Take breaks every 45-60 minutes
+
+#### Code Practices
+1. **Test Early** - Run tests after each change
+2. **Verify Before Commit** - Check truth scores
+3. **Review Security** - Always for sensitive code
+4. **Profile Performance** - Use `/perf` for optimization
+5. **Save Sessions** - For complex work
+6. **Learn from AI** - Ask questions frequently
+
+#### Mode Selection
+- **Driver Mode**: When learning, controlling implementation
+- **Navigator Mode**: For rapid prototyping, generation
+- **Switch Mode**: Long sessions, balanced collaboration
+- **TDD Mode**: Building with tests
+- **Review Mode**: Quality focus
+- **Mentor Mode**: Learning priority
+- **Debug Mode**: Fixing issues
+
+### Troubleshooting
+
+#### Session Won't Start
+- Check agent availability
+- Verify configuration file syntax
+- Ensure clean workspace
+- Review log files
+
+#### Session Disconnected
+- Use `--recover` to restore
+- Check network connection
+- Verify background processes
+- Review auto-save files
+
+#### Poor Performance
+- Reduce verification threshold
+- Disable continuous testing
+- Check system resources
+- Use lighter AI model
+
+#### Configuration Issues
+- Validate JSON syntax
+- Check file permissions
+- Review priority order (CLI > env > project > user > global)
+- Run `claude-flow pair config validate`
+
+### Quality Metrics
+
+#### Truth Score Thresholds
+```
+Error:   < 0.90 ❌
+Warning: 0.90 - 0.95 ⚠️
+Good:    0.95 - 0.98 ✅
+Excellent: > 0.98 🌟
+```
+
+#### Coverage Thresholds
+```
+Error:   < 70% ❌
+Warning: 70% - 80% ⚠️
+Good:    80% - 90% ✅
+Excellent: > 90% 🌟
+```
+
+#### Complexity Thresholds
+```
+Error:   > 15 ❌
+Warning: 10 - 15 ⚠️
+Good:    5 - 10 ✅
+Excellent: < 5 🌟
+```
+
+### Environment Variables
+
+Override configuration via environment:
+
+```bash
+export CLAUDE_PAIR_MODE=driver
+export CLAUDE_PAIR_VERIFY=true
+export CLAUDE_PAIR_THRESHOLD=0.98
+export CLAUDE_PAIR_AGENT=senior-dev
+export CLAUDE_PAIR_AUTO_TEST=true
+```
+
+### Command History
+
+Navigate history:
+- `↑/↓` - Navigate through command history
+- `Ctrl+R` - Search command history
+- `!!` - Repeat last command
+- `!<n>` - Run command n from history
+
+### Keyboard Shortcuts (Configurable)
+
+Default shortcuts:
+```json
+{
+  "shortcuts": {
+    "switch": "ctrl+shift+s",
+    "suggest": "ctrl+space",
+    "review": "ctrl+r",
+    "test": "ctrl+t"
+  }
+}
+```
+
+### Related Commands
+
+- `claude-flow pair --help` - Show help
+- `claude-flow pair config` - Manage configuration
+- `claude-flow pair profile` - Manage profiles
+- `claude-flow pair templates` - List templates
+- `claude-flow pair agents` - List available agents