pickup

Pickup — Agent Context Reconstruction

Reconstruct working context from handoff records, active agent state, and repo history. Inspired by Smith's loop startup protocol — each iteration starts fresh, reconstructs state from the repository, not from model memory.

Pickup is the inverse of handoff. Where handoff externalizes context, pickup internalizes it.

When to Use This Skill

• Starting a new session on a project that has prior handoff records
• Entering a worktree to continue someone else's work
• After a context compression to rebuild awareness
• When you need to understand what parallel agents have done or are doing
• First thing in a new session before writing any code

When NOT to Use This Skill

• No .claude/handoff/ directory exists — there's nothing to pick up
• You just handed off and are continuing in the same session — you already have context
• Quick one-off tasks that don't need project history
• The project has never used the handoff/pickup protocol

The 4 Steps (MANDATORY)

Step 1: Locate Shared Coordination Space (REQUIRED)

Find the main worktree and verify handoff data exists:

MAIN_WORKTREE=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
HANDOFF_DIR="${MAIN_WORKTREE}/.claude/handoff"

Check what's available:

# Does the handoff directory exist?
ls "${HANDOFF_DIR}/" 2>/dev/null

# Who's currently active?
ls "${HANDOFF_DIR}/active/" 2>/dev/null

# What handoffs exist?
ls "${HANDOFF_DIR}/handoffs/" 2>/dev/null

If ${HANDOFF_DIR} doesn't exist, report "No handoff history found" and stop. This project hasn't used the protocol yet.

Gate: You've confirmed handoff data exists and know the paths.

Step 2: Read Active Agents (REQUIRED)

Check who's currently working by reading all files in active/:

# List all active agents
for f in "${HANDOFF_DIR}/active/"*.json; do
  cat "$f" 2>/dev/null
done

For each active agent, note:

• Agent name (filename without .json)
• What they're working on (task field)
• What files they claim (touching field)
• Heartbeat freshness — if heartbeat + 30 minutes < now, consider the agent dead (ghost presence). Flag it but don't delete it.

Build a summary: "N agents currently active. Agent X is working on Y, touching files A, B, C."

If there are claimed files that overlap with your planned work, flag the conflict before proceeding.

If the project uses distributed coordination via /coordinate, also check the switchboard repo for active agents and claims. The switchboard has the most current state since it's updated in real-time (vs handoff files which are point-in-time snapshots).

Gate: You know who's active, what they're doing, and whether there are conflicts with your work.

Step 3: Read Handoff Records (REQUIRED)

Read handoff records in reverse chronological order (newest first). Start with the HANDOFFS.md index:

cat "${HANDOFF_DIR}/HANDOFFS.md" 2>/dev/null

Then read the most recent handoff from each agent directory:

for agent_dir in "${HANDOFF_DIR}/handoffs/"*/; do
  AGENT=$(basename "$agent_dir")
  LATEST=$(ls "$agent_dir" | sort -n | tail -1)
  echo "=== ${AGENT} (${LATEST}) ==="
  cat "${agent_dir}/${LATEST}"
done

For each handoff, extract:

• What was completed (Done section)
• What remains (Remaining section) — this is your potential starting point
• What was decided (Decisions section) — respect these unless you have reason to override
• What files were key (Key Files section) — read these first when starting work

Reconciliation (CRITICAL)

Do NOT blindly trust handoffs. Verify against current repo state:

1. Check if remaining items are still remaining: git log --oneline {handoff_sha}..HEAD — has someone else completed them since?
2. Check if decisions still hold: Are the files mentioned in Key Files still structured the way the decision describes?
3. Check for reverts: git log --oneline --grep="revert" {handoff_sha}..HEAD — was the handoff's work reverted?

If a handoff's claims conflict with current repo state, note it in your briefing as "STALE" and explain the discrepancy.

Gate: You have a reconciled view — what's still relevant from handoffs vs. what's changed since.

