start-pairing

Start Pairing Command

Manages pair programming sessions with structured knowledge transfer. Tracks driver/navigator roles, captures decisions and learnings, and produces session summaries.

Usage

/start-pairing [TICKET_ID] [--topic TOPIC] [--end] [--slack] [--remote]
/start-pairing --end                    # End active pairing session
/start-pairing --list                   # List recent pair sessions

Options:

• TICKET_ID: Jira ticket ID for context (optional, topic required if omitted)
• --topic TOPIC: Free-form topic name if not ticket-based
• --end: End the current active session
• --slack: Post session summary to Slack
• --remote: Async pairing mode (leave notes for partner)
• --list: Show recent pairing sessions

Phase 1: Session Setup

// Check for active session
const getActiveSession = () => {
  const sessionDir = '.claude/sessions';
  if (!fs.existsSync(sessionDir)) {
    return null;
  }

  const files = fs.readdirSync(sessionDir)
    .filter(f => f.startsWith('pair-') && f.endsWith('.md'));

  if (!files.length) return null;

  // Get most recent
  const latest = files.sort().pop();
  const content = fs.readFileSync(`${sessionDir}/${latest}`, 'utf8');

  // Check if session is still active (no end marker)
  if (!content.includes('## Session End')) {
    return {
      file: `${sessionDir}/${latest}`,
      data: content
    };
  }

  return null;
};

// Handle --end flag
if (args.includes('--end')) {
  const active = getActiveSession();
  if (!active) {
    console.log('❌ No active pairing session found');
    return;
  }

  console.log('🛑 Ending pairing session...');
  // Jump to Phase 4
  await endSession(active.file);
  return;
}

// Handle --list flag
if (args.includes('--list')) {
  const sessionDir = '.claude/sessions';
  if (!fs.existsSync(sessionDir)) {
    console.log('No session history');
    return;
  }

  const files = fs.readdirSync(sessionDir)
    .filter(f => f.startsWith('pair-') && f.endsWith('.md'))
    .sort()
    .reverse();

  console.log('\n📋 Recent Pairing Sessions:\n');
  files.slice(0, 10).forEach(f => {
    const content = fs.readFileSync(`${sessionDir}/${f}`, 'utf8');
    const match = content.match(/^# Pair Session: (.+)$/m);
    const title = match ? match[1] : f;
    console.log(`- ${f.replace('.md', '')}\n  ${title}`);
  });
  return;
}

// Detect active session
const activeSession = getActiveSession();
if (activeSession && !args[0]) {
  console.log('⚠️  Active pairing session detected:');
  console.log(activeSession.data.split('\n').slice(0, 5).join('\n'));
  console.log('Use /start-pairing --end to end it, or /start-pairing TICKET to start new');
  return;
}

console.log('\n🚀 Starting pair programming session...\n');

// Get ticket ID or topic
let ticketId = args[0];
let topic = null;

if (ticketId && !ticketId.match(/[A-Z]+-\d+/)) {
  topic = ticketId;
  ticketId = null;
} else if (args.includes('--topic')) {
  const idx = args.indexOf('--topic');
  topic = args[idx + 1];
}

if (!ticketId && !topic) {
  ticketId = await prompt('Ticket ID (or press enter for free topic): ');
  if (!ticketId) {
    topic = await prompt('Topic for this pairing session: ');
  }
}

// Get participants
console.log('\n👥 Pairing Participants\n');

const driver = await prompt('Driver name (who\'s coding): ');
if (!driver) {
  console.log('❌ Driver name required');
  return;
}

const navigator = await prompt('Navigator name (who\'s reviewing/guiding): ');
if (!navigator) {
  console.log('❌ Navigator name required');
  return;
}

// Get session goal
const goal = await prompt('\n🎯 Session goal or focus area: ');
const timeBox = await prompt('Time box in minutes (optional): ') || '60';

console.log('✓ Session configured\n');

// Create session directory
const sessionDir = '.claude/sessions';
if (!fs.existsSync(sessionDir)) {
  fs.mkdirSync(sessionDir, { recursive: true });
}

// Create session file
const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, -5);
const sessionFile = `${sessionDir}/pair-${timestamp}.md`;

const sessionTitle = ticketId ? `${ticketId} - ${goal}` : `${topic} - ${goal}`;

const initialContent = `# Pair Session: ${sessionTitle}

**Started**: ${new Date().toISOString()}
**Driver**: ${driver}
**Navigator**: ${navigator}
**Time Box**: ${timeBox} minutes
${ticketId ? `**Ticket**: ${ticketId}` : `**Topic**: ${topic}`}

## Session Context

(Loading context...)

## Decisions Made

(Decisions will be tracked here)

## Code Changes

(Summary of code modifications)

## Learnings

(Key learnings and patterns discovered)

## Open Questions

(Unresolved issues or follow-ups)

## Session Notes

(Ongoing session notes)

`;

fs.writeFileSync(sessionFile, initialContent);
console.log(`📝 Session file: ${sessionFile}\n`);

// Store active session reference
const activeFile = `${sessionDir}/.active`;
fs.writeFileSync(activeFile, sessionFile);