@staff0rd/assist 0.220.1 → 0.221.0

package/README.md

@@ -45,9 +45,11 @@ After installation, the `assist` command will be available globally. You can als
 - `/devlog` - Generate devlog entry for the next unversioned day
 - `/draft` - Draft a new backlog item with LLM-assisted questioning
 - `/forward-comments` - Split a coarse PR comment (e.g. from Slack) into per-line review comments on the current branch's PR, attributed to the original reviewer
+- `/handover` - Write a session handover note (`.assist/HANDOVER.md`) for the next conversation; archives any prior handover first. The SessionStart hook surfaces the handover at the start of the next session
 - `/pr` - Raise a PR with a concise description
 - `/refactor` - Run refactoring checks for code quality
 - `/prompts` - Analyze denied tool calls and suggest settings changes to auto-allow recurring prompts
+- `/recall` - Recall context from the most recent prior session in this repo by summarising its transcript (skips sdk-cli-only sessions); read-only, emits a `# Recall` block in chat
 - `/refine` - Refine an existing backlog item through conversation
 - `/restructure` - Analyze and restructure tightly-coupled files
 - `/review-comments` - Process PR review comments one by one
@@ -201,6 +203,9 @@ After installation, the `assist` command will be available globally. You can als
 - `assist sql tables [connection]` - List tables in the connected database (via INFORMATION_SCHEMA.TABLES)
 - `assist sql columns <table> [connection]` - List columns for a table (use `schema.table` for non-default schema; via INFORMATION_SCHEMA.COLUMNS)
 - `assist screenshot <process>` - Capture a screenshot of a running application window (e.g. `assist screenshot notepad`). Output directory is configurable via `screenshot.outputDir` (default `./screenshots`)
