open/graceful-handoff
1
0
Fork 0
Code Issues Releases Activity

Compare commits

base: open:main
Branches Tags
open:main
open:v3.1.0
open:v3.0.0
open:v2.1.0
..
compare: open:v3.1.0
Branches Tags
open:main
open:v3.1.0
open:v3.0.0
open:v2.1.0

No commits in common. "main" and "v3.1.0" have entirely different histories.
main ... v3.1.0

2 changed files with 31 additions and 60 deletions
Download patch file Download diff file Expand all files Collapse all files

8
CHANGELOG.md
View file

@ -4,14 +4,6 @@ All notable changes to graceful-handoff are documented here.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
## [Unreleased]
### Changed
- **README brought in line with the org repo standard** (`repo-standard` gate, 0 ERROR). Documentation only — no plugin code, version, or behaviour changed. H1 is now the repo name; the opening line is verbatim the forge description (so description == catalog == README is machine-checkable); `## Install` is a top-level heading on the first screen and carries the CLI command `claude plugin install graceful-handoff@ktg-plugin-marketplace` next to `marketplace add`; `## Non-goals` and `## Changelog` sections added.
- **Dropped the static `tests-30` badge.** This forge has no CI runner, so the badge asserted a run nothing verifies. The Testing section now states the command and says plainly that nothing runs it automatically. Note for the catalog: the tests axis no longer has a badge backing it.
- **Fixed two dead `../../README.md` references** inherited from the monorepo (README lines 7 and the marketplace footer) — both pointed outside a standalone repo and 404'd.
## [3.1.0] - 2026-06-24
### Changed

83
README.md
View file

