open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

docs(graceful-handoff): 2.0 — sync README, CLAUDE.md, root README

Browse source
This commit is contained in:
Kjell Tore Guttormsen 2026-05-01 06:06:16 +02:00
commit 1f0b03b1e5
3 changed files with 155 additions and 166 deletions
Download patch file Download diff file Expand all files Collapse all files

22
README.md
View file

@ -144,21 +144,23 @@ Research-informed thresholds. Alerts are progressive and never blocking. Privacy
---
### [Graceful Handoff](plugins/graceful-handoff/) `v1.0.0`
### [Graceful Handoff](plugins/graceful-handoff/) `v2.0.0`
Session handoff in under 60 seconds. Built for context-constrained models like Opus 4.7 where sessions fill fast.
Auto-trigger session handoff at context threshold. Manual `/graceful-handoff` always works as backup. Built for Opus 4.7.
When you hit 60-70% context and have to start a new session, three things usually get rushed or forgotten: summarizing state, committing finished work, and writing a continuation prompt. `/graceful-handoff` does all three in one step.
When you hit 60-70% context and have to start a new session, three things usually get rushed or forgotten: summarizing state, committing finished work, and writing a continuation prompt. v2.0 removes all three from the user's hands.
- **Auto-detect handoff type** — multi-session (active ultraplan project), plugin-work (inside a marketplace plugin), or single-task (fallback)
- **Writes `NEXT-SESSION-PROMPT.local.md`** — 7-section artifact (why, status, how to continue, push-policy, verification, gotchas) matching the established pattern in llm-security and config-audit
- **Auto-commit + push** — generates Conventional Commits message from `git diff --stat`, respects pre-commit hooks (secrets, pathguard), pushes to Forgejo. `--no-commit` skips
- **Copy-paste prompt for next session** — the critical output, always printed even if everything else fails
- **No subagents, no web** — entirely inline in the main session, under 60 seconds budget
- **Auto-trigger via Stop hook** — at estimated ≥70% context, writes artifact + commits (push remains user-triggered: irreversible operations stay manual)
- **statusLine hint** — display-only warning at 60% and urgent reminder at 70% (never runs git, safe per research)
- **SessionStart auto-load** — on `--resume` / `compact`, handoff content is injected into the new session via `additionalContext`; no manual `cat` needed
- **Skill-architecture** — `disable-model-invocation: true` so Claude can't autonomously invoke the side-effect-bearing flow; user triggers manually or hooks call the pipeline directly
- **Deterministic JSON pipeline** — `scripts/handoff-pipeline.mjs` returns structured JSON; tests run without LLM involvement
- **Explicit staging** — pipeline stages ONLY the artifact (never `git add -A`, regression-tested)
- **No subagents, no web** — under 60s budget; pinned to Sonnet 4.6 to free Opus for the next session
Key command: `/graceful-handoff [topic-slug] [--no-commit] [--dry-run]`
Key command: `/graceful-handoff [topic-slug] [--no-commit] [--no-push] [--dry-run]`
1 command · 0 hooks · 0 agents · declarative markdown
3 hooks · 1 skill · 1 pipeline · 36 tests · BREAKING from v1.0
→ [Full documentation](plugins/graceful-handoff/README.md)

73
plugins/graceful-handoff/CLAUDE.md
View file

