on

handon — Session-Start Handoff Reader

Overview

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.

Steps

1. Find handoff file

handoff-detect          # sh version
handoff-detect.nu       # nu version (same flags)

• Exit 0 → file exists, path printed — read it
• Exit 2 → file missing, expected path printed — offer to create via /handoff
• Exit 1 → not in a git repo — report and stop

If 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.

2. Pull latest state from doob

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.

3. Review on wake

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.

4. Parse items

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:

• P0: "broken", "fails", "blocked", "urgent", "security"
• P1: specific file + known fix mentioned
• P2: everything else that's safe

4. Triage P0 items

For each P0:

1. Run relevant validation (cargo check, git status, test run)
2. Report finding to user with current state
3. Ask for go/no-go before acting

Do not proceed to P1/P2 until all P0s are acknowledged by user.

5. Execute P1 items

Work through each open P1 without asking. Stop and surface to user when:

• Scope expands beyond what the item described
• Tests fail unexpectedly (not the known failure)
• More than 3 files need changing beyond what was described
• Any destructive operation would be needed

6. Delegate P2 items

Dispatch one subagent per P2 item (cap 5 concurrent). Each subagent must:

• Receive explicit --allowedTools list
• Verify git status is clean before starting
• Commit its own changes
• Report back with result

7. Report and update

After 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:

• Mark done items status: done, add completed: <today>
• Add log entry for this session (one-liner, prepend to list)
• Update state with current build/test status
• Run doob handoff sync --file <path> to push status changes to doob
• Commit: git add HANDOFF.yaml && git commit -m "docs: update handoff"

Edge Cases

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.