Session Boundary Skill

Detect and handle session boundaries for multi-context autopilot workflows.

Purpose

Manage smooth transitions across context windows by:

•Detecting when context is about to be compacted
•Generating comprehensive handoff documents
•Restoring state after context restoration
•Tracking session metrics for workflow optimization

When to Invoke

•Automatically via SessionStart hook (startup, resume, compact triggers)
•Automatically via PreCompact hook (before context compaction)
•Automatically via Stop hook (session end)
•Manually via /context next or /context status
•During /feature continue or /epic continue

Core Concepts

Write-Through State Pattern

Critical: Never keep state only in conversation memory. Always persist immediately.

yaml

# Good: Write to state.yaml immediately
session:
  id: "session-20251204-143000"
  started_at: "2025-12-04T14:30:00Z"
  phase_at_start: "implement"
  decisions_made: ["Redis for token blacklist"]

# Bad: Keeping state only in conversation
# "I decided to use Redis..." (lost on compaction)

Session Lifecycle

code

┌──────────────┐    ┌──────────────┐    ┌──────────────┐
│ SessionStart │───▶│   Working    │───▶│     Stop     │
│   (restore)  │    │   (track)    │    │ (checkpoint) │
└──────────────┘    └──────────────┘    └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │  PreCompact  │
                    │  (handoff)   │
                    └──────────────┘
                           │
                           ▼
                    ┌──────────────┐
                    │ SessionStart │
                    │  (restore)   │
                    └──────────────┘

Hook Integration

Hook	Trigger	Purpose
SessionStart	startup, resume, compact	Restore workflow context
PreCompact	auto, manual	Generate handoff before context loss
Stop	session end	Checkpoint current state

Session Manager Commands

bash

# Start new session (with optional autopilot)
bash .spec-flow/scripts/bash/session-manager.sh start --autopilot

# View current status
bash .spec-flow/scripts/bash/session-manager.sh status

# Record important decision
bash .spec-flow/scripts/bash/session-manager.sh decision "Using Redis for caching"

# Generate handoff manually
bash .spec-flow/scripts/bash/session-manager.sh handoff

# End session with summary
bash .spec-flow/scripts/bash/session-manager.sh end --summary "Completed auth implementation"

# Control autopilot mode
bash .spec-flow/scripts/bash/session-manager.sh autopilot on|off|status

# View session history
bash .spec-flow/scripts/bash/session-manager.sh history

State Schema (session block)

Added to state.yaml (schema v2.2.0):

yaml

session:
  id: "session-20251204-143000"
  started_at: "2025-12-04T14:30:00Z"
  ended_at: null
  last_activity: "2025-12-04T16:45:00Z"
  phase_at_start: "implement"
  tasks_at_start: 12
  tasks_completed_this_session: 4
  decisions_made:
    - "Redis for token blacklist"
    - "JWT expiry 15min"
  handoffs:
    - id: "handoff-20251204-163000"
      at: "2025-12-04T16:30:00Z"
  last_handoff_id: "handoff-20251204-163000"
  last_handoff_at: "2025-12-04T16:30:00Z"
  autopilot_enabled: false
  duration_seconds: null
  summary: null

Handoff Document Structure

Located at: {workflow_dir}/sessions/handoff-{timestamp}.md

markdown

# Session Handoff: {slug}

> Generated: {timestamp}
> Trigger: {context compaction | manual | session end}
> Phase: {current_phase}
> Status: {current_status}

## Quick Resume

```bash
/{workflow_type} continue

Current State

Metric	Value
Workflow Type	feature/epic
Slug	{slug}
Current Phase	{phase}
Phase Status	{status}
Tasks Progress	{completed} / {total}

Next Task

{next_uncompleted_task}

Recent Decisions

{list_of_recent_decisions}

Key Artifacts

•State: state.yaml
•Tasks: tasks.md
•Notes: NOTES.md ...

Context for Next Session

•Read state.yaml for complete workflow state
•Check tasks.md for task completion status
•Review NOTES.md for recent decisions and blockers
•Use /context next for detailed next steps

code


## Integration Points

### /feature continue and /epic continue

Both commands now:
1. Display session status before resuming
2. Check for and display handoff documents
3. Start a new session for tracking

### /context Command

- `/context status` - Shows session and workflow status
- `/context next` - Generates handoff document
- `/context add` - Records item to backlog

### NOTES.md Session Markers

Session boundaries are recorded in NOTES.md:

```markdown
---

## Session Boundary: 2025-12-04T16:30:00Z

*Context compaction occurred. Handoff saved to: sessions/handoff-20251204-163000.md*

Autopilot Mode

When autopilot_enabled: true:

•Stop hook can return {"decision": "block"} to continue execution
•Workflow continues through context compaction automatically
•Session boundaries are transparent to the workflow
•Only blocks on actual failures (CI, tests, deployment)

Enable via:

bash

bash .spec-flow/scripts/bash/session-manager.sh autopilot on

Or during session start:

bash

bash .spec-flow/scripts/bash/session-manager.sh start --autopilot

Metrics Tracked

•Session duration
•Tasks completed per session
•Decisions made per session
•Handoffs generated
•Phase transitions within session

Used for:

•Workflow optimization
•Velocity analysis
•Context usage patterns