Task Handoff

---
name: task-handoff
description: "Checkpoint library — orchestrators call this (build-phase, build-step, plan-expedite, user-draft); operators usually want /session-wrap. Modes: --loop [--no-commit] (write current.md), --next-task [label] (durable task-boundary save), --resume (read current.md + orient), --end (delegates to /session-wrap)."
user-invocable: true
---

# task-handoff

Checkpoint library for `current.md` writes and reads. Its callers are orchestrating
skills — `build-phase`, `build-step`, `plan-expedite`, `user-draft` — that need a durable
checkpoint or an in-window resume. Operators wanting a session transition should use
`/session-wrap`. Bare `/task-handoff` (no flag) defaults to `--resume`.

**current.md contract:** file format, field definitions, overwrite-vs-append rules, path
resolution, staleness, and lifecycle are owned by
`.claude/references/task-state-schema.md` (workspace reference, not published in this mirror) — follow
it for every read and write. Safety-critical minimum: resolve the path via
`git rev-parse --show-toplevel`, never cwd-relative (worktree writes are deleted on cleanup).

None of these modes emits `/compact` or `/clear` — auto-compaction plus the `SessionStart`
re-inject hook handle context in-window (CLAUDE.md § Session wrap & commit discipline).

---

## `--loop` — checkpoint write

**Cost:** ~5 seconds, no user interaction. Output one line: `"Checkpoint written."`

Read-merge-write `current.md` — read the existing file first, then apply the schema doc's
per-field append-vs-overwrite rules (it owns that split; do not re-derive it here). Then
commit: `chore: task-state checkpoint [task] [status]`.

Callers invoke it after each meaningful action — tests pass, a hypothesis is ruled out,
before a new iteration. It should feel nearly zero-cost.

**`--loop --no-commit`** — same write, NO git commit. Required inside `build-phase`: its
Step 2e checkpoint commit picks up `current.md`, so a separate commit here would double-commit
and break 2d/2e race detection (which compares HEAD against origin before committing).

---

## `--next-task [label]` — task-boundary save

**Cost:** ~30 seconds. Durable boundary write when switching tasks within the same goal
(e.g. plan-expedite → build-phase): the same read-merge-write as `--loop` — the finished
task's entries land in Completed (append); WIP, Next Action, and Status are overwritten to
point at the next task (`[label]`) — plus a MEMORY.md update, commit, and push.

Then **keep working in-window**. No manual `/compact` is needed to cross a task boundary.
If a *deliberate* focused reset is genuinely wanted (not the default), emit a
`/compact [focus]` line for the user to type — `/compact` has no programmatic trigger.

---

## `--resume` — in-window orient

Reads `current.md` (path per the schema doc) plus git state and outputs an orientation
block — no window switch. Use after a compaction or `/clear`.

```
Resuming [Task field]: [Status]
[Next Action field verbatim]
```

Then proceed with the next action — do NOT ask for confirmation.

---

## `--end` — true session end

Delegates to `/session-wrap`, which triages.