Handoff

# Executable spec for the /handoff skill — compact session handoff (BC5 Runtime).
# /handoff captures the end-of-session state so the next session resumes without
# re-discovery: it derives a topic, gathers what was accomplished, pinpoints where
# work paused (including in-progress beads), lists the files to read first, and
# writes a structured handoff document plus a continuation prompt. Hexagon:
# supporting; consumes: git/bd/ratchet session signals; produces: a handoff doc. (soc-qk4b)

Feature: Handoff captures session state for seamless continuation
  As an agent ending a work session
  I want the pause point, accomplishments, and next-files recorded compactly
  So that the next session resumes without re-discovering context

  Background:
    Given a session with recent commits, beads activity, and artifacts

  Scenario: Topic is taken from the argument or derived from recent activity
    When /handoff runs
    Then a provided topic is used as the handoff identifier
    And with no topic it derives one from recent commits, the current bead, or ratchet state
    And it falls back to a timestamped slug when no descriptive source exists

  Scenario: Accomplishments are gathered from session evidence, not memory
    When the handoff is assembled
    Then it reviews recent commits, changed files, research/plans produced, and closed issues

  Scenario: The pause point and in-progress work are recorded
    When the handoff identifies where work stopped
    Then it states the last action, the intended next action, and any pending blockers
    And it lists beads still in progress so the next session can reclaim them

  Scenario: The next session is told which files to read first
    When the handoff is written
    Then it lists recently modified core files and the key research/plan artifacts

  Scenario: Output is a structured document plus a continuation prompt
    When /handoff completes
    Then it writes a dated handoff document under the handoff directory
    And it emits a continuation prompt the next session can act on directly


#!/usr/bin/env bash
set -euo pipefail
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0; FAIL=0

check() { if bash -c "$2"; then echo "PASS: $1"; PASS=$((PASS + 1)); else echo "FAIL: $1"; FAIL=$((FAIL + 1)); fi; }

check "SKILL.md exists" "[ -f '$SKILL_DIR/SKILL.md' ]"
check "SKILL.md has YAML frontmatter" "head -1 '$SKILL_DIR/SKILL.md' | grep -q '^---$'"
check "SKILL.md has name: handoff" "grep -q '^name: handoff' '$SKILL_DIR/SKILL.md'"
check "SKILL.md mentions session context" "grep -qi 'session context\|session continuation' '$SKILL_DIR/SKILL.md'"
check "SKILL.md mentions .agents/ artifacts" "grep -q '\.agents/' '$SKILL_DIR/SKILL.md'"

echo ""; echo "Results: $PASS passed, $FAIL failed"
[ $FAIL -eq 0 ] && exit 0 || exit 1


---
name: handoff
description: Write compact session handoffs.
practices:
- adr
- wiki-knowledge-surface
- code-complete
hexagonal_role: supporting
consumes: []
produces:
- .agents/research/*.md
context_rel: []
skill_api_version: 1
context:
  window: inherit
  intent:
    mode: none
  intel_scope: none
metadata:
  tier: session
  dependencies: []
output_contract: .agents/handoffs/YYYY-MM-DD-*.md
---
# Handoff Skill

> **Quick Ref:** Create structured handoff for session continuation. Output: `.agents/handoff/YYYY-MM-DD-<topic>.md` + continuation prompt.

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

Create a handoff document that enables seamless session continuation.

## Execution Steps

Given `/handoff [topic]`:

### Step 1: Create Output Directory

```bash
mkdir -p .agents/handoff
```

### Step 2: Identify Session Context

**If topic provided:** Use it as the handoff identifier.

**If no topic:** Derive from recent activity:
```bash
# Recent commits
git log --oneline -5 --format="%s" | head -1

# Check current issue
bd current 2>/dev/null | head -1

# Check ratchet state
ao ratchet status 2>/dev/null | head -3
```

Use the most descriptive source as the