Feature: Plan-aware session handoff commands (/create_handoff + /resume_plan)

[longevityboris]

Problem

Superpowers v5.0.5's writing-plans skill creates detailed plans saved to docs/superpowers/plans/, and the execution handoff offers subagent-driven or inline execution. But when context fills up mid-execution (or the user needs to start a new session for any reason), there's no structured way to hand off plan state to the next session.

The current workaround — manually asking Claude to summarize state before ending — is unreliable and loses the structured plan reference. The writing-plans skill suggests /compact after planning, but compacting doesn't preserve which tasks are done, what gotchas were discovered, or what the next concrete step is.

This is the #1 pain point in the Claude Code community right now. The viral post about it by @zarazhangrui got 3,311 likes on X. Anthropic has open issues about it with no resolution.

Proposed Solution

Two new slash commands that integrate with Superpowers' existing plan workflow:

/create_handoff

Run when context is getting full or before ending a session. It:

1. Locates the active plan in docs/superpowers/plans/ (most recent .md)
2. Captures plan progress — which tasks are done (via TodoWrite/checkbox state), which remain
3. Records git state — branch, last commit, uncommitted changes, test status
4. Captures decisions & gotchas — the things that cost 45 minutes to rediscover
5. Writes specific next steps — not "continue the refactor" but "Implement Task 4 starting with the failing test in tests/auth/test_jwt.py"
6. Saves to thoughts/shared/handoffs/ (or configurable location)

/resume_plan

Run at the start of a new session. It:

1. Finds the most recent handoff + plan file
2. Validates git state against what the handoff expects
3. Reports discrepancies (e.g., handoff says uncommitted changes exist but git status is clean)
4. Offers execution choice: subagent-driven (recommended) or inline via executing-plans

How it connects to existing Superpowers skills

writing-plans → creates plan → user works → context fills up
                                                    ↓
                                          /create_handoff
                                                    ↓
                                          new session
                                                    ↓
                                          /resume_plan
                                                    ↓
                                subagent-driven-development or executing-plans

Why this belongs in Superpowers (not just user config)

1. Plan-awareness: Generic handoff tools don't know about Superpowers' plan format, task structure, or TodoWrite state. A Superpowers-native handoff can reference the exact plan file and track which tasks are complete.

2. Workflow integration: The handoff should connect to subagent-driven-development and executing-plans on resume, not require the user to manually re-invoke the right skill.

3. Consistency with existing patterns: Superpowers already manages the plan lifecycle (brainstorming → writing-plans → execution). Handoff is the missing link in that chain.

Working Implementation

We've built and tested this pattern. The commands are plain .md files in ~/.claude/commands/ that instruct Claude to generate structured handoff documents. Happy to submit as a PR if there's interest.

We also have supporting hooks:

• A Stop hook that blocks at 70% context and prompts /create_handoff
• A SessionStart hook that auto-loads the most recent handoff
• A PreCompact hook that saves continuity state before compaction

Related

• anthropics/claude-code#11455 — Session Handoff / Continuity Support (OPEN, no native solution)
• anthropics/claude-code#30438 — First-Class Plan System proposal
• anthropics/claude-code#30510 — Delegate to Background Agent at ExitPlanMode
• Clear context after building detailed implementation plan - Claude Code #478 — Clear context after building plan (CLOSED, partially addressed by /compact suggestion)
• brainstorming/writing-plans SKILL efficiency #512 — Writing-plans token efficiency

— Boris @ 199 Biotechnologies

[obra]

I've literally never had a problem with just telling superpowers to just continue with the plan in $filename.

We've finally almost gotten rid of our legacy slash commands and we should never need to add new slash commands. Just talk to the agent.