diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md index bcfe64f9..882cd512 100644 --- a/.claude/agents/action-planning-agent.md +++ b/.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:** diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md index 3080d67a..6c578f67 100644 --- a/.claude/agents/code-developer.md +++ b/.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) diff --git a/.claude/agents/code-review-test-agent.md b/.claude/agents/code-review-test-agent.md index f993819e..17c8d47f 100644 --- a/.claude/agents/code-review-test-agent.md +++ b/.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 diff --git a/.claude/agents/conceptual-planning-agent.md b/.claude/agents/conceptual-planning-agent.md index e350a69b..f2306eda 100644 --- a/.claude/agents/conceptual-planning-agent.md +++ b/.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 diff --git a/.claude/commands/workflow/execute.md b/.claude/commands/workflow/execute.md index 4ffdb85d..bcd1deee 100644 --- a/.claude/commands/workflow/execute.md +++ b/.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 diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md index 85fc4572..0951b6d4 100644 --- a/.claude/commands/workflow/plan.md +++ b/.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) diff --git a/.claude/scripts/read-task-paths.sh b/.claude/scripts/read-task-paths.sh new file mode 100644 index 00000000..ac091743 --- /dev/null +++ b/.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 "}" \ No newline at end of file diff --git a/.claude/workflows/workflow-architecture.md b/.claude/workflows/workflow-architecture.md index ec46f671..d4cfb8a6 100644 --- a/.claude/workflows/workflow-architecture.md +++ b/.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: diff --git a/README.md b/README.md index 3f197990..7e8adced 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,7 @@ Claude Code Workflow (CCW) is built on three core architectural principles: ### **JSON-First Data Model** - **Single Source of Truth**: All workflow states and task definitions stored in structured `.task/impl-*.json` files +- **Task-Specific Paths**: New `paths` field enables precise CLI analysis targeting concrete project paths - **Generated Views**: Markdown documents created on-demand from JSON data sources - **Data Consistency**: Eliminates synchronization issues through centralized data management - **Performance**: Direct JSON operations with sub-millisecond query response times @@ -47,6 +48,7 @@ CCW automatically adjusts workflow structure based on project complexity: ### Dual CLI Integration - **Gemini CLI**: Deep codebase analysis, pattern recognition, and investigation workflows - **Codex CLI**: Autonomous development, code generation, and implementation automation +- **Task-Specific Targeting**: Precise path management for focused analysis (replaces `--all-files`) - **Template System**: Unified template library for consistent workflow execution - **Cross-Platform Support**: Windows and Linux compatibility with unified path handling @@ -238,6 +240,8 @@ cd src/api && /update-memory-related ├── planning-templates/ # Role-specific planning approaches ├── prompt-templates/ # AI interaction templates ├── scripts/ # Automation and utility scripts +│ ├── read-task-paths.sh # Convert task JSON paths to @ format +│ └── get_modules_by_depth.sh # Project structure analysis ├── tech-stack-templates/ # Technology-specific configurations ├── workflows/ # Core workflow documentation │ ├── system-architecture.md # Architecture specifications diff --git a/README_CN.md b/README_CN.md index b6d1e8fb..09c51b1b 100644 --- a/README_CN.md +++ b/README_CN.md @@ -16,6 +16,7 @@ Claude Code Workflow (CCW) 建立在三个核心架构原则之上: ### **JSON优先数据模型** - **单一数据源**: 所有工作流状态和任务定义存储在结构化的 `.task/impl-*.json` 文件中 +- **任务特定路径**: 新增 `paths` 字段实现针对具体项目路径的精准CLI分析 - **生成视图**: 从JSON数据源按需创建Markdown文档 - **数据一致性**: 通过集中式数据管理消除同步问题 - **性能**: 直接JSON操作,亚毫秒级查询响应时间 @@ -47,6 +48,7 @@ CCW根据项目复杂度自动调整工作流结构: ### 双CLI集成 - **Gemini CLI**: 深度代码库分析,模式识别和调查工作流 - **Codex CLI**: 自主开发,代码生成和实现自动化 +- **任务特定定位**: 精准路径管理实现聚焦分析(替代 `--all-files`) - **模板系统**: 统一模板库确保一致的工作流执行 - **跨平台支持**: Windows和Linux兼容性,统一路径处理