Claude-Code-Workflow/.claude/workflows/session-management-principles.md

Workflow Session Management Principles

Overview

This document provides simplified session state management with minimal overhead, phase-level tracking, and streamlined coordination.

Multi-Session Architecture

Session Registry System

Lightweight Global Registry: .workflow/session_status.jsonl

The system supports multiple concurrent sessions with a single active session:

{"id":"WFS-oauth-integration","status":"paused","description":"OAuth2 authentication implementation","created":"2025-09-07T10:00:00Z","directory":".workflow/WFS-oauth-integration"}
{"id":"WFS-user-profile","status":"active","description":"User profile feature","created":"2025-09-07T11:00:00Z","directory":".workflow/WFS-user-profile"}
{"id":"WFS-bug-fix-123","status":"completed","description":"Fix login timeout issue","created":"2025-09-06T14:00:00Z","directory":".workflow/WFS-bug-fix-123"}

Registry Management:

• Single Active Rule: Only one session can have status="active"
• Automatic Registration: Sessions auto-register on creation
• Session Discovery: Commands query registry for active session context
• Context Inheritance: Active session provides default workspace and documents

Command Pre-execution Protocol

Universal Session Awareness: All commands automatically check for active session context before execution

FUNCTION execute_command(command, args):
  active_session = get_active_session_from_registry()
  
  IF active_session EXISTS:
    context = load_session_context(active_session.directory)
    workspace = active_session.directory
    inherit_task_context(context)
  ELSE:
    context = create_temporary_workspace()
    workspace = temporary_directory
  
  execute_with_context(command, args, context, workspace)
END FUNCTION

Protocol Benefits:

• Active Session Discovery: Query .workflow/session_status.jsonl for active session
• Context Inheritance: Use active session directory and documents for command execution
• Fallback Mode: Commands can operate without active session (creates temporary workspace)
• Output Location: Active session determines where files are created/modified
• Task Context: Active session provides current task purpose and requirements

Individual Session Tracking

All workflow state for each session managed through workflow-session.json with comprehensive structure:

Session State Structure

{
  "session_id": "WFS-[topic-slug]",
  "project": "feature description",
  "type": "simple|medium|complex",
  "current_phase": "PLAN|IMPLEMENT|REVIEW",
  "status": "active|paused|completed",
  
  "progress": {
    "completed_phases": ["PLAN"],
    "current_tasks": ["impl-1", "impl-2"],
    "last_checkpoint": "2025-09-07T10:00:00Z"
  },
  
  "meta": {
    "created": "2025-09-05T10:00:00Z",
    "updated": "2025-09-07T10:00:00Z"
  }
}

Simplified Phase Management

Phase-Level Tracking Only

• Planning Phase: Track completion status only
• Implementation Phase: Track active tasks, not detailed progress
• Review Phase: Track completion status only

Minimal Checkpoint Strategy

• Phase Transitions: Save state when moving between phases
• User Request: Manual checkpoint on explicit user action
• Session End: Final state save before closing

Checkpoint Data (Minimal)

{
  "save_triggers": ["phase_complete", "user_request", "session_end"],
  "save_data": ["phase_status", "active_tasks", "session_meta"],
  "resume_logic": "resume_from_last_phase_checkpoint"
}

Simplified Context Preservation

Essential Context Only

• Planning documents available to implementation phase
• Implementation results available to review phase
• Minimal handoff data between phases

Simple State Transitions

{
  "phase_completed": "PLAN",
  "next_phase": "IMPLEMENT",
  "completed_at": "2025-09-07T10:00:00Z",
  "artifacts": {
    "plan_document": "IMPL_PLAN.md"
  }
}

Simplified Recovery

Basic Recovery Logic

def resume_workflow():
    session = load_session()
    
    if session.current_phase == "PLAN":
        check_plan_document_exists()
    elif session.current_phase == "IMPLEMENT":
        load_active_tasks()
    elif session.current_phase == "REVIEW":
        check_implementation_complete()

Minimal State Validation

• Check current phase is valid
• Verify session directory exists
• Confirm basic file structure

Simple Recovery Strategy

• Phase Restart: If unclear state, restart current phase
• User Confirmation: Ask user to confirm resume point
• Minimal Recovery: Restore basic session info only

Simplified Agent Integration

Minimal Agent Requirements

• Report task completion status
• Update task JSON files
• No complex checkpoint management needed

Phase Integration

• Planning Agents: Create planning documents
• Implementation Agents: Update task status to completed
• Review Agents: Mark review as complete

Error Handling

Common Scenarios

1. Session File Missing: Create new session file with defaults
2. Invalid Phase State: Reset to last known valid phase
3. Multi-Session Conflicts: Auto-resolve by latest timestamp

Session Lifecycle

Simple Lifecycle

1. Create: Generate session ID and directory
2. Activate: Set as current active session
3. Execute: Track phase completion only
4. Complete: Mark as finished

State Transitions

INACTIVE → ACTIVE → COMPLETED
    ↑         ↓         ↓
  CREATE    WORK    FINISH

Implementation Guidelines

Key Principles

• Minimal State: Only track essential information
• Phase-Level Updates: Avoid frequent micro-updates
• Simple Recovery: Basic session restoration only
• User Control: Manual checkpoint requests

Success Metrics

• Fast session resume (< 1 second)
• Minimal file I/O operations
• Clear session state understanding
• No complex synchronization needed