handoff-create

handoff-create

Create one concise, directed Markdown handoff artifact for a future continuation. This is the create step in the handoff skill family; pickup/resume/list intent belongs to handoff-pickup, and lifecycle/admin flows belong to the handoff umbrella.

Create contract

A handoff is directed durable work context for a specific future continuation — future-you, a future agent, a future worktree, or a teammate; the handoff umbrella owns the full definition.

A handoff must answer:

Given this requested focus, what does the next session need to know to proceed correctly?

If the user gave a meaningful continuation focus, use it. If they only asked for "a handoff" with no focus/title/resume goal, ask exactly this and stop until they answer:

What should the future session continue from this handoff?

Use handoff vocabulary first: handoff artifact, continuation focus, create a handoff, handoff slug. Branch Memory is only the storage command behind this skill; mention namespace, key, ref, or commit only as technical locator evidence, recovery detail, or error context.

Do not store secrets, credentials, binary data, generated build output, or large logs. Store paths to useful logs and files instead of copying their contents.

Resolve branch and slug

Branch:

1. If the user names a branch, use it explicitly with --branch <branch>.
2. Otherwise confirm the current branch before writing:

git branch --show-current

Stop if the repo is in detached HEAD. Use git status --short when branch/worktree state is needed to write accurate current-state context.

Handoff slug:

• Storage namespace: handoff.
• Entry key shape: flat <semantic-slug>.md; do not include /.
• Use an explicit slug/key if the user provides one and it is specific enough to recognize later.
• Otherwise compose the final directed Markdown handoff artifact first, then derive the slug from that final content.
• Use the continuation focus/title as context inside the artifact, not as the direct slug source.
• Make the slug summarize the future continuation action and subject apparent in the artifact body.
• Do not normalize the name by hand: ns handoff create normalizes --slug deterministically (lowercase; non-alphanumeric runs become single -; leading/trailing - trimmed; a trailing .md is dropped) and reports the final slug in its result. Read the final slug back from the command output. Aim for roughly 3-8 words.
• Avoid generic-only slugs like handoff, session, work, task, follow-up, or continue, and raw request preambles like i-want-to-handoff.
• Prefer semantic slugs like address-review-feedback, add-pickup-handoff-command, associate-sessions-with-branches, or resume-plan-implementation.

Compose artifact

Compose concise, future-continuation-oriented Markdown content directly in the command input or in a visible review response. Use this canonical shape:

# Handoff: <title>

Continuation focus: <What the future session should continue, decide, verify, or implement.>

## Context

<Why this handoff exists and what branch/work it concerns.>

## Current State

<What is already done, what changed, and what is not yet done.>

## Decisions / Findings

<Key decisions, constraints, useful discoveries, or gotchas.>

## Next Steps

<Concrete next actions for a future session.>

## Investigation Sources

- Source session ID: <exact id supplied by the invoking surface, or an explicit unavailable value>
- Source session log: <exact path supplied by the invoking surface, or an explicit unavailable value>
- Related files:
  - <path> — <why inspecting it would help>

## Useful Commands / Files

<Commands, files, PRs, issues, docs, or technical locators that help resume.>

Every handoff must include ## Investigation Sources. When the invoking surface supplies a source session id or log path, copy it exactly; when the harness exposes no persisted session log, record that unavailability explicitly instead of inventing a path. List concrete paths to other relevant child/subagent session logs, plans, reports, saved command output, and key source or test files, with a short reason each is useful. If no additional investigation files were identified, say so. These pointers are an audit and recovery trail; the handoff must remain self-contained without reading them.

Keep the artifact terse. Avoid owners, due dates, task databases, hidden metadata, or workflow-state machinery.

Do not create hidden temp/draft files for handoff-create. If the user needs review or editing before creation, present the proposed Markdown in chat or a structured UI and iterate there; then create the final artifact through the canonical storage command below. If the user explicitly asks for a real file or path, treat that as a separate file-writing request. If durable review state is needed, use a clearly named Branch Memory draft only with explicit user intent.

Store safely

Store the final artifact directly through the portable ns command face without an intermediate file. Use a quoted here-doc delimiter that does not appear in the handoff content:

ns handoff create --branch <branch> --file /dev/stdin --format json <<'HANDOFF_EOF'
<final Markdown handoff content>
HANDOFF_EOF

The command reads the final content once, derives its semantic slug, checks for a collision, and stores the exact bytes. Its JSON result reports slugSource: "content-derived", slug, key, provider, model, and durable reference evidence; use its reported branch and slug in follow-up commands and the user-facing report. Pass --slug <handoff name or slug> only when the user explicitly supplies an override; that result reports slugSource: "explicit" and requestedSlug. ns handoff create refuses an existing artifact by default. If it reports a collision, stop unless the user explicitly asked to replace it. Do not fall back to raw Branch Memory for normal creation.

Raw brmem is recovery-only. If ns handoff create is unavailable or a storage-layer diagnostic requires it, preflight with brmem check <semantic-slug>.md --namespace handoff --branch <branch>, then use brmem put <semantic-slug>.md --namespace handoff --branch <branch> --file /dev/stdin only after preserving the same collision safety.

Report and route follow-up

Report the result in handoff vocabulary first:

Created handoff `<semantic-slug>` on branch `<branch>`.

Then include a compact technical locator when useful:

• Namespace: handoff
• Entry: <semantic-slug>.md
• Locator/ref and commit printed by brmem

When a user asks to resume from an existing handoff, prefer handoff-pickup.

For handoff lifecycle vocabulary and non-create admin flows such as copy, move, delete, or garbage collection, load the handoff umbrella and its references rather than duplicating those recipes here.