+- `assist handover archive [--suffix <s>]` - Archive the current `.assist/HANDOVER.md` to `.assist/handovers/archive/<ISO-ts>[-<suffix>].md`. Prints the archive path; no-op when no handover exists
+- `assist handover summarise <jsonl>` - Print a one-line summary of a session JSONL via `claude -p --model haiku`. Filters sdk-cli-only transcripts and sets a recursion-guard env var so the inner SessionStart hook short-circuits
+- `assist handover load` - SessionStart hook entry point: reads `{cwd, session_id}` from stdin, archives any existing `.assist/HANDOVER.md`, and emits `{ hookSpecificOutput: { hookEventName: "SessionStart", additionalContext }, systemMessage }`. When no handover exists, falls back to summarising the most-recent non-current, non-sdk-cli prior JSONL under `~/.claude/projects/<encoded-cwd>/`. Honors `_CLAUDE_HOOK_SUMMARISE_RUNNING` so nested invocations short-circuit silently
 - `assist mermaid export [file.md]` - Render each fenced mermaid block to `<stem>-<index>.svg` via [Kroki](https://kroki.io). With no file, scans `*.md` in the current directory (non-recursive). Use `--out <dir>` to override the output directory. Use `--index <n>` to render only the nth mermaid block (1-based; requires a file argument). Endpoint is configurable via `mermaid.krokiUrl` (default `https://kroki.io`).
 - `assist prompts` - Show top 10 denied tool calls by frequency with count and repo breakdown
 - `assist coverage` - Print global statement coverage percentage

package/claude/commands/handover.md

@@ -0,0 +1,54 @@
+---
+description: Write a session handover note for the next conversation
+---
+
+Write a concise handover note for the next session working on this repo. The note captures everything the next session needs to pick up where this one left off.
+
+## Step 1: Archive the previous handover
+
+Run `assist handover archive` first. If a `.assist/HANDOVER.md` already exists, it is moved to `.assist/handovers/archive/<ISO-ts>.md` (path printed to stdout). If no handover exists, the command is a no-op.
+
+Do NOT skip this step — re-running `/handover` must never overwrite a prior unsaved note.
+
+## Step 2: Write `.assist/HANDOVER.md`
+
+Always operate on the current working directory. Write the file at `.assist/HANDOVER.md` (create the `.assist/` directory if needed). Use the following sections, in this order, and omit none even if empty (use a single "—" placeholder line):
+
+```markdown
+# Handover
+
+## Current Task
+
+What is actively being worked on right now — one or two sentences. Include the backlog item ID or PR number if applicable.
+
+## Just Done
+
+The most recent things completed in this session. Bullet list. Include file paths where relevant.
+
+## Next Steps
+
+What the next session should do next, in order. Bullet list. Be concrete — name files, commands, or decisions.
+
+## Key Files
+
+Files that the next session will most likely need to read or edit. Bullet list of `path:line` references where useful.
+
+## Open Decisions
+
+Choices that have not yet been made, or were deferred. State the options briefly so the next session can resume the deliberation.
+
+## Watch Out For
+
+Non-obvious gotchas, in-flight refactors, broken tests, half-applied changes, or anything that could trip up the next session.
+
+## Don't Do
+
+Things that have been ruled out, attempted unsuccessfully, or that the user has explicitly asked not to do. Saves the next session from repeating dead ends.
+```
+
+## Guidelines
+
+- Keep each section terse — bullets, not paragraphs. The next session will read this cold.
+- Reference concrete file paths and line numbers wherever it helps orientation.
+- Do not summarise context that is already obvious from the code or git history.
+- Do not commit `.assist/HANDOVER.md` — it is gitignored.

package/claude/commands/recall.md

@@ -0,0 +1,52 @@
+---
+description: Recall context from the most recent prior session in this repo
+---
+
+Summarise the most recent **prior** Claude Code session for this working directory, so the current session can pick up where it left off. Always operate on the current working directory; do not ask which repo to recall.
+
+## Step 1: Locate the prior session JSONL
+
+Sessions are stored under `~/.claude/projects/<encoded-cwd>/`, where `<encoded-cwd>` is the absolute current working directory with every `/` replaced by `-` (e.g. `/home/me/git/foo` → `-home-me-git-foo`).
+
+1. Compute `<encoded-cwd>` from the absolute path of the current working directory. Do not hard-code a path — derive it.
+2. List `*.jsonl` files in that directory, newest-first by mtime.
+3. Walk the list and pick the **first** file that satisfies all of:
+   - It is **not** the current session's JSONL (the current session id is in `$CLAUDE_SESSION_ID` if set, or matches the JSONL whose tail you would actively be appending to right now — when in doubt, skip the newest if it could be this session).
+   - It is **not** an sdk-cli-only transcript. A transcript is sdk-cli-only when every `type:"user"` entry with text content has `"entrypoint":"sdk-cli"`. If at least one `type:"user"` entry has `"entrypoint":"cli"` (or any value other than `sdk-cli`), the transcript counts as a real interactive session and is eligible.
+
+If no eligible prior session exists, emit:
+
+```markdown
+# Recall
+
+No prior session found for this directory.
+```
+
+…and stop.
+
+## Step 2: Emit the # Recall block
+
+Read enough of the chosen JSONL to understand what the previous session was working on (recent human user turns are the highest signal — skip tool results and assistant messages). Then emit a single `# Recall` block directly in chat. **Do not write any file.**
+
+Use this structure:
+
+```markdown
+# Recall
+
+**Previous session:** <one-line summary of what the prior session was doing>
+
+**Key points:**
+- <bullet> — what was happening, decisions made, or where it stopped
+- <bullet>
+- <bullet>
+
+**Suggested next step:** <one concrete thing to do now, or "—" if unclear>
+```
+
+## Guidelines
+
+- Always operate on the current working directory — never guess or substitute another repo.
+- Keep the summary terse. The user is reading it cold at the start of a new session.
+- Prefer concrete file paths, command names, and backlog IDs over vague descriptions.
+- If `.assist/HANDOVER.md` exists, the SessionStart hook will already have surfaced it — `/recall` complements that by pulling context from the prior transcript, not the handover file.
+- Do not modify any files. `/recall` is read-only.

package/claude/settings.json

@@ -19,6 +19,12 @@
 				"matcher": "",
 				"hooks": [{ "type": "command", "command": "assist notify" }]
 			}
+		],
+		"SessionStart": [
+			{
+				"matcher": "",
+				"hooks": [{ "type": "command", "command": "assist handover load" }]
+			}
 		]
 	},
 	"permissions": {
@@ -70,6 +76,10 @@
 			"SlashCommand(/test-cover)",
 			"Skill(test-review)",
 			"SlashCommand(/test-review)",
+			"Skill(handover)",
+			"SlashCommand(/handover)",
+			"Skill(recall)",
+			"SlashCommand(/recall)",
 			"WebFetch(domain:staffordwilliams.com)"
 		],
 		"deny": [