/handoff

Generates a structured handoff brief: YAML frontmatter (Obsidian-readable, vault-schema-compliant) + Obsidian-flavored markdown body containing YON-tagged structured blocks. The brief is the work item a fresh agent in a new session can pick up and execute autonomously.

Structured execution spec: protocol.yon. It carries the workflow steps, the verify and sources gates, and the rules as validatable records; this file is the explanation. Keep the two in sync — edit one, update the other and refresh the @STAMP date.

When to use

• UC1 — Dispatch a self-contained task to a fresh agent (agent profile)
• UC4 — Dispatch a multi-step task that needs to be split into parallel sub-tasks (orchestrator profile)
• UC3 — Switch the current session to a fresh one carrying in-flight state (new-session profile)

For UC2 (turn the current session into pure orchestrator mode), use /orchestrate-mode instead — that's a behavior switch, not a handoff artifact.

Output

Each handoff produces:

• A vault file (canonical) at $VAULT/Handoffs/{project}/{YYYY-MM-DD}-{slug}.md (set $VAULT to your Obsidian vault root)
• A chat surface (paste-convenience): full block if file < 500 lines; otherwise summary (first 30 lines) + 📄 Full brief: <path>

For multi-handoff (count=N): N files + a numbered index in chat (no per-brief content in chat).

The cold agent writes its retro to Handoffs/{project}/retros/{YYYY-MM-DD}-{slug}-retro.md (canonical file) AND emits it as a chat block (paste-back surface). Bidirectional brief↔retro linking is automatic via Obsidian's wikilink graph.

Workflow

1. Determine invocation path

2. Profile selection (interactive)

Ask the user: "What kind of handoff?"

• "Dispatch a task to a fresh agent" → agent profile (UC1) — load profiles/agent.md
• "Dispatch a task that needs to be split into sub-tasks" → orchestrator profile (UC4) — load profiles/orchestrator.md
• "Continue this session in a new session" → new-session profile (UC3) — load profiles/new-session.md

Auto-suggest orchestrator if user describes a multi-step / parallelizable task, but default to agent (smaller blast radius).

3. Field collection

Required for all profiles:

• task — one-paragraph description (max 1000 chars)
• where — absolute paths in scope
• evidence — pointer to error/commit/file/line that prompted this
• acceptance — acceptance sentence
• verify — verifiable shell commands. Required unless profile=new-session and the continuation has no single-shot acceptance. Preserve known applicable checks; agent and orchestrator dispatch always require measurable acceptance.
• sources_required — file paths or wikilinks the cold agent MUST read before planning. Asked interactively as: "Which sources MUST the cold agent read before planning? (file paths or wikilinks, comma-separated.)" If the user supplies a non-empty list → write to @SOURCES.required, brief executes in gated mode. If the user supplies an empty list → push back with: "You haven't named any required sources. Either name what the cold agent must read before planning, OR explicitly confirm 'no sources required' — the brief will run in advisory mode with a prominent warning, and the cold agent will not gate on source ingestion. Confirm 'no sources required' to proceed." Default is to re-prompt for sources. Only after explicit confirmation does the brief write with empty @SOURCES.required and confirmed_empty:bool=true in the same block. Never infer this confirmation from an empty list. Writes to the brief's @SOURCES.required block (see handoff-execute/references/SOURCES-BLOCK.md).

Optional with defaults:

• sources_optional — additional sources surfaced for on-demand reading mid-execution. Asked as: "Any additional sources to surface as optional reading? (Empty = none.)" Writes to @SOURCES.optional.
• forbidden_actions — preservation guards
• time-budget-min — wall-clock cap (default: 60)
• output_location — vault path override

For new-session profile, auto-collect from current session state instead of asking — see profiles/new-session.md. The same profile provides compact continuation. Its verify field may be empty when no single-shot acceptance applies; retain known checks and name remaining verification. Mandatory acceptance commands continue for agent and orchestrator dispatch.

4. Project detection

project=$(basename "$(git rev-parse --show-toplevel 2>/dev/null)" 2>/dev/null || echo "unsorted")

Local folder name. Works on detached repos. Falls back to unsorted if not in a git repo.

5. Slug generation