@ -1,40 +1,63 @@
# graceful-handoff
# graceful-handoff (v2.0)
Én kommando (`/graceful-handoff`) som produserer en komplett sesjonsoverlevering i ett steg: NEXT-SESSION-artefakt, commit+push, og copy-paste-prompt for neste sesjon.
Auto-trigger sesjonsoverlevering ved kontekst-terskel, med manuell `/graceful-handoff` som backup. Skill-arkitektur (`disable-model-invocation: true`), deterministisk JSON-pipeline, og tre hooks som dekker hint, auto-eksekvering, og auto-load.
## Når brukes den
Når du nærmer deg kontekst-trøskelen (typisk 60-70% på Opus 4.7) og må starte en ny sesjon. Kommandoen tar jobben med å oppsummere state og pushe ferdig arbeid fra minutter ned til sekunder.
- **Automatisk:** Stop hook fyrer ved estimert ≥70% kontekst-bruk. Skriver artefakt + commit. Push gjenstår manuell.
- **Manuelt:** `/graceful-handoff` ved 60-70% (eller når som helst). statusLine viser hint ved 60% og urgent ved 70%.
- **Ny sesjon:** SessionStart hook auto-leser handoff-fil ved `source: resume` eller `source: compact` og injiserer i kontekst.
## Hva den skriver
## Komponenter
| Fil | Når |
|-----|-----|
| `NEXT-SESSION-PROMPT.local.md` (eller `NEXT-SESSION-<slug>.local.md`) | Alltid — hovedartefakt med 7 seksjoner (Hvorfor / Status / Fortsett / Push-policy / Verifisering / Husk) |
| `REMEMBER.md` | Hvis den finnes — oppdaterer "Sist oppdatert" og PÅGÅENDE-seksjon |
| `TODO.md` | Hvis den finnes — flytter ferdige items, legger til neste-økt-items |
| Commit + push | Hvis ucommittede endringer finnes OG `--no-commit` ikke er gitt |
| Fil | Rolle |
|-----|-------|
| `skills/graceful-handoff/SKILL.md` | Slash-command-handler. Frontmatter: `disable-model-invocation: true`, `model: claude-sonnet-4-6`, sub-scoped `allowed-tools`. Body orkestrerer pipeline-skriptet. |
| `scripts/handoff-pipeline.mjs` | Deterministisk Node-skript. Klassifiserer handoff-type, skriver artefakt, håndterer commit-bekreftelse, returnerer JSON. |
| `hooks/scripts/statusline-monitor.mjs` | Display-only hint. Leser `context_window.used_percentage` fra payload. |
| `hooks/scripts/stop-context-monitor.mjs` | Estimerer kontekst fra transcript-størrelse. Spawner pipeline ved ≥70%. |
| `hooks/scripts/session-start-load-handoff.mjs` | Auto-leser NEXT-SESSION-fil ved resume/compact, archiverer etter load. |
| `hooks/hooks.json` | Registrerer alle tre hooks + statusLine. |
Alle handoff-filer er `*.local.md`-mønster → gitignored, ikke sporet i git.
## Arkitektur-prinsipper
## Arkitektur
- **Hard cut fra commands/ til skills/.** v2.0 har ingen bakoverkompatibilitet.
- **disable-model-invocation: true.** Modellen kan IKKE invokere skill-en autonomt — bruker trigger manuelt eller hooks kaller pipeline-skriptet direkte.
- **Pipeline er deterministisk.** Tester kjører mot pipeline-skriptet uten LLM. Driftvariasjoner mellom Opus/Sonnet/Haiku elimineres for selve handoff-arbeidet.
- **Push aldri automatisk.** Reversibel handling (commit) auto-eksekveres; irreversibel (push) krever bruker.
- **Eksplisitt staging.** Pipeline stager kun artefakten (+ REMEMBER.md/TODO.md hvis de finnes). ALDRI `git add -A` — det scoopper opp ubeslektet WIP. Regression-test håndhever dette.
Helt deklarativ — ingen hooks, ingen agents, ingen subprocess. Main-sesjonen utfører alle seks faser inline med Bash + Read/Write/Edit:
## Auto-trigger-mekanikk
1. Detekter arbeidsmappe og prosjekt (pwd, git, find)
2. Identifiser handoff-type (multi-sesjon / plugin-arbeid / enkelt-oppgave)
3. Skriv NEXT-SESSION-artefakt til riktig lokasjon
4. Oppdater REMEMBER.md og TODO.md
5. Commit + push med Conventional Commits-melding (auto-generert)
6. Print copy-paste-prompt til terminal
Claude Code eksponerer ikke real-time kontekst-prosent til hooks (Anthropic har closed feature requests #16988, #27969, #34340). Vi approksimerer:
1. Stop hook får `transcript_path` i payload
2. `wc -c <transcript>` → char count
3. Tokens ≈ chars / 3.5
4. Sammenlign mot `context_window_size` fra payload (200k default, 1M støttet)
5. Ved ≥ 70% (estimert): spawn pipeline med `--auto --no-push --non-interactive`
Lock-fil `<transcript_dir>/.handoff-lock-<session_id>` hindrer repeat-firing innen samme sesjon.
## Tester
```bash
node --test plugins/graceful-handoff/tests/
```
36+ tester på tvers av 6 test-filer. Stop hook-tester bruker stub pipeline (genererer en mid-test fake `scripts/handoff-pipeline.mjs` i temp dir) for å unngå reelle git-operasjoner mot marketplace-repoet.
## Tidsbudsjett
< 60 sekunder totalt. Ingen Agent-delegering, ingen WebSearch. Hvis den drar ut: bruker er allerede på kontekst-trøskelen og trenger output raskt.
< 60 sekunder totalt for hele pipelinen. Pipeline-skriptet er testbart med `node:test` uten LLM-kall.
## Begrensninger (v1.0.0)
## Åpne antakelser (verifiseres ved smoke-test)
- Ingen auto-invokasjon ved kontekst-terskel — bruker triggrer manuelt
- Ingen backup av eksisterende NEXT-SESSION-filer (overskrives, men merger fra innhold)
- Ingen integrasjon mot ultraplan-local progress.json (lesing, ikke skriving)
- Commit-meldingen er auto-generert uten bekreftelse — bruk `--no-commit` hvis du vil håndtere commit manuelt
- **statusLine-plassering i `hooks/hooks.json`** vs `~/.claude/settings.json`. Vi setter den i hooks.json som første-prioritet design.
- **Token-estimering ±10%** mot Claude's reelle telling.
- **Issue #26251** (`disable-model-invocation: true` regression). Smoke-test at `/graceful-handoff` fungerer etter installasjon.
## Versjonering
- v1.0.0 (2026-04-19): initial declarative command
- v2.0.0 (2026-05-01): skill-arkitektur + JSON-pipeline + 3 hooks + auto-trigger (BREAKING)

252
plugins/graceful-handoff/README.md
View file

@ -1,31 +1,36 @@
# graceful-handoff
> Sesjonsoverlevering på under 60 sekunder. Designet for Opus 4.7-sesjoner som fyller kontekst raskt.
> Auto-trigger session handoff at context threshold. Manual `/graceful-handoff` always works. Designet for Opus 4.7.
**Problemet:** Opus 4.7 fyller kontekstvinduet mye raskere enn 4.6 — ofte innen ~5 minutter for reelt arbeid. Når du er på 60-70% og må starte ny sesjon, er det tre manuelle steg som blir hastverk eller glemt:
**Problemet:** Opus 4.7 fyller kontekstvinduet raskt — ofte innen ~5 minutter for reelt arbeid. Når du er på 60-70% og må starte ny sesjon, er det tre manuelle steg som blir hastverk eller glemt:
1. Oppsummere hvor arbeidet står (commits, lokale endringer, hva som er testet)
2. Commite og pushe ferdig arbeid (ellers tapes det)
3. Skrive en copy-paste-prompt som lar neste sesjon fortsette uten tap
`/graceful-handoff` gjør alle tre, automatisk, i ett steg.
**v2.0 fjerner alle tre steg fra brukerens hender:**
- **statusLine-hint ved 60%** og urgent reminder ved 70% (display-only, trygt)
- **Stop hook auto-eksekvering ved estimert ≥70%**: skriver artefakt + commit (push gjenstår — irreversibel handling beholdes manuell)
- **SessionStart auto-load ved `source: resume`/`compact`**: handoff-innholdet injiseres automatisk i ny sesjon, ingen `cat` nødvendig
- **Manuell `/graceful-handoff`** fungerer som backup — alltid
## Installasjon
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
# Deretter /plugin install graceful-handoff
# Deretter: /plugin install graceful-handoff
```
## Bruk
Minimum:
### Manuell trigger
```
/graceful-handoff
```
Med slug (hvis du har flere handoffs i samme mappe):
Med slug:
```
/graceful-handoff refactor-auth
@ -37,118 +42,84 @@ Uten auto-commit:
/graceful-handoff --no-commit
```
Dry-run (se hva som ville skjedd):
Dry-run:
```
/graceful-handoff --dry-run
```
## Hvordan den fungerer
Kommandoen utfører 6 faser inline i main-sesjonen (ingen Agent-delegering, ingen WebSearch — alt må skje raskt):
### 1. Detekter arbeidsmappe
```bash
pwd
git status --porcelain
git log --oneline -10
# Let oppover etter .claude-plugin/plugin.json
# Let etter .claude/projects/*/brief.md + progress.json
```
### 2. Identifiser handoff-type
| Type | Når |
|------|-----|
| `multi-sesjon` | Aktivt ultraplan-prosjekt finnes (progress.json status ≠ "completed") |
| `plugin-arbeid` | Inne i en marketplace-plugin (`.claude-plugin/plugin.json` finnes oppover i tre) |
| `enkelt-oppgave` | Ingen av over |
### 3. Skriv NEXT-SESSION-artefakt
Standardfilnavn: `NEXT-SESSION-PROMPT.local.md`. Med slug: `NEXT-SESSION-<slug>.local.md`.
Lokasjon:
- `multi-sesjon` → i prosjektmappen
- `plugin-arbeid` → i plugin-root
- `enkelt-oppgave` → i cwd
Innhold (7 seksjoner — samme struktur som `NEXT-SESSION-PROMPT.local.md` i llm-security/config-audit):
```markdown
# NEXT-SESSION-PROMPT — <tittel>
## Hvorfor dette eksisterer
...
## Status ved sesjonshåndoff
### ✅ Ferdig
### ⏳ Ikke startet / delvis
### ⚠️ Brutt / kjent risiko
## Slik fortsetter du
...
## Push-policy
...
## Verifiseringskommandoer
...
## Husk
...
```
### 4. Oppdater REMEMBER.md og TODO.md
Kun hvis filene finnes (opprettes ikke i random mapper). Flytter ferdige items, oppdaterer datoer.
### 5. Commit + push
Skip hvis `--no-commit`, `--dry-run`, eller `git status --porcelain` er tom.
Auto-genererer Conventional Commits-melding basert på endrede filer:
| Filmønster | Type |
|------------|------|
| `tests/**` | `test` |
| `*.md`, `README`, `CHANGELOG` | `docs` |
| Ny funksjon i `hooks/`, `scanners/` | `feat` |
| Bugfix | `fix` |
| Config, lockfile | `chore` |
Scope: plugin-navn hvis alle endringer er i én plugin.
Viser meldingen til bruker før commit. Pusher til `origin <current-branch>`.
Pre-commit hooks (secrets, pathguard) respekteres — hvis de blokkerer, stopper kommandoen og rapporterer uten bypass.
### 6. Print copy-paste-prompt
Kompakt blokk til terminal som bruker kopierer direkte til ny Claude-sesjon:
Auto-mode (used internally by Stop hook):
```
═════════════════════════════════════════════
NESTE SESJON — copy-paste til ny Claude:
═════════════════════════════════════════════
cd /Users/.../plugins/llm-security
cat NEXT-SESSION-PROMPT.local.md
git log --oneline -5
git status
Fortsett fra Commit 2 (entropy-scanner kontekst-suppression).
═════════════════════════════════════════════
/graceful-handoff --auto --no-push --non-interactive
```
### Automatisk trigger
Ingen handling kreves. Når kontekst krysser estimert 70%, fyrer Stop hook automatisk:
1. Skriver `NEXT-SESSION-PROMPT.local.md`
2. Stager kun handoff-artefakten (IKKE andre dirty filer — eksplisitt fix i v2.0)
3. Committer
4. **Pusher IKKE** — dette gjør du selv når du er klar
Ved ny sesjon (`claude --resume`), SessionStart hook leser handoff-filen automatisk og injiserer innhold i konteksten. Filen blir deretter renamet til `*.archived.local.md` for å hindre stale-load.
## Arkitektur (v2.0)
```
skills/graceful-handoff/SKILL.md # Frontmatter: disable-model-invocation, model: sonnet-4-6
scripts/handoff-pipeline.mjs # Deterministisk pipeline, returnerer JSON
hooks/scripts/statusline-monitor.mjs # Display: 60% / 70% hint
hooks/scripts/stop-context-monitor.mjs # Auto-execute ved estimert ≥70%
hooks/scripts/session-start-load-handoff.mjs # Auto-load på resume/compact
hooks/hooks.json # Registrerer alt
```
`disable-model-invocation: true` betyr at Claude IKKE kan invokere skill-en autonomt — bruker må trigge manuelt eller hook må kalle pipeline-skriptet direkte (Stop hook gjør det siste).
## Auto-trigger ved kontekst-terskel — hvordan virker det?
Det finnes ingen Claude Code-primitiv som eksponerer real-time kontekst-prosent til hooks (Anthropic har closed feature requests #16988, #27969, #34340). Vi bruker derfor en **approksimasjon**:
1. **Stop hook** fyrer etter hver model-respons og får `transcript_path` i payload
2. Hooken leser `wc -c <transcript>` for char-count
3. Estimerer tokens som `chars / 3.5`
4. Sammenligner mot `context_window_size` fra payload (default 200k, men respekterer 1M-windows)
5. Ved estimert ≥ 70%: spawner pipeline synkront
Dette estimatet kan avvike ±10% fra Claude's reelle telling. **70% er konservativt valgt** — gir buffer mot drift.
For å hindre repeat-firing innen samme sesjon: lock-fil `<transcript_dir>/.handoff-lock-<session_id>` opprettes ved første trigger.
## Argumenter
| Argument | Beskrivelse |
|----------|-------------|
| `[topic-slug]` | Kebab-case slug. Med slug: `NEXT-SESSION-<slug>.local.md`. Uten: `NEXT-SESSION-PROMPT.local.md` |
| `--no-commit` | Hopp over commit+push. Bruker håndterer commit manuelt |
| `--dry-run` | Ingen filer skrives, ingen git-operasjoner. Print kun hva som ville skjedd |
| `--no-push` | Commit OK, men ikke push (Stop hook bruker dette) |
| `--dry-run` | Ingen filer skrives, ingen git-operasjoner |
| `--auto` | Non-interactive, auto-Y på commit-bekreftelse (kun for hooks) |
| `--non-interactive` | Uten `--auto`: feil; med: kjør uten prompts |
## Frontmatter (SKILL.md)
```yaml
---
name: graceful-handoff
description: Produser handoff-artefakt, commit+push, og copy-paste-prompt for neste sesjon.
disable-model-invocation: true
model: claude-sonnet-4-6
allowed-tools: Bash(git:*) Bash(jq:*) Bash(node:*) Bash(find:*) Bash(pwd:*) Read Write Glob
---
```
**Merk:** `allowed-tools` er pre-approval, ikke restriction. Den fjerner permission-prompts for listede verktøy, men blokkerer ikke ulistede. For ekte sandbox: bruk project-level `permissions.deny` rules.
## Tidsbudsjett
< 60 sekunder totalt for hele pipelinen (manuell eller auto). Pipeline-skriptet er testbart med `node:test` uten LLM-kall.
## Eksempler
@ -156,65 +127,58 @@ Fortsett fra Commit 2 (entropy-scanner kontekst-suppression).
```
cd plugins/llm-security
# ... arbeid ...
/graceful-handoff
# → skriver plugins/llm-security/NEXT-SESSION-PROMPT.local.md
# → oppdaterer plugins/llm-security/REMEMBER.md + TODO.md
# → committer + pusher
# → printer copy-paste-prompt
# ... arbeid frem til 65% kontekst ...
# Auto-trigger: ved 70% fyrer Stop hook automatisk:
# → skriver plugins/llm-security/NEXT-SESSION-PROMPT.local.md
# → committer ARTEFAKTEN (ikke andre dirty filer)
# → IKKE pusher (du gjør det selv)
git push # når klar
```
**Multi-sesjon (ultraplan-prosjekt):**
**Manuell trigger med flagg:**
```
cd prosjekt-med-.claude/projects/2026-04-18-foo/
/graceful-handoff
# → skriver .claude/projects/2026-04-18-foo/NEXT-SESSION-PROMPT.local.md
# → (REMEMBER/TODO kun hvis de finnes i prosjektmappen)
# → committer + pusher
/graceful-handoff refactor-auth --no-commit
# → skriver plugins/<rot>/NEXT-SESSION-refactor-auth.local.md
# → ingen git-operasjoner
```
**Flere parallelle handoffs:**
**Ny sesjon:**
```
/graceful-handoff api-migration
/graceful-handoff token-refresh
# → to filer: NEXT-SESSION-api-migration.local.md + NEXT-SESSION-token-refresh.local.md
claude --resume
# SessionStart hook auto-injiserer handoff-innholdet i konteksten
# Du kan starte å jobbe direkte
```
**Bare artefakt, ingen git:**
## Tester
```
/graceful-handoff --no-commit
# → skriver artefakt + REMEMBER/TODO
# → git status viser fortsatt uncommittede endringer
```bash
node --test plugins/graceful-handoff/tests/
```
**Forhåndssjekk:**
36 tester på tvers av:
- `skill-structure.test.mjs` — frontmatter + commands/-fjerning (8)
- `scripts/handoff-pipeline.test.mjs` — pipeline JSON, idempotens, no-staging-regression, edge cases (11)
- `hooks/statusline-monitor.test.mjs` — terskler, null payload, malformed JSON (9)
- `hooks/stop-context-monitor.test.mjs` — estimering, lock-fil, stub pipeline (7)
- `hooks/session-start-load-handoff.test.mjs` — source filter, multi-level search, archive (9)
- `plugin-manifest.test.mjs` — plugin.json schema, CHANGELOG (6)
```
/graceful-handoff --dry-run
# → printer planlagt artefakt, foreslått commit-melding, copy-paste-prompt
# → skriver ingenting, gjør ingen git-operasjoner
```
## Begrensninger og åpne antakelser
## Tidsbudsjett
< 60 sekunder totalt. Hvis den drar ut: lag en minimal handoff med det du har, og noter det som ufullstendig. Aldri Agent-delegering eller WebSearch — main-sesjonen er raskere.
## Begrensninger (v1.0.0)
- Ingen auto-invokasjon ved kontekst-terskel — bruker triggrer manuelt. Vurderes i v1.1
- Commit-meldingen er auto-generert uten Y/n-bekreftelse. Hvis kvalitet blir et problem: rapporter, vurderer "vis og bekreft" i v1.1
- Overskriver eksisterende NEXT-SESSION-fil (merger fra innhold, men ikke fra diff). Sikkerhetskopi-mønster vurderes
- Ingen integrasjon mot `.claude/projects/*/progress.json` utover lesing
- **statusLine-plassering i `hooks/hooks.json`** er en åpen antakelse. Verifiser med smoke-test; fallback er å flytte til global `~/.claude/settings.json`.
- **Token-estimering ±10%** mot Claude's reelle telling. 70%-tersklen er konservativ.
- **Issue [#26251](https://github.com/anthropics/claude-code/issues/26251)** — `disable-model-invocation: true` regression kan blokkere user-invocation. Manuell smoke-test før du stoler på det.
- **Push gjenstår alltid manuell.** Auto-eksekvering pusher ALDRI — irreversibel handling beholdes hos bruker.
- Auto-trigger respekterer pre-commit hooks (secrets, pathguard) — bypasser ALDRI med `--no-verify`.
## Sikkerhet
- Respekterer alle pre-commit hooks (secrets-scanning, pathguard). Bypasser ALDRI
- Filer er `*.local.md` → matches av `*.local.md` i global/prosjekt-gitignore
- Ingen nettverks-kall, ingen eksterne avhengigheter
- Krever kun `allowed-tools: Read, Write, Edit, Bash, Glob`
- Pipeline stager **kun** handoff-artefakten + REMEMBER.md/TODO.md (hvis de finnes). Stagger ALDRI andre dirty filer (regression-test håndhever dette).
- Filer er `*.local.md` → matches av `.gitignore`-mønstre i alle prosjekter
- Ingen nettverks-kall (ingen WebSearch, ingen Agent-delegering)
- Bash sub-scoped: `Bash(git:*)`, `Bash(jq:*)`, `Bash(node:*)`, `Bash(find:*)`, `Bash(pwd:*)`
## Lisens