Step 4: Synthesize Briefing (REQUIRED)

Produce a structured briefing. This is your output — present it to the user or use it to guide your work:

## Pickup Briefing — {project} ({timestamp})

### Active Agents
- {agent-name}: working on {task}, touching {files} (heartbeat: {freshness})
- (or "No active agents")

### Recent Handoffs
- {agent-name} ({timestamp}): {one-line summary}
  - Remaining: {key remaining items}
  - Decisions: {key decisions still in effect}

### Conflicts
- {file/area}: claimed by {agent} AND relevant to your work
- (or "No conflicts detected")

### Stale Records
- {handoff ref}: {what's stale and why}
- (or "All records current")

### Recommended Starting Point
Based on remaining items and current repo state:
1. {Highest priority remaining item}
2. {Next priority item}
3. {Next priority item}

Gate: Briefing is complete, reconciled, and actionable.

After Pickup: Register Your Presence

If you're starting work (not just reading history), write a presence file:

AGENT_NAME="{your-agent-name}"  # worktree name or branch
cat > "${HANDOFF_DIR}/active/${AGENT_NAME}.json" << 'EOF'
{
  "agent": "{agent-name}",
  "branch": "{branch-name}",
  "started": "{ISO-8601}",
  "heartbeat": "{ISO-8601}",
  "task": "{what you're about to work on}",
  "touching": ["{file1}", "{file2}"],
  "status": "working"
}
EOF

This tells other agents you're active. Update the heartbeat field periodically if working for a long session.

Red Flags - STOP

If you catch yourself:

• ❌ Starting to code before reading handoffs — pickup FIRST, code second
• ❌ Trusting a handoff without reconciling against git — handoffs are claims, not truth
• ❌ Ignoring active agent claims — if someone claims a file, coordinate before touching it
• ❌ Reading every handoff ever written — only read the latest per agent, plus any since your last pickup
• ❌ Skipping presence registration — other agents can't coordinate with a ghost

STOP. Complete the full pickup protocol before writing code.

Verification Checklist

Before starting work:

• Checked for active agents and noted any file conflicts
• Read latest handoff from each relevant agent
• Reconciled handoff claims against current git state
• Identified stale records (if any)
• Synthesized briefing with recommended starting point
• Registered your presence in active/ (if starting work)

Best Practices

1. Run pickup at session start, every time — even if you think you know the state. The repo may have changed.
2. Reconciliation catches drift — a handoff written 3 days ago may reference work that's been reverted or superseded. Always verify.
3. Read handoffs newest-first — the most recent handoff per agent is usually sufficient. Go deeper only if the latest references prior handoffs.
4. Flag conflicts early — if your work overlaps with an active agent's claims, resolve it BEFORE writing code, not after.
5. Ghost detection saves time — a stale presence file (>30 min no heartbeat) means that agent probably crashed. Don't wait for it.

Related Skills

• /handoff — The producer of handoff records. Run this when finishing work.
• /signal — Mid-work coordination signals. Check these during pickup for recent decisions/problems.
• /coordinate — If the project uses the switchboard, pickup should read both handoff records AND the live coordination state for the most complete picture.
• /repo-ingest — Updates the coordination protocol by learning from external repos.

After Using This Skill

MANDATORY NEXT STEPS:

• Register your presence if starting work
• Begin work based on the recommended starting point

OPTIONAL NEXT STEPS:

• Write a /signal if you're claiming files not listed in your presence
• Review journal entries for deeper history beyond handoff summaries

Changelog

v1.1.0 (2026-04-11)

• Added switchboard integration: check coordination repo for active state during pickup
• Clarified dual-source reconciliation: handoffs (permanent) + switchboard (live)

v1.0.0 (2026-04-11)

• Initial skill creation
• Smith-inspired state reconstruction from repository
• Active agent detection with ghost presence handling
• Handoff reconciliation against git state
• Structured briefing output format
• Presence registration after pickup