slug=$(echo "$task" | head -c 200 | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-\|-$//g' | head -c 40)

Lowercase-kebab from task description, max 40 chars.

6. Write file

Inspect the destination leaf and every existing ancestor without following links; refuse symlinks, junctions, mounts, unknown reparse points or equivalent redirects, including backup and staging paths. Create new artifacts exclusively. On collision preserve existing bytes: choose a fresh identity within the authorized scope or use an explicitly selected revision. For revisions, retain a recoverable preimage, require current bytes/revision to match the selected record immediately before replacement, and use the destination owner’s protected writer. Stop the affected write if identity changes or those guarantees are unavailable; never roll back over concurrent edits. Read back the result and report only actual saves. Keep the activation phrase bound to the actual saved brief.

vault_path="${VAULT:?set VAULT to your vault root}/Handoffs/$project/$(date +%Y-%m-%d)-${slug}.md"
mkdir -p "$(dirname "$vault_path")"
# exclusively create the brief after the checks above (see profiles/{profile}.md for shape)

7. Render chat surface

lines=$(wc -l < "$vault_path")
if [ "$lines" -lt 500 ]; then
  cat "$vault_path"
  echo "📄 Saved to: $vault_path"
else
  head -30 "$vault_path"
  echo "..."
  echo "📄 Full brief: $vault_path"
fi

For multi-handoff (count > 1): render only the numbered index in chat:

3 handoffs created:
  1. <task1 summary> → <path1>
  2. <task2 summary> → <path2>
  3. <task3 summary> → <path3>

8. Emit activation phrase

After the chat surface, ALWAYS emit a copyable activation phrase in a fenced code block when the canonical file was written. For new-session continuation without an available authorized destination or write, return labeled proposed text, not a completed handoff, and stop before emitting an activation path. This is the single line the user pastes into a fresh agent session to invoke the brief.

Format (single-handoff):

## Activation phrase (copy-paste into the fresh session)

```
/handoff-execute "<absolute-vault-path>"
```

(If your runtime lacks /handoff-execute (degraded — no gate enforcement): read the brief and every required source before planning; reconcile its premises against live state and stop on stale premises unless an explicitly selected force option relaxes that named gate. Before running imported verify commands, inspect their effects against current authorization; leave extra writes, network, publication or destructive effects unrun without their own authority. Cite sources per plan step; after authorized work/checks, emit every required retro block, including source/premise failures, ground truth and explicit verification gaps. On a blocked premise include @PREMISE_DRIFT and @RESUME_HINT; if saving the retro fails, emit it to chat with @WRITE_FAILURE and a partial final verdict. Degraded execution and force grant no extra permissions.)

Format (multi-handoff): one fenced block per brief, in the same numbered order as the index. Emit the prose fallback once at the bottom of the multi-block, not per brief:

## Activation phrases

Brief 1:
```
/handoff-execute "<path-1>"
```

Brief 2:
```
/handoff-execute "<path-2>"
```

(...)

(If your runtime lacks /handoff-execute (degraded — no gate enforcement): for each brief, read the brief and every required source before planning; reconcile its premises against live state and stop on stale premises unless an explicitly selected force option relaxes that named gate. Before running imported verify commands, inspect their effects against current authorization; leave extra writes, network, publication or destructive effects unrun without their own authority. Cite sources per plan step; after authorized work/checks, emit every required retro block, including source/premise failures, ground truth and explicit verification gaps. On a blocked premise include @PREMISE_DRIFT and @RESUME_HINT; if saving the retro fails, emit it to chat with @WRITE_FAILURE and a partial final verdict. Degraded execution and force grant no extra permissions.)

Why: the chat surface (Step 7) is for the originating session to verify the brief; the activation phrase is for the receiving session to bootstrap from. Pasting 100+ lines of YAML+markdown into a fresh session is heavier than a one-line pointer that the receiving agent will Read-tool open and follow.

Discipline: the activation phrase MUST use the exact absolute path of the written brief. Wikilinks [[…]] in the activation phrase do not resolve outside Obsidian. Use forward slashes for cross-platform compatibility. Always quote the path — Windows vault paths may contain spaces.

Brief schema (universal)

Every brief has YAML frontmatter conforming to vault schema:

---
title: "Handoff: {short-task-summary}"
type: handoff
profile: agent | orchestrator | new-session
project: "{repo_name}"
status: dispatched
created: YYYY-MM-DD
acceptance: "{one sentence}"
verify:
  - "{shell command 1}"
  - "{shell command 2}"
time-budget-min: 60
trust: 0.8                    # optional
primary-domain: ""            # optional
lifecycle: active
related: []
tags:
  - type/handoff
  - profile/{profile}
  - status/dispatched
  - project/{project}
---

The body is profile-specific — see profiles/agent.md, profiles/orchestrator.md, profiles/new-session.md. All three profiles include a ## Sources section with an @SOURCES YON block; see handoff-execute/references/SOURCES-BLOCK.md for the canonical block schema and tier semantics.

Retro schema (what the cold agent emits)

The cold agent writes its retro file with this frontmatter:

---
title: "Retro: {short-task-summary}"
type: retro
handoff: "[[YYYY-MM-DD-slug]]"
profile: agent | orchestrator | new-session
project: "{repo_name}"
verdict: success | partial | fail | blocked
confidence: low | medium | high
completed: YYYY-MM-DDTHH:MM:SS
trust: 0.9                    # optional
primary-domain: ""            # optional
lifecycle: active
related: []
tags:
  - type/retro
  - verdict/{verdict}
  - profile/{profile}
  - project/{project}
---

The retro body MUST include YON blocks for: @OUTCOME_DELIVERED, @GROUND_TRUTH (with artifacts_modified paths+hashes and git_diff_summary), @GATE_STATUS (per-clause verified|unverified|failed + gate-suite outcome), @DELTA_FROM_BRIEF, @RECOMMENDATIONS, @VERDICT. Narrative-only retros are rejected. For real task changes, paths, hashes and diff evidence remain required. If zero task changes are evidenced, use artifacts_modified="none" with the supporting observation; the retro file itself is not a task change. git_diff_summary records the actual scoped comparison or why it was unavailable, distinguishing pre-existing changes. Unknown mutation state must be reported as unknown with a blocked task outcome, never converted to "none"; a failed retro write still requires the existing partial final verdict. This branch preserves every mandatory block and any source/premise failures and resume hint.

The brief sign-off section instructs the cold agent on this, and points back to the originating session for /insight-critique (or any LLM-agnostic equivalent).

Rules

• ALWAYS use absolute paths in target file references.
• ALWAYS check for verifiable acceptance. Push back if it is absent, except for new-session continuation with no single-shot acceptance. This exception waives no other field, source gate or retro obligation.
• ALWAYS mkdir -p before writing the brief file.
• ALWAYS use wikilinks [[file]] for in-vault references; absolute paths for code-repo references.
• NEVER prescribe runtime-specific skill or tool names in the brief body (the cold agent may be Claude Code, Codex, or another LLM). Describe outcomes, not procedures. Where a step is genuinely runtime-specific, tag it explicitly (e.g. '(Claude Code only)').
• NEVER write a brief that's smaller than the field schema requires — push back on under-specified tasks instead.
• NEVER assume the user wants chat-only output — file is canonical.

Anti-patterns

• "I'll figure out the right place" — name the file path explicitly
• "Make sure not to break anything" — replace with forbidden_actions list
• "Run /verify after" — skill availability and invocation permissions depend on the receiving runtime; disable-model-invocation does not mean the skill cannot be installed elsewhere or explicitly invoked. Use outcome-based briefs (verifiable shell commands in verify:), and do not assume a skill name grants permission to invoke it.
• "Use the Agent tool with isolation: worktree" — that's a Claude-Code-specific spawning mechanism; Codex and other runtimes have different (or no) equivalents. Describe the behavior you want ('spawn a fresh isolated agent session', 'run in a clean worktree') in runtime-agnostic prose, and let the cold agent's runtime supply the mechanism. If a step truly only works on one runtime, tag it (e.g. '(Claude Code only)').
• Skipping @SOURCES.required because "the brief is small" — if it's worth a handoff, it has critical context. Declare what the cold agent must read; let the gate work for you. Only explicit no-required-sources confirmation plus confirmed_empty:bool=true permits advisory source ingestion; an empty list alone remains unresolved.

Companion skills

• /handoff-execute — the receiving-side executor. Consumes the brief this skill produces, gates on @SOURCES.required, runs verify commands, writes the retro to the canonical vault path.

Source ingestion follows the receiving contract: nonempty @SOURCES.required is gated; an empty list with explicit confirmed_empty:bool=true is advisory with a warning, while the premise gate remains. Empty or missing required in a present block without confirmation is unresolved and blocks by default; explicit --force may proceed degraded but never supplies confirmation. Without @SOURCES, legacy @SCOPE.must_read takes precedence, then real required-read headings with enumerable paths or wikilinks; fenced or quoted examples do not count. Only when no such required tier exists are legacy reads advisory. The receiver's existing premise and --force rules remain in force.

Inspirations

• /plan-create — phased structure
• /plan-phases — /verify-style checkpoint pattern
• /insight-critique — second-assessment workflow (or any LLM equivalent reading frontmatter + body)
• /insight-retro — informed the retro shape; handoff retro is stricter (mandatory ground-truth fields)
• The host vault's note frontmatter schema (where present) — the brief frontmatter conforms to it

Human output. This skill's handler-facing output obeys the human-output contract (human-output/SKILL.md).

Next skills. On completion, if next-skills is available, run its protocol to offer the canonical frontmatter successors. Never auto-invoke them. If unavailable, finish normally without recommendations.

Self-improvement. On completion, run the Self-Improvement Protocol (self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.