Handoff Receiver

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

intent

you inherit work mid-stream from a prior session. your job is to locate the active handoff, validate the repo matches documented state, resume execution from the exact next step, and update the handoff artifact before handing off again. use this when a peer agent or external system has left a handoff file and passed the torch to you. skip this if you are continuing your own session or have no prior handoff.

inputs

required:

• active handoff file (path varies by project structure; detected automatically)
• INDEX.md in the same handoff directory (compact table of all handoff streams and their status)
• git repository state (branch, uncommitted changes, recent commits)
• write access to .trellis/handoffs/, docs/handoffs/, or project root (whichever holds CURRENT)

external connections:

• local filesystem: bash, read, write, grep
• git: to verify branch, diff, and log state

setup guidance:

• no auth or env vars required. all data is local.
• if you lack write access to the handoff directory, ask the user for permission before updating CURRENT, INDEX.md, or the handoff file itself.

procedure

step 1: locate and index the active handoff

1. check .trellis/handoffs/CURRENT first. if present, read it and note the handoff path it contains.
2. if not found, check docs/handoffs/CURRENT. if present, read it.
3. if not found, check CURRENT in project root. if present, read it.
4. if none exist, search for the latest legacy handoff file (e.g., handoff.md in root or docs/). if found, use it.
5. if no handoff is found at all, stop. ask one minimal question: "what is the path to your handoff file?" do not proceed without a concrete path.

input: filesystem paths. output: confirmed path to active handoff file (e.g., .trellis/handoffs/2026-05-22-12-40-open-core.md).

step 1.5: read index and classify all streams

1. read INDEX.md from the same directory as the handoff file (or the same directory as CURRENT if CURRENT was found).
2. scan the index table only. do not open every handoff file yet.
3. classify each row by its status field:
   • in_progress or open and row path matches the CURRENT pointer: active stream. proceed to step 2.
   • in_progress and row path does not match CURRENT: conflict. ask the user one question: "which stream is authoritative, the one in CURRENT or the in_progress row in INDEX.md?"
   • paused: parallel stream. note it. surface it in takeover output (see output contract below) but do not execute it.
   • done or superseded: archived. skip.
   • orphan: unattended work. open only the Goal and Next Steps sections of that handoff. ask the user one focused question: "how should i classify this orphan stream: paused, merged into active, superseded, or left as-is?"
4. if CURRENT points to a handoff file that is not listed in INDEX.md, treat this as index drift. ask one focused question: "should i add this handoff to INDEX.md, or is CURRENT stale?" do not continue without clarity.
5. after locating the active handoff, update it in place:
   • set status: in_progress
   • set taken_over_at: <ISO 8601 timestamp now>
   • set taken_over_by: handoff-receiver
   • set updated_at: <ISO 8601 timestamp now>

input: INDEX.md file. output: confirmed active handoff path, list of parallel/orphan streams (if any), handoff file updated with takeover metadata.

step 2: read decision-critical sections first

1. open the active handoff file.
2. read these sections in strict order:
   • Goal (one sentence scope)
   • Current State (completion percentage, blockers, key facts)
   • Next Steps (numbered list of actionable items)
   • Decisions Made (settled trade-offs and constraints)
   • Context for the Next Session (gotchas, tool setup, external dependencies)
