Handoff Receiver

use this skill when you're the new skill or agent receiving work from a previous session handoff file. the goal is to continue delivery with minimal drift, no scope expansion, and clear state recovery.

intent

handoff-receiver enables safe continuity across agent sessions by locating the active handoff artifact, validating repo state against documented work, and resuming execution from the next actionable step. use it whenever you take over mid-project work. this skill prevents duplicate effort, catches state mismatches, and keeps the handoff artifact fresh so the next session has zero confusion.

inputs

• handoff file location: one of .trellis/handoffs/CURRENT, docs/handoffs/CURRENT, CURRENT (project root), or legacy handoff.md. the skill prefers the explicit CURRENT pointer pattern.
• index file: INDEX.md in the same directory as the handoff, providing compact status metadata for all streams (active, paused, orphan, done, superseded).
• git repo state: current branch, unstaged changes, diff stat, and recent commit log. the skill uses these to detect state drift vs. the handoff's documented file changes and commands run.
• external connections: none required. this skill operates on local files and git state only.
• environment assumptions: bash shell, git installed, read and write access to handoff directory and .git/ folder.

procedure

step 1: locate the active handoff and index

1. check for .trellis/handoffs/CURRENT (preferred standard location). if found, read its contents to get the active handoff path.
2. if not found, check docs/handoffs/CURRENT. if found, read it.
3. if not found, check CURRENT in project root. if found, read it.
4. if none of the above exist, check for legacy handoff.md in project root.
5. once the handoff path is confirmed, locate the matching INDEX.md in the same directory as the handoff file.
6. read INDEX.md into memory (do not scan the directory; the index is the source of truth).

input: handoff filesystem paths (location hints). output: confirmed active handoff file path, confirmed index file path, parsed index table in memory.

step 2: classify all streams from the index

1. iterate through each row in INDEX.md.
2. for each row, read the status field and match it against the CURRENT pointer:
   • if status: in_progress or status: open and the row path matches CURRENT: mark as active. proceed to step 3.
   • if status: in_progress and the row path does not match CURRENT: mark as conflict. do not proceed until user clarifies which stream is authoritative.
   • if status: paused: mark as parallel stream. surface it in takeover output but do not execute.
   • if status: done or status: superseded: mark as archived. skip.
   • if status: orphan: mark as orphan. open only that file's Goal and Next Steps sections, then ask the user one focused question: should this be marked paused, merged into the active stream, superseded, or left as-is.
3. if CURRENT points to a handoff path not listed in INDEX.md, treat this as index drift. stop and ask one focused question before continuing.

input: index file contents, CURRENT pointer. output: classified stream statuses, list of parallel/orphan streams to surface, confirmation that active stream is unambiguous.

step 3: mark the active handoff as taken over

1. open the active handoff file.
2. update (or add if missing) these fields at the top of the handoff:
   • status: in_progress
   • taken_over_at: <ISO8601 timestamp>
   • taken_over_by: handoff-receiver
   • updated_at: <ISO8601 timestamp>
3. write the updated handoff back to disk.

input: active handoff file path. output: handoff file updated with takeover metadata.

step 4: read decision-critical sections in order

1. read Goal from the active handoff. capture the in-scope objective in one sentence.
2. read Current State from the active handoff. capture completion percentage and current blockers.
3. read Next Steps from the active handoff. capture the first actionable item and remaining items.
4. read Decisions Made from the active handoff. capture any explicit constraints, trade-offs, or settled questions.
5. read Context for the Next Session from the active handoff. capture any environmental or dependency notes.

input: active handoff file. output: parsed goal, current state summary, next steps list, decisions list, context notes. do not read the full file yet; read only these five sections.

step 5: reconcile handoff vs. repository reality

1. run git rev-parse --abbrev-ref HEAD and capture the current branch.
2. run git status --short and capture unstaged/untracked file list.
3. run git diff --stat HEAD and capture file change summary.
4. run git log --oneline -10 and capture recent commits.
5. compare this git state against the Files Changed and Commands Run sections in the handoff.
6. if the mismatch is small and explainable (e.g. one extra commit, one new untracked file, same branch), continue to step 6.
7. if the mismatch is major (different branch, unrelated file deltas, missing files listed in handoff), stop and ask one minimal clarification question. do not proceed until the user confirms the repo state is correct.

input: active handoff file, current git state. output: validated repo state, confirmation that handoff and repo are in sync (or explicit mismatch details if not).

step 6: execute next steps in strict order

