docs: clarify CLI command intent and add output routing

- **Intent Clarification**: Distinguished analysis (read-only) from execution (modifies code) commands
- **Output Routing**: Added comprehensive output destination logic for all CLI commands
- **Scratchpad Integration**: Introduced `.workflow/.scratchpad/` for non-session-specific outputs

## Analysis Commands (Read-Only)
- `/cli:analyze`, `/cli:chat`, `/cli:mode:*`: Added "Core Behavior" emphasizing read-only nature
- Added "MODE: analysis" in command templates
- Examples clearly show recommendations vs. code changes

## Execution Commands (Modifies Code)
- `/cli:execute`: Added ⚠️ warnings about code modification
- `/cli:codex-execute`: Clarified multi-stage execution with detailed output structure
- Both commands now have "Output Routing" sections

## Workflow Architecture Updates
- Added `.workflow/.scratchpad/` directory definition
- Output routing logic: session-relevant → `.chat/`, otherwise → `.scratchpad/`
- File naming pattern: `[command-type]-[brief-description]-[timestamp].md`
- Examples for both analysis and implementation commands

## Key Improvements
- Prevents confusion between analysis and implementation operations
- Solves output loss when no active session exists
- Prevents unrelated analyses from cluttering session history
- Provides centralized location for ad-hoc outputs

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

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

.claude/commands/cli/analyze.md

@@ -14,10 +14,18 @@ allowed-tools: SlashCommand(*), Bash(*), TodoWrite(*), Read(*), Glob(*)
 
 ## Purpose
 
-Quick codebase analysis using CLI tools. Automatically detects analysis type and selects appropriate template.
+Quick codebase analysis using CLI tools. **Analysis only - does NOT modify code**.
 
+**Intent**: Understand code patterns, architecture, and provide insights/recommendations
 **Supported Tools**: codex, gemini (default), qwen
 
+## Core Behavior
+
+1. **Read-Only Analysis**: This command ONLY analyzes code and provides insights
+2. **No Code Modification**: Results are recommendations and analysis reports
+3. **Template-Based**: Automatically selects appropriate analysis template
+4. **Smart Pattern Detection**: Infers relevant files based on analysis target
+
 ## Parameters
 
 - `--tool <codex|gemini|qwen>` - Tool selection (default: gemini)
@@ -29,8 +37,9 @@ Quick codebase analysis using CLI tools. Automatically detects analysis type and
 1. Parse tool selection (default: gemini)
 2. If `--enhance`: Execute `/enhance-prompt` first to expand user intent
 3. Auto-detect analysis type from keywords → select template
-4. Build command with auto-detected file patterns
-5. Execute and return results
+4. Build command with auto-detected file patterns and `MODE: analysis`
+5. Execute analysis (read-only, no code changes)
+6. Return analysis report with insights and recommendations
 
 ## File Pattern Auto-Detection
 
@@ -44,17 +53,64 @@ Keywords trigger specific file patterns:
 
 For complex patterns, use `rg` or MCP tools to discover files first, then execute CLI with precise file references.
 
-## Examples
+## Command Template
 
 ```bash
-/cli:analyze "authentication patterns"              # Auto: gemini + auth patterns
-/cli:analyze --tool qwen "component architecture"   # Qwen architecture analysis
-/cli:analyze --tool codex "performance bottlenecks" # Codex deep analysis
-/cli:analyze --enhance "fix auth issues"            # Enhanced prompt → analysis
+cd . && ~/.claude/scripts/gemini-wrapper -p "
+PURPOSE: [analysis goal from target]
+TASK: [auto-detected analysis type]
+MODE: analysis
+CONTEXT: @{CLAUDE.md} [auto-detected file patterns]
+EXPECTED: Insights, patterns, recommendations (NO code modification)
+RULES: [auto-selected template] | Focus on [analysis aspect]
+"
 ```
 
+## Examples
+
+**Basic Analysis**:
+```bash
+/cli:analyze "authentication patterns"
+# Executes: Gemini analysis with auth file patterns
+# Returns: Pattern analysis, architecture insights, recommendations
+```
+
+**Architecture Analysis**:
+```bash
+/cli:analyze --tool qwen "component architecture"
+# Executes: Qwen with component file patterns
+# Returns: Architecture review, design patterns, improvement suggestions
+```
+
+**Performance Analysis**:
+```bash
+/cli:analyze --tool codex "performance bottlenecks"
+# Executes: Codex deep analysis with performance focus
+# Returns: Bottleneck identification, optimization recommendations
+```
+
+**Enhanced Analysis**:
+```bash
+/cli:analyze --enhance "fix auth issues"
+# Step 1: Enhance prompt to expand context
+# Step 2: Analysis with expanded context
+# Returns: Root cause analysis, fix recommendations (NO automatic fixes)
+```
+
+## Output Routing
+
+**Output Destination Logic**:
+- **Active session exists AND analysis is session-relevant**:
+  - Save to `.workflow/WFS-[id]/.chat/analyze-[timestamp].md`
+- **No active session OR one-off analysis**:
+  - Save to `.workflow/.scratchpad/analyze-[description]-[timestamp].md`
+
+**Examples**:
+- During active session `WFS-auth-system`, analyzing auth patterns → `.chat/analyze-20250105-143022.md`
+- No session, quick security check → `.scratchpad/analyze-security-20250105-143045.md`
+
 ## Notes
 
 - Command templates, file patterns, and best practices: see intelligent-tools-strategy.md (loaded in memory)
-- Active workflow session: results saved to `.workflow/WFS-[id]/.chat/`
-- No session: results returned directly
+- Scratchpad directory details: see workflow-architecture.md
+- Scratchpad files can be promoted to workflow sessions if analysis proves valuable