3. capture in your internal state:
   • exact in-scope objective
   • current completion percentage or phase
   • first actionable next step (item #1 from Next Steps)
   • explicit constraints and trade-offs

do not read Files Changed, Commands Run, or other detail sections yet. those come in step 3.

input: active handoff file. output: mental model of goal, current state, next step, and constraints.

step 3: reconcile handoff vs repository reality

1. run these git commands to capture current repo state:

   git rev-parse --abbrev-ref HEAD
   git status --short
   git diff --stat HEAD
   git log --oneline -10
   

2. compare the output with the Files Changed and Commands Run sections in the handoff. look for:
   • branch name match
   • staged or unstaged changes that align with the handoff
   • recent commits that match the handoff log
3. if mismatch is small and explainable (e.g., one unrelated commit, one extra untracked file), continue.
4. if mismatch is major (different branch, unrelated deltas across many files, missing files documented in handoff), ask one minimal clarification question: "repo state differs from handoff expectations at [point A]. should i [option 1] or [option 2]?" do not proceed until answered.

input: git state, handoff file. output: confirmation that repo matches handoff expectations (or explicit user clarity on divergence).

step 4: execute next steps in strict order

1. take the first incomplete item from Next Steps in the handoff.
2. keep scope fixed to the handoff goal. do not add new features, refactor architecture, or expand scope unless blocked by a correctness issue (e.g., "this step cannot run because of a fundamental flaw").
3. re-run any validation commands listed in Commands Run before starting work to verify the setup is still intact.
4. execute the next step. if you get stuck:
   • check Decisions Made in the handoff. if the decision applies, follow it without re-opening the trade-off.
   • if blocked by an unresolved decision not yet in the handoff, ask exactly one focused question and wait for answer.
5. update your own local tracking of completed vs remaining steps.

input: Next Steps list, repo state. output: one completed step, remaining steps identified for next handoff.

step 5: update handoff artifact before yielding

1. open the active handoff file.
2. update these sections:
   • Current State: reflect actual completion status and blockers now
   • Next Steps: remove item #1 (completed). renumber remaining items. keep items actionable and specific.
   • Errors Encountered: add any new errors, warnings, or gotchas encountered during this session
   • Files Changed: add any new files modified or created
   • Commands Run: add any new commands executed
3. keep all content factual and concise. do not add interpretation or opinion.
4. decide the end state:
   • work is complete: set status: done. clear the CURRENT pointer file (delete it or set it to empty). update the matching row in INDEX.md to status: done.
   • work is paused: keep status: in_progress. if the paused state is long (hours or days), consider creating a fresh handoff file with the same goal but updated Next Steps. set the old handoff to status: paused, create the new handoff, move the CURRENT pointer to the new file, and add both rows to INDEX.md (old row paused, new row open).
   • work is replaced by a new handoff in the same stream: set the old handoff to status: superseded. add a field superseded_by: <path to new handoff>. move the CURRENT pointer to the new handoff file. update INDEX.md: old row superseded, new row open or in_progress.
5. do not create extra summary files, changelog files, or narrative logs unless explicitly requested by the user.

input: completed work, decision on end state. output: updated handoff file with new state, updated CURRENT pointer (if applicable), updated INDEX.md (if applicable).

decision points

no handoff found:

• if no handoff file exists in any standard location, then ask the user for the path. do not guess or scan the entire project.

conflict in index:

• if CURRENT points to a handoff with status: in_progress in the index, then proceed to step 2.
• if CURRENT points to a handoff not listed in INDEX.md, then ask the user if CURRENT is stale or the index is out of sync before continuing.
• if index lists a different in_progress handoff than CURRENT, then ask the user which is authoritative.

orphan or paused streams:

• if index lists a paused handoff, then surface it in the output but do not execute it.
• if index lists an orphan handoff, then open only its Goal and Next Steps. ask the user how to classify it (paused, merged, superseded, or left alone).

repo divergence:

• if git state matches handoff expectations, then continue to step 4.
• if git state diverges slightly (one unrelated commit, one extra file), then continue but note it in the next handoff update.
• if git state diverges significantly (wrong branch, many unrelated changes, missing documented files), then ask one clarification question and wait for answer before proceeding.

blocked during execution:

• if you hit an unresolved decision not documented in Decisions Made, then ask exactly one focused question and wait.
• if a validation command fails, then check Commands Run and Current State for setup guidance before re-running.
• if scope creep arises (e.g., user asks for a new feature mid-handoff), then create a separate handoff stream for the new feature. do not mix it into the active handoff.

end state determination:

• if all items in Next Steps are complete, then set status: done and clear CURRENT.
• if work is paused mid-step, then keep status: in_progress and consider creating a fresh handoff file if the pause is long.
• if work is replaced by a new handoff (new approach, new tool, new scope), then set old handoff to status: superseded and update INDEX.md.

output contract

when you take over a handoff, respond to the user with this format:

using handoff: <path>

## goal
<one sentence from the Goal section>

## current step
<the exact Next Steps item #1 you are about to execute>

## parallel streams
<none, OR one line per paused/orphan handoff: "paused: <path> (goal in one sentence)", etc.>

## blockers
<none, OR one-line description of any blocker preventing immediate execution>

if a blocker or conflict exists (e.g., index drift, repo divergence, unresolved decision), add a final line:

action needed: <one focused question for the user>

outcome signal

you know the skill worked when:

1. takeover confirmed: you output the formatted status above with no questions remaining about which handoff is active.
2. repo validated: git state matches handoff expectations (or divergence is explained and accepted).
3. next step identified: you have read and understood the first item in Next Steps and are ready to execute it.
4. handoff updated: before you yield (pause or complete), the handoff file is re-written with updated Current State, Next Steps, and metadata. no stale data remains.
5. index consistent: CURRENT pointer, INDEX.md row, and actual handoff file path are all in sync. no drift.
6. scope held: you executed only items from the handoff Next Steps and did not add new features, refactor, or change the goal.

---

anti-patterns

• starting implementation before running git status and comparing against the handoff.
• ignoring Decisions Made and reopening settled trade-offs.
• mixing new feature requests into handoff continuation. create a separate handoff stream for new work.
• updating many files before finishing Next Steps item #1.
• writing a new handoff file when an existing one should be updated in place.
• scanning the entire handoff directory when CURRENT and INDEX.md already provide active stream metadata.
• reading the full body of every historical handoff instead of relying on INDEX.md status and goal summaries.
• not updating the handoff artifact before yielding. this breaks the next takeover.

example

index state:

CURRENT → `.trellis/handoffs/2026-05-22-12-40-open-core.md`
INDEX.md row for onboarding: status: orphan
INDEX.md row for billing: status: paused
INDEX.md row for open-core: status: in_progress

expected takeover flow:

1. read CURRENT and detect active path: .trellis/handoffs/2026-05-22-12-40-open-core.md.
2. read INDEX.md and classify rows: open-core is active, billing is paused, onboarding is orphan.
3. open only the onboarding orphan to read Goal and Next Steps. ask user: "this orphan onboarding stream has not been touched. should i mark it paused, merge it into open-core, or supersede it?"
4. proceed to step 2 on the active open-core handoff once user clarifies the orphan.
5. execute and update accordingly.

---

credits: original design from clawhub. enriched for implexa quality standards, explicit decision trees, and edge case handling.