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

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

/session-start

What happens:

Project status report generated - Health, git status, recent work, open items
Interactive prompts via AskUserQuestion - User selects what to work on, which branch, and session objectives through multiple-choice questions
Branch selection - Choose from active branches or create new (hotfix/feature/bugfix)
Context loaded - Architecture, decisions, patterns from last session
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

/checkpoint

What happens:

Automatic capture - Git diff, metrics, TDD cycles analyzed
Interactive prompts via AskUserQuestion - User chooses whether to add notes, create git commit, or both
Checkpoint saved - Comprehensive snapshot generated
Git commit - Optionally create commit with auto-generated or custom message

Use when:

At logical milestones
Completing sub-tasks
Before switching contexts

Examples:

# Simple checkpoint
python scripts/session.py checkpoint --label "oauth-complete"

# Checkpoint with notes and git commit
python scripts/session.py checkpoint --label "feature-complete" --notes "OAuth flow tested" --commit

# With custom commit message
python scripts/session.py checkpoint --label "bugfix" --commit --message "fix: resolve auth token expiry"

End Session (`/session-end`)

Comprehensive knowledge capture and handoff

/session-end

What happens:

Final checkpoint created - Captures current state
Interactive prompts via AskUserQuestion - User provides session accomplishments, decisions made, and context for next session
Handoff generated - Full session summary with metrics and next steps
Git push - User chooses whether to push commits to remote
State saved - Ready for next session

Use when:

Finishing work session
End of day
Before extended break

Session Lifecycle

START → Load full project context with status report WORK → Track changes automatically in background CHECKPOINT → Save progress with automatic git analysis END → Generate handoff with comprehensive session summary

Key Features

1. Objectives Management

Track what you're trying to accomplish:

# Add objective
python scripts/session.py objectives add "Implement OAuth2 integration"

# Mark complete
python scripts/session.py objectives complete obj-1

# List all
python scripts/session.py objectives list

2. Blocker Tracking

Record impediments:

# Add blocker
python scripts/session.py blockers add "Waiting on API keys"

# Resolve
python scripts/session.py blockers resolve blk-1

3. Decision Logging

Capture architectural decisions with context:

# Record decision
python scripts/session.py decisions add "Using repository pattern for data access" \
  --rationale "Separates domain logic from persistence" \
  --alternatives "Active Record: Too coupled to database"

4. Context Queries

Check current state:

# Full status
python scripts/session.py status

# Just objectives
python scripts/session.py status --objectives

# History
python scripts/session.py history --count 10

Agent Onboarding

When AI agents (like Claude Code) start, session management provides instant context:

# Automatically loads on agent start:
# - Project architecture pattern
# - Code conventions
# - Recent decisions
# - Current objectives
# - Active blockers
# - Git history analysis
# - File changes summary

Agent receives structured brief including:

What we're building (objectives)
How to build it (architecture, patterns, conventions)
What's done (progress)
What's next (next actions)
What to watch for (blockers, TODOs)

Storage Structure

project/
├── .session/                # Git-tracked, shared across team
│   ├── config.yaml         # Configuration
│   ├── architecture.md     # Architecture documentation
│   ├── conventions.md      # Code conventions
│   └── decision-log.md     # All decisions (auto-generated)
│
└── .git/
    └── sessions/           # Local, developer-specific
        └── <branch>/
            ├── objectives.md
            ├── blockers.md
            └── context.json

Design principle: Shared context (architecture, conventions) is git-tracked. Personal workflow data (objectives, notes) stays local.

Configuration

Edit .session/config.yaml:

session:
  auto_track: true          # Track file changes automatically
  handoff_on_end: true      # Generate handoff when ending
  
context:
  architecture: hexagonal   # Your architecture pattern
  patterns:                 # Patterns to enforce
    - repository-pattern
    - dependency-injection
  
tracking:
  watch_patterns:           # Files to monitor
    - "src/**/*.py"
    - "tests/**/*.py"

Workflows

Daily Development

# Morning: Resume work
python scripts/session.py resume

# During work: Checkpoint at milestones
python scripts/session.py checkpoint --label "api-complete"

# Evening: End with handoff
python scripts/session.py end

Context Switching

# Urgent bug comes in
python scripts/session.py switch hotfix/critical-bug

# Fix bug
python scripts/session.py checkpoint --message "Fix security issue"
python scripts/session.py end --merge-to main

# Back to feature
python scripts/session.py resume feature/main-work

Team Handoffs

# Generate comprehensive handoff
python scripts/session.py end --handoff --summary

# Next developer loads context
python scripts/session.py resume <branch>

Enhanced Commits

Session checkpoints create git commits with rich metadata:

feat(auth): Implement OAuth2 provider

Completed Google OAuth flow with PKCE support.

Session-Objectives:
- [x] OAuth provider interface
- [▶] Google OAuth (this commit)
- [ ] GitHub OAuth (next)

Decisions:
- Using PKCE flow for enhanced security
  Rationale: Protection against code interception
  
