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.