feat: Add task-specific path management system for precise CLI analysis

- Add 'paths' field to task JSON schema with semicolon-separated concrete paths
- Create read-task-paths.sh script to convert paths to Gemini @ format
- Update all agents to use task-specific paths instead of --all-files
- Integrate get_modules_by_depth.sh for project structure discovery
- Update workflow planning to populate paths field automatically
- Enhance execute command to pass task-specific paths to agents
- Update documentation for new path management system

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

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

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

@@ -42,8 +42,9 @@ You are a pure execution agent specialized in creating actionable implementation
 ```
 
 **Analysis CLI Usage Standards**:
-- **Gemini CLI**: Follow unified guidelines: `@~/.claude/workflows/gemini-unified.md`
-- **Codex CLI**: Follow unified guidelines: `@~/.claude/workflows/codex-unified.md`
+- **Gemini CLI**: Use task-specific paths: `gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md}" `
+- **Codex CLI**: Use task-specific paths: `codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]"`
+- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md
 
 ### Deep Analysis Execution
 **When DEEP_ANALYSIS_REQUIRED flag is present:**

.claude/agents/code-developer.md

@@ -56,8 +56,10 @@ ELIF context insufficient OR task has analysis marker:
   - **Purpose**: Enables autonomous development with intelligent file discovery and code generation
 
 **Analysis CLI Usage Standards**:
-- **Gemini CLI**: Follow unified guidelines: @~/.claude/workflows/gemini-unified.md
-- **Codex CLI**: Follow unified guidelines: @~/.claude/workflows/codex-unified.md
+- **Gemini CLI**: Use task-specific paths from JSON: `gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]" `
+- **Codex CLI**: Use task-specific paths from JSON: `codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [prompt]"`
+- **Follow Guidelines**: @~/.claude/workflows/gemini-unified.md and @~/.claude/workflows/codex-unified.md
+
 
 **Test-Driven Development**:
 - Write tests first (red → green → refactor)

.claude/agents/code-review-test-agent.md

@@ -76,6 +76,11 @@ When [GEMINI_CLI_REQUIRED] flag is present or complexity triggers apply, gather
 Use the targeted review context template:
 @~/.claude/workflows/gemini-unified.md
 
+**Gemini CLI Command**:
+```bash
+gemini -p "$(.claude/scripts/read-task-paths.sh [task-json-file]) @{CLAUDE.md} [review-analysis-prompt]"
+```
+
 This executes a change-specific Gemini CLI command that identifies:
 - **Change understanding**: What specific task was being implemented
 - **Repository conventions**: Standards used in similar files and functions
@@ -89,6 +94,11 @@ When [CODEX_CLI_REQUIRED] flag is present, execute autonomous analysis:
 Use the autonomous development context template:
 @~/.claude/workflows/codex-unified.md
 
+**Codex CLI Command**:
+```bash
+codex --full-auto exec "$(.claude/scripts/read-task-paths.sh [task-json-file]) [autonomous-review-prompt]"
+```
+
 This executes autonomous Codex CLI analysis that provides:
 - **Autonomous understanding**: Intelligent discovery of implementation context
 - **Code generation insights**: Autonomous development recommendations

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

