session-management

# Session Management

Manage coding sessions with git-native workflows, intelligent context preservation, and seamless agent onboarding.

## Core Concept

**Sessions = Branches + Context**

Session management enhances git workflows by:
- Mapping branches to work sessions with objectives
- Creating enhanced commits with decision metadata
- Tracking progress, blockers, and architectural decisions
- Generating comprehensive handoffs between sessions
- Providing instant context loading for AI agents

## Quick Start

### Initialize in Project

```bash
python scripts/init_session.py
```

Creates `.sessions/` directory with:
- `config.yaml` - Session configuration (optional)
- `checkpoints/` - Checkpoint storage
- `state.json` - Current session state

### Core Workflows

**Important**: All slash commands use the `AskUserQuestion` tool to gather inputs interactively. The Python scripts accept CLI arguments, so commands collect user choices via multiple-choice prompts, then execute scripts with those arguments.

#### Session Start (`/session-start`)

**Rapid re-immersion for both human and AI**

```bash
/session-start
```

**What happens:**
1. **Project status report generated** - Health, git status, recent work, open items
2. **Interactive prompts via AskUserQuestion** - User selects what to work on, which branch, and session objectives through multiple-choice questions
3. **Branch selection** - Choose from active branches or create new (hotfix/feature/bugfix)
4. **Context loaded** - Architecture, decisions, patterns from last session
5. **Session ready** - Both human and AI fully contextualized

**Use when:**
- Starting work on a project
- Returning after days away
- Context switching between projects

#### Create Checkpoint (`/checkpoint`)

**Quick save points during work**

```bash
/checkpoint
```

**What happens:**
1. **Automatic capture** - Git diff, metrics, TDD cycles analyzed
2. **Interactive prompts via AskUserQuestion** - User chooses whether to add notes, create