agent-handoff-kit

EN: A portable, file-based handoff protocol that makes long Agent tasks survive context compression, model switching, crashes, and multi-agent takeovers — without losing progress or lying about what was actually verified. 中文： 一个可移植、基于文件的工作交接协议，让长任务在上下文压缩、切换模型、崩溃或多人接手后不丢进度，也绝不把"计划"伪装成"已完成的事实"。

Value proposition / 价值主张

• EN: Not a todo list — a handoff-quality contract that separates Verified · Completed · Pending · Assumption.
• 中文： 不是待办清单，而是一份"可移交、可恢复、可验证"的 Agent 工作状态协议，明确区分"已验证 / 已完成 / 待完成 / 假设"。

---

Why / 为什么需要它

Long Agent tasks die in four ways. This kit kills all four.

Failure	How this kit prevents it
Context window compressed → plan forgotten	State lives in 4 files, not in context.
Switched from Claude to Codex → no shared memory	Files are vendor-neutral; any agent reads them.
Crash mid-task → "did it finish?" unknown	EVIDENCE_LOG.md records what actually ran + output.
New person/agent takes over → re-derives everything	HANDOFF.md enables resume in <30 seconds.

中文： 长任务死于四种方式，本工具包全部拦截——上下文压缩丢失计划、切换厂商无共享记忆、崩溃后不知是否完成、接手者重复推导。状态写入 4 个文件，而非留在上下文里。

---

Demo / 演示

Animated placeholder. Replace with a real 30-second GIF before publishing (e.g., a screen recording of 任务中断 → 新 Agent 30 秒恢复).

---

Install / 安装

This is an open-standard Agent Skill. Install it separately into each host you use — they do not share skill directories.

Claude Code

mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit
# or copy the folder here if you downloaded a tarball

Then in Claude Code, the skill activates when a task exceeds 30 min or you say 继续 / 接手 / 恢复 / 下次再做.

Cursor

mkdir -p ~/.cursor/skills
cd ~/.cursor/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

Codex

mkdir -p ~/.codex/skills
cd ~/.codex/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

Gemini CLI

mkdir -p ~/.gemini/skills
cd ~/.gemini/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

重要 / Important: Each host has its own skills directory. Installing in Claude Code does not make it available in Cursor. Install in every host you use. Every host reads the same SKILL.md and references/, so behavior is consistent across vendors.

Verify install

python3 ~/.claude/skills/agent-handoff-kit/scripts/check_state.py --selfcheck

---

The Four State Files / 四个状态文件

File	Holds
TASK_STATE.md	Goal, scope, current phase, status, blockers.
EVIDENCE_LOG.md	Commands run, output summaries, test results, links.
HANDOFF.md	The single file to resume in <30s.
DECISIONS.md	Trade-offs and why.

Status markers enforce honesty:

Marker	Meaning
[x]	Verified — done AND proven by evidence
[~]	Completed — done, NOT yet verified
[ ]	Pending — not started
[?]	Assumption — needs confirmation

铁律： 永远不要把 [?] 标成 [x]。永远不要让 [~] 没有对应的验证步骤。

---

Natural-language workflow / 自然语言工作流

You do not need to type slash commands. Just say what you want:

You say	Equivalent	What happens
"保存检查点" / "save checkpoint"	/checkpoint	Refresh all 4 files, honest status, write next step.
"恢复任务" / "resume"	/resume	Read state → handoff → decisions → last 5 evidence entries, continue.
"交接给下一位" / "handoff"	/handoff	Finalize HANDOFF.md with resume-in-30s instructions.

---

Complete example: 任务中断 → 新 Agent 30 秒恢复上下文

Setup

You are implementing a Stripe checkout integration across 3 endpoints. Task estimated at ~90 minutes. At minute 40 the session is interrupted (context limit hit, day ends).

Step 1 — Before interruption, the running Agent wrote TASK_STATE.md

# Task State

## Goal
Integrate Stripe Checkout into the billing service with idempotent webhook handling.

## Scope
- In: /api/checkout, /api/webhook, idempotency keys, unit tests.
- Out: refunds, customer portal, UI.

## Current Phase
Phase 2 of 3: Implementation (Phase 1 setup done, Phase 3 tests pending).

