Claude-Code-Workflow/.claude/commands/workflow/session.md

name, description, usage, argument-hint, examples

name	description	usage	argument-hint	examples
workflow-session	Workflow session management with multi-session registry support	/workflow:session <start|pause|resume|list|switch|status> [complexity] ["task description"]	start|pause|resume|list|switch|status [simple|medium|complex] ["task description or session ID"]	/workflow:session start complex "implement OAuth2 authentication" /workflow:session start simple "fix login bug" /workflow:session pause /workflow:session resume /workflow:session list /workflow:session switch WFS-oauth-integration /workflow:session status

Workflow Session Management Commands

Overview

Enhanced session management with multi-session registry support. Provides unified state tracking through workflow-session.json (individual sessions) and session_status.jsonl (lightweight registry).

Core Principles

Session Management: @~/.claude/workflows/session-management-principles.md

Session Registry System

Multi-Session Management

The system maintains a lightweight registry (.workflow/session_status.jsonl) tracking all sessions:

{"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 Rules

• Single Active Session: Only one session can be active at a time
• Automatic Registration: New sessions auto-register on creation
• Session Discovery: Commands query registry to find active session
• Context Inheritance: Active session provides default context for all commands

Commands

Start Workflow Session (初始化)

/workflow:session start <complexity> "task description"

Session Initialization Process:

• Replaces /workflow:init - Initializes new workflow session
• Generates unique session ID (WFS-[topic-slug] format)
• Registers in session registry - Adds entry to .workflow/session_status.jsonl
• Sets as active session - Deactivates other sessions automatically
• Creates comprehensive directory structure
• Determines complexity (auto-detect if not specified)
• Sets initial phase based on complexity

Directory Structure Creation:

.workflow/WFS-[topic-slug]/
├── workflow-session.json          # Session state and metadata  
├── IMPL_PLAN.md                    # Combined planning document (always created)
├── [.brainstorming/]               # Optional brainstorming phase
├── [TODO_LIST.md]                  # Progress tracking (auto-triggered)
├── reports/                        # Generated reports directory
└── .task/                          # Task management directory
    ├── impl-*.json                 # Hierarchical task definitions
    ├── impl-*.*.json               # Subtasks (up to 3 levels deep)
    └── impl-*.*.*.json             # Detailed subtasks

File Generation Standards:

• workflow-session.json: Core session state with comprehensive document tracking
• IMPL_PLAN.md: Initial planning document template (all complexity levels)
• reports/ directory: Created for future report generation by other workflow commands
• .task/ directory: Hierarchical task management system setup
• Automatic backups: Session state backups created during critical operations

Phase Initialization:

• Simple: Ready for direct IMPLEMENT (minimal documentation)
• Medium/Complex: Ready for PLAN phase (document generation enabled)

Session State Setup:

• Creates workflow-session.json with simplified document tracking
• Initializes hierarchical task management system (max 3 levels)
• Creates IMPL_PLAN.md for all complexity levels
• Auto-triggers TODO_LIST.md for Medium/Complex workflows
• NOTE: Does NOT execute workflow - only sets up infrastructure

Next Steps After Initialization:

• Use /workflow:plan to populate IMPL_PLAN.md (all workflows)
• Use /workflow:implement for task execution (all workflows)
• Use /workflow:review for validation phase

File Generation and State Management

Initial File Creation

When starting a new session, the following files are automatically generated:

workflow-session.json Structure

{
  "session_id": "WFS-[topic-slug]",
  "created_at": "2025-09-07T14:00:00Z",
  "type": "simple|medium|complex",
  "description": "[user task description]",
  "current_phase": "INIT",
  "status": "active",
  "phases": {
    "INIT": {
      "status": "completed",
      "completed_at": "2025-09-07T14:00:00Z",
      "files_created": ["IMPL_PLAN.md", "workflow-session.json"],
      "directories_created": [".task", "reports"]
    },
    "BRAINSTORM": {
      "status": "pending",
      "enabled": false
    },
    "PLAN": {
      "status": "pending", 
      "enabled": true
    },
    "IMPLEMENT": {
      "status": "pending",
      "enabled": true
    },
    "REVIEW": {
      "status": "pending",
      "enabled": true
    }
  },
  "documents": {
    "planning": {
      "IMPL_PLAN.md": {
        "status": "template_created",
        "path": ".workflow/WFS-[topic-slug]/IMPL_PLAN.md",
        "created_at": "2025-09-07T14:00:00Z",
        "type": "planning_document"
      }
    }
  },
  "task_system": {
    "enabled": true,
    "max_depth": 3,
    "task_count": 0,
    "directory": ".task"
  },
  "registry": {
    "registered_in": ".workflow/session_status.jsonl",
    "active_session": true
  }
}

Initial IMPL_PLAN.md Template

# Implementation Plan
*Session: WFS-[topic-slug] | Created: 2025-09-07 14:00:00*

## Project Overview
- **Description**: [user task description]
- **Complexity**: [simple|medium|complex]
- **Estimated Effort**: [TBD]
- **Target Completion**: [TBD]

## Requirements Analysis
*To be populated by planning phase*

## Task Breakdown  
*To be populated by planning phase*

## Implementation Strategy
*To be populated by planning phase*

## Success Criteria
*To be populated by planning phase*

---
*Template created by /workflow:session start*
*Use /workflow:plan to populate this document*

Backup and Recovery System

Automatic Backup Creation

• Trigger Events: Session pause, critical state changes, error recovery
• Backup Location: .workflow/WFS-[topic-slug]/.backups/
• Retention: Last 5 backups per session
• Format: Timestamped JSON and markdown backups

Backup Structure

.workflow/WFS-[topic-slug]/.backups/
├── session-2025-09-07-14-00.json    # Session state backup
├── session-2025-09-07-15-30.json
├── session-2025-09-07-16-45.json
├── IMPL_PLAN-2025-09-07-14-00.md    # Document backups  
└── TODO_LIST-2025-09-07-15-30.md

Recovery Operations

• Auto-recovery: On session corruption or inconsistency
• Manual recovery: Via /workflow:session recover --from-backup
• Integrity checks: Automatic validation on session load

Session Registry Management

Session Status Registry (.workflow/session_status.jsonl)

{"id":"WFS-oauth-integration","status":"active","description":"OAuth2 authentication implementation","created":"2025-09-07T14:00:00Z","directory":".workflow/WFS-oauth-integration","complexity":"complex"}

Registry Operations

• Registration: Automatic on session creation
• Status Updates: Real-time status synchronization
• Cleanup: Automatic removal of completed sessions (optional)
• Discovery: Used by all workflow commands for session context

Pause Workflow

/workflow:session pause

• Immediately saves complete session state
• Preserves context across all phases (conceptual/action/implementation)
• Sets status to "interrupted" with timestamp
• Shows resume instructions
• Maintains TodoWrite synchronization

Resume Workflow

/workflow:session resume

• Detects current phase from workflow-session.json
• Loads appropriate agent context and state
• Continues from exact interruption point
• Maintains full context continuity
• Restores TodoWrite state

List Sessions

/workflow:session list

• Displays all sessions from registry with status
• Shows session ID, status, description, and creation date
• Highlights currently active session
• Provides quick overview of all workflow sessions

Switch Active Session

/workflow:session switch <session-id>

• Switches the active session to the specified session ID
• Automatically pauses the currently active session
• Updates registry to set new session as active
• Validates that target session exists and is valid
• Commands executed after switch will use new active session context

Session Status

/workflow:session status

• Shows current active session details
• Displays session phase, progress, and document status
• Lists available sessions from registry
• Provides quick session health check

Session State

Session state is tracked through two complementary systems:

Registry State (.workflow/session_status.jsonl)

Lightweight multi-session tracking:

{"id":"WFS-user-auth-system","status":"active","description":"OAuth2 authentication","created":"2025-09-07T10:30:00Z","directory":".workflow/WFS-user-auth-system"}

Individual Session State (workflow-session.json)

Detailed session state with document management:

{
  "session_id": "WFS-user-auth-system", 
  "project": "OAuth2 authentication",
  "type": "complex",
  "status": "active|paused|completed",
  "current_phase": "PLAN|IMPLEMENT|REVIEW",
  "created": "2025-09-05T10:30:00Z",
  "directory": ".workflow/WFS-user-auth-system",
  "documents": {
    "IMPL_PLAN.md": {
      "status": "generated", 
      "path": ".workflow/WFS-user-auth-system/IMPL_PLAN.md",
      "last_updated": "2025-09-05T10:30:00Z"
    },
    "TODO_LIST.md": {
      "status": "auto_triggered", 
      "path": ".workflow/WFS-user-auth-system/TODO_LIST.md",
      "last_updated": "2025-09-05T11:20:00Z"
    }
  },
  "task_system": {
    "enabled": true,
    "directory": ".workflow/WFS-user-auth-system/.task",
    "next_main_task_id": 1,
    "max_depth": 3,
    "task_count": {
      "total": 0,
      "main_tasks": 0,
      "subtasks": 0
    }
  }
}

To check status, use: /workflow:status To mark complete: Simply finish all tasks and review phase

Session State Management

Session Responsibilities

• Lifecycle Management: Start, pause, resume sessions
• State Persistence: Save and restore workflow state
• Phase Tracking: Monitor current phase (PLAN/IMPLEMENT/REVIEW)
• Context Preservation: Maintain context across interruptions

What Session Does NOT Do

• No Execution: Does not run agents or execute tasks
• No Planning: Does not generate planning documents
• No Implementation: Does not run code development
• Execution Delegation: All execution via appropriate phase commands:
  • /workflow:plan - Planning execution
  • /workflow:implement - Implementation execution
  • /workflow:review - Review execution

Automatic Checkpoints

@~/.claude/workflows/session-management-principles.md

Checkpoints created by phase commands:

• /workflow:plan creates checkpoints during planning
• /workflow:implement creates checkpoints after agents
• /workflow:review creates final validation checkpoint
• Session commands only manage checkpoint restoration

Cross-Phase Context Preservation

• All phase outputs preserved in session
• Context automatically transferred between phases
• PRD documents bridge conceptual → action planning
• Implementation plans bridge action → implementation
• Full audit trail maintained for decisions

State Validation

• Verify required artifacts exist for resumption
• Check file system consistency with session state
• Validate TodoWrite synchronization
• Ensure agent context completeness