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/<project>/<YYYY-MM-DD>/...
• Permanent knowledge: $HOME/.openclaw/shared/knowledge/<project>/...

Invocation

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

• /handoff <project> [options] (default mode)
• /handoff load <project> [--date YYYY-MM-DD] (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: /handoff load <project> [--date YYYY-MM-DD]

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

---
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/<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.