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: $HOME/.openclaw/shared/handoff///...
• Permanent knowledge: $HOME/.openclaw/shared/knowledge//...

Invocation

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

• /handoff [options] (default mode)
• /handoff load [--date YYYY-MM-DD] (subcommand)

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

Supported forms (v1)

This skill currently supports only two user-facing forms:

1) Default: /handoff [options]

2) Load: /handoff load [--date YYYY-MM-DD]

Subcommand parsing rules (must follow)

• Treat the first token after /handoff as either:
• a (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 [--date YYYY-MM-DD]:

1) Search under: $HOME/.openclaw/shared/handoff//

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
• --update prefer updating an existing relevant handoff file
• --log also generate a matching _work_log.md
• --name optional short name ("slug") for the file base name
• --permanent permanent-doc mode (ONLY propose updates unless --apply)
• --apply 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 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:

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:

---
type: handoff
temporary: true
project: <project>
date: <YYYY-MM-DD>
created_at: <ISO8601>
author: <agentId>
session: <sessionKey if available>
---

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//INDEX.md pointing to recent handoffs.
• If no 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.