Handoff (shared)

Create temporary handoff documents and (optionally) propose/apply updates to permanent docs.

Shared vault layout

Root: $HOME/.openclaw/shared/ (Obsidian vault)

• - Temporary handoffs: INLINECODE1
• Permanent knowledge: INLINECODE2

Invocation

This skill is usually invoked via slash command (Telegram nativeSkills):

• - /handoff <project> [options] (default mode)
• INLINECODE4 (subcommand)

If native skill commands are unavailable, use: /skill handoff <input>.

Supported forms (v1)

This skill currently supports only two user-facing forms:

1) Default: /handoff <project> [options]
2) Load: INLINECODE7

Subcommand parsing rules (must follow)

• - Treat the first token after /handoff as either:

- a <project> (default mode), or - the literal subcommand load.

• - Only load is supported as a subcommand in v1.
• Any other token that looks like a subcommand (e.g. integrity, list, help, : variants) must be treated as unsupported. In that case:

1) explain it’s unsupported, 2) show the two supported forms above, 3) ask the user to restate.

/handoff load behavior

Goal: help the user quickly locate the most relevant existing handoff doc for a project.

When invoked as /handoff load <project> [--date YYYY-MM-DD]:

1) Search under: $HOME/.openclaw/shared/handoff/<project>/
2) Prefer checking an INDEX.md if present; otherwise search by recency.
3) If --date is provided, narrow to that date folder first.
4) Output:
- The best matching handoff path(s)
- A 3–8 bullet summary of what each file contains (read only)
- Ask whether to update an existing file or create a new one.

No file writes in load mode unless the user explicitly asks to update/create.

Inputs (suggested schema)

When the user provides options, interpret them like:

• - --new force creating a new handoff file
• INLINECODE23 prefer updating an existing relevant handoff file
• INLINECODE24 also generate a matching INLINECODE25
• INLINECODE26 optional short name ("slug") for the file base name
• INLINECODE27 permanent-doc mode (ONLY propose updates unless --apply)
• INLINECODE29 apply the proposed permanent-doc patch (requires explicit user confirmation)

If options are omitted:

• - default is to search for a relevant existing handoff for the same <project> and ask whether to update it or create a new one (default suggestion: update).

Critical principles (must follow)

Confirm before writing

Before any write or edit, you MUST: 1) state the resolved absolute path(s) you intend to write, and 2) ask the user to confirm.

Permanent docs: propose first

In --permanent mode you MUST:

• - read the target doc if it exists,
• analyze its existing style/purpose,
• output a PROPOSED PATCH (clear section-level changes),
• STOP and ask for explicit confirmation.

Only after explicit confirmation AND --apply should you write/edit the file.

Focus of permanent docs

Permanent docs should capture long-term maintainable knowledge:

• - architecture/procedures/debugging workflows
• the evolution of understanding (wrong assumptions → what became clear)

Temporary handoff doc requirements

A handoff doc is meant to be discarded after use. It must include:

1) Title: Project Handoff: <project>
2) Header note: temporary/discard after use
3) Key document links (permanent docs). If any new permanent docs were created in THIS session, link them here and explain each link in 1 sentence.
4) Session Goal
5) Work Done (concise)
6) Current Status (artifact/knowledge state, not actions)
7) Next Steps (actionable)
8) If --log used: link to the work log file

Also include a YAML header for indexing:

CODEBLOCK0

Work log document (only with --log)

Work log is detailed and command-ish:

• - commands executed + key outputs
• files read/modified + summary of changes
• hypotheses/decisions/errors

Avoid duplicating overview/goal/status/next steps from the handoff.

Implementation hints

• - Prefer relative Obsidian-friendly links inside the vault when linking other vault docs.
• Each project should keep: $HOME/.openclaw/shared/handoff/<project>/INDEX.md pointing to recent handoffs.
• If no <project> exists yet, propose creating the project folder + INDEX.md and ask for confirmation before writing.
• Ask the user if anything is unclear before proceeding when requirements are ambiguous.