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

name, description, usage, examples

name	description	usage	examples
complete	Mark the active workflow session as complete and remove active flag	/workflow:session:complete	/workflow:session:complete

Complete Workflow Session (/workflow:session:complete)

Purpose

Mark the currently active workflow session as complete, update its status, and remove the active flag marker.

Usage

/workflow:session:complete

Behavior

Session Completion Process

1. Locate Active Session: Find current active session via .workflow/.active-* marker file
2. Update Session Status: Modify workflow-session.json with completion data
3. Remove Active Flag: Delete .workflow/.active-[session-name] marker file
4. Generate Summary: Display completion report and statistics

Status Updates

Updates workflow-session.json with:

• status: "completed"
• completed_at: Current timestamp
• final_phase: Current phase at completion
• completion_type: "manual" (distinguishes from automatic completion)

State Preservation

Preserves all session data:

• Implementation plans and documents
• Task execution history
• Generated artifacts and reports
• Session configuration and metadata

Completion Summary Display

Session Overview

✅ Session Completed: WFS-oauth-integration
   Description: Implement OAuth2 authentication
   Created: 2025-09-07 14:30:00
   Completed: 2025-09-12 16:45:00
   Duration: 5 days, 2 hours, 15 minutes
   Final Phase: IMPLEMENTATION

Progress Summary

📊 Session Statistics:
   - Tasks completed: 5/5 (100%)
   - Files modified: 12
   - Tests created: 8
   - Documentation updated: 3 files
   - Average task duration: 2.5 hours

Generated Artifacts

📄 Session Artifacts:
   ✅ IMPL_PLAN.md (Complete implementation plan)
   ✅ TODO_LIST.md (Final task status)
   ✅ .task/ (5 completed task files)
   📊 reports/ (Session reports available)

Archive Information

🗂️  Session Archive:
   Directory: .workflow/WFS-oauth-integration/
   Status: Completed and archived
   Access: Use /context WFS-oauth-integration for review

No Active Session

If no active session exists:

⚠️  No Active Session to Complete

Available Options:
- View all sessions: /workflow:session:list
- Start new session: /workflow:session:start "task description"
- Resume paused session: /workflow:session:resume

Next Steps Suggestions

After completion, displays contextual actions:

🎯 What's Next:
- View session archive: /context WFS-oauth-integration
- Start related session: /workflow:session:start "build on OAuth work"
- Review all sessions: /workflow:session:list
- Create project report: /workflow/report

Error Handling

Common Error Scenarios

• No active session: Clear message with alternatives
• Corrupted session state: Validates before completion, offers recovery
• File system issues: Handles permissions and access problems
• Incomplete tasks: Warns about unfinished work, allows forced completion

Validation Checks

Before completing, verifies:

• Session directory exists and is accessible
• workflow-session.json is valid and readable
• Marker file exists and matches session
• No critical errors in session state

Forced Completion

For problematic sessions:

# Option to force completion despite issues
/workflow:session:complete --force

Integration with Workflow System

Session Lifecycle

Completes the session workflow:

• INIT → PLAN → IMPLEMENT → COMPLETE
• Maintains session history for reference
• Preserves all artifacts and documentation

TodoWrite Integration

• Synchronizes final TODO state
• Marks all remaining tasks as archived
• Preserves task history in session directory

Context System

• Session remains accessible via /context <session-id>
• All documents and reports remain available
• Can be referenced for future sessions

Command Variations

Basic Completion

/workflow:session:complete

With Summary Options

/workflow:session:complete --detailed    # Show detailed statistics
/workflow:session:complete --quiet       # Minimal output
/workflow:session:complete --force       # Force completion despite issues

Session State After Completion

Directory Structure Preserved

.workflow/WFS-[session-name]/
├── workflow-session.json    # Updated with completion data
├── IMPL_PLAN.md            # Preserved
├── TODO_LIST.md            # Final state preserved
├── .task/                  # All task files preserved
└── reports/                # Generated reports preserved

Session JSON Example

{
  "id": "WFS-oauth-integration",
  "description": "Implement OAuth2 authentication",
  "status": "completed",
  "created_at": "2025-09-07T14:30:00Z",
  "completed_at": "2025-09-12T16:45:00Z",
  "completion_type": "manual",
  "final_phase": "IMPLEMENTATION",
  "tasks_completed": 5,
  "tasks_total": 5
}

---

Result: Current active session is marked as complete, archived, and no longer active. All session data is preserved for future reference.