Conductor-Beads: Command for Claude Code

Conductor Handoff

Create a comprehensive context handoff document when you need to transfer implementation progress to a new section or session. Essential for large tracks that span multiple AI context windows.

1. Identify Active Track

• Find track marked [~] in conductor/tracks.md
• If no active track, ask user to specify or halt
• Load spec.md, plan.md, and implement_state.json
• Check for parallel_state.json (indicates parallel execution in progress)

1a. Parallel Execution Check

If parallel_state.json exists:

"⚠️ This track has parallel workers currently running:" [List workers and their status]

"A) Wait for workers to complete before handoff" "B) Create handoff anyway (workers will continue)" "C) Cancel handoff"

• If A: Monitor parallel_state.json until all complete, then proceed
• If B: Include parallel state in handoff document
• If C: HALT

2. Gather Handoff Context

Progress Analysis:

• Count completed [x], in-progress [~], pending [ ] tasks
• Calculate overall percentage
• Identify current phase and task position

Recent Changes:

git log --oneline -10
git diff --name-only HEAD~5

Unresolved Issues:

• Check for [!] blocked markers in plan.md
• Read blockers.md if exists
• Ask user for any pending decisions or important context

3. Update Implementation State

Update conductor/tracks/<track_id>/implement_state.json with section tracking:

{
  "current_phase": "...",
  "current_phase_index": 1,
  "current_task_index": 3,
  "completed_phases": ["Phase 1"],
  "section_count": 2,
  "last_handoff": "<ISO timestamp>",
  "handoff_history": [
    {
      "section": 1,
      "timestamp": "...",
      "phase_at_handoff": "...",
      "task_at_handoff": 5,
      "handoff_file": "handoff_<timestamp>.md"
    }
  ],
  "status": "handed_off"
}

4. Create Handoff Document

Create conductor/tracks/<track_id>/handoff_<YYYYMMDD_HHMMSS>.md with:

• Header: Track info, section number, timestamp, link to previous handoff
• Thread URL: Current Amp thread URL ($AMP_CURRENT_THREAD_ID) for context retrieval
• Progress Summary: Overall %, current phase/task, completed/remaining tasks
• Parallel Execution State: (if applicable) Worker status, file locks, pending workers
• Key Implementation Decisions: Important choices made during this section
• Code Changes Summary: Files modified, new files, recent commits
• Learnings Extracted: Key patterns/gotchas from learnings.md this section
• Unresolved Issues: Blockers, pending decisions, questions
• Context for Next Section: Critical info, architecture notes, testing status
• Next Steps: Immediate tasks, upcoming phase work
• Resume Instructions: Commands and specific actions to continue