feat(handoff): improve resumable session state

[baleen37]

Summary

• redesign handoff files around Task, Completed, Current State, and verifiable Next Steps
• embed an artifact-only resume gate and keep user directions verbatim with one First action
• retire pickup and align XDG handoff permissions during setup

Tests

• npm test
• bats tests/me/handoff-skill.bats tests/frontmatter_tests.bats tests/me/me-specific.bats
• npm run check:codex
• git diff --check

Summary by CodeRabbit

• New Features
  • Added structured handoff documents with clearer task status, current state, completed work, and next steps.
  • Handoffs now use a configurable XDG-based storage location and preserve write-only behavior.
  • Setup automatically configures permissions for the handoff directory.
• Bug Fixes
  • Improved handoff validation to prevent missing details, duplicate sections, secrets, and inaccurate state claims.
• Tests
  • Added coverage for handoff structure, storage configuration, resume guidance, and pickup behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 58774d88-bec7-4881-9b12-5cb74d663934

📥 Commits

Reviewing files that changed from the base of the PR and between 34a04e1 and b4a4746.

📒 Files selected for processing (8)

• docs/superpowers/plans/2026-07-18-handoff-resumable-state.md
• docs/superpowers/specs/2026-07-18-handoff-resumable-state-design.md
• plugins/me/skills/handoff/SKILL.md
• plugins/me/skills/setup/SKILL.md
• plugins/me/skills/setup/configure-handoff-directory.mjs
• plugins/me/skills/setup/settings.json
• tests/fixtures/handoff/compound-user-direction.md
• tests/me/handoff-skill.bats

---

📝 Walkthrough

Walkthrough

The PR redesigns the write-only handoff skill around structured resumable state, moves handoff storage to an XDG-based directory, adds setup automation for permissions, and introduces documentation, fixtures, and Bats tests covering the new contract.

Changes

Handoff redesign

Layer / File(s)	Summary
Handoff contract and implementation plan docs/superpowers/plans/..., docs/superpowers/specs/...	Defines required sections, conditional context, resume-gate ordering, write-only behavior, and implementation validation steps.
Structured handoff generation plugins/me/skills/handoff/SKILL.md	Updates explicit triggering, XDG output handling, structured sections, validation rules, first-action derivation, and resume protocol guidance.
Handoff directory setup plugins/me/skills/setup/*	Adds directory configuration automation, updates setup instructions and checklist coverage, and changes the default handoff permission path.
Fixtures and behavioral validation tests/fixtures/handoff/*, tests/me/handoff-skill.bats	Adds representative handoff content and tests section structure, directory handling, context rules, output validation, ordering, and pickup-related exclusions.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Possibly related PRs

• baleen37/bstack#628: Earlier handoff-skill design changes overlap with this PR’s handoff location, output structure, and rules.
• baleen37/bstack#638: Earlier permission handling for handoff directories overlaps with this PR’s setup and additionalDirectories changes.
• baleen37/bstack#640: Both changes modify handoff resume and pickup behavior in SKILL.md.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/improve-handoff

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}