Impact:
- Added: src/auth/oauth_provider.py
- Tests: +12 unit tests
- Coverage: 79% → 84%

Session-Time: 2h 15m

Advanced Features

Session Analysis

# Analyze session health
python scripts/session.py analyze

# Calculate velocity
python scripts/session.py analyze --velocity

# Pattern detection
python scripts/session.py analyze --patterns

Session History

# Recent sessions with metrics
python scripts/session.py history --count 5 --metrics

# Compare sessions
python scripts/session.py compare <session-id>

Reports

# Weekly summary
python scripts/session.py report --weekly

# Project summary
python scripts/session.py report --project --format markdown

Bundled Resources

Scripts

init_session.py - Initialize session management in project
session.py - Main CLI for all session operations
analyze_git.py - Git history analysis utilities

References

commands.md - Complete command reference
handoff-template.md - Template for session handoffs
config-reference.md - All configuration options

Assets

config-template.yaml - Default configuration
architecture-template.md - Architecture documentation template
conventions-template.md - Conventions template

Best Practices

For Solo Development:

Start every session with objectives
Checkpoint at logical milestones
Record decisions when making them
End sessions with handoffs (helps future you)

For Teams:

Commit .session/ directory (shared context)
Keep personal workflow local
Link blockers to issue tracker
Generate handoffs for transitions

For AI-Assisted Development:

Session management provides instant agent context
No need to re-explain project structure
Architectural patterns automatically enforced
Decisions preserved across sessions

Troubleshooting

Session not loading?

python scripts/session.py status --verbose
python scripts/session.py start --resume

Need to reinitialize?

python scripts/init_session.py --force

View current configuration:

cat .session/config.yaml

CCMP Plugin Integration

Session management automatically integrates with other CCMP plugins:

With claude-context-manager 📚

Auto-loads relevant context on session start:

python scripts/session.py start feature/auth
# → Automatically loads src/auth/claude.md
# → Shows context health warnings
# → Includes patterns and gotchas in brief

Checkpoints trigger context health checks:

python scripts/session.py checkpoint --label "api-complete"
# → Detects src/api/ changed
# → Warns if context is stale
# → Offers: "Update context? [y/N]"

Handoffs include context health:

python scripts/session.py end --handoff
# → Includes context health score
# → Lists files needing updates
# → Recommends maintenance for next session

With tdd-workflow 🧪

TDD mode automatically enhances sessions:

python scripts/session.py start feature/auth --tdd
# → TDD workflow detects and activates
# → Automatic RED-GREEN-REFACTOR checkpoints
# → TDD metrics in session status
# → Test coverage tracking

Session analysis detects TDD:

python scripts/session.py analyze
# → Shows TDD cycles completed
# → Detects commits without tests
# → Reports discipline violations

Integration API

Uses .ccmp/state.json for plugin coordination. See lib/ccmp_integration.py for details.

Developers: Import the integration library:

from lib.ccmp_integration import CCMPIntegration

integration = CCMPIntegration()
if integration.is_active("session-management"):
    session = integration.get_state("session-management")

Integration Notes

Session management is designed to work with:

Git (required) - Source of truth for history
Issue Trackers (optional) - Link blockers to tickets
CI/CD (optional) - Include build status in briefings
Coverage Tools (optional) - Track quality metrics

For integration guides, see references/integrations.md.

session-management

Session Management

Core Concept

Quick Start

Initialize in Project

Core Workflows

Session Start (`/session-start`)

Create Checkpoint (`/checkpoint`)

End Session (`/session-end`)

Session Lifecycle

Key Features

1. Objectives Management

2. Blocker Tracking

3. Decision Logging

4. Context Queries

Agent Onboarding

Storage Structure

Configuration

Workflows

Daily Development

Context Switching

Team Handoffs

Enhanced Commits

Advanced Features

Session Analysis

Session History

Reports

Bundled Resources

Scripts

References

Assets

Best Practices

Troubleshooting

CCMP Plugin Integration

With claude-context-manager 📚

With tdd-workflow 🧪

Integration API

Integration Notes

See Also

Similar Skills

session-management

Session Management

Core Concept

Quick Start

Initialize in Project

Core Workflows

Session Start (/session-start)

Create Checkpoint (/checkpoint)

End Session (/session-end)

Session Lifecycle

Key Features

1. Objectives Management

2. Blocker Tracking

3. Decision Logging

4. Context Queries

Agent Onboarding

Storage Structure

Configuration

Workflows

Daily Development

Context Switching

Team Handoffs

Enhanced Commits

Advanced Features

Session Analysis

Session History

Reports

Bundled Resources

Scripts

References

Assets

Best Practices

Troubleshooting

CCMP Plugin Integration

With claude-context-manager 📚

With tdd-workflow 🧪

Integration API

Integration Notes

See Also

Similar Skills

Session Start (`/session-start`)

Create Checkpoint (`/checkpoint`)

End Session (`/session-end`)