Use at the start of a session to orient to outstanding work — scans for HANDOFF.yaml (or HANDOFF.md) files, triages items by priority, and acts according to risk level without asking for approval on P1/P2 work.
Scan the current directory tree for handoff files, parse items by priority, and act:
| Priority | Action |
|---|---|
| P0 | Validate current state immediately. Report to user. Ask before touching anything. |
| P1 | Execute autonomously. Stop only if scope expands or something unexpected happens. |
| P2 | Delegate to subagents. Cap at 5 concurrent. |
handoff-detect # sh version
handoff-detect.nu # nu version (same flags)
/handoffIf invoked from a workspace root (e.g. ~/dev) with no .git, sweep subdirs with find . -name "HANDOFF.*.*.yaml" | sort instead.
If only a legacy HANDOFF.md exists at repo root, read it as freeform. Do not convert unless asked.
Before parsing the local file, sync doob → HANDOFF.yaml to pick up any status changes made outside this session:
doob handoff sync --file <path-to-HANDOFF.yaml>
If doob is not on PATH, skip and continue with the local file as-is.
Before triaging by priority, scan all items for unreviewed human-edit entries — any extra
entry with type: human-edit and no reviewed field (or reviewed is absent).
Surface these first, regardless of item priority:
## Review on Wake
- [id] "[title]" — human edited `<field>` → `<value>` on <date>
<note if present>
Do not act on these items automatically. Present to user and wait for acknowledgement before
proceeding to P0 triage. After the user acknowledges, note which items were reviewed — handoff
will stamp reviewed: <today> on those entries at session end.
From HANDOFF.yaml: read items list directly. Filter to status: open or status: blocked.
Items with a doob_uuid are tracked in doob — their status is authoritative from the sync above.
From HANDOFF.md: read the "Known Gaps", "Next Up", "Parked", or "Remaining Work" sections. Infer priority:
For each P0:
cargo check, git status, test run)Do not proceed to P1/P2 until all P0s are acknowledged by user.
Work through each open P1 without asking. Stop and surface to user when:
Dispatch one subagent per P2 item (cap 5 concurrent). Each subagent must:
--allowedTools listgit status is clean before startingAfter all work:
## Handoff Triage — <path/to/repo>
P0:
- [id] [name] "[title]" → [state found] → [action / question]
P1:
- [id] [name] "[title]" → done | blocked: <reason>
P2:
- [id] [name] "[title]" → delegated | skipped: <reason>
Then update HANDOFF.yaml:
status: done, add completed: <today>log entry for this session (one-liner, prepend to list)state with current build/test statusdoob handoff sync --file <path> to push status changes to doobgit add HANDOFF.yaml && git commit -m "docs: update handoff"No handoff file found: Report "No HANDOFF.yaml found in <path>." Offer to create one via /handoff.
HANDOFF.md only: Read it, triage as normal, note at end: "Consider migrating to HANDOFF.yaml for structured triage."
All items done or parked: Report clean state, no action needed.
Blocked item: Do not attempt. Report the blocker to user verbatim from the description field.