1. from the Next Steps section, take the first incomplete item.
2. execute that item in full. keep scope fixed to the handoff's stated goal. do not re-architect, expand scope, or open new feature requests unless blocked by correctness.
3. re-run any validation commands listed in the handoff's Commands Run section that relate to the current step.
4. if blocked by an unresolved decision, ask exactly one focused question and wait for an answer before proceeding.
5. once the first item is complete, mark it as done in your internal tracking (do not yet update the handoff file).
6. move to the second item and repeat until all items are done or you reach a pause point.

input: next steps list from handoff, current repo state. output: completed work, updated repo state, list of any new errors or blockers encountered.

step 7: update handoff artifact and prepare for yield

1. open the active handoff file.
2. update Current State with the new completion status and any new blockers.
3. update Next Steps by removing completed items and keeping remaining items actionable (one-line summaries, not full details).
4. update Errors Encountered section with any new errors, or leave it as-is if none.
5. update Commands Run with any new commands executed in this session.
6. update Files Changed with any new files modified or created in this session.
7. update taken_over_at, taken_over_by, and updated_at timestamps.
8. write the updated handoff back to disk.
9. decide on the next state:
   • if work is complete: set status: done, clear the matching CURRENT pointer file (or delete it), and update the matching INDEX.md row to status: done.
   • if work is paused mid-stream: update status: paused in the existing handoff, and keep CURRENT pointing to it.
   • if work is truly replaced by a new handoff in the same stream: create the new handoff file, set the old handoff to status: superseded, add superseded_by: <new path> to the old handoff, move CURRENT to the new file path, and update both rows in INDEX.md.
10. do not create extra summary files unless explicitly requested by the user.

input: completed work, errors, new commands, updated repo state. output: handoff artifact refreshed on disk, CURRENT pointer updated, INDEX.md rows updated, ready for next session.

decision points

if no handoff is found at any of the four locations (step 1): stop and ask one minimal question: "what is the path to the handoff file?" do not search the directory. require the user to provide the explicit path.

if index drift is detected (CURRENT points to a path not in INDEX.md): stop and ask one focused question: "the CURRENT pointer references <path>, but INDEX.md does not list it. is this pointer stale, or should INDEX.md be updated?" do not continue until clarified.

if multiple streams have status: in_progress and one is CURRENT while another is not (conflict): stop and ask one focused question: "stream <path A> is marked in_progress and in CURRENT, but stream <path B> is also marked in_progress. which stream should i continue?" require explicit user choice before proceeding.

if an orphan handoff exists: open only its Goal and Next Steps sections. ask one focused question: "found orphan handoff at <path>. should this be marked paused, merged into the active stream, superseded, or left as-is?" do not execute the orphan unless the user directs you to.

if git state conflicts with documented handoff state (major mismatch in step 5): stop and ask one minimal clarification question: "repo is on branch <X> with files <Y> changed, but handoff documents branch <Z> and files <W>. is the repo state correct?" do not proceed until the user confirms.

if a next step is blocked by an unresolved decision: ask exactly one focused question about that decision. do not invent the answer. wait for user input.

if work is complete but no new handoff is needed: set status: done, delete or clear the CURRENT pointer file, update INDEX.md row to status: done. do not create a continuation handoff.

if work needs to continue but a new handoff is clearer than updating the old one: create the new handoff, set the old handoff to status: superseded, add superseded_by: <new path>, update both INDEX.md rows, and move CURRENT to the new file.

output contract

when reporting takeover status to the user, respond with this exact format:

Using handoff: <path>

## Goal
<one sentence summary of in-scope objective>

## Current Step
<the exact next steps item being executed now>

## Parallel Streams
<none> OR <one line per paused/orphan handoff with status and goal>

## Blockers
<none> OR <one-line blocker>

the handoff file itself is updated on disk at the location specified in step 7. the INDEX.md file is updated to reflect the new status and timestamps. if a new handoff is created, the new path is written to the CURRENT pointer file.

outcome signal

the skill worked if:

1. the user sees the takeover status output showing the correct goal, current step, and any parallel streams.
2. the active handoff file on disk is updated with new taken_over_at, taken_over_by, and updated_at timestamps.
3. the first next step executes without scope drift or re-architecture.
4. at pause or completion, the handoff artifact on disk has fresh Current State, Next Steps, and Errors Encountered sections, with completed items removed.
5. the INDEX.md row for the active handoff reflects the correct status (done, paused, or in_progress).
6. if work is complete, the CURRENT pointer file is cleared or deleted, and no ambiguity remains for the next session.
7. if work is paused or superseded, the CURRENT pointer points to the correct continuation handoff or is cleared, and INDEX.md is consistent.