@@ -53,6 +53,7 @@ def handle_analysis_markers(prompt):
     if "[GEMINI_CLI_REQUIRED]" in prompt:
         for dimension in dimensions:
             result = execute_gemini_cli(
+                command=f"gemini -p \"$(.claude/scripts/read-task-paths.sh [task-json-file]) @{{CLAUDE.md}} {dimension}\"",
                 dimension=dimension,
                 role_context=role,
                 topic=topic
@@ -61,6 +62,7 @@ def handle_analysis_markers(prompt):
     
     elif "[CODEX_CLI_REQUIRED]" in prompt:
         result = execute_codex_cli(
+            command=f"codex --full-auto exec \"$(.claude/scripts/read-task-paths.sh [task-json-file]) {topic}\"",
             autonomous_analysis=True,
             role_context=role, 
             topic=topic

.claude/commands/workflow/execute.md

@@ -168,6 +168,9 @@ Task(subagent_type="code-developer",
      - Risks: Schema changes require database migration, Existing user data compatibility
      - Performance: Index JWT fields for faster lookups
      
+     Focus Paths (from task JSON): $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
+     Gemini Command: gemini -p "$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}"
+     
      IMPORTANT: Update TODO_LIST.md and create summary in provided directories upon completion.
      Use implementation details above for precise, targeted development.",
      description="Execute impl-1.2 with full workflow context and implementation details")
@@ -237,10 +240,14 @@ Task(subagent_type="code-developer",
      - Workflow Directory: .workflow/WFS-user-auth/
      - TODO_LIST Location: .workflow/WFS-user-auth/TODO_LIST.md
      - Summaries Directory: .workflow/WFS-user-auth/.summaries/
+     - Task JSON: .workflow/WFS-user-auth/.task/impl-1.2.json
      
-     CRITICAL: Update TODO_LIST.md and create completion summary using provided paths.",
+     Focus Paths: $(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json)
+     Analysis Command: Use gemini -p \"$(.claude/scripts/read-task-paths.sh .workflow/WFS-user-auth/.task/impl-1.2.json) @{CLAUDE.md}\"
      
-     description="Agent executes with full discovered context")
+     CRITICAL: Use task-specific paths for focused analysis. Update TODO_LIST.md and create completion summary using provided paths.",
+     
+     description="Agent executes with task-specific paths and full discovered context")
 ```
 
 ### Status Tracking Integration

.claude/commands/workflow/plan.md

@@ -91,6 +91,7 @@ The command automatically detects input type:
 - Automatically creates .task/ files when complexity warrants
 - Generates hierarchical task structure (max 3 levels)
 - Updates session state with task references
+- Runs project structure analysis to populate paths field
 
 ### Implementation Field Requirements
 ⚠️ **CRITICAL**: All generated tasks must include detailed implementation guidance
@@ -132,6 +133,31 @@ The command automatically detects input type:
 - **context_notes**: Dependencies, risks, performance considerations
 - **analysis_source**: manual|gemini|codex|auto-detected
 
+**Paths Field Population Process**:
+1. **Project Structure Analysis**: Run `get_modules_by_depth.sh` to discover project structure
+2. **Relevance Filtering**: Match discovered modules to task requirements
+3. **Path Selection**: Choose concrete directories/files (avoid wildcards)
+4. **Format**: Semicolon-separated list (e.g., `"src/auth;tests/auth;config/auth.json"`)
+
+**Path Selection Strategy**:
+```pseudo
+# Step 1: Analyze project structure
+modules = Bash(.claude/scripts/get_modules_by_depth.sh list)
+
+# Step 2: Extract relevant modules based on task scope
+relevant_paths = []
+for module in modules:
+    if matches_task_scope(module.path, task_requirements):
+        relevant_paths.append(module.path)
+
+# Step 3: Add specific files mentioned in requirements
+specific_files = extract_file_mentions(task_requirements)
+relevant_paths.extend(specific_files)
+
+# Step 4: Format as semicolon-separated string
+task.paths = join(relevant_paths, ";")
+```
+
 **Quality Standards**:
 - logic_flow must use specified symbols (───►, ◊───, ◄───)
 - Each file must have specific location (function name or line range)

.claude/scripts/read-task-paths.sh

@@ -0,0 +1,56 @@
+#!/bin/bash
+# Read paths field from task JSON and convert to Gemini @ format
+# Usage: read-task-paths.sh [task-json-file]
+
+TASK_FILE="$1"
+
+if [ -z "$TASK_FILE" ]; then
+    echo "Usage: read-task-paths.sh [task-json-file]" >&2
+    exit 1
+fi
+
+if [ ! -f "$TASK_FILE" ]; then
+    echo "Error: Task file '$TASK_FILE' not found" >&2
+    exit 1
+fi
+
+# Extract paths field from JSON
+paths=$(grep -o '"paths":[[:space:]]*"[^"]*"' "$TASK_FILE" | sed 's/"paths":[[:space:]]*"\([^"]*\)"/\1/')
+
+if [ -z "$paths" ]; then
+    # No paths field found, return empty @ format
+    echo "@{}"
+    exit 0
+fi
+
+# Convert semicolon-separated paths to comma-separated @ format
+formatted_paths=$(echo "$paths" | sed 's/;/,/g')
+
+# For directories, append /**/* to get all files
+# For files (containing .), keep as-is
+IFS=',' read -ra path_array <<< "$formatted_paths"
+result_paths=()
+
+for path in "${path_array[@]}"; do
+    # Trim whitespace
+    path=$(echo "$path" | xargs)
+    
+    if [ -n "$path" ]; then
+        # Check if path is a directory (no extension) or file (has extension)
+        if [[ "$path" == *.* ]]; then
+            # File path - keep as is
+            result_paths+=("$path")
+        else
+            # Directory path - add wildcard expansion
+            result_paths+=("$path/**/*")
+        fi
+    fi
+done
+
+# Output Gemini @ format
+printf "@{"
+printf "%s" "${result_paths[0]}"
+for i in "${result_paths[@]:1}"; do
+    printf ",%s" "$i"
+done
+printf "}"

.claude/workflows/workflow-architecture.md

@@ -75,7 +75,7 @@ Each session directory contains `workflow-session.json`:
 - **Performance**: Direct JSON access without parsing overhead
 
 ### Task JSON Schema
-All task files use this 9-field schema:
+All task files use this 10-field schema:
 
 ```json
 {
@@ -84,6 +84,7 @@ All task files use this 9-field schema:
   "status": "pending|active|completed|blocked|container",
   "type": "feature|bugfix|refactor|test|docs", 
   "agent": "code-developer|planning-agent|code-review-test-agent",
+  "paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts",
   
   "context": {
     "requirements": ["JWT authentication", "OAuth2 support"],
@@ -147,6 +148,34 @@ All task files use this 9-field schema:
 }
 ```
 
+### Paths Field Details
+
+The **paths** field specifies concrete project paths (folders and files) relevant to the task implementation:
+
+#### Path Format
+- **Semicolon-separated list**: `"folder1;folder2;specific_file.ts"`
+- **Concrete paths**: Use actual directory/file names without wildcards
+- **Mixed types**: Can include both directories and specific files
+- **Relative paths**: From project root (e.g., `src/auth`, not `./src/auth`)
+
+#### Path Selection Strategy
+- **Directories**: Include relevant module directories (e.g., `src/auth`, `tests/auth`)
+- **Specific files**: Include files explicitly mentioned in requirements (e.g., `config/auth.json`)
+- **Avoid wildcards**: Use concrete paths discovered via `get_modules_by_depth.sh`
+- **Focus scope**: Only include paths directly related to task implementation
+
+#### Examples
+```json
+// Authentication system task
+"paths": "src/auth;tests/auth;config/auth.json;src/middleware/auth.ts"
+
+// UI component task
+"paths": "src/components/Button;src/styles;tests/components"
+
+// Database migration task  
+"paths": "migrations;src/models;config/database.json"
+```
+
 ### Implementation Field Details
 
 The **implementation** field provides detailed code implementation guidance with 4 core components: