feat: Redesign test-gen workflow with independent session and cross-session context

Major redesign of test-gen workflow based on simplified architecture:

Core Changes:
- Creates independent test session (WFS-test-[source]) instead of modifying existing session
- Implements 4-phase execution with concept-enhanced analysis integration
- Reuses IMPL-*.json format with meta.type="test-fix" (no new task type)
- Auto-detects cross-session context via workflow-session.json metadata

4-Phase Workflow:
1. Phase 1: Create test session with workflow_type and source_session_id metadata
2. Phase 2: Auto-detect and gather cross-session context (summaries, git changes, tests)
3. Phase 3: Analyze implementation with concept-enhanced (parallel Gemini + Codex)
4. Phase 4: Generate IMPL-001.json task with test strategy from ANALYSIS_RESULTS.md

Key Features:
- Session isolation: Test session separate from implementation session
- Parameter simplification: context-gather auto-detects via metadata (no --source-session param)
- Format reuse: IMPL-*.json with meta.type field (zero changes to execute/status tools)
- Analysis integration: concept-enhanced provides comprehensive test strategy and code targets
- Automatic cross-session: Collects source session artifacts automatically

Tool Modifications Required:
- session-start: Support test session metadata (workflow_type, source_session_id)
- context-gather: Auto-detect test session and gather from source session
- task-generate: Extract test strategy from ANALYSIS_RESULTS.md
- concept-enhanced: No changes (already supports analysis)
- execute: No changes (already dispatches by meta.agent)

Data Flow:
User → session-start (creates test session) → context-gather (auto cross-session)
→ concept-enhanced (analyzes + generates strategy) → task-generate (creates task)
→ Returns summary → User triggers /workflow:execute separately

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

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

.claude/agents/action-planning-agent.md

@@ -228,7 +228,7 @@ Generate individual `.task/IMPL-*.json` files with:
       "modification_points": ["Apply requirements"],
       "logic_flow": ["Load spec", "Analyze", "Implement", "Validate"]
     },
-    "target_files": ["file:function:lines"]
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
 ```

.claude/commands/workflow/execute.md

@@ -356,8 +356,8 @@ Task(subagent_type="{meta.agent}",
 
      **WORKFLOW COMPLETION CHECK**:
      After updating task status, check if workflow is complete:
-     total_tasks=\$(ls .workflow/*/\.task/*.json | wc -l)
+     total_tasks=\$(find .workflow/*/\.task/ -name "*.json" -type f 2>/dev/null | wc -l)
-     completed_tasks=\$(ls .workflow/*/\.summaries/*.md 2>/dev/null | wc -l)
+     completed_tasks=\$(find .workflow/*/\.summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
      if [ \$total_tasks -eq \$completed_tasks ]; then
        SlashCommand(command=\"/workflow:session:complete\")
      fi"),
@@ -433,7 +433,7 @@ Task(subagent_type="{meta.agent}",
       "task_description": "Implement following consolidated synthesis specification...",
       "modification_points": ["Apply synthesis specification requirements..."]
     },
-    "target_files": ["file:function:lines"]
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
 ```

.claude/commands/workflow/review.md

@@ -55,7 +55,7 @@ if [ ! -d ".workflow/${sessionId}" ]; then
 fi
 
 # Check for completed tasks
-if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(ls .workflow/${sessionId}/.summaries/IMPL-*.md 2>/dev/null)" ]; then
+if [ ! -d ".workflow/${sessionId}/.summaries" ] || [ -z "$(find .workflow/${sessionId}/.summaries/ -name "IMPL-*.md" -type f 2>/dev/null)" ]; then
     echo "❌ No completed implementation found. Complete implementation first"
     exit 1
 fi

.claude/commands/workflow/session/complete.md

@@ -44,8 +44,8 @@ mv temp.json .workflow/WFS-session/workflow-session.json
 
 ### Step 5: Count Final Statistics
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
+find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 6: Remove Active Marker
@@ -56,12 +56,12 @@ rm .workflow/.active-WFS-session-name
 ## Simple Bash Commands
 
 ### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
+- **Find active session**: `find .workflow/ -name ".active-*" -type f`
 - **Get session name**: `basename marker | sed 's/^\.active-//'`
 - **Update status**: `jq '.status = "completed"' session.json > temp.json`
 - **Add timestamp**: `jq '.completed_at = "'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"'`
-- **Count tasks**: `ls .task/*.json | wc -l`
+- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
 - **Remove marker**: `rm .workflow/.active-session`
 
 ### Completion Result
@@ -92,11 +92,11 @@ Session Completion Summary:
 ### Error Handling
 ```bash
 # No active session
-ls .workflow/.active-* 2>/dev/null || echo "No active session found"
+find .workflow/ -name ".active-*" -type f 2>/dev/null || echo "No active session found"
 
 # Incomplete tasks
-task_count=$(ls .task/*.json | wc -l)
+task_count=$(find .task/ -name "*.json" -type f | wc -l)
-summary_count=$(ls .summaries/*.md 2>/dev/null | wc -l)
+summary_count=$(find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l)
 test $task_count -eq $summary_count || echo "Warning: Not all tasks completed"
 ```
 

.claude/commands/workflow/session/list.md

@@ -35,8 +35,8 @@ jq -r '.session_id, .status, .project' .workflow/WFS-session/workflow-session.js
 
 ### Step 4: Count Task Progress
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null | wc -l
+find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 5: Get Creation Time
@@ -47,11 +47,11 @@ jq -r '.created_at // "unknown"' .workflow/WFS-session/workflow-session.json
 ## Simple Bash Commands
 
 ### Basic Operations
-- **List sessions**: `ls .workflow/WFS-*`
+- **List sessions**: `find .workflow/ -maxdepth 1 -type d -name "WFS-*"`
-- **Find active**: `ls .workflow/.active-*`
+- **Find active**: `find .workflow/ -name ".active-*" -type f`
 - **Read session data**: `jq -r '.session_id, .status' session.json`
-- **Count tasks**: `ls .task/*.json | wc -l`
+- **Count tasks**: `find .task/ -name "*.json" -type f | wc -l`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **Count completed**: `find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l`
 - **Get timestamp**: `jq -r '.created_at' session.json`
 
 ## Simple Output Format

.claude/commands/workflow/status.md

@@ -25,7 +25,7 @@ Generates on-demand views from JSON task data. No synchronization needed - all v
 
 ### Step 1: Find Active Session
 ```bash
-ls .workflow/.active-* 2>/dev/null | head -1
+find .workflow/ -name ".active-*" -type f 2>/dev/null | head -1
 ```
 
 ### Step 2: Load Session Data
@@ -35,7 +35,7 @@ cat .workflow/WFS-session/workflow-session.json
 
 ### Step 3: Scan Task Files
 ```bash
-ls .workflow/WFS-session/.task/*.json 2>/dev/null
+find .workflow/WFS-session/.task/ -name "*.json" -type f 2>/dev/null
 ```
 
 ### Step 4: Generate Task Status
@@ -45,8 +45,8 @@ cat .workflow/WFS-session/.task/impl-1.json | jq -r '.status'
 
 ### Step 5: Count Task Progress
 ```bash
-ls .workflow/WFS-session/.task/*.json | wc -l
+find .workflow/WFS-session/.task/ -name "*.json" -type f | wc -l
-ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
+find .workflow/WFS-session/.summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ### Step 6: Display Overview
@@ -66,11 +66,11 @@ ls .workflow/WFS-session/.summaries/*.md 2>/dev/null | wc -l
 ## Simple Bash Commands
 
 ### Basic Operations
-- **Find active session**: `ls .workflow/.active-*`
+- **Find active session**: `find .workflow/ -name ".active-*" -type f`
 - **Read session info**: `cat .workflow/session/workflow-session.json`
-- **List tasks**: `ls .workflow/session/.task/*.json`
+- **List tasks**: `find .workflow/session/.task/ -name "*.json" -type f`
 - **Check task status**: `cat task.json | jq -r '.status'`
-- **Count completed**: `ls .summaries/*.md | wc -l`
+- **Count completed**: `find .summaries/ -name "*.md" -type f | wc -l`
 
 ### Task Status Check
 - **pending**: Not started yet
@@ -87,8 +87,8 @@ test -f .workflow/.active-* && echo "Session active"
 for f in .workflow/session/.task/*.json; do jq empty "$f" && echo "Valid: $f"; done
 
 # Check summaries match
-ls .task/*.json | wc -l
+find .task/ -name "*.json" -type f | wc -l
-ls .summaries/*.md | wc -l
+find .summaries/ -name "*.md" -type f 2>/dev/null | wc -l
 ```
 
 ## Simple Output Format

.claude/commands/workflow/test-gen.md

@@ -1,11 +1,11 @@
 ---
 name: test-gen
-description: Orchestrate test-fix workflow by analyzing implementation and generating TEST-FIX tasks
+description: Create independent test-fix workflow session by analyzing completed implementation
-usage: /workflow:test-gen [session-id]
+usage: /workflow:test-gen <source-session-id>
-argument-hint: "[session-id]"
+argument-hint: "<source-session-id>"
 examples:
-  - /workflow:test-gen
   - /workflow:test-gen WFS-user-auth
+  - /workflow:test-gen WFS-api-refactor
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
@@ -13,134 +13,177 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 
 ## Coordinator Role
 
-**This command is a pure orchestrator**: Analyze completed implementation session, generate test-fix workflow through standardized tool commands, and trigger automated test validation.
+**This command is a pure orchestrator**: Creates an independent test-fix workflow session for validating a completed implementation. It reuses the standard planning toolchain with automatic cross-session context gathering.
+
+**Core Principles**:
+- **Session Isolation**: Creates new `WFS-test-[source]` session to keep verification separate from implementation
+- **Context-First**: Prioritizes gathering code changes and summaries from source session
+- **Format Reuse**: Creates standard `IMPL-*.json` task, using `meta.type: "test-fix"` for agent assignment
+- **Parameter Simplification**: Tools auto-detect test session type via metadata, no manual cross-session parameters needed
 
 **Execution Flow**:
-1. Initialize TodoWrite → Execute Phase 1 → Parse output → Update TodoWrite
+1. Initialize TodoWrite → Create test session → Parse session ID
-2. Execute Phase 2 with Phase 1 data → Parse output → Update TodoWrite
+2. Gather cross-session context (automatic) → Parse context path
-3. Execute Phase 3 with Phase 2 data → Parse output → Update TodoWrite
+3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
-4. Execute Phase 4 with Phase 3 validation → Update TodoWrite → Return summary
+4. Generate test task from analysis → Return summary
 
 ## Core Rules
 
-1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 session discovery
+1. **Start Immediately**: First action is TodoWrite initialization, second action is Phase 1 test session creation
 2. **No Preliminary Analysis**: Do not read files or analyze before Phase 1
 3. **Parse Every Output**: Extract required data from each phase for next phase
 4. **Sequential Execution**: Each phase depends on previous phase's output
-5. **Complete All Phases**: Do not return to user until Phase 4 completes
+5. **Complete All Phases**: Do not return to user until Phase 4 completes (execution triggered separately)
 6. **Track Progress**: Update TodoWrite after every phase completion
-7. **Use Standard Tools**: Follow plan.md pattern using context-gather, concept-enhanced, task-generate
+7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
 
 ## 4-Phase Execution
 
-### Phase 1: Session Discovery & Context Gathering
+### Phase 1: Create Test Session
-**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [sessionId] \"TEST-FIX: Validate implementation for [sessionId]\"")`
+**Command**: `SlashCommand(command="/workflow:session:start --new \"Test validation for [sourceSessionId]\"")`
 
-**Session ID Resolution**:
+**Input**: `sourceSessionId` from user argument (e.g., `WFS-user-auth`)
-- If argument provided → Use directly as `sessionId`
-- If no argument → Auto-detect from `.workflow/.active-*` marker
-- Format: `WFS-[session-name]`
 
-**Task Description Structure**:
+**Expected Behavior**:
-```
+- Creates new session with pattern `WFS-test-[source-slug]` (e.g., `WFS-test-user-auth`)
-GOAL: Execute and validate all tests for completed implementation
+- Writes metadata to `workflow-session.json`:
-SCOPE: Test execution, failure diagnosis, code fixing
+  - `workflow_type: "test_session"`
-CONTEXT: Implementation session [sessionId] with completed IMPL tasks
+  - `source_session_id: "[sourceSessionId]"`
-```
+- Returns new session ID for subsequent phases
 
 **Parse Output**:
-- Extract: context package path (store as `contextPath`)
+- Extract: new test session ID (store as `testSessionId`)
-- Typical pattern: `.workflow/[sessionId]/.process/context-package-test.json`
+- Pattern: `WFS-test-[slug]`
 
 **Validation**:
-- Session directory `.workflow/[sessionId]/` exists
+- Source session `.workflow/[sourceSessionId]/` exists
-- Session has completed IMPL tasks (check .summaries/IMPL-*-summary.md)
+- Source session has completed IMPL tasks (`.summaries/IMPL-*-summary.md`)
-- Context package created successfully
+- New test session directory created
+- Metadata includes `workflow_type` and `source_session_id`
 
 **TodoWrite**: Mark phase 1 completed, phase 2 in_progress
 
 ---
 
-### Phase 2: Implementation Analysis
+### Phase 2: Gather Cross-Session Context
-**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]")`
+**Command**: `SlashCommand(command="/workflow:tools:context-gather --session [testSessionId]")`
 
-**Input**: `sessionId` from Phase 1, `contextPath` from Phase 1
+**Input**: `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
 
-**Expected Analysis**:
+**Automatic Detection**:
-- Review completed implementation summaries
+- context-gather reads `.workflow/[testSessionId]/workflow-session.json`
-- Identify test files and coverage gaps
+- Detects `workflow_type: "test_session"`
-- Assess test execution strategy
+- Automatically uses `source_session_id` to gather source session context
-- Determine failure diagnosis approach
+- No need for manual `--source-session` parameter
+
+**Cross-Session Context Collection** (Automatic):
+- Implementation summaries: `.workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md`
+- Code changes: `git log --since=[source_session_created_at]` for changed files
+- Original plan: `.workflow/[sourceSessionId]/IMPL_PLAN.md`
+- Test files: Discovered via MCP code-index tools
 
 **Parse Output**:
-- Verify `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` created
+- Extract: context package path (store as `contextPath`)
-- Extract test execution recommendations
+- Pattern: `.workflow/[testSessionId]/.process/context-package.json`
-- Identify critical test areas
 
 **Validation**:
-- File `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` exists
+- Context package created in test session directory
-- Contains test strategy and execution plan
+- Contains source session artifacts (summaries, changed files)
-- Lists focus test paths and acceptance criteria
+- Includes test file inventory
 
 **TodoWrite**: Mark phase 2 completed, phase 3 in_progress
 
 ---
 
-### Phase 3: TEST-FIX Task Generation
+### Phase 3: Implementation Analysis
-**Command**: `SlashCommand(command="/workflow:tools:task-generate --session [sessionId]")`
+**Command**: `SlashCommand(command="/workflow:tools:concept-enhanced --session [testSessionId] --context [contextPath]")`
 
-**Input**: `sessionId` from Phase 1
+**Input**:
+- `testSessionId` from Phase 1 (e.g., `WFS-test-user-auth`)
+- `contextPath` from Phase 2 (e.g., `.workflow/WFS-test-user-auth/.process/context-package.json`)
+
+**Analysis Focus**:
+- Review implementation summaries from source session
+- Identify test files and coverage gaps
+- Assess test execution strategy (unit, integration, e2e)
+- Determine failure diagnosis approach
+- Recommend code quality improvements
 
 **Expected Behavior**:
-- Parse ANALYSIS_RESULTS.md for test requirements
+- Reads context-package.json with cross-session artifacts
-- Generate TEST-FIX-001.json with:
+- Executes parallel analysis (Gemini for test strategy, optional Codex for validation)
-  - `meta.type: "test-fix"`
+- Generates comprehensive test execution strategy
-  - `meta.agent: "@test-fix-agent"`
+- Identifies code modification targets for test fixes
-  - `context.requirements`: Test execution requirements
+- Provides feasibility assessment for test validation
-  - `context.focus_paths`: Test files and source files
-  - `context.acceptance`: All tests pass criteria
-  - `flow_control.pre_analysis`: Load implementation summaries
-  - `flow_control.implementation_approach`: Test execution strategy
 
 **Parse Output**:
-- Verify `.workflow/[sessionId]/.task/TEST-FIX-001.json` exists
+- Verify `.workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md` created
-- Verify `.workflow/[sessionId]/IMPL_PLAN.md` updated
+- Contains test strategy and execution plan
-- Verify `.workflow/[sessionId]/TODO_LIST.md` updated
+- Lists code modification targets (format: `file:function:lines` or `file`)
+- Includes risk assessment and optimization recommendations
 
 **Validation**:
-- Task JSON has correct structure (id, meta.type="test-fix", meta.agent="@test-fix-agent")
+- File `.workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md` exists
-- IMPL_PLAN.md contains test-fix strategy
+- Contains complete analysis sections:
-- TODO_LIST.md shows TEST-FIX-001 task
+  - Current State Analysis (test coverage, existing tests)
+  - Proposed Solution Design (test execution strategy)
+  - Implementation Strategy (code targets, feasibility)
+  - Solution Optimization (performance, quality)
+  - Critical Success Factors (acceptance criteria)
 
 **TodoWrite**: Mark phase 3 completed, phase 4 in_progress
 
 ---
 
-### Phase 4: Execute Test-Fix Workflow
+### Phase 4: Generate Test Task
-**Command**: `SlashCommand(command="/workflow:execute --session [sessionId]")`
+**Command**: `SlashCommand(command="/workflow:tools:task-generate --session [testSessionId]")`
 
-**Input**: `sessionId` from Phase 1
+**Input**: `testSessionId` from Phase 1
 
 **Expected Behavior**:
-- Workflow executor detects TEST-FIX-001 task
+- Reads ANALYSIS_RESULTS.md from Phase 3
-- Assigns to @test-fix-agent
+- Extracts test strategy and code modification targets
-- Agent executes tests using flow_control.pre_analysis
+- Generates `IMPL-001.json` (reusing standard format) with:
-- If failures: diagnoses and fixes code
+  - `meta.type: "test-fix"` (enables @test-fix-agent assignment)
-- Re-runs tests until all pass
+  - `meta.agent: "@test-fix-agent"`
-- Generates completion summary
+  - `context.requirements`: Test execution requirements from analysis
+  - `context.focus_paths`: Test files and source files from analysis
+  - `context.acceptance`: All tests pass criteria
+  - `flow_control.pre_analysis`: Load source session summaries
+  - `flow_control.implementation_approach`: Test execution strategy from ANALYSIS_RESULTS.md
+  - `flow_control.target_files`: Code modification targets from analysis
+
+**Parse Output**:
+- Verify `.workflow/[testSessionId]/.task/IMPL-001.json` exists
+- Verify `.workflow/[testSessionId]/IMPL_PLAN.md` created
+- Verify `.workflow/[testSessionId]/TODO_LIST.md` created
 
 **Validation**:
-- Workflow execution started successfully
+- Task JSON has `id: "IMPL-001"` and `meta.type: "test-fix"`
-- TEST-FIX-001 task status updated to "active" or "completed"
+- IMPL_PLAN.md contains test validation strategy from ANALYSIS_RESULTS.md
+- TODO_LIST.md shows IMPL-001 task
+- flow_control includes code targets and test strategy
+- Task is ready for /workflow:execute
 
 **TodoWrite**: Mark phase 4 completed
 
 **Return to User**:
 ```
-Test-fix workflow initiated for session: [sessionId]
+Independent test-fix workflow created successfully!
-- TEST-FIX-001 created and executing
+
-- @test-fix-agent validating implementation
+Source Session: [sourceSessionId]
-- Progress: /workflow:status [sessionId]
+Test Session: [testSessionId]
+Task Created: IMPL-001 (test-fix)
+
+Next Steps:
+1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
+2. Execute validation: /workflow:execute
+3. Monitor progress: /workflow:status
+
+The @test-fix-agent will:
+- Execute all tests
+- Diagnose any failures
+- Fix code until tests pass
 ```
 
 ---
@@ -150,72 +193,112 @@ Test-fix workflow initiated for session: [sessionId]
 ```javascript
 // Initialize (before Phase 1)
 TodoWrite({todos: [
-  {"content": "Execute context gathering for test-fix", "status": "in_progress", "activeForm": "Executing context gathering for test-fix"},
+  {"content": "Create independent test session", "status": "in_progress", "activeForm": "Creating test session"},
-  {"content": "Execute implementation analysis", "status": "pending", "activeForm": "Executing implementation analysis"},
+  {"content": "Gather cross-session context", "status": "pending", "activeForm": "Gathering cross-session context"},
-  {"content": "Execute TEST-FIX task generation", "status": "pending", "activeForm": "Executing TEST-FIX task generation"},
+  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
-  {"content": "Execute test-fix workflow", "status": "pending", "activeForm": "Executing test-fix workflow"}
+  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
 ]})
 
 // After Phase 1
 TodoWrite({todos: [
-  {"content": "Execute context gathering for test-fix", "status": "completed", "activeForm": "Executing context gathering for test-fix"},
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
-  {"content": "Execute implementation analysis", "status": "in_progress", "activeForm": "Executing implementation analysis"},
+  {"content": "Gather cross-session context", "status": "in_progress", "activeForm": "Gathering cross-session context"},
-  {"content": "Execute TEST-FIX task generation", "status": "pending", "activeForm": "Executing TEST-FIX task generation"},
+  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
-  {"content": "Execute test-fix workflow", "status": "pending", "activeForm": "Executing test-fix workflow"}
+  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
 ]})
 
-// Continue pattern for Phase 2, 3, 4...
+// After Phase 2
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
+  {"content": "Analyze implementation for test strategy", "status": "in_progress", "activeForm": "Analyzing implementation"},
+  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
+]})
+
+// After Phase 3
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
+  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
+  {"content": "Generate test validation task", "status": "in_progress", "activeForm": "Generating test validation task"}
+]})
+
+// After Phase 4
+TodoWrite({todos: [
+  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
+  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
+  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
+  {"content": "Generate test validation task", "status": "completed", "activeForm": "Generating test validation task"}
+]})
 ```
 
 ## Data Flow
 
 ```
-Session ID (from argument or auto-detect)
+User: /workflow:test-gen WFS-user-auth
     ↓
-Phase 1: context-gather --session sessionId "test-fix description"
+Phase 1: session-start --new "Test validation for WFS-user-auth"
-    ↓ Output: contextPath (context-package-test.json)
+    ↓ Creates: WFS-test-user-auth session
+    ↓ Writes: workflow-session.json with workflow_type="test_session", source_session_id="WFS-user-auth"
+    ↓ Output: testSessionId = "WFS-test-user-auth"
     ↓
-Phase 2: concept-enhanced --session sessionId --context contextPath
+Phase 2: context-gather --session WFS-test-user-auth
-    ↓ Input: sessionId + contextPath
+    ↓ Auto-detects: test session type from workflow-session.json
-    ↓ Output: ANALYSIS_RESULTS.md (test execution strategy)
+    ↓ Auto-reads: source_session_id = "WFS-user-auth"
+    ↓ Gathers: Cross-session context (summaries, code changes, tests)
+    ↓ Output: .workflow/WFS-test-user-auth/.process/context-package.json
     ↓
-Phase 3: task-generate --session sessionId
+Phase 3: concept-enhanced --session WFS-test-user-auth --context context-package.json
-    ↓ Input: sessionId + ANALYSIS_RESULTS.md
+    ↓ Reads: context-package.json with cross-session artifacts
-    ↓ Output: TEST-FIX-001.json, IMPL_PLAN.md, TODO_LIST.md
+    ↓ Executes: Parallel analysis (Gemini test strategy + optional Codex validation)
+    ↓ Analyzes: Test coverage, execution strategy, code targets
+    ↓ Output: .workflow/WFS-test-user-auth/.process/ANALYSIS_RESULTS.md
     ↓
-Phase 4: execute --session sessionId
+Phase 4: task-generate --session WFS-test-user-auth
-    ↓ Input: sessionId + TEST-FIX-001.json
+    ↓ Reads: ANALYSIS_RESULTS.md with test strategy and code targets
-    ↓ Output: Test execution and fixing
+    ↓ Generates: IMPL-001.json with meta.type="test-fix"
+    ↓ Output: Task, plan, and todo files in test session
     ↓
-Return summary to user
+Return: Summary with next steps (user triggers /workflow:execute separately)
 ```
 
-## Context Gathering Customization
+## Session Metadata Design
 
-context-gather will analyze:
+**Test Session (`WFS-test-user-auth/workflow-session.json`)**:
-- Completed IMPL task summaries
+```json
-- Git changes since session start
+{
-- Test files in focus_paths
+  "session_id": "WFS-test-user-auth",
-- Implementation files to be tested
+  "project": "Test validation for user authentication implementation",
-- Test framework configuration
+  "status": "planning",
+  "created_at": "2025-10-03T12:00:00Z",
+  "workflow_type": "test_session",
+  "source_session_id": "WFS-user-auth"
+}
+```
 
-## Analysis Focus
+## Automatic Cross-Session Context Collection
 
-concept-enhanced will analyze:
+When `context-gather` detects `workflow_type: "test_session"`:
-- Test coverage gaps
+
-- Test execution strategy (unit, integration, e2e)
+**Collected from Source Session** (`.workflow/WFS-user-auth/`):
-- Failure diagnosis approaches
+- Implementation summaries: `.summaries/IMPL-*-summary.md`
-- Code fixing patterns
+- Code changes: `git log --since=[source_created_at] --name-only`
-- Test framework best practices
+- Original plan: `IMPL_PLAN.md`
+- Task definitions: `.task/IMPL-*.json`
+
+**Collected from Current Project**:
+- Test files: `mcp__code-index__find_files(pattern="*.test.*")`
+- Test configuration: `package.json`, `jest.config.js`, etc.
+- Source files: Based on changed files from git log
 
 ## Task Generation Output
 
-task-generate creates TEST-FIX-001.json with:
+task-generate creates `IMPL-001.json` (reusing standard format) with:
 
 ```json
 {
-  "id": "TEST-FIX-001",
+  "id": "IMPL-001",
-  "title": "Execute and validate tests for [sessionId]",
+  "title": "Execute and validate tests for [sourceSessionId]",
   "status": "pending",
   "meta": {
     "type": "test-fix",
@@ -239,11 +322,11 @@ task-generate creates TEST-FIX-001.json with:
   "flow_control": {
     "pre_analysis": [
       {
-        "step": "load_implementation_summaries",
+        "step": "load_source_session_summaries",
-        "action": "Load completed IMPL task summaries",
+        "action": "Load implementation summaries from source session",
         "commands": [
-          "bash(find .workflow/[sessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
+          "bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
-          "Read(.workflow/[sessionId]/.summaries/IMPL-001-summary.md)"
+          "Read(.workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md)"
         ],
         "output_to": "implementation_context",
         "on_error": "skip_optional"
@@ -286,20 +369,22 @@ task-generate creates TEST-FIX-001.json with:
 ## Error Handling
 
 ### Phase 1 Failures
-- **No session found**: Return error "No active session detected. Provide session-id or run /workflow:plan first"
+- **Source session not found**: Return error "Source session [sourceSessionId] not found in .workflow/"
-- **Invalid session**: Return error "Session [sessionId] not found or incomplete"
+- **Invalid source session**: Return error "Source session [sourceSessionId] has no completed IMPL tasks"
-- **No implementation**: Return error "No completed IMPL tasks found. Complete implementation first"
+- **Session creation failed**: Return error "Could not create test session. Check /workflow:session:start"
 
 ### Phase 2 Failures
-- **Analysis failed**: Return error "Implementation analysis failed. Check context package"
+- **Context gathering failed**: Return error "Could not gather cross-session context. Check source session artifacts"
-- **No test strategy**: Return error "Could not determine test execution strategy"
+- **No source artifacts**: Return error "Source session has no implementation summaries or git history"
 
 ### Phase 3 Failures
-- **Task generation failed**: Retry once, then return error with details
+- **Analysis failed**: Return error "Implementation analysis failed. Check context package and ANALYSIS_RESULTS.md"
-- **Invalid task structure**: Return error with JSON validation details
+- **No test strategy**: Return error "Could not determine test execution strategy from analysis"
+- **Missing code targets**: Warning only, proceed with general test task
 
 ### Phase 4 Failures
-- **Execution failed**: Return error "Could not start test-fix workflow. Check session state"
+- **Task generation failed**: Retry once, then return error with details
+- **Invalid task structure**: Return error with JSON validation details
 
 ## Workflow Integration
 
@@ -307,18 +392,22 @@ task-generate creates TEST-FIX-001.json with:
 ```
 1. Implementation Phase (prior to test-gen)
    /workflow:plan "Build auth system"
+   → Creates WFS-auth session
    → @code-developer implements + writes tests
-   → Creates IMPL-001-summary.md
+   → Creates IMPL-001-summary.md in WFS-auth
 
 2. Test Generation Phase (test-gen)
    /workflow:test-gen WFS-auth
-   Phase 1: context-gather → Creates context-package-test.json
+   Phase 1: session-start → Creates WFS-test-auth session
-   Phase 2: concept-enhanced → Creates ANALYSIS_RESULTS.md
+   Phase 2: context-gather → Gathers from WFS-auth, creates context-package.json
-   Phase 3: task-generate → Creates TEST-FIX-001.json
+   Phase 3: concept-enhanced → Analyzes implementation, creates ANALYSIS_RESULTS.md
-   Phase 4: execute → Triggers @test-fix-agent
+   Phase 4: task-generate → Creates IMPL-001.json with meta.type="test-fix"
+   Returns: Summary with next steps
 
-3. Test-Fix Phase (automated)
+3. Test Execution Phase (user-triggered)
-   @test-fix-agent picks up TEST-FIX-001
+   /workflow:execute
+   → Detects active session: WFS-test-auth
+   → @test-fix-agent picks up IMPL-001 (test-fix type)
    → Runs test suite
    → Diagnoses failures (if any)
    → Fixes source code
@@ -327,39 +416,72 @@ task-generate creates TEST-FIX-001.json with:
 ```
 
 ### Output Files Created
-- `.workflow/[sessionId]/.process/context-package-test.json` - Test context package
+
-- `.workflow/[sessionId]/.process/ANALYSIS_RESULTS.md` - Test execution strategy
+**In Test Session** (`.workflow/WFS-test-auth/`):
-- `.workflow/[sessionId]/.task/TEST-FIX-001.json` - Task definition
+- `workflow-session.json` - Contains workflow_type and source_session_id
-- `.workflow/[sessionId]/IMPL_PLAN.md` - Updated with test-fix plan
+- `.process/context-package.json` - Cross-session context from WFS-auth
-- `.workflow/[sessionId]/TODO_LIST.md` - Updated with TEST-FIX task
+- `.process/ANALYSIS_RESULTS.md` - Test strategy and code targets from concept-enhanced
-- `.workflow/[sessionId]/.summaries/TEST-FIX-001-summary.md` - Created by test-fix-agent after completion
+- `.task/IMPL-001.json` - Test-fix task definition
+- `IMPL_PLAN.md` - Test validation plan (from ANALYSIS_RESULTS.md)
+- `TODO_LIST.md` - Task checklist
+- `.summaries/IMPL-001-summary.md` - Created by @test-fix-agent after completion
 
 ## Best Practices
 
-1. **Run after implementation complete**: Ensure all IMPL tasks are done before test-gen
+1. **Run after implementation complete**: Ensure source session has completed IMPL tasks and summaries
-2. **Check git commits**: Make sure implementation changes are committed
+2. **Check git commits**: Implementation changes should be committed for accurate git log analysis
-3. **Verify test files exist**: Code-developer should have created tests
+3. **Verify test files exist**: Source implementation should include test files
-4. **Monitor execution**: Use `/workflow:status` to track test-fix progress
+4. **Independent sessions**: Test session is separate from implementation session for clean separation
-5. **Review failures**: If tests fail repeatedly, check test-fix-agent summary for details
+5. **Monitor execution**: Use `/workflow:status` to track test-fix progress after /workflow:execute
 
 ## Coordinator Checklist
 
-✅ Initialize TodoWrite before any command
+✅ Initialize TodoWrite before any command (4 phases)
-✅ Execute Phase 1 immediately with session ID
+✅ Phase 1: Create test session with source session ID
-✅ Parse context package path from Phase 1 output
+✅ Parse new test session ID from Phase 1 output
-✅ Pass session ID and context path to Phase 2 command
+✅ Phase 2: Run context-gather (auto-detects test session, no extra params)
-✅ Verify ANALYSIS_RESULTS.md after Phase 2
+✅ Verify context-package.json contains cross-session artifacts
-✅ Pass session ID to Phase 3 command
+✅ Phase 3: Run concept-enhanced with session and context path
-✅ Verify all Phase 3 outputs (task JSON, IMPL_PLAN, TODO_LIST)
+✅ Verify ANALYSIS_RESULTS.md contains test strategy and code targets
-✅ Pass session ID to Phase 4 command
+✅ Phase 4: Run task-generate to create IMPL-001.json
+✅ Verify task has meta.type="test-fix" and meta.agent="@test-fix-agent"
+✅ Verify flow_control includes analysis insights and code targets
 ✅ Update TodoWrite after each phase
-✅ Return summary only after Phase 4 completes
+✅ Return summary after Phase 4 (execution is separate user action)
+
+## Required Tool Modifications
+
+### `/workflow:session:start`
+- Support `--new` flag for test session creation
+- Auto-detect test session pattern from task description
+- Write `workflow_type: "test_session"` and `source_session_id` to metadata
+
+### `/workflow:tools:context-gather`
+- Read session metadata to detect `workflow_type: "test_session"`
+- Auto-extract `source_session_id` from metadata
+- Gather cross-session context from source session artifacts
+- Include git log analysis from source session creation time
+
+### `/workflow:tools:concept-enhanced`
+- No changes required (already supports cross-session context analysis)
+- Will automatically analyze test strategy based on context-package.json
+- Generates ANALYSIS_RESULTS.md with code targets and test execution plan
+
+### `/workflow:tools:task-generate`
+- Recognize test session context and generate appropriate task
+- Create `IMPL-001.json` with `meta.type: "test-fix"`
+- Extract test strategy from ANALYSIS_RESULTS.md
+- Include code targets and cross-session references in flow_control
+
+### `/workflow:execute`
+- No changes required (already dispatches by meta.agent)
 
 ## Related Commands
 - `/workflow:plan` - Create implementation workflow (run before test-gen)
-- `/workflow:tools:context-gather` - Phase 1 tool for context collection
+- `/workflow:session:start` - Phase 1 tool for test session creation
-- `/workflow:tools:concept-enhanced` - Phase 2 tool for analysis
+- `/workflow:tools:context-gather` - Phase 2 tool for cross-session context collection
-- `/workflow:tools:task-generate` - Phase 3 tool for task creation
+- `/workflow:tools:concept-enhanced` - Phase 3 tool for implementation analysis and test strategy
-- `/workflow:execute` - Phase 4 workflow execution
+- `/workflow:tools:task-generate` - Phase 4 tool for test task creation
+- `/workflow:execute` - Execute test-fix workflow (user-triggered after test-gen)
 - `/workflow:status` - Check workflow progress
 - `@test-fix-agent` - Agent that executes and fixes tests

.claude/commands/workflow/tools/concept-enhanced.md

@@ -141,6 +141,9 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      RULES:
      - Focus on SOLUTION IMPROVEMENTS and KEY DESIGN DECISIONS, NOT task planning
      - Provide architectural rationale, evaluate alternatives, assess tradeoffs
+     - **CRITICAL**: Identify code targets - existing files as "file:function:lines", new files as "file"
+     - For modifications: specify exact files/functions/line ranges
+     - For new files: specify file path only (no function or lines)
      - Do NOT create task lists, implementation steps, or code examples
      - Do NOT generate any code snippets or implementation details
      - **MUST write output to .workflow/{session_id}/.process/gemini-solution-design.md**
@@ -172,6 +175,8 @@ Advanced solution design and feasibility analysis engine with parallel CLI execu
      RULES:
      - Focus on TECHNICAL FEASIBILITY and RISK ASSESSMENT, NOT implementation planning
      - Validate architectural decisions, identify potential issues, recommend optimizations
+     - **CRITICAL**: Verify code targets - existing files "file:function:lines", new files "file"
+     - Confirm exact locations for modifications, identify additional new files if needed
      - Do NOT create task breakdowns, step-by-step guides, or code examples
      - Do NOT generate any code snippets or implementation details
      - **MUST write output to .workflow/{session_id}/.process/codex-feasibility-validation.md**
@@ -301,6 +306,39 @@ Generated ANALYSIS_RESULTS.md focuses on **solution improvements, key design dec
 - **Module Dependencies**: {dependency_graph_and_order}
 - **Quality Assurance**: {qa_approach_and_validation}
 
+### Code Modification Targets
+**Purpose**: Specific code locations for modification AND new files to create
+
+**Format**:
+- Existing files: `file:function:lines` (with line numbers)
+- New files: `file` (no function or lines)
+
+**Identified Targets**:
+1. **Target**: `src/auth/AuthService.ts:login:45-52`
+   - **Type**: Modify existing
+   - **Modification**: Enhance error handling
+   - **Rationale**: Current logic lacks validation for edge cases
+
+2. **Target**: `src/auth/PasswordReset.ts`
+   - **Type**: Create new file
+   - **Purpose**: Password reset functionality
+   - **Rationale**: New feature requirement
+
+3. **Target**: `src/middleware/auth.ts:validateToken:30-45`
+   - **Type**: Modify existing
+   - **Modification**: Add token expiry check
+   - **Rationale**: Security requirement for JWT validation
+
+4. **Target**: `tests/auth/PasswordReset.test.ts`
+   - **Type**: Create new file
+   - **Purpose**: Test coverage for password reset
+   - **Rationale**: Test requirement for new feature
+
+**Note**:
+- For new files, only specify the file path (no function or lines)
+- For existing files without line numbers, use `file:function:*` format
+- Task generation will refine these during the `analyze_task_patterns` step
+
 ### Feasibility Assessment
 - **Technical Complexity**: {complexity_rating_and_analysis}
 - **Performance Impact**: {expected_performance_characteristics}

.claude/commands/workflow/tools/task-generate-agent.md

@@ -212,7 +212,7 @@ Task(
         "Validate against acceptance criteria"
       ]
     },
-    "target_files": ["file:function:lines"]
+    "target_files": ["file:function:lines", "path/to/NewFile.ts"]
   }
 }
 \`\`\`

.claude/commands/workflow/tools/task-generate.md

@@ -142,12 +142,12 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
       },
       {
         "step": "analyze_task_patterns",
-        "action": "Analyze existing code patterns",
+        "action": "Analyze existing code patterns and identify modification targets",
         "commands": [
           "bash(cd \"[focus_paths]\")",
-          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Analyze patterns TASK: Review '[title]' CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Pattern analysis RULES: Prioritize synthesis-specification.md\")"
+          "bash(~/.claude/scripts/gemini-wrapper -p \"PURPOSE: Identify modification targets TASK: Analyze '[title]' and locate specific files/functions/lines to modify CONTEXT: [synthesis_specification] [individual_artifacts] EXPECTED: Code locations in format 'file:function:lines' RULES: Prioritize synthesis-specification.md, identify exact modification points\")"
         ],
-        "output_to": "task_context",
+        "output_to": "task_context_with_targets",
         "on_error": "fail"
       }
     ],
@@ -175,8 +175,40 @@ Generate task JSON files and IMPL_PLAN.md from analysis results with automatic a
 1. Parse analysis results and extract task definitions
 2. Detect brainstorming artifacts with priority scoring
 3. Generate task context (requirements, focus_paths, acceptance)
-4. Build flow_control with artifact loading steps
+4. **Determine modification targets**: Extract specific code locations from analysis
-5. Create individual task JSON files in `.task/`
+5. Build flow_control with artifact loading steps and target_files
+6. Create individual task JSON files in `.task/`
+
+#### Target Files Generation (Critical)
+**Purpose**: Identify specific code locations for modification AND new files to create
+
+**Source Data Priority**:
+1. **ANALYSIS_RESULTS.md** - Should contain identified code locations
+2. **Gemini/MCP Analysis** - From `analyze_task_patterns` step
+3. **Context Package** - File references from `focus_paths`
+
+**Format**: `["file:function:lines"]` or `["file"]` (for new files)
+- `file`: Relative path from project root (e.g., `src/auth/AuthService.ts`)
+- `function`: Function/method name to modify (e.g., `login`, `validateToken`) - **omit for new files**
+- `lines`: Approximate line range (e.g., `45-52`, `120-135`) - **omit for new files**
+
+**Examples**:
+```json
+"target_files": [
+  "src/auth/AuthService.ts:login:45-52",
+  "src/middleware/auth.ts:validateToken:30-45",
+  "src/auth/PasswordReset.ts",
+  "tests/auth/PasswordReset.test.ts",
+  "tests/auth.test.ts:testLogin:15-20"
+]
+```
+
+**Generation Strategy**:
+- **New files to create** → Use `["path/to/NewFile.ts"]` (no function or lines)
+- **Existing files with specific locations** → Use `["file:function:lines"]`
+- **Existing files with function only** → Search lines using MCP/grep `["file:function:*"]`
+- **Existing files (explore entire)** → Mark as `["file.ts:*:*"]`
+- **No specific targets** → Leave empty `[]` (agent explores focus_paths)
 
 ### Phase 3: Artifact Detection & Integration
 

.claude/workflows/context-search-strategy.md

@@ -6,6 +6,12 @@ type: search-guideline
 
 # Context Search Strategy
 
+## ⚡ Execution Environment
+
+**CRITICAL**: All commands execute in **Bash environment** (Git Bash on Windows, Bash on Linux/macOS)
+
+**❌ Forbidden**: Windows-specific commands (`findstr`, `dir`, `where`, `type`, `copy`, `del`) - Use Bash equivalents (`grep`, `find`, `which`, `cat`, `cp`, `rm`)
+
 ## ⚡ Core Search Tools
 
 **rg (ripgrep)**: Fast content search with regex support
@@ -18,6 +24,7 @@ type: search-guideline
 - **Use find for files** - Locate files/directories by name
 - **Use grep sparingly** - Only when rg unavailable
 - **Use get_modules_by_depth.sh first** - MANDATORY for program architecture analysis before planning
+- **Always use Bash commands** - NEVER use Windows cmd/PowerShell commands
 
 ### Quick Command Reference
 ```bash

.claude/workflows/task-core.md

@@ -49,7 +49,8 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
     },
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken"
+      "src/middleware/auth.ts:validateToken",
+      "src/auth/PasswordReset.ts"
     ]
   }
 }
@@ -81,7 +82,7 @@ All task files use this simplified 5-field schema (aligned with workflow-archite
 **Components**:
 - **pre_analysis**: Array of sequential process steps
 - **implementation_approach**: Task execution strategy
-- **target_files**: Specific files to modify in "file:function:lines" format
+- **target_files**: Files to modify/create - existing files in `file:function:lines` format, new files as `file` only
 
 **Step Structure**:
 ```json

.claude/workflows/workflow-architecture.md

@@ -175,7 +175,8 @@ All task files use this unified 5-field schema with optional artifacts enhanceme
     },
     "target_files": [
       "src/auth/login.ts:handleLogin:75-120",
-      "src/middleware/auth.ts:validateToken"
+      "src/middleware/auth.ts:validateToken",
+      "src/auth/PasswordReset.ts"
     ]
   }
 }
@@ -219,7 +220,7 @@ The **flow_control** field manages task execution with two main components:
 - **task_description**: Comprehensive implementation description
 - **modification_points**: Specific code modification targets
 - **logic_flow**: Business logic execution sequence
-- **target_files**: Target file list in `file:function:lines` format
+- **target_files**: Target file list - existing files in `file:function:lines` format, new files as `file` only
 
 #### Tool Reference
 **Command Types Available**:

README.md

@@ -233,6 +233,41 @@ After installation, run the following command to ensure CCW is working:
 
 ## ⚙️ Configuration
 
+### **Prerequisites: Required Tools**
+
+Before using CCW, install the following command-line tools:
+
+#### **Core CLI Tools**
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| **Gemini CLI** | AI analysis & documentation | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
+| **Codex CLI** | AI development & implementation | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
+| **Qwen Code** | AI architecture & code generation | `npm install -g @qwen-code/qwen-code` ([Docs](https://github.com/QwenLM/qwen-code)) |
+
+#### **System Utilities**
+
+| Tool | Purpose | Installation |
+|------|---------|--------------|
+| **ripgrep (rg)** | Fast code search | [Download](https://github.com/BurntSushi/ripgrep/releases) or `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
+| **jq** | JSON processing | [Download](https://jqlang.github.io/jq/download/) or `brew install jq` (macOS), `apt install jq` (Ubuntu) |
+
+**Quick Install (All Tools):**
+
+```bash
+# macOS
+brew install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Ubuntu/Debian
+sudo apt install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Windows (Chocolatey)
+choco install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+```
+
 ### **Essential: Gemini CLI Setup**
 
 Configure Gemini CLI for optimal integration:

README_CN.md

@@ -236,6 +236,41 @@ bash <(curl -fsSL https://raw.githubusercontent.com/catlog22/Claude-Code-Workflo
 
 ## ⚙️ 配置
 
+### **前置要求：必需工具**
+
+在使用 CCW 之前，请安装以下命令行工具：
+
+#### **核心 CLI 工具**
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| **Gemini CLI** | AI 分析与文档生成 | `npm install -g @google/gemini-cli` ([GitHub](https://github.com/google-gemini/gemini-cli)) |
+| **Codex CLI** | AI 开发与实现 | `npm install -g @openai/codex` ([GitHub](https://github.com/openai/codex)) |
+| **Qwen Code** | AI 架构与代码生成 | `npm install -g @qwen-code/qwen-code` ([文档](https://github.com/QwenLM/qwen-code)) |
+
+#### **系统实用工具**
+
+| 工具 | 用途 | 安装方式 |
+|------|------|----------|
+| **ripgrep (rg)** | 快速代码搜索 | [下载](https://github.com/BurntSushi/ripgrep/releases) 或 `brew install ripgrep` (macOS), `apt install ripgrep` (Ubuntu) |
+| **jq** | JSON 处理 | [下载](https://jqlang.github.io/jq/download/) 或 `brew install jq` (macOS), `apt install jq` (Ubuntu) |
+
+**快速安装（所有工具）：**
+
+```bash
+# macOS
+brew install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Ubuntu/Debian
+sudo apt install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+
+# Windows (Chocolatey)
+choco install ripgrep jq
+npm install -g @google/gemini-cli @openai/codex @qwen-code/qwen-code
+```
+
 ### **必需: Gemini CLI 设置**
 
 配置 Gemini CLI 以实现最佳集成：