feat: Enhance CLI resume functionality with usage guidance and multi-session merge

- Add resume usage timing guidance (multi-round planning, multi-model collaboration)
- Document multi-session merge capability with --resume <id1>,<id2> syntax
- Improve CLI prompt validation to allow resume without explicit prompt
- Streamline documentation by removing redundant examples and model details

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

.claude/workflows/cli-tools-usage.md

@@ -139,9 +139,7 @@ RULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) $(ca
 - Recommended MODE: `analysis` (read-only) for analysis tasks, `write` for file creation
 - Priority: Prefer Gemini; use Qwen as fallback
 
-**Models** (override via `--model`):
+
-- Gemini: `gemini-2.5-pro`
-- Qwen: `coder-model`, `vision-model`
 
 **Error Handling**: HTTP 429 may show error but still return results - check if results exist
 
@@ -154,19 +152,25 @@ RULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) $(ca
 - Best for: Implementation, testing, automation, bug fixes
 - No default MODE - must explicitly specify `--mode analysis` or `--mode write`
 
-**Models**: `gpt-5.2`
 
 ### Session Resume
 
-**Resume via `--resume` parameter**:
+**When to Use**:
+- Multi-round planning (analysis → planning → implementation)
+- Multi-model collaboration (Gemini → Codex on same topic)
+- Topic continuity (building on previous findings)
+
+**Usage**:
 
 ```bash
-ccw cli -p "Continue analyzing" --tool gemini --mode analysis --resume              # Resume last session
+ccw cli -p "Continue analyzing" --tool gemini --mode analysis --resume              # Resume last
-ccw cli -p "Fix issues found" --tool codex --mode write --resume <id>           # Resume specific session
+ccw cli -p "Fix issues found" --tool codex --mode write --resume <id>              # Resume specific
+ccw cli -p "Merge findings" --tool gemini --mode analysis --resume <id1>,<id2>     # Merge multiple
 ```
 
-- **`--resume` (empty)**: Resume most recent session
+- **`--resume`**: Last session
-- **`--resume <id>`**: Resume specific execution ID
+- **`--resume <id>`**: Specific session
+- **`--resume <id1>,<id2>`**: Merge sessions (comma-separated)
 
 **Context Assembly** (automatic):
 ```
@@ -223,7 +227,6 @@ Every command MUST include these fields:
   - Bad Example: (missing)
   - Good Example: "$(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) $(cat ~/.claude/workflows/cli-templates/prompts/analysis/03-assess-security-risks.txt) \| Focus on authentication \| Ignore test files"
 
-
 ### CONTEXT Configuration
 
 **Format**: `CONTEXT: [file patterns] | Memory: [memory context]`
@@ -293,15 +296,6 @@ ccw cli -p 'RULES: $(cat ~/.claude/workflows/cli-templates/protocols/analysis-pr
 ccw cli -p "RULES: \$(cat ~/.claude/workflows/cli-templates/protocols/analysis-protocol.md) ..." --tool gemini
 ```
 
-**Examples**:
-```bash
-# Specific template (preferred)
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt) | Focus on auth | analysis=READ-ONLY
-
-# Universal fallback (when no specific template matches)
-RULES: $(cat ~/.claude/workflows/cli-templates/prompts/universal/00-universal-rigorous-style.txt) | Focus on security patterns | analysis=READ-ONLY
-```
-
 ### Template System
 
 **Base Path**: `~/.claude/workflows/cli-templates/prompts/`
@@ -376,10 +370,6 @@ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/universal/00-universal-ri
   - Description: Resume previous session
   - Default: -
 
-- **`--no-stream`**
-  - Description: Disable streaming
-  - Default: false
-
 ### Directory Configuration
 
 #### Working Directory (`--cd`)
@@ -500,10 +490,6 @@ RULES: $(cat ~/.claude/workflows/cli-templates/protocols/write-protocol.md) $(ca
 
 **Codex Multiplier**: 3x allocated time (minimum 15min / 900000ms)
 
-```bash
-ccw cli -p "<prompt>" --tool gemini --mode analysis --timeout 600000   # 10 min
-ccw cli -p "<prompt>" --tool codex --mode write --timeout 1800000   # 30 min
-```
 
 ### Permission Framework
 
@@ -528,13 +514,6 @@ ccw cli -p "<prompt>" --tool codex --mode write --timeout 1800000   # 30 min
 - **Discover patterns first** - Use rg/MCP before CLI execution
 - **Default to full context** - Use `@**/*` unless specific files needed
 
-### Workflow Integration
-
-- **Understanding**: `ccw cli -p "<prompt>" --tool gemini --mode analysis`
-- **Architecture**: `ccw cli -p "<prompt>" --tool gemini --mode analysis`
-- **Implementation**: `ccw cli -p "<prompt>" --tool codex --mode write`
-- **Quality**: `ccw cli -p "<prompt>" --tool codex --mode write`
-
 ### Planning Checklist
 
 - [ ] **Purpose defined** - Clear goal and intent

ccw/src/commands/cli.ts

@@ -402,14 +402,16 @@ async function execAction(positionalPrompt: string | undefined, options: CliExec
     finalPrompt = positionalPrompt;
   }
 
-  if (!finalPrompt) {
+  // Prompt is required unless resuming
+  if (!finalPrompt && !resume) {
     console.error(chalk.red('Error: Prompt is required'));
     console.error(chalk.gray('Usage: ccw cli -p "<prompt>" --tool gemini'));
     console.error(chalk.gray('   or: ccw cli -f prompt.txt --tool codex'));
+    console.error(chalk.gray('   or: ccw cli --resume --tool gemini'));
     process.exit(1);
   }
 
-  const prompt_to_use = finalPrompt;
+  const prompt_to_use = finalPrompt || '';
 
   // Parse resume IDs for merge scenario
   const resumeIds = resume && typeof resume === 'string' ? resume.split(',').map(s => s.trim()).filter(Boolean) : [];
@@ -679,14 +681,14 @@ export async function cliCommand(
 
     default: {
       const execOptions = options as CliExecOptions;
-      // Auto-exec if: has -p/--prompt, has --stdin, has --resume, or subcommand looks like a prompt
+      // Auto-exec if: has -p/--prompt, has -f/--file, has --resume, or subcommand looks like a prompt
       const hasPromptOption = !!execOptions.prompt;
-      const hasStdin = !!execOptions.stdin;
+      const hasFileOption = !!execOptions.file;
       const hasResume = execOptions.resume !== undefined;
       const subcommandIsPrompt = subcommand && !subcommand.startsWith('-');
 
-      if (hasPromptOption || hasStdin || hasResume || subcommandIsPrompt) {
+      if (hasPromptOption || hasFileOption || hasResume || subcommandIsPrompt) {
-        // Treat as exec: use subcommand as positional prompt if no -p option
+        // Treat as exec: use subcommand as positional prompt if no -p/-f option
         const positionalPrompt = subcommandIsPrompt ? subcommand : undefined;
         await execAction(positionalPrompt, execOptions);
       } else {
@@ -694,38 +696,32 @@ export async function cliCommand(
         console.log(chalk.bold.cyan('\n  CCW CLI Tool Executor\n'));
         console.log('  Unified interface for Gemini, Qwen, and Codex CLI tools.\n');
         console.log('  Usage:');
-        console.log(chalk.gray('    ccw cli -p "<prompt>" --tool <tool>     Direct execution (recommended)'));
+        console.log(chalk.gray('    ccw cli -p "<prompt>" --tool <tool>     Execute with prompt'));
-        console.log(chalk.gray('    ccw cli "<prompt>" --tool <tool>        Shorthand'));
+        console.log(chalk.gray('    ccw cli -f prompt.txt --tool <tool>     Execute from file'));
-        console.log(chalk.gray('    ccw cli exec "<prompt>" --tool <tool>   Explicit exec'));
         console.log();
         console.log('  Subcommands:');
         console.log(chalk.gray('    status              Check CLI tools availability'));
         console.log(chalk.gray('    storage [cmd]       Manage CCW storage (info/clean/config)'));
-        console.log(chalk.gray('    exec <prompt>       Execute a CLI tool (optional, default behavior)'));
         console.log(chalk.gray('    history             Show execution history'));
         console.log(chalk.gray('    detail <id>         Show execution detail'));
         console.log(chalk.gray('    test-parse [args]   Debug CLI argument parsing'));
         console.log();
-        console.log('  Exec Options:');
+        console.log('  Options:');
-        console.log(chalk.gray('    -p, --prompt <text> Prompt text (preferred for multi-line)'));
+        console.log(chalk.gray('    -p, --prompt <text> Prompt text'));
         console.log(chalk.gray('    -f, --file <file>   Read prompt from file'));
-        console.log(chalk.gray('    --stdin             Read prompt from stdin'));
+        console.log(chalk.gray('    --tool <tool>       Tool: gemini, qwen, codex (default: gemini)'));
-        console.log(chalk.gray('    --tool <tool>       Tool to use: gemini, qwen, codex (default: gemini)'));
         console.log(chalk.gray('    --mode <mode>       Mode: analysis, write, auto (default: analysis)'));
         console.log(chalk.gray('    --model <model>     Model override'));
         console.log(chalk.gray('    --cd <path>         Working directory'));
-        console.log(chalk.gray('    --includeDirs <dirs>  Additional directories (comma-separated)'));
+        console.log(chalk.gray('    --includeDirs <dirs>  Additional directories'));
-        console.log(chalk.gray('    ccw cli -ps>      Timeout in milliseconds (default: 300000)'));
+        console.log(chalk.gray('    --timeout <ms>      Timeout (default: 300000)'));
-        console.log(chalk.gray('    --no-stream         Disable streaming output'));
         console.log(chalk.gray('    --resume [id]       Resume previous session'));
-        console.log(chalk.gray('    --id <id>           Custom execution ID'));
         console.log();
         console.log('  Examples:');
         console.log(chalk.gray('    ccw cli -p "Analyze auth module" --tool gemini'));
-        console.log(chalk.gray('    ccw cli "Simple prompt" --tool codex --mode write'));
+        console.log(chalk.gray('    ccw cli -f prompt.txt --tool codex --mode write'));
-        console.log(chalk.gray('    ccw cli -p "$(cat prompt.txt)" --tool gemini'));
+        console.log(chalk.gray('    ccw cli -p "$(cat template.md)" --tool gemini'));
         console.log(chalk.gray('    ccw cli --resume --tool gemini'));
-        console.log(chalk.gray('    ccw cli history --tool gemini --limit 10'));
         console.log();
       }
     }