@ -1,51 +1,26 @@
# graceful-handoff
# Graceful Handoff Plugin for Claude Code
One-command session handoff into the STATE.md continuity system. Overwrites the nearest STATE.md with a complete state-of-play and commits per remote policy.
> One command to end a session cleanly and hand it to the next one — `/graceful-handoff` reaches a natural stopping point and overwrites the nearest `STATE.md` with a complete, self-standing state-of-play.
> **Solo-maintained, fork-and-own.** This plugin is a starting point, not a vendor product. Issues are welcome as signals; pull requests are not accepted. See [GOVERNANCE.md](GOVERNANCE.md) for the full model and what upstream provides.
*AI-generated: all code produced by Claude Code through dialog-driven development. Every change is human-directed, reviewed, and validated before commit.*
*AI-generated: all code produced by Claude Code through dialog-driven development. [Full disclosure →](../../README.md#ai-generated-code-disclosure)*
![Version](https://img.shields.io/badge/version-3.1.0-blue)
![Platform](https://img.shields.io/badge/platform-Claude_Code_Plugin-purple)
![Skill](https://img.shields.io/badge/skill-1-green)
![Hooks](https://img.shields.io/badge/hooks-0-lightgrey)
![Pipeline](https://img.shields.io/badge/STATE--helper-deterministic-cyan)
![Tests](https://img.shields.io/badge/tests-30-success)
![License](https://img.shields.io/badge/license-MIT-lightgrey)
A Claude Code plugin that makes session handoff a single deliberate command, fully integrated with a `STATE.md`-based continuity system. When a session is filling up — or you simply want to stop — `/graceful-handoff` reaches a natural stopping point, **overwrites the nearest `STATE.md`** with where you are, the next concrete step, and what to read, then commits per your remote policy. The next session reads that `STATE.md` and stands on its own.
---
## Install
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
claude plugin install graceful-handoff@ktg-plugin-marketplace
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"graceful-handoff@ktg-plugin-marketplace": true
}
}
```
## Requirements
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.x+
- Node.js (any recent LTS — for the helper script)
- A git repository (the helper detects detached HEAD / missing upstream and reports gracefully)
---
## Table of Contents
- [What Is This?](#what-is-this)
- [Non-goals](#non-goals)
- [The Problem](#the-problem)
- [The STATE.md Model](#the-statemd-model)
- [Quick Start](#quick-start)
@ -58,7 +33,6 @@ Or enable directly in `~/.claude/settings.json`:
- [Testing](#testing)
- [What Changed in v3.0 (BREAKING)](#what-changed-in-v30-breaking)
- [Limitations & Open Assumptions](#limitations--open-assumptions)
- [Changelog](#changelog)
- [License](#license)
- [Feedback & Contributing](#feedback--contributing)
@ -79,19 +53,6 @@ The skill is `disable-model-invocation: true`: the model cannot trigger a handof
---
## Non-goals
What this plugin deliberately does *not* do — read this before adopting it:
- **It never triggers itself.** No hooks, no Stop auto-trigger, no context-percentage threshold. If you want a handoff written automatically when a session fills up, this is the wrong plugin — v2 did that and v3 removed it on purpose.
- **It does not read `STATE.md` back.** Injecting the nearest `STATE.md` at session start is the job of a global `session-start.sh` hook you own. This plugin only writes.
- **It does not push.** The helper has no push path at all; pushing stays a separate, user-triggered step.
- **It is not a general-purpose commit tool.** `--commit` stages `STATE.md` plus explicitly named `--also` paths, and nothing else. Unrelated dirty files stay dirty — by design.
- **It does not edit `MEMORY.md` or `CLAUDE.md`.** It warns when `MEMORY.md` grows past 200 lines; the edit is yours.
- **It does not publish anything.** `STATE.md` is internal state-of-play, never a public artifact — on a public remote it stays gitignored and uncommitted.
---
## The Problem
Long sessions fill the context window. The classic failure mode is summarizing, committing, and writing a continuation prompt under time pressure — or skipping steps and losing continuity. Earlier versions of this plugin attacked that with auto-trigger hooks that wrote a separate `NEXT-SESSION-PROMPT` artifact.
@ -143,7 +104,29 @@ The `👉 NESTE` block is always first, right after the title — it carries the
## Quick Start
Installed? Then the whole workflow is one command:
### Prerequisites
- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v2.x+
- Node.js (any recent LTS — for the helper script)
- A git repository (the helper detects detached HEAD / missing upstream and reports gracefully)
### Install
```bash
claude plugin marketplace add https://git.fromaitochitta.com/open/ktg-plugin-marketplace.git
```
Or enable directly in `~/.claude/settings.json`:
```json
{
"enabledPlugins": {
"graceful-handoff@ktg-plugin-marketplace": true
}
}
```
### Hand off
```
> /graceful-handoff
@ -278,7 +261,7 @@ node --test 'tests/**/*.test.mjs'
| `tests/scripts/handoff-pipeline.test.mjs` | `--plan`/`--commit`/`--dry-run`, nearest-STATE resolution, remote classification, **no-`git add -A` regression**, gitignored-STATE skip, detached HEAD |
| `tests/plugin-manifest.test.mjs` | plugin.json version + description, CHANGELOG `[3.0.0]` BREAKING + preserved history |
The suite runs in a few seconds — no LLM involvement. **Nothing runs it automatically:** this forge has no CI runner, so the command above from a clean clone is the only verification. That is also why this README carries no test badge — a static one would assert a run nobody performed.
The suite runs in a few seconds — no LLM involvement.
---
@ -290,6 +273,8 @@ The suite runs in a few seconds — no LLM involvement. **Nothing runs it automa
- **Remote-aware tracked/local-only policy** so `STATE.md` never leaks to a public mirror.
- **Removed the Sonnet pin** — handoff synthesis inherits the session model.
Full history in [`CHANGELOG.md`](CHANGELOG.md).
---
## Limitations & Open Assumptions
@ -300,12 +285,6 @@ The suite runs in a few seconds — no LLM involvement. **Nothing runs it automa
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md).
---
## License
MIT. See [`LICENSE`](LICENSE).
@ -316,4 +295,4 @@ MIT. See [`LICENSE`](LICENSE).
- **Bug reports + feature requests:** open an issue on [Forgejo](https://git.fromaitochitta.com/open/ktg-plugin-marketplace)
- **Pull requests:** not accepted on this repo (solo project, dialog-driven development with Claude Code). Fork freely if you need to extend.
- **Marketplace:** part of [ktg-plugin-marketplace](https://git.fromaitochitta.com/open/ktg-plugin-marketplace) — see the catalog for related plugins.
- **Marketplace:** part of [ktg-plugin-marketplace](https://git.fromaitochitta.com/open/ktg-plugin-marketplace) — see the [root README](../../README.md) for related plugins.