v2.5.0 — Auto-Read, No More Asking

What changed

未读 HANDOFF 自动加载，不再询问「要不要先读？」

栋老师反馈：新会话 + 未读 HANDOFF = 续接意图，多问一句是多余摩擦。

Changes

• New Session Protocol Step 0: unread HANDOFF → auto-read immediately; .done only → ask
• handoff_reminder.py: signal message updated from "要不要先读？" to "直接加载继续工作"
• install_reminder.py: install message updated to reflect auto-load behavior
• README.md: auto-resume as default, manual trigger as fallback
• GitHub repo description updated
• SKILL.md: Quick Reference, Common Mistakes, How it works all synced
• PROJECT.ftmd: decision log appended, verified question marked done

Files

• SKILL.md: +17/-15
• handoff_reminder.py: +1/-1
• install_reminder.py: +1/-1
• README.md: +10/-12
• PROJECT.ftmd: +19/-7

v2.4.0 — SessionStart Auto-Reminder

What's new

🔔 SessionStart Auto-Reminder

Never forget to resume context. After a one-command install, Claude Code proactively asks "要不要先读 HANDOFF?" at the start of every new session.

• handoff_reminder.py — SessionStart hook that detects HANDOFF files and prompts the user
• install_reminder.py — One-command setup: auto-detects Python, copies script, configures settings.json (idempotent)
• SKILL.md proactive prompt — Claude now offers to set up the auto-reminder after every /handoff
• README.md — Auto-reminder highlighted in Quick Start

How to use

python install_reminder.py

Restart Claude Code. Done.

Commits since v2.3.1

• docs: add auto-reminder to README Quick Start
• feat: skill prompts Claude to offer auto-reminder setup
• feat: add install_reminder.py — one-command SessionStart hook setup
• feat: add SessionStart auto-reminder hook

v2.3.1 — Review-Validated & Rule-Refined

Since v2.3.0:

External Feedback

• 栋老师完整评审：评分 8.5/10，确认双文件架构 + 验证协议 + 失败记忆为三大核心优势
• 5 个改进方向 + 5 个优先级功能已记录为 V2.4 路线图

Refinements

• FTMD 对外传播名称：「AI Agent Context Transfer Format」
• GitHub 上传规则明确：新 skill 先确认再推，已有 skill 直接推送
• Skill 开发质量标准固化（6 条：零依赖审计、canonical trigger、专业 README、跨文件对齐、全量同步、7+1 清单）

Documentation

• README: FTMD name propagation
• PROJECT.ftmd: +5 Decision Log entries from review session

No functional changes. V2.3.0 users do not need to upgrade.

v2.3.0 — Fully Self-Contained & Battle-Hardened

V2.3.0 — 去硬依赖 + 零依赖审计 + Canonical Trigger

Part 1: Remove claude-mem Hard Dependency

Handoff is now a fully self-contained skill. Zero external dependencies.

• claude-mem → optional enhancement. Was a hard dependency, now an optional complement.
• 4 inline guards added. Every claude-mem touchpoint has "if available... else skip silently".
• Detection method documented. AI checks for mcp__*mem-search* tools.

Part 2: Zero-Dependency Hardening (3 audit rounds, 17 fixes)

Audited every line for implicit dependencies. Simulated new user: fresh Claude Code, no skills, no claude-mem, any model, any platform.

Fix	Area
Hardcoded E:\projects\handoffs\ → pwd	Save Location
python → python3 or python	Environment capture (macOS/Ubuntu compat)
7× git guard (if this is a git repo)	Verification, doctor, recovery, snapshot
3× tests guard (if available)	Verification, doctor
OS-neutral format example	Documentation
8→9 sections count fix	Bug fix
Fall-through logic for save location	Robustness
Trigger description expanded	Discoverability

Part 3: 「先读 HANDOFF」Canonical Trigger

Established the official resume phrase, enforced in 6 locations:
Post-Generation · New Session Protocol · Quick Reference · README · CONTRIBUTING · GitHub repo description

Part 4: README Professional Rewrite

137 → 295 lines: Hero section, Problem/Solution narrative, ASCII architecture diagram, 5 badges, Comparison matrix (8 dimensions × 4 alternatives), 6 Design Principles, Real-World Workflow with 🔁 loop summary.

Part 5: CONTRIBUTING.md

Added 7+1 sync checklist, Convention section, 6 Design Principles.

---

For new users: Copy SKILL.md → ~/.claude/skills/handoff/ → /handoff → done.
To resume: Say 先读 HANDOFF in a new session.

