docs: sync README with current hand-off-session skill behavior

0051f0e→main·

alishakawaguchi·3mo ago·1 file·+18 added/-54 removed

Update session source, remove deleted CLI subcommands and flags, document compaction summary format, simplify quick start examples.

Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com

Changes

1

• MREADME.md+18/-54

12 unmodified lines

13
14
15
16
16
17
18
19
2 unmodified lines

22
23
24
25
26
27
28
29
30
31
32
33
34
35
25
26
27
28
29
30
31
32
33
34
35
1 unmodified line

37
38
39
43
44
45
46
47
48
40
41
42
14 unmodified lines

57
58
59
69
70
71
72
73
74
60
61
62
63
64
76
65
66
78
79
80
81
82
83
84
85
86
67
68
88
69
70
71
72
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

12 unmodified lines

## What You Get

- Cross-agent skills for Entire workflows
- Shared commands and install docs by agent
- Install docs per agent platform
- A consistent handoff workflow across Codex, Claude, OpenCode, Cursor, and Gemini

## First Skill: `hand-off-session`
2 unmodified lines

Current behavior:

- uses `entire` CLI as the primary backend for session and checkpoint explanation
- reads sessions from `.entire/metadata`
- uses `entire explain --checkpoint <id> --full --no-pager` to read full checkpoint transcripts privately
- falls back to `entire explain --checkpoint <id> --raw-transcript --no-pager` if full transcript output is unavailable
- falls back to direct repo parsing when the CLI path is unavailable
- supports external checkpoint repos configured via `.entire/settings.json` `checkpoint_remote`
- allows explicit checkpoint repo override with `--checkpoint-repo <local-clone-path>`
- if no local checkpoint clone is available, tells the user that access to the remote checkpoint repo is required
- supports `list`, `latest`, `show`, and `all`
- keeps transcript content private by default
- returns a small summary instead of dumping raw transcript lines
- auto-detects the most recent session from `.git/entire-sessions/`
- reads the raw transcript at the path stored in session metadata
- produces a structured compaction summary (Task Overview, Current State, Important Discoveries, Next Steps, Context to Preserve) instead of dumping raw transcript lines
- surfaces unanswered questions from the previous agent for the user to answer
- supports checkpoint handoff via `entire explain --checkpoint <id> --full --no-pager`
- falls back to `entire explain --checkpoint <id> --raw-transcript --no-pager` if full output is unavailable
- resolves checkpoints from: local `entire/checkpoints/v1` branch, `.entire/settings.json` `checkpoint_remote`, or nearby local clone
- filters sessions by agent name (e.g. "codex", "gemini") when mentioned

## Installation

1 unmodified line

Use the local plugin in `.claude-plugin/`.

Package contents:

- marketplace: `.claude-plugin/marketplace.json`
- skill: `hand-off-session`
- command: `hand-off-session`

### Codex

Open `.codex/INSTALL.md` and follow the install instructions for Codex.
14 unmodified lines

Natural language examples:

- "hand off this session to codex"
- "get the latest active session"
- "get the latest active session for codex"
- "get the most recent session"
- "list current sessions"
- "show checkpoint `<id>`"
- "hand off this session"
- "hand off the codex session"
- "pick up where codex left off"
- "hand off checkpoint 7b7c2be8a262"

Command-style examples:
## Checkpoint Resolution

- `hand-off-session`
- `hand-off-session list`
- `hand-off-session latest`
- `hand-off-session active`
- `hand-off-session --agent codex latest`
- `hand-off-session --agent codex active`
- `hand-off-session show <session-id>`
- `hand-off-session show checkpoint <checkpoint-id>`
- `hand-off-session --checkpoint-repo <local-clone-path> show checkpoint <checkpoint-id>`
Checkpoints are resolved in this order:

## External Checkpoint Repos
1. local `entire/checkpoints/v1` branch
2. `.entire/settings.json` `checkpoint_remote`
3. nearby local clone

If a repo uses Entire `checkpoint_remote`, `hand-off-session` resolves checkpoints in this order:

1. explicit `--checkpoint-repo <path>`
2. `entire` CLI resolution when available in the current repo
3. local `entire/checkpoints/v1` branch
4. nearby local clone inferred from `.entire/settings.json`

If no local clone is available, the helper does not fetch automatically. It tells the user:

- which checkpoint repo is configured
- the derived remote URL when it can infer one
- that remote checkpoint repo access is required
- to either clone it locally or pass `--checkpoint-repo <path>`

## Repo Layout

The repo follows the same general shape as `superpowers`:

- `skills/` for source-of-truth skill instructions