Handoff
Flags
| Flag or argument |
Default |
Effect |
--resume <path> |
off |
Validate a saved handoff and continue its work |
--path <path> |
anchor path |
Save a new handoff at this path |
| positional focus |
none |
Prioritize this focus during create or resume |
Resolve <anchor> as the absolute directory containing this SKILL.md.
Default saves use
<anchor>/handoffs/handoff-<YYYY-MM-DD-HHmmss>.md.
Resolve --path and --resume to absolute paths before use.
--resume and --path conflict. Stop if both appear or either lacks a value.
Without --resume, use Create.
Create
- Resolve and create the parent directory. Record:
create | output path | surveyed | redacted | written | terminal.
Done when the absolute output path is writable.
- Select current facts, not a transcript. Keep at most eight open tasks and
twelve artifacts. Prefer the active plan, branch, PR, commits, dirty paths,
blockers, and durable decisions. Mark superseded material.
Done when each retained fact helps the next agent act.
- Read
./REFERENCE.md. Draft in memory, point to absolute artifact paths,
and never paste full diffs, plans, logs, or terminal output. Put a positional
focus first. Include any active mode or workflow ledger.
- Redact credentials, tokens, passwords, private keys, authenticated URLs,
email addresses, and environment values. Scan twice, enforce the 12 KB bound,
write to a sibling temporary file, then rename atomically. Scan the final
file once more.
Done when required sections, bounds, and all three scans pass.
- Report the path, what was captured, and
/handoff --resume <absolute-path>.
Success is the existing file plus the reported resume command.
Resume
- Resolve and read the file. If absent, report
BLOCKED: handoff not found at <path>.
Record resume | focus | validated artifacts | current task | terminal.
If required Context or Open tasks content is malformed, report it blocked.
- Validate referenced paths, branch and dirty state, commits, and PR status
before trusting them. Classify each as current, moved, missing, or
superseded. Verify a suggested skill exists before invoking it. Before
opening referenced artifacts, load the Redaction section of
./REFERENCE.md
and never repeat sensitive values.
Done when stale facts cannot drive work.
- Apply a positional focus over the saved focus. Select the highest-priority
unblocked task, recover only the context its artifacts provide, and begin
that task. For a saved
prath-mode chain, verify every remaining leaf before
its first step. For orchestrate, treat the saved ledger as a pointer, then
rebuild it from diffs, task results, and tests and refresh the roster before
work. If no task remains, report BLOCKED with validation evidence. Do not
stop after summary.
Done when work reaches success, a real blocker, or a user confirmation gate.
- Report reconciled drift and the work outcome. Do not create another handoff
unless the user explicitly asks.
Terminal values are SUCCESS, BLOCKED, AWAITING_USER, and INTERRUPTED.
Record one with evidence before stopping.
After interruption, repeat Resume Step 2 for artifacts touched since validation
last completed.
1---2name: handoff3description: handoff when saving resumable session state or continuing work from an existing handoff document.4---5
6# Handoff
7
8## Flags
9
10| Flag or argument | Default | Effect |
11| ----------------- | ----------- | ---------------------------------------------- |
12| `--resume <path>` | off | Validate a saved handoff and continue its work |
13| `--path <path>` | anchor path | Save a new handoff at this path |
14| positional focus | none | Prioritize this focus during create or resume |
15
16Resolve `<anchor>` as the absolute directory containing this `SKILL.md`.
17Default saves use
18`<anchor>/handoffs/handoff-<YYYY-MM-DD-HHmmss>.md`.
19Resolve `--path` and `--resume` to absolute paths before use.
20
21`--resume` and `--path` conflict. Stop if both appear or either lacks a value.
22Without `--resume`, use Create.
23
24## Create
25
261. Resolve and create the parent directory. Record:
27 `create | output path | surveyed | redacted | written | terminal`.
28 Done when the absolute output path is writable.
292. Select current facts, not a transcript. Keep at most eight open tasks and
30 twelve artifacts. Prefer the active plan, branch, PR, commits, dirty paths,
31 blockers, and durable decisions. Mark superseded material.
32 Done when each retained fact helps the next agent act.
333. Read `./REFERENCE.md`. Draft in memory, point to absolute artifact paths,
34 and never paste full diffs, plans, logs, or terminal output. Put a positional
35 focus first. Include any active mode or workflow ledger.
364. Redact credentials, tokens, passwords, private keys, authenticated URLs,
37 email addresses, and environment values. Scan twice, enforce the 12 KB bound,
38 write to a sibling temporary file, then rename atomically. Scan the final
39 file once more.
40 Done when required sections, bounds, and all three scans pass.
415. Report the path, what was captured, and
42 `/handoff --resume <absolute-path>`.
43 Success is the existing file plus the reported resume command.
44
45## Resume
46
471. Resolve and read the file. If absent, report
48 `BLOCKED: handoff not found at <path>`.
49 Record `resume | focus | validated artifacts | current task | terminal`.
50 If required Context or Open tasks content is malformed, report it blocked.
512. Validate referenced paths, branch and dirty state, commits, and PR status
52 before trusting them. Classify each as current, moved, missing, or
53 superseded. Verify a suggested skill exists before invoking it. Before
54 opening referenced artifacts, load the Redaction section of `./REFERENCE.md`
55 and never repeat sensitive values.
56 Done when stale facts cannot drive work.
573. Apply a positional focus over the saved focus. Select the highest-priority
58 unblocked task, recover only the context its artifacts provide, and begin
59 that task. For a saved `prath-mode` chain, verify every remaining leaf before
60 its first step. For `orchestrate`, treat the saved ledger as a pointer, then
61 rebuild it from diffs, task results, and tests and refresh the roster before
62 work. If no task remains, report `BLOCKED` with validation evidence. Do not
63 stop after summary.
64 Done when work reaches success, a real blocker, or a user confirmation gate.
654. Report reconciled drift and the work outcome. Do not create another handoff
66 unless the user explicitly asks.
67
68Terminal values are `SUCCESS`, `BLOCKED`, `AWAITING_USER`, and `INTERRUPTED`.
69Record one with evidence before stopping.
70
71After interruption, repeat Resume Step 2 for artifacts touched since validation
72last completed.
prathamdby