feat: Session handoff skill for context preservation - #10

Summary

Adds a complete handoff system that captures session state before context compaction and restores it afterward, enabling seamless session continuity across agents and tools.

What's included

• 3 new skills: superpowers-ruby:handoff (create), superpowers-ruby:handoff-resume (restore), superpowers-ruby:handoff-list (browse)
• 2 hook scripts: hooks/handoff-create (mechanical capture of git state, plan files, modified files) and hooks/handoff-restore (restore + archive consumed handoffs)
• Automatic compaction hooks: PreCompact/PostCompact for Claude Code, experimental.session.compacting/session.compacted for OpenCode. Codex gets manual-only support (no compaction hooks available).
• Cross-agent handoff: Documents are plain markdown with YAML frontmatter — any agent (Claude Code, OpenCode, Codex) or human can resume from them

How it works

Session running → Context grows → Compaction triggers
    ↓
PreCompact hook writes docs/handoffs/YYYY-MM-DD-<topic>.md
  (git state, modified files, plan references, LLM placeholder sections)
    ↓
Compaction happens
    ↓
PostCompact hook reads the handoff, injects as additionalContext
  (LLM fills in Goal, Decisions, Next Steps from compacted memory)
    ↓
Session continues seamlessly

Manual flow: /superpowers-ruby:handoff creates a full LLM-enriched handoff. /superpowers-ruby:handoff-resume in a new session reads and restores it.

Handoff document structure

---
created: 2026-04-14T14:30:22+00:00
branch: lg/handoff
trigger: compact | manual
restored: false
topic: handoff-skill-implementation
---

Sections: Goal, Current State, Key Decisions, Modified Files, Failed Approaches, Files to Read, Next Steps, Open Questions

Archival

Consumed handoffs get restored: true + restored_at in frontmatter and move to docs/handoffs/_archive/.

Version bump

Bumped to 6.3.0 across all 6 manifest files. Backfilled missing 6.2.0 CHANGELOG entry.

Test plan

• Run hooks/handoff-create --trigger compact — verify doc created in docs/handoffs/ with correct frontmatter and mechanical sections
• Run hooks/handoff-restore — verify JSON output with additionalContext, file marked restored, moved to _archive/
• Invoke /superpowers-ruby:handoff manually — verify all sections filled by LLM
• Invoke /superpowers-ruby:handoff-resume in fresh session — verify context restored
• Invoke /superpowers-ruby:handoff-list — verify table output
• Verify hooks/hooks.json has valid PreCompact and PostCompact entries
• Verify .opencode/plugins/superpowers.js has experimental.session.compacting and session.compacted handlers
• Trigger actual compaction in Claude Code — verify end-to-end automatic handoff

🤖 Generated with Claude Code