Handoff

Handoff (end-of-session signoff)

A general-purpose, cross-project routine. It is a global tool, callable from ANY folder. It always operates on the current project (the session's working directory) and never drags one project's context into another. The skill is portable; the artifacts it writes are local to wherever you run it.

Goal: make the next session productive cold. The single highest-value output is the cross-system wiring map (repo -> branch -> host/URL -> data store -> external services/IDs), because that is what is most expensive to rediscover and usually lives in no single file.

When to use

• The user says "handoff" / "wrap up" / "sign off" / "end of session".
• After finishing a meaningful chunk of work, before context is lost.

When NOT to use

• Mid-task with no natural stopping point. Do not interrupt active work to run this.

Hard safety rules (do not violate)

1. Propose-only cleanup. NEVER delete data (DB rows, external records, files) without an explicit per-item confirmation from the user. Default to a dry-run list. This is what makes the skill safe to run routinely.
2. Never commit or push unless the user explicitly asks. Surface uncommitted/unpushed work as findings; do not act on it.
3. Scope to the current project only. Do not read or mutate another project's data.
4. Any index/roll-up is append/update, not overwrite. Preserve other projects' rows.
5. Verify before asserting. Read the actual state (git status, DB, deploy API) rather than recalling it.
6. Never write live secrets into artifacts. In the wiring map and pointers, record service names, locations, and env-var names (e.g. .env: STRIPE_SECRET_KEY) — never the value of a key, token, password, or connection string, and never a URL with embedded credentials. HANDOFF.md is git-tracked; assume it will be pushed.

Configuration (portable)

This skill has no machine-specific paths baked in. It reads optional settings from a handoff.json in the project's .claude/ directory (or the nearest ancestor .claude/), all fields optional:

{
  "workspaceRoot": "",   // absolute path where the thin cross-project index lives; omit to skip the index
  "workspaceName": "",   // label for the index header, e.g. "Acme ClaudeOS"
  "syncMemory": true     // whether to run the memory lane (see below)
}

If workspaceRoot is unset and the user has not told you their workspace root, skip the workspace index and just write the per-project HANDOFF.md (it is fully portable). You may offer to save a workspaceRoot once so future runs maintain the index.

Process

1. Orient

• Determine the current project root (cwd) and its CLAUDE.md/instructions file (if any). The project's handoff doc is HANDOFF.md beside it.
• Load handoff.json config if present.

2. Fan out subagent lanes (parallel)

Dispatch one subagent per lane (in a single message so they run concurrently). In a session that already holds full context you MAY gather a lane's facts directly instead of dispatching; in a cold/resumed session, dispatch, because the subagents do the rediscovery. If the runtime has no sub-agent capability (for example, plain chat rather than Claude Code or Cowork), do NOT skip the lanes — run them sequentially in the main context instead of dispatching. Dispatching is an optimization, not a requirement. Each lane writes findings to a scratch file and returns a short summary.

• Docs lane - reconcile the project's instructions + any spec/plan/doc files against what actually shipped this session. Produce proposed doc edits + drafted content for each HANDOFF.md section.
• Git/deploy lane - git status + branch/push state for each repo touched; which commit is live on each deploy target; flag leftover placeholders (REPLACE_WITH_*, TODO, stray fences) in shipped files.
• Data-audit lane - enumerate stale/test data created or left this session (DB test rows, orphaned external records, temp files). Classify each SAFE-TO-DELETE vs KEEP with a reason. Proposes only; never deletes.
• Memory lane (only if syncMemory and the environment documents a memory convention in its instructions files) - update that memory store with durable cross-session facts. If no memory convention exists, skip this lane.

3. Write the project HANDOFF.md

• Read the existing HANDOFF.md first. Preserve any human-authored content outside the five managed sections rather than clobbering it on regenerate.

Regenerate /HANDOFF.md with these five sections, in this order (a cold reader wants status and wiring first):

#  Handoff
_Last updated:  - _

## 1. Status

## 2. Wiring map
| Asset | Repo @ branch | Host / URL | Data store | External services / IDs |
|---|---|---|---|---|

## 3. Open threads / next actions

## 4. Changelog (recent first)

## 5. Pointers

4. Update the workspace index (only if workspaceRoot is known)

In /HANDOFF.md, add or update ONE row for this project, leaving all other rows intact:

#  Handoff Index
_One row per active initiative. Open the project's own HANDOFF.md for detail. Maintained by the /handoff skill._

| Project | HANDOFF.md | Status (one line) | Updated |
|---|---|---|---|
|  |  |  |  |

5. Propose cleanup (confirm-gated)

Present the data-audit lane's SAFE-TO-DELETE list as a numbered checklist with counts and reasons. Ask the user which to delete (y/N per item, or "all"/"none"). Delete ONLY what they confirm. List KEEP items too, with why, so nothing is silently dropped.

6. Signoff summary

Print a tight summary: what changed this session, what is live, what is pending, what needs the human, and where the fresh session should start.

Notes

• The per-project HANDOFF.md is the human-readable, git-trackable copy; the memory store (if any) is the always-auto-loaded copy. Keep both; they serve different moments.
• General tools go global; project knowledge stays folder-scoped. This skill embodies that: global skill, local artifacts.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cheflamb
• Source: cheflamb/claudeos-handoff
• License: MIT

Install and usage instructions live in the source repository linked above.