strikt/handover
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial release of handover plugin for Claude Code

Browse Source 
- /handover skill: creates living document preserving context across sessions
- /takeover skill: recovers from forgotten handovers by reading old transcripts
- Statusline: shows context usage % and topic segmentation
- Background daemon uses Haiku for cheap conversation analysis
- Tracks suppressed issues, learnings, dead ends, open questions
- Auto WIP commits to prevent accidental reverts
This commit is contained in:
Marc J. Schmidt
2026-02-05 11:10:54 +01:00
commit cec8f1ca7d
9 changed files with 841 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
skills/handover/SKILL.md Normal file
View File

@@ -0,0 +1,177 @@
---
name: handover
description: Generate a handover prompt for the next worker when ending a work session. Use this when the user says "handover", "next worker", or wants to save context for continuing later.
user-invocable: true
---
# Handover Skill
Curate the living handover document (`.claude/handover.md`) and commit WIP state so the next agent generation can continue seamlessly. The handover document is institutional memory — it accumulates learnings across sessions and is pruned each handover to prevent rot.
## Phase 1: Gather Context (automated)
Do all of these silently, no user interaction yet. **Do NOT run git commands** — you have the full conversation context and know what happened this session. The next agent can run `git log` themselves.
1. Read `.claude/handover.md` if it exists (this is the living document from previous generations)
2. Check if a plan file is active in the current session. If so, note its path
3. Run `TaskList` to capture all active tasks (pending and in-progress). These are session-local and will be lost when the session ends — they MUST be preserved in the handover document.
4. **Scan for suppressed issues** in the conversation context. These are issues that were avoided rather than fixed. Look for:
- Tests removed from whitelists or skip-lists
- Tests marked with `.skip`, `xit`, `xdescribe`, `@disabled`, or similar
- Test files deleted or excluded
- Code commented out with TODO/FIXME/HACK annotations
- Error handling that catches and silences instead of fixing
- Workarounds with comments like "doesn't support this yet", "crashes the compiler"
- Features or cases explicitly excluded ("let me remove this", "skip this for now")
This is critical — suppressed issues are the easiest things to lose permanently.
5. From conversation context, identify:
- What was worked on this session
- Which files were modified and why
- Current branch name
- Any test failures encountered (do NOT re-run tests)
- Any discoveries, gotchas, or dead ends
- Any unresolved technical decisions
## Phase 2: Curate Knowledge (automated)
If `.claude/handover.md` exists with entries, curate them **yourself** — don't ask the user. You have access to the codebase; they don't remember every implementation detail.
For each section with entries, verify relevance by checking the code:
- **Learnings**: Check if the code/pattern described still exists. If refactored away or behavior changed, it's stale.
- **Dead Ends**: Check if the constraint that caused the dead end still applies. If the blocker was removed, it's stale.
- **Open Questions**: Check if the code now reflects a clear decision. If so, it's resolved.
- **Suppressed Issues**: Check if the suppression (skipped test, commented code, etc.) is still present. If the issue was properly fixed and the suppression removed, it can be retired.
When a learning is confirmed still true, upgrade it from ⚠️ to ✅.
**No user interaction.** Just do the curation and move on.
## Phase 3: Write the Handover Document
Write/update `.claude/handover.md` with this structure:
```markdown
# Handover
## Init Checklist
<!-- Next agent: complete these steps IN ORDER before doing anything else. -->
1. Read this entire handover document
2. Read `CLAUDE.md` for project rules
3. Read the active plan file (if listed below) — this is the original vision
4. Run the verification command (below) to confirm expected state
5. Recreate tasks from the Tasks section via `TaskCreate`
6. Verify any unverified learnings you plan to rely on (marked with ⚠️)
7. Check the Suppressed Issues section — do not re-suppress these without noting it
## Architecture Snapshot
<!-- Slowly evolving — only update when structure actually changes. Max 15 lines. -->
<!-- Format: indented tree for structure, arrow chains for data flow, one-line annotations for key constraints. -->
{agent generates this on Gen 1 from CLAUDE.md and codebase knowledge, then only updates when architecture changes}
## Current State
<!-- Overwritten each handover -->
- **Branch**: {current branch name}
- **Active plan**: {path to plan file, or "none"}
- **Working on**: {one-line summary}
- **Dirty files**:
- `path/to/file.ts` — {one-line annotation of what changed}
- ...
- **Failing tests**: {test names + failure reason, or "none known"}
- **Environment notes**: {docker state, rebuilt packages, etc., or "clean"}
- **Verification command**: {single command next agent should run first to confirm state}
## Next Steps
<!-- Overwritten each handover. This is your immediate roadmap — check back here if you feel yourself drifting. -->
1. {Highest priority item with file locations}
2. ...
3. ...
## Alignment Check
<!-- Read this when you're mid-session and unsure if you're on track. -->
- **Goal**: {one-sentence description of what this work is trying to achieve}
- **Scope boundary**: {what is NOT in scope — things to avoid getting pulled into}
- **Plan file**: {path, or "none"} — if you're deviating from the plan, stop and tell the user
## Tasks
<!-- Overwritten each handover. Next agent: recreate these via TaskCreate on init. -->
- [ ] {task subject} — {description} [status: pending/in_progress]
- ...
## Learnings
<!-- Append new, remove agent-verified stale. Each entry dated. -->
<!-- ⚠️ = unverified (written by previous agent, not yet confirmed by a later agent) -->
<!-- ✅ = verified (a later agent checked and confirmed this is still true) -->
- ⚠️ [{date}] {learning}
## Dead Ends
<!-- Append new, remove agent-verified stale. Each entry dated. -->
- [{date}] Tried {approach} for {goal} — failed because {reason}
## Suppressed Issues
<!-- Append new, remove when properly fixed. Each entry has file location. -->
- [{date}] `{file:line}` — {what was suppressed and why}
## Open Questions
<!-- Append new, remove when resolved. Each entry dated. -->
- [{date}] {question}
## Generation Log
<!-- One line per handover, never pruned -->
- [{date}] Gen {N}: {one-line summary of what this session did}
```
Rules:
- **Init Checklist**: static, never changes (it's instructions for the next agent)
- **Architecture Snapshot**: slowly evolving. Generate on Gen 1 from CLAUDE.md and what you know. On subsequent handovers, only update if architecture actually changed this session (new modules, renamed paths, new data flows). If nothing changed, leave it untouched. Max 15 lines. Use this format:
- Indented tree for directory/module structure (only top 2 levels, annotate each line)
- Arrow chains for key data flows (`input → transform → output`)
- One-line notes for key constraints or invariants
- **Current State**, **Next Steps**, **Alignment Check**, and **Tasks**: always overwritten completely
- **Learnings**: append new entries with ⚠️ (unverified). During curation (Phase 2), when the agent confirms a learning is still true, upgrade it to ✅. Soft cap ~15 items
- **Dead Ends**: append new, remove stale. Soft cap ~10 items
- **Suppressed Issues**: append new, remove ONLY when the issue is properly fixed (not just suppressed again). Soft cap ~10 items. Include `file:line` so the next agent can find it
- **Open Questions**: append new, remove resolved. Soft cap ~5 items
- **Generation Log**: append only, never prune. This is the audit trail
- Use date format `YYYY-MM-DD`
## Phase 4: WIP Commit
1. Stage all dirty working files AND `.claude/handover.md`
2. Create a commit with this format:
```
wip: handover — {one-line summary of current state}
Next steps:
- {step 1}
- {step 2}
- {step 3}
Handover document: .claude/handover.md
```
3. Do NOT push. The user decides when to push.
Important: Use `git add` with specific file paths. Do NOT use `git add -A` or `git add .`.
## Phase 5: Output Summary
After committing, output:
1. The full contents of the updated `.claude/handover.md`
2. The commit hash
3. A reminder: **"Next session: open `.claude/handover.md` and continue the work"**
4. If tasks were captured: **"The next agent should recreate the Tasks section via `TaskCreate` on init."**
## Size Management
If any section exceeds its soft cap, prune the oldest entries that are no longer relevant. Use your judgment — you can verify against the codebase.
The goal is to keep the document scannable. A 200-line handover document defeats the purpose.
## First-Time Use
If `.claude/handover.md` does not exist yet:
- Skip Phase 2 (no existing entries to curate)
- Create the file fresh with all sections
- Generation Log starts at "Gen 1"

94
skills/takeover/SKILL.md Normal file
View File

@@ -0,0 +1,94 @@
---
name: takeover
description: Recover from a forgotten handover by analyzing a closed session's transcript. Use when you start a new session and realize the previous one didn't run /handover.
user-invocable: true
---
# Takeover Skill
Recover context from a previous session that ended without running `/handover`. This skill reads the transcript from a closed session and creates the handover document retroactively.
## When to Use
- You started a new session and realized the last one didn't handover
- You want to recover learnings from an old session
- The previous agent crashed or was terminated unexpectedly
## Instructions
When this skill is invoked:
### Phase 1: Find Recent Sessions
1. List recent session transcripts:
```bash
ls -lt ~/.claude/projects/*//*.jsonl | head -20
```
2. Show the user a list of recent sessions with:
- Session ID (first 8 chars)
- Project path
- Last modified time
- File size (rough indicator of session length)
3. Ask the user which session to recover:
- "Which session would you like to recover? (enter number or session ID prefix)"
- Default to the most recent one that's NOT the current session
### Phase 2: Analyze the Transcript
1. Read the selected transcript file (the .jsonl file)
2. Extract all messages (both user and assistant) and parse them:
```javascript
// Each line is a JSON object
// Look for j.message.role === "user" or "assistant"
// Extract text content from j.message.content
```
3. From the transcript, identify:
- What was being worked on
- Which files were modified (look for Edit/Write tool calls)
- Any test failures mentioned
- Any learnings or discoveries
- Any suppressed issues (tests skipped, code commented out)
- Any unresolved questions or decisions
- Active tasks (look for TaskCreate/TaskUpdate calls)
### Phase 3: Generate Handover Document
Follow the same structure as the regular handover skill, but note that this is a **retroactive takeover**:
1. Read existing `.claude/handover.md` if it exists
2. Create/update the handover document with:
- All the standard sections (see handover skill)
- Mark this as a takeover in the Generation Log:
`[date] Gen N (takeover): recovered from session XXXXXXXX — {summary}`
3. **Do NOT create a WIP commit** — the files may have changed since that session
### Phase 4: Output Summary
Show the user:
1. What was recovered from the old session
2. The updated `.claude/handover.md` content
3. Any warnings (e.g., "Files may have changed since that session")
4. Reminder: "Review the handover document and verify the state is accurate"
## Notes
- This skill reads transcript files directly, it doesn't have the live conversation context
- The recovered information may be incomplete compared to a live handover
- Always verify the recovered state against the current codebase
- If the project has changed significantly since the old session, some learnings may be stale
## Transcript File Location
Session transcripts are stored at:
```
~/.claude/projects/{project-path-hash}/{session-id}.jsonl
```
The project path hash is the project directory with slashes replaced by dashes, e.g.:
`-Users-marc-bude-deepkit-framework`