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

Workflow Session Management Principles

Overview

This document provides simplified session state management using marker files for active session tracking.

Multi-Session Architecture

Active Session Marker System

Ultra-Simple Active Tracking: .workflow/.active-[session-name]

The system supports multiple concurrent sessions with a single active session marked by file presence:

.workflow/
├── WFS-oauth-integration/         # Session directory (paused)
├── WFS-user-profile/             # Session directory (paused)
├── WFS-bug-fix-123/              # Session directory (completed)
└── .active-WFS-user-profile      # Marker file (indicates active session)

Marker File Benefits:

• Zero Parsing: File existence check is atomic and instant
• Atomic Operations: File creation/deletion is naturally atomic
• Visual Discovery: ls .workflow/.active-* shows active session immediately
• No Corruption Risk: No JSON parsing, no file format issues
• Simple Switching: Delete old marker + create new marker = session switch

Command Pre-execution Protocol

Universal Session Awareness: All commands automatically detect active session through marker file

FUNCTION execute_command(command, args):
  active_marker = find_file(".workflow/.active-*")
  
  IF active_marker EXISTS:
    session_name = extract_name_from_marker(active_marker)
    session_dir = ".workflow/" + session_name
    context = load_session_context(session_dir + "/workflow-session.json")
    workspace = session_dir
  ELSE:
    context = create_temporary_workspace()
    workspace = temporary_directory
  
  execute_with_context(command, args, context, workspace)
END FUNCTION

Protocol Benefits:

• Instant Discovery: No file parsing, just check file existence
• Context Inheritance: Use active session directory for all operations
• Fallback Mode: Commands work without any active session
• Output Location: Active session determines file creation location
• Task Context: Active session provides current workflow context

Session State Management

Active Session Detection

# Check for active session
active_session=$(ls .workflow/.active-* 2>/dev/null | head -1)
if [ -n "$active_session" ]; then
  session_name=$(basename "$active_session" | sed 's/^\.active-//')
  echo "Active session: $session_name"
else
  echo "No active session"
fi

Session Activation

# Switch to different session
rm .workflow/.active-* 2>/dev/null  # Remove any existing active marker
touch .workflow/.active-WFS-new-feature  # Mark new session as active

Session Discovery

# List all available sessions
ls -d .workflow/WFS-*/ 2>/dev/null | sed 's|.workflow/||;s|/$||'

# Show active session status
if ls .workflow/.active-* >/dev/null 2>&1; then
  active=$(ls .workflow/.active-* | sed 's|.workflow/.active-||')
  echo "✅ Active: $active"
else  
  echo "⏸️ No active session"
fi

Individual Session Tracking

All workflow state for each session managed through workflow-session.json in each session directory:

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"
  }
}

Note: The status field in individual session files is informational only. The actual active status is determined by the presence of .active-[session-name] marker file.

Session Lifecycle Operations

Create New Session

# 1. Create session directory
mkdir .workflow/WFS-new-feature

# 2. Initialize workflow-session.json
echo '{"session_id":"WFS-new-feature","status":"active",...}' > .workflow/WFS-new-feature/workflow-session.json

# 3. Set as active (deactivate others automatically)
rm .workflow/.active-* 2>/dev/null
touch .workflow/.active-WFS-new-feature

Switch Session

# Atomic session switching
rm .workflow/.active-* 2>/dev/null && touch .workflow/.active-WFS-different-feature

Pause Session (Deactivate)

# Remove active marker (session becomes paused)
rm .workflow/.active-WFS-current-feature

Resume Session

# Reactivate paused session
rm .workflow/.active-* 2>/dev/null  # Clear any active session
touch .workflow/.active-WFS-paused-session  # Activate target session

Complete Session

# 1. Update session status
echo '{"session_id":"WFS-feature","status":"completed",...}' > .workflow/WFS-feature/workflow-session.json

# 2. Remove active marker
rm .workflow/.active-WFS-feature

# 3. Optional: Archive session directory
mv .workflow/WFS-feature .workflow/completed/WFS-feature

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"
  }
}

Error Recovery and Validation

Session Consistency Checks

# Validate active session integrity
active_marker=$(ls .workflow/.active-* 2>/dev/null | head -1)
if [ -n "$active_marker" ]; then
  session_name=$(basename "$active_marker" | sed 's/^\.active-//')
  session_dir=".workflow/$session_name"
  
  if [ ! -d "$session_dir" ]; then
    echo "⚠️ Orphaned active marker: $active_marker"
    echo "   Session directory missing: $session_dir"
    echo "   Removing orphaned marker..."
    rm "$active_marker"
  fi
fi

Multi-Active Session Detection

# Detect multiple active markers (error condition)
active_count=$(ls .workflow/.active-* 2>/dev/null | wc -l)
if [ "$active_count" -gt 1 ]; then
  echo "❌ Multiple active sessions detected:"
  ls .workflow/.active-* | sed 's|.workflow/.active-|  - |'
  echo "   Keeping most recent, removing others..."
  
  # Keep newest, remove others
  newest=$(ls -t .workflow/.active-* 2>/dev/null | head -1)
  ls .workflow/.active-* 2>/dev/null | grep -v "$newest" | xargs rm -f
  echo "   ✅ Resolved: $(basename "$newest" | sed 's/^\.active-//')"
fi

Recovery Strategies

• Missing Session Directory: Remove orphaned active marker
• Multiple Active Markers: Keep newest, remove others
• Corrupted Session File: Recreate from template with session name
• No Active Session: Commands work in temporary mode

Performance Benefits

Ultra-Fast Operations

• Session Detection: Single ls command (< 1ms)
• Session Switching: Two file operations (delete + create)
• Status Check: File existence test (instant)
• No Parsing Overhead: Zero JSON/text processing

Scalability

• Hundreds of Sessions: No performance degradation
• Concurrent Access: File system handles locking automatically
• Atomic Operations: No race conditions or corruption risk

Implementation Guidelines

Key Principles

• File Existence = Truth: Marker file presence is the single source of truth
• Atomic State Changes: All session operations are atomic file operations
• Visual Management: Users can see and manage active sessions directly
• Zero Configuration: No registry files to maintain or repair
• Self-Healing: Automatic detection and resolution of inconsistent states

Success Metrics

• Fast session resume (< 100ms)
• Zero parsing overhead
• Visual session management
• Self-healing consistency
• No registry maintenance needed

---

System ensures: Ultra-simple session management using marker files for instant, atomic, and visually manageable session state tracking.