pair-programming

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

# Start simple pair programming
claude-flow pair --start

TDD Session

# Test-driven development
claude-flow pair --start \
  --mode tdd \
  --test-first \
  --coverage 90

---

Complete Guide

Session Control Commands

Starting Sessions

# 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

# 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.

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.

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.

# 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:

claude-flow pair --start \
  --mode tdd \
  --test-first \
  --coverage 100

Workflow: Write failing test → Implement → Refactor → Repeat

Review Mode - Continuous code review:

claude-flow pair --start \
  --mode review \
  --strict \
  --security

Features: Real-time feedback, security scanning, performance analysis

Mentor Mode - Learning-focused:

claude-flow pair --start \
  --mode mentor \
  --explain-all \
  --pace slow

Features: Detailed explanations, step-by-step guidance, pattern teaching

Debug Mode - Problem-solving:

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

Configuration

Basic Configuration

Create .claude-flow$pair-config.json:

{
  "pair": {
    "enabled": true,
    "defaultMode": "switch",
    "defaultAgent": "auto",
    "autoStart": false,
    "theme": "professional"
  }
}

Complete Configuration

{
  "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

{
  "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

# 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:

# 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:

{
  "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:

# 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:

# 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:

# 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:

# 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:

# 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:

# 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

# 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

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

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

# 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

# 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:

{
  "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

# 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:

claude-flow pair --start --git --auto-commit

With CI/CD:

claude-flow pair --start --ci --non-interactive

With IDE:

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:

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:

{
  "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