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

name: start description: Discover existing sessions or start new workflow session with intelligent session management and conflict detection argument-hint: [--type <workflow|review|tdd|test|docs>] [--auto|--new] [optional: task description for new session] examples: - /workflow:session:start - /workflow:session:start --auto "implement OAuth2 authentication" - /workflow:session:start --type review "Code review for auth module" - /workflow:session:start --type tdd --auto "implement user authentication" - /workflow:session:start --type test --new "test payment flow"

Start Workflow Session (/workflow:session:start)

Overview

Manages workflow sessions with three operation modes: discovery (manual), auto (intelligent), and force-new.

Dual Responsibility:

1. Project-level initialization (first-time only): Creates .workflow/project.json for feature registry
2. Session-level initialization (always): Creates session directory structure

Session Types

The --type parameter classifies sessions for CCW dashboard organization:

Type	Description	Default For
workflow	Standard implementation (default)	/workflow:plan
review	Code review sessions	/workflow:review-module-cycle
tdd	TDD-based development	/workflow:tdd-plan
test	Test generation/fix sessions	/workflow:test-fix-gen
docs	Documentation sessions	/memory:docs
lite-plan	Lightweight planning workflow	/workflow:lite-plan
lite-fix	Lightweight bug fix workflow	/workflow:lite-fix

Special Behavior for lite-plan and lite-fix:

• These types automatically infer the storage location (.workflow/.lite-plan/ or .workflow/.lite-fix/)
• No need to specify --location parameter when using these types
• Alternative: Use --location lite-plan or --location lite-fix directly

Validation: If --type is provided with invalid value, return error:

ERROR: Invalid session type. Valid types: workflow, review, tdd, test, docs, lite-plan, lite-fix

Step 0: Initialize Project State (First-time Only)

Executed before all modes - Ensures project-level state file exists by calling /workflow:init.

Check and Initialize

# Check if project state exists
bash(test -f .workflow/project.json && echo "EXISTS" || echo "NOT_FOUND")

If NOT_FOUND, delegate to /workflow:init:

// Call workflow:init for intelligent project analysis
SlashCommand({command: "/workflow:init"});

// Wait for init completion
// project.json will be created with comprehensive project overview

Output:

• If EXISTS: PROJECT_STATE: initialized
• If NOT_FOUND: Calls /workflow:init → creates .workflow/project.json with full project analysis

Note: /workflow:init uses cli-explore-agent to build comprehensive project understanding (technology stack, architecture, key components). This step runs once per project. Subsequent executions skip initialization.

Mode 1: Discovery Mode (Default)

Usage

/workflow:session:start

Step 1: List Active Sessions

ccw session list --location active

Step 2: Display Session Metadata

ccw session WFS-promptmaster-platform read workflow-session.json

Step 4: User Decision

Present session information and wait for user to select or create session.

Output: SESSION_ID: WFS-[user-selected-id]

Mode 2: Auto Mode (Intelligent)

Usage

/workflow:session:start --auto "task description"

Step 1: Check Active Sessions Count

ccw session list --location active
# Check result.total in response

Step 2a: No Active Sessions → Create New

# Generate session slug from description
# Pattern: WFS-{lowercase-slug-from-description}

# Create session with ccw (creates directories + metadata atomically)
ccw session init WFS-implement-oauth2-auth --type workflow

Output: SESSION_ID: WFS-implement-oauth2-auth

Step 2b: Single Active Session → Check Relevance

# Get session list with metadata
ccw session list --location active

# Read session metadata for relevance check
ccw session WFS-promptmaster-platform read workflow-session.json

# If task contains project keywords → Reuse session
# If task unrelated → Create new session (use Step 2a)

Output (reuse): SESSION_ID: WFS-promptmaster-platform Output (new): SESSION_ID: WFS-[new-slug]

Step 2c: Multiple Active Sessions → Use First

# Get first active session from list
ccw session list --location active
# Use first session_id from result.active array

# Output warning and session ID
# WARNING: Multiple active sessions detected
# SESSION_ID: WFS-first-session

Mode 3: Force New Mode

Usage

/workflow:session:start --new "task description"

Step 1: Generate Unique Session Slug

# Convert description to slug: lowercase, alphanumeric + hyphen, max 50 chars
# Check if exists via ccw session list, add counter if collision
ccw session list --location active

Step 2: Create Session Structure

# Basic init - creates directories + default metadata
ccw session init WFS-fix-login-bug --type workflow

# Advanced init - with custom metadata
ccw session init WFS-oauth-implementation --type workflow --content '{"description":"OAuth2 authentication system","priority":"high","complexity":"medium"}'

Default Metadata (auto-generated):

{
  "session_id": "WFS-fix-login-bug",
  "type": "workflow",
  "status": "planning",
  "created_at": "2025-12-17T..."
}

Custom Metadata (merged with defaults):

{
  "session_id": "WFS-oauth-implementation",
  "type": "workflow",
  "status": "planning",
  "created_at": "2025-12-17T...",
  "description": "OAuth2 authentication system",
  "priority": "high",
  "complexity": "medium"
}

Field Usage:

• description: Displayed in dashboard (replaces session_id as title)
• status: Can override default "planning" (e.g., "active", "implementing")
• Custom fields: Any additional fields are saved and accessible programmatically

Output: SESSION_ID: WFS-fix-login-bug

Execution Guideline

• Non-interrupting: When called from other commands, this command completes and returns control to the caller without interrupting subsequent tasks.

Output Format Specification

Success

SESSION_ID: WFS-session-slug

Error

ERROR: --auto mode requires task description
ERROR: Failed to create session directory

Analysis (Auto Mode)

ANALYSIS: Task relevance = high
DECISION: Reusing existing session
SESSION_ID: WFS-promptmaster-platform

Session ID Format

• Pattern: WFS-[lowercase-slug]
• Characters: a-z, 0-9, - only
• Max length: 50 characters
• Uniqueness: Add numeric suffix if collision (WFS-auth-2, WFS-auth-3)

session_manager Tool Alternative

The above bash commands can be replaced with ccw tool exec session_manager:

List Sessions

# List active sessions with metadata
ccw tool exec session_manager '{"operation":"list","location":"active","include_metadata":true}'

# Response: {"success":true,"result":{"active":[{"session_id":"WFS-xxx","metadata":{...}}],"total":1}}

Create Session (replaces mkdir + echo)

# Single command creates directories + metadata
ccw tool exec session_manager '{
  "operation": "init",
  "session_id": "WFS-my-session",
  "metadata": {
    "project": "my project description",
    "status": "planning",
    "type": "workflow",
    "created_at": "2025-12-10T08:00:00Z"
  }
}'

Read Session Metadata

ccw tool exec session_manager '{"operation":"read","session_id":"WFS-xxx","content_type":"session"}'