v2.2 — Recovery Protocol, evidence-backed verification

v2.2 — Recovery and trust

Recovery Protocol

New sessions now follow a 3-step recovery workflow after reading handoff files:

1. Verify git state — confirm branch and last commit match HANDOFF's Git Snapshot
2. Spot-check [V] claims — re-read one referenced file or re-run one test to confirm evidence
3. Confirm next step — state the first Next Step to user before beginning work

[V] Evidence Required

Every [V] claim in the Completed section must now include its evidence source inline:

• ✅ Login redirect fixed [V] (AuthGuard.tsx:42, 7 tests pass in auth-guard.test.tsx)
• ❌ Login redirect fixed [V] — no evidence, not acceptable

If no file, test, or commit can be cited to prove a claim, it must be downgraded to [?].

v2.1 — Data boundaries, expansion control, anti-fatigue

v2.1 — Architecture hardening

Based on peer review of the V2 design.

Changes

• Entry cap (30) — Decision Log and Failure Memory each capped at 30 entries. Oldest deleted on overflow. Prevents PROJECT.ftmd from growing indefinitely.
• claude-mem data boundary — Explicit boundary table: what belongs to claude-mem (cross-project knowledge, user preferences) vs. handoff (current project state, session decisions).
• Timeline as decision evolution — Timeline command explicitly scoped to strategic decisions, not development logs or file edits.
• Consecutive rejection stop — If user declines reminders twice in a row, all further auto-reminders stop for that session.

Docs

• README: Added Compatibility section — skill works on any Claude Code instance regardless of underlying model (tested on DeepSeek). FTMD files readable by any AI tool.

v2.0 — Dual-file model, environment capture, subcommands

V2.0 — Project State Management

Core upgrade from session handoff tool to project memory layer.

New: Dual-File Model

File	Role
PROJECT.ftmd	Long-term memory — decisions, failures, environment (never deleted)
HANDOFF-YYYY-MM-DD.ftmd	Session snapshot — what happened this session, what's next

Decisions and lessons no longer get lost when handoffs are archived.

New: Environment Auto-Capture

OS, Shell, Node, Python, Git, Claude Code version recorded automatically on every /handoff.

New: Git Snapshot Section

HANDOFF.ftmd now includes branch, last commit, and changed files — the new session doesn't need to rescan the repo.

New: Subcommands

Command	Purpose
/handoff	Generate HANDOFF + update PROJECT + cleanup
/handoff status	One-line project status
/handoff timeline	Decision log and failure memory in chronological order
/handoff doctor	Health check: PROJECT, HANDOFF, Git, Env, Tests

Changed from v1.x

• HANDOFF.ftmd: 8 → 9 sections (added Git Snapshot)
• HANDOFF count cap: 5 → 3 (PROJECT.ftmd now carries the history)
• New session protocol: reads PROJECT.ftmd first, then HANDOFF
• Source-of-truth rank: PROJECT.ftmd inserted above HANDOFF

v1.2 — Workflow closure, forced verification, README polish

What's new in v1.2

• Post-Generation prompt — After writing HANDOFF, actively suggests opening a new session. Closes the workflow loop: write → restart → resume.
• Mandatory git diff --stat — Verification step 1 now requires git diff --stat output used verbatim in File Map. No more recalled file lists.
• README badges — Version and license badges for a more polished repo appearance.

From v1.1.1

• Quick Reference now matches New Session Protocol behavior
• Missing-handoff fallback response added

v1.1 — FTMD format spec, proactive checks, example

What's new in v1.1

• FTMD format spec — Frictionless Transfer Markdown Document, formally named and documented
• Proactive milestone checks — nudges at ~10 exchange intervals, not just reactive rot detection
• HANDOFF-example.ftmd — complete real-world example (login redirect fix scenario)
• Short-Session Gate quantified — 4 concrete criteria instead of vague "~5 exchanges"
• Multiple handoff handling — New Session Protocol now reads only the newest, marks rest .done
• GitHub topics — claude-code, handoff, skill, session-continuity, ftmd, ai-workflow

What's in v1.0 (initial)

• 8-section handoff template (Task → Startup Protocol)
• Verification Protocol with [V]/[?] tagging
• Source-of-Truth Rank
• Degradation detection (reactive)
• claude-mem bidirectional integration
• Auto-cleanup rules (stale purge + count cap)
• 4-level save location priority
• Short-session gate
• Common mistakes reference