Resume work from a handoff document

Prerequisites

# Check project setup (thoughts, CLAUDE.md snippet, config)
if [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" ]]; then
  "${CLAUDE_PLUGIN_ROOT}/scripts/check-project-setup.sh" || exit 1
fi

# Auto-discover most recent handoff. Three-source waterfall:
#   1. CATALYST_HANDOFF_PATH env var (CTL-484 continuation-worker contract —
#      set by orchestrate-revive's continuation branch when it spawns
#      `claude --bg --resume` after a turn-cap exhaustion).
#   2. workflow-context.sh recent handoffs (interactive flows).
#   3. (handled later in Step 4) interactive picker.
RECENT_HANDOFF=""
if [[ -n "${CATALYST_HANDOFF_PATH:-}" && -f "$CATALYST_HANDOFF_PATH" ]]; then
  RECENT_HANDOFF="$CATALYST_HANDOFF_PATH"
elif [[ -f "${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" ]]; then
  RECENT_HANDOFF=$("${CLAUDE_PLUGIN_ROOT}/scripts/workflow-context.sh" recent handoffs)
fi
if [[ -n "$RECENT_HANDOFF" ]]; then
  if [[ "${CATALYST_IS_CONTINUATION:-}" == "true" ]]; then
    echo "📋 Continuation worker — resuming from CATALYST_HANDOFF_PATH: $RECENT_HANDOFF"
  else
    echo "📋 Auto-discovered recent handoff: $RECENT_HANDOFF"
  fi
else
  echo "⚠️ No recent handoff found in workflow context or filesystem"
fi

Configuration Note

This command uses ticket references like PROJ-123. Replace PROJ with your Linear team's ticket prefix:

• Read from .catalyst/config.json if available
• Otherwise use a generic format like TICKET-XXX
• Examples: ENG-123, FEAT-456, BUG-789

You are tasked with resuming work from a handoff document through an interactive process. These handoffs contain critical context, learnings, and next steps from previous work sessions that need to be understood and continued.

Initial Response

Auto-discovery has already run in Prerequisites above. Check its output and follow this priority:

0. If CATALYST_IS_CONTINUATION=true AND CATALYST_HANDOFF_PATH is set (CTL-484 continuation-worker contract from orchestrate-revive): the env-var hook in Prerequisites already selected the handoff. Skip directly to Step 3 without prompting the user — this is a background-dispatched continuation, not an interactive resume. Confirmation gates would hang the worker.

1. If user provided a file path as parameter: Use the provided path (user override). Skip to Step 3.

2. If user provided a ticket number (like PROJ-123):

   • Run humanlayer thoughts sync to ensure thoughts/ is up to date
   • Look in thoughts/shared/handoffs/PROJ-123/ directory
   • List all handoffs for that ticket
   • If multiple exist, use the most recent (by timestamp in filename YYYY-MM-DD_HH-MM-SS)
   • If none exist, tell user and wait for input
   • Skip to Step 3

3. If no parameters provided AND Prerequisites output shows a discovered handoff (📋):

   • Show user the discovered path
   • Ask: "Proceed with this handoff? [Y/n]"
   • If yes: use it and skip to Step 3
   • If no: proceed to option 4

4. If no parameters AND Prerequisites shows no handoff found (⚠️):

   • List available handoffs from thoughts/shared/handoffs/
   • Show most recent 5 handoffs with dates
   • Ask user which one to use
   • Wait for user input with path or ticket number

STEP 3: Analyze the handoff

Once you have a handoff path:

• Read the handoff document FULLY (no limit/offset)
• Immediately read any research or plan documents it references
• Do NOT use sub-agents to read these critical files
• Ingest all context from the handoff
• Propose course of action to user
• Get confirmation before proceeding

Process Steps

Step 1: Read and Analyze Handoff

1. Read handoff document completely:

   • Use the Read tool WITHOUT limit/offset parameters
   • Extract all sections:
     • Task(s) and their statuses
     • Recent changes
     • Learnings
     • Artifacts
     • Action items and next steps
     • Other notes

2. Spawn focused research tasks: Based on the handoff content, spawn parallel research tasks to verify current state:

   Task 1 - Verify recent changes:
   Check if the recent changes mentioned in the handoff still exist.
   1. Verify files mentioned in "Recent changes" section
   2. Check if the described changes are still present
   3. Look for any subsequent modifications
   4. Identify any conflicts or regressions
   Use tools: Read, Grep, Glob
   Return: Current state of recent changes with file:line references
   

   Task 2 - Validate current codebase state:
   Verify the current state against what's described in the handoff.
   1. Check files mentioned in "Learnings" section
   2. Verify patterns and implementations still exist
   3. Look for any breaking changes since handoff
   4. Identify new related code added since handoff
   Use tools: Read, Grep, Glob
   Return: Validation results and any discrepancies found
   

   Task 3 - Gather artifact context:
   Read all artifacts mentioned in the handoff.
   1. Read feature documents listed in "Artifacts"
   2. Read implementation plans referenced
   3. Read any research documents mentioned
   4. Extract key requirements and decisions
   Use tools: Read
   Return: Summary of artifact contents and key decisions
   

3. Wait for ALL sub-tasks to complete before proceeding

4. Read critical files identified:

   • Read files from "Learnings" section completely
   • Read files from "Recent changes" to understand modifications
   • Read any new related files discovered during research

Step 2: Synthesize and Present Analysis

1. Present comprehensive analysis:

   I've analyzed the handoff from [date] by [researcher]. Here's the current situation:
   
   **Original Tasks:**
   - [Task 1]: [Status from handoff] → [Current verification]
   - [Task 2]: [Status from handoff] → [Current verification]
   
   **Key Learnings Validated:**
   - [Learning with file:line reference] - [Still valid/Changed]
   - [Pattern discovered] - [Still applicable/Modified]
   
   **Recent Changes Status:**
   - [Change 1] - [Verified present/Missing/Modified]
   - [Change 2] - [Verified present/Missing/Modified]
   
   **Artifacts Reviewed:**
   - [Document 1]: [Key takeaway]
   - [Document 2]: [Key takeaway]
   
   **Recommended Next Actions:**
   Based on the handoff's action items and current state:
   1. [Most logical next step based on handoff]
   2. [Second priority action]
   3. [Additional tasks discovered]
   
   **Potential Issues Identified:**
   - [Any conflicts or regressions found]
   - [Missing dependencies or broken code]
   
   Shall I proceed with [recommended action 1], or would you like to adjust the approach?
   

2. Get confirmation before proceeding

Step 3: Create Action Plan

1. Use TodoWrite to create task list:

   • Convert action items from handoff into todos
   • Add any new tasks discovered during analysis
   • Prioritize based on dependencies and handoff guidance

2. Present the plan:

   I've created a task list based on the handoff and current analysis:
   
   [Show todo list]
   
   Ready to begin with the first task: [task description]?
   

Step 4: Begin Implementation

1. Start with the first approved task
2. Reference learnings from handoff throughout implementation
3. Apply patterns and approaches documented in the handoff
4. Update progress as tasks are completed

CLI Tools

When you need to fetch ticket context from Linear (e.g., reading a ticket referenced in the handoff), use the Linearis CLI. For exact syntax, run linearis issues usage or see /catalyst-dev:linearis — do not guess commands.

Guidelines

1. Be Thorough in Analysis:

   • Read the entire handoff document first
   • Verify ALL mentioned changes still exist
   • Check for any regressions or conflicts
   • Read all referenced artifacts

2. Be Interactive:

   • Present findings before starting work
   • Ge