## Progress
- [x] Stripe SDK added + keys via env (EVIDENCE: E-003)
- [x] /api/checkout creates PaymentIntent (EVIDENCE: E-005, curl 200)
- [~] /api/webhook signature verification written, NOT yet tested
- [ ] Idempotency key handling
- [ ] Unit tests for webhook
- [?] Stripe sends `payment_intent.succeeded` for this account tier (assume yes, confirm)

## Blockers
- None currently.

## Last Updated
2026-07-30T12:41:00Z · claude-opus · session-7c3

Step 2 — And HANDOFF.md

# Handoff

## Resume In <30 Seconds
1. Read TASK_STATE.md → Goal + Progress
2. Read this file → Immediate Next Step
3. Read DECISIONS.md → constraints
4. Skim EVIDENCE_LOG.md → last 5 entries (E-001..E-006)

## Immediate Next Step
Run `npm test test/webhook.spec.ts`. The signature-verification code in
`src/webhook.ts:42` is written but UNVERIFIED ([~]). If tests pass, mark it
[x] and move to idempotency keys. If they fail, the likely cause is the
raw-body requirement — see DECISIONS.md D-002.

## Do NOT
- Do not add refunds. Out of scope.
- Do not commit the .env file. Secrets stay local.

## Handoff From / To
From: claude-opus @ 2026-07-30T12:41:00Z
To: any agent or human

Step 3 — Interruption happens

Context wiped. Day ends. Laptop closed.

Step 4 — Next day, a fresh Codex session opens

You: 接手昨天那个 Stripe 任务。

New Agent (Codex): Running resume protocol — reads TASK_STATE.md, HANDOFF.md, DECISIONS.md, last 5 EVIDENCE_LOG.md entries.

Resume complete in 22 seconds. Status summary:

• Goal: Stripe Checkout integration, 3 endpoints.
• Verified done: SDK setup, /api/checkout.
• Completed-but-unverified: webhook signature check (src/webhook.ts:42).
• Next step per HANDOFF.md: npm test test/webhook.spec.ts.
• Open assumption: payment_intent.succeeded event tier — needs confirmation.

Running the test now.

Result: Zero re-derivation. The new agent knew exactly what was proven, what was only written, and what to do next — because the protocol forced the previous agent to distinguish Verified from Completed.

---

Optional validation script / 可选校验脚本

Before any handoff, run:

python3 scripts/check_state.py            # checks TASK_STATE.md etc. in cwd
python3 scripts/check_state.py --strict   # exit 1 on any warning

It detects: missing task goal, missing immediate next step, missing verification evidence for [~] items, unresolved [?] assumptions, and stale blockers. A bash fallback is provided at scripts/check_state.sh.

---

Privacy / 隐私

• No secrets written. State files reference env var names (STRIPE_SECRET_KEY) and config paths — never the values. The skill refuses to write credentials.
• No project content uploaded. All four files are local Markdown. Nothing is sent to any external service. Evidence links are relative paths or local run IDs.
• Safe to commit. If you commit state files to a repo, .gitignore your .env and any paths referenced as evidence that contain secrets. A sample .gitignore snippet is in references/host-integration.md.

中文： 不写入任何密钥、Token、凭证；状态文件只用环境变量名或相对路径引用。所有文件均为本地 Markdown，不上传任何项目内容到外部服务。

---

Evaluation / 评测

15 cases covering context-wipe recovery, cross-vendor handoff, test failures, requirement changes, interruptions, and human handoff — see EVALUATION.md.

---

File map / 文件地图

agent-handoff-kit/
├── SKILL.md                       # activation rules + protocol summary
├── README.md                      # this file
├── LICENSE                        # MIT
├── EVALUATION.md                  # 15 evaluation cases
├── references/
│   ├── state-schemas.md           # field-level schema for the 4 files
│   ├── file-templates.md          # copy-paste starter templates
│   ├── workflow.md                # checkpoint / resume / handoff sequences
│   └── host-integration.md        # install on Claude/Cursor/Codex/Gemini
├── scripts/
│   ├── check_state.py             # state validator (python3)
│   └── check_state.sh             # state validator (bash fallback)
└── docs/
    └── demo.svg                   # animated placeholder

---

License

MIT — see LICENSE. Copyright (c) 2026 whaojie797-design