diff --git a/.claude/commands/gemini-chat.md b/.claude/commands/gemini-chat.md index 0d7c476b..00231801 100644 --- a/.claude/commands/gemini-chat.md +++ b/.claude/commands/gemini-chat.md @@ -131,7 +131,7 @@ END FUNCTION - **Trigger**: Activated by the `--save-session` flag. - **Action**: Saves the complete interaction, including the template used, context, and Gemini's output. -- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session. If the file doesn't exist, create it. +- **Session Check**: Check for `.workflow/.active-*` marker file to identify current active session. No file creation needed. - **Location Strategy**: - **IF active session exists**: Save to existing `.workflow/WFS-[topic-slug]/.chat/` directory - **IF no active session**: Create new session directory following WFS naming convention @@ -146,12 +146,11 @@ END FUNCTION **Session Detection Workflow:** ```pseudo FUNCTION determine_save_location(): - // STEP 1: Ensure session status file exists - IF NOT file_exists(".workflow/session_status.jsonl"): - create_empty_session_registry(".workflow/session_status.jsonl") + // STEP 1: Check for active session marker + active_marker = find_file(".workflow/.active-*") - // STEP 2: Check for existing active session - active_sessions = query_session_registry(".workflow/session_status.jsonl") + // STEP 2: Extract session name if marker exists + active_session_name = extract_session_name(active_marker) IF active_sessions.count > 0: // Use existing active session directory diff --git a/.claude/commands/gemini-execute.md b/.claude/commands/gemini-execute.md index db91e33a..37b8921b 100644 --- a/.claude/commands/gemini-execute.md +++ b/.claude/commands/gemini-execute.md @@ -192,7 +192,7 @@ This template is automatically filled and generated after execution. - **Trigger**: Activated by the `--save-session` flag. - **Action**: Saves the complete execution session, including inferred context, Gemini analysis, and implementation results. -- **Session Check**: Query `.workflow/session_status.jsonl` to identify current active session. If the file doesn't exist, create it. +- **Session Check**: Check for `.workflow/.active-*` marker file to identify current active session. No file creation needed. - **Location Strategy**: - **IF active session exists**: Save to existing `.workflow/WFS-[topic-slug]/.chat/` directory - **IF no active session**: Create new session directory following WFS naming convention diff --git a/.claude/commands/gemini-mode.md b/.claude/commands/gemini-mode.md index bda57b13..07bed839 100644 --- a/.claude/commands/gemini-mode.md +++ b/.claude/commands/gemini-mode.md @@ -128,7 +128,7 @@ END FUNCTION ⚠️ **CRITICAL**: Before analysis, MUST check for existing active session to ensure proper workflow context and documentation storage. **Session Check Process:** -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it. +1. **Check Active Session**: Check for `.workflow/.active-*` marker file to identify active session. No file creation needed. 2. **Context Integration**: Use existing active session for proper analysis context 3. **Documentation Strategy**: Store analysis results in appropriate session directory structure diff --git a/.claude/commands/task/breakdown.md b/.claude/commands/task/breakdown.md index 77d9580a..804543e8 100644 --- a/.claude/commands/task/breakdown.md +++ b/.claude/commands/task/breakdown.md @@ -23,7 +23,7 @@ Intelligently breaks down complex tasks into manageable subtasks with automatic ⚠️ **CRITICAL**: Before breakdown, MUST check for existing active session to avoid creating duplicate sessions. ### Session Check Process -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it. +1. **Check Active Session**: Check for `.workflow/.active-*` marker file to identify active session containing the parent task. 2. **Session Validation**: Use existing active session containing the parent task 3. **Context Integration**: Load existing session state and task hierarchy diff --git a/.claude/commands/workflow/action-plan.md b/.claude/commands/workflow/action-plan.md index b01fec3a..d089ce45 100644 --- a/.claude/commands/workflow/action-plan.md +++ b/.claude/commands/workflow/action-plan.md @@ -179,7 +179,7 @@ function detect_input_type(args): ### Session Check Process ⚠️ **CRITICAL**: Check for existing active session before planning -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` +1. **Check Active Session**: Check for `.workflow/.active-*` marker file 2. **Session Selection**: Use existing active session or create new 3. **Context Integration**: Load session state and existing context diff --git a/.claude/commands/workflow/brainstorm.md b/.claude/commands/workflow/brainstorm.md index 41c01a12..2671d6d3 100644 --- a/.claude/commands/workflow/brainstorm.md +++ b/.claude/commands/workflow/brainstorm.md @@ -109,7 +109,7 @@ END FUNCTION ⚠️ **CRITICAL**: Before brainstorming, MUST check for existing active session to avoid creating duplicate sessions. **Session Check Process:** -1. **Query Session Registry**: Check `.workflow/session_status.jsonl` for active sessions. If the file doesn't exist, create it. +1. **Check Active Session**: Check for `.workflow/.active-*` marker file to identify active session. No file creation needed. 2. **Session Selection**: Use existing active session or create new one only if none exists 3. **Context Integration**: Load existing session state and continue brainstorming phase diff --git a/.claude/commands/workflow/session.md b/.claude/commands/workflow/session.md index 2879a355..68737fb5 100644 --- a/.claude/commands/workflow/session.md +++ b/.claude/commands/workflow/session.md @@ -16,7 +16,7 @@ examples: # 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). +Enhanced session management with marker file-based active session tracking. Provides unified state tracking through `workflow-session.json` (individual sessions) and `.active-[session-name]` marker files (active status). ## Core Principles @@ -25,11 +25,13 @@ Enhanced session management with multi-session registry support. Provides unifie ## Session Registry System ### Multi-Session Management -The system maintains a lightweight registry (`.workflow/session_status.jsonl`) tracking all sessions: -```jsonl -{"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"} +The system uses marker files to track active sessions: +```bash +.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) ``` ### Registry Rules @@ -47,7 +49,7 @@ The system maintains a lightweight registry (`.workflow/session_status.jsonl`) t **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 active marker** - Creates `.workflow/.active-[session-name]` marker file - **Sets as active session** - Deactivates other sessions automatically - Creates comprehensive directory structure - Determines complexity (auto-detect if not specified) @@ -145,7 +147,7 @@ When starting a new session, the following files are automatically generated: "directory": ".task" }, "registry": { - "registered_in": ".workflow/session_status.jsonl", + "active_marker": ".workflow/.active-[session-name]", "active_session": true } } @@ -186,9 +188,11 @@ When starting a new session, the following files are automatically generated: ### Session Registry Management -#### Session Status Registry (.workflow/session_status.jsonl) -```jsonl -{"id":"WFS-oauth-integration","status":"active","description":"OAuth2 authentication implementation","created":"2025-09-07T14:00:00Z","directory":".workflow/WFS-oauth-integration","complexity":"complex"} +#### Active Session Marker (.workflow/.active-[session-name]) +```bash +# Active session is indicated by presence of marker file +ls .workflow/.active-* 2>/dev/null +# Output: .workflow/.active-WFS-oauth-integration ``` #### Registry Operations @@ -248,10 +252,16 @@ When starting a new session, the following files are automatically generated: ### Session State Session state is tracked through two complementary systems: -#### Registry State (`.workflow/session_status.jsonl`) -Lightweight multi-session tracking: -```jsonl -{"id":"WFS-user-auth-system","status":"active","description":"OAuth2 authentication","created":"2025-09-07T10:30:00Z","directory":".workflow/WFS-user-auth-system"} +#### Active Session Marker (`.workflow/.active-[session-name]`) +Lightweight active session tracking: +```bash +# Check for active session +if ls .workflow/.active-* >/dev/null 2>&1; then + active_session=$(ls .workflow/.active-* | sed 's|.workflow/.active-||') + echo "Active session: $active_session" +else + echo "No active session" +fi ``` #### Individual Session State (`workflow-session.json`) diff --git a/.claude/workflows/file-structure-standards.md b/.claude/workflows/file-structure-standards.md index 73eab7fc..267acd83 100644 --- a/.claude/workflows/file-structure-standards.md +++ b/.claude/workflows/file-structure-standards.md @@ -105,7 +105,7 @@ impl-2 # Another main task ### Directory Permissions and Access - All workflow directories are project-local -- Session registry at `.workflow/session_status.jsonl` (global) +- Active session marked by `.workflow/.active-[session-name]` marker file (global) - Individual sessions in `.workflow/WFS-[topic-slug]/` (session-specific) ## Document Generation Triggers diff --git a/.claude/workflows/session-management-principles.md b/.claude/workflows/session-management-principles.md index fb735d26..4ae2c6e5 100644 --- a/.claude/workflows/session-management-principles.md +++ b/.claude/workflows/session-management-principles.md @@ -2,37 +2,41 @@ ## Overview -This document provides simplified session state management with minimal overhead, phase-level tracking, and streamlined coordination. +This document provides simplified session state management using marker files for active session tracking. ## Multi-Session Architecture -### Session Registry System -**Lightweight Global Registry**: `.workflow/session_status.jsonl` +### Active Session Marker System +**Ultra-Simple Active Tracking**: `.workflow/.active-[session-name]` -The system supports multiple concurrent sessions with a single active session: -```jsonl -{"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"} +The system supports multiple concurrent sessions with a single active session marked by file presence: +```bash +.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) ``` -**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 +**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 check for active session context before execution +**Universal Session Awareness**: All commands automatically detect active session through marker file ```pseudo FUNCTION execute_command(command, args): - active_session = get_active_session_from_registry() + active_marker = find_file(".workflow/.active-*") - IF active_session EXISTS: - context = load_session_context(active_session.directory) - workspace = active_session.directory - inherit_task_context(context) + 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 @@ -42,22 +46,57 @@ 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 +- **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 +```bash +# 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 +```bash +# 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 +```bash +# 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` with comprehensive structure: +All workflow state for each session managed through `workflow-session.json` in each session directory: ### Session State Structure ```json { "session_id": "WFS-[topic-slug]", "project": "feature description", - "type": "simple|medium|complex", + "type": "simple|medium|complex", "current_phase": "PLAN|IMPLEMENT|REVIEW", "status": "active|paused|completed", @@ -74,6 +113,54 @@ All workflow state for each session managed through `workflow-session.json` with } ``` +**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 +```bash +# 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 +```bash +# Atomic session switching +rm .workflow/.active-* 2>/dev/null && touch .workflow/.active-WFS-different-feature +``` + +### Pause Session (Deactivate) +```bash +# Remove active marker (session becomes paused) +rm .workflow/.active-WFS-current-feature +``` + +### Resume Session +```bash +# Reactivate paused session +rm .workflow/.active-* 2>/dev/null # Clear any active session +touch .workflow/.active-WFS-paused-session # Activate target session +``` + +### Complete Session +```bash +# 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 @@ -81,7 +168,7 @@ All workflow state for each session managed through `workflow-session.json` with - **Implementation Phase**: Track active tasks, not detailed progress - **Review Phase**: Track completion status only -### Minimal Checkpoint Strategy +### 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 @@ -105,7 +192,7 @@ All workflow state for each session managed through `workflow-session.json` with ### Simple State Transitions ```json { - "phase_completed": "PLAN", + "phase_completed": "PLAN", "next_phase": "IMPLEMENT", "completed_at": "2025-09-07T10:00:00Z", "artifacts": { @@ -114,75 +201,78 @@ All workflow state for each session managed through `workflow-session.json` with } ``` -## Simplified Recovery +## Error Recovery and Validation -### Basic Recovery Logic -```python -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() +### Session Consistency Checks +```bash +# 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 ``` -### 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 +### Multi-Active Session Detection +```bash +# 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 -- **Minimal State**: Only track essential information -- **Phase-Level Updates**: Avoid frequent micro-updates -- **Simple Recovery**: Basic session restoration only -- **User Control**: Manual checkpoint requests +- **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 (< 1 second) -- Minimal file I/O operations -- Clear session state understanding -- No complex synchronization needed \ No newline at end of file +- 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. \ No newline at end of file