Refactor execution modes and CLI integration across agents

- Updated code-developer, tdd-developer, and test-fix-agent to streamline execution modes based on task.meta.execution_config.method. - Removed legacy command handling and introduced CLI handoff for 'cli' execution method. - Enhanced buildCliHandoffPrompt to include task JSON path and improved context handling. - Updated task-generate-agent and task-generate-tdd to reflect new execution method mappings and removed command field from implementation_approach. - Improved CLI settings validation in CliSettingsModal with format and length checks. - Added localization for new CLI settings messages in English and Chinese. - Enhanced GPU selector to use localized strings for GPU types. - Introduced TypeScript LSP setup documentation for better user guidance.
2026-02-11 02:33:51 +08:00 · 2026-02-02 19:21:30 +08:00
parent 2305e7b8e7
commit 545679eeb9
18 changed files with 192 additions and 405 deletions
--- a/.claude/agents/action-planning-agent.md
+++ b/.claude/agents/action-planning-agent.md
@@ -288,8 +288,8 @@ function computeCliStrategy(task, allTasks) {
    "execution_group": "parallel-abc123|null",
    "module": "frontend|backend|shared|null",
    "execution_config": {
-      "method": "agent|hybrid|cli",
-      "cli_tool": "codex|gemini|qwen|auto",
+      "method": "agent|cli",
+      "cli_tool": "codex|gemini|qwen|auto|null",
      "enable_resume": true,
      "previous_cli_id": "string|null"
    }
@@ -303,7 +303,7 @@ function computeCliStrategy(task, allTasks) {
 - `execution_group`: Parallelization group ID (tasks with same ID can run concurrently) or `null` for sequential tasks
 - `module`: Module identifier for multi-module projects (e.g., `frontend`, `backend`, `shared`) or `null` for single-module
 - `execution_config`: CLI execution settings (MUST align with userConfig from task-generate-agent)
-  - `method`: Execution method - `agent` (direct), `hybrid` (agent + CLI), `cli` (CLI only)
+  - `method`: Execution method - `agent` (direct) or `cli` (CLI only). Only two values in final task JSON.
  - `cli_tool`: Preferred CLI tool - `codex`, `gemini`, `qwen`, `auto`, or `null` (for agent-only)
  - `enable_resume`: Whether to use `--resume` for CLI continuity (default: true)
  - `previous_cli_id`: Previous task's CLI execution ID for resume (populated at runtime)
@@ -318,14 +318,16 @@ userConfig.executionMethod → meta.execution_config

 "cli" →
  meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
-  Execution: Agent executes pre_analysis, then hands off context + implementation_approach to CLI
+  Execution: Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()

 "hybrid" →
-  meta.execution_config = { method: "hybrid", cli_tool: userConfig.preferredCliTool, enable_resume: true }
-  Execution: Agent decides which tasks to handoff to CLI based on complexity
+  Per-task decision: set method to "agent" OR "cli" per task based on complexity
+  - Simple tasks (≤3 files, straightforward logic) → { method: "agent", cli_tool: null, enable_resume: false }
+  - Complex tasks (>3 files, complex logic, refactoring) → { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
+  Final task JSON always has method = "agent" or "cli", never "hybrid"
 ```

-**Note**: implementation_approach steps NO LONGER contain `command` fields. CLI execution is controlled by task-level `meta.execution_config` only.
+**IMPORTANT**: implementation_approach steps do NOT contain `command` fields. Execution routing is controlled by task-level `meta.execution_config.method` only.

 **Test Task Extensions** (for type="test-gen" or type="test-fix"):

@@ -344,7 +346,7 @@ userConfig.executionMethod → meta.execution_config
 - `test_framework`: Existing test framework from project (required for test tasks)
 - `coverage_target`: Target code coverage percentage (optional)

-**Note**: CLI tool usage for test-fix tasks is now controlled via `flow_control.implementation_approach` steps with `command` fields, not via `meta.use_codex`.
+**Note**: CLI tool usage for test-fix tasks is now controlled via task-level `meta.execution_config.method`, not via `meta.use_codex`.

 #### Context Object

@@ -555,59 +557,45 @@ The examples above demonstrate **patterns**, not fixed requirements. Agent MUST:

 ##### Implementation Approach

-**Execution Modes**:
+**Execution Control**:

-The `implementation_approach` supports **two execution modes** based on the presence of the `command` field:
+The `implementation_approach` defines sequential implementation steps. Execution routing is controlled by **task-level `meta.execution_config.method`**, NOT by step-level `command` fields.

-1. **Default Mode (Agent Execution)** - `command` field **omitted**:
+**Two Execution Modes**:
+
+1. **Agent Mode** (`meta.execution_config.method = "agent"`):
   - Agent interprets `modification_points` and `logic_flow` autonomously
   - Direct agent execution with full context awareness
   - No external tool overhead
   - **Use for**: Standard implementation tasks where agent capability is sufficient
-   - **Required fields**: `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, `output`

-2. **CLI Mode (Command Execution)** - `command` field **included**:
-   - Specified command executes the step directly
-   - Leverages specialized CLI tools (codex/gemini/qwen) for complex reasoning
-   - **Use for**: Large-scale features, complex refactoring, or when user explicitly requests CLI tool usage
-   - **Required fields**: Same as default mode **PLUS** `command`, `resume_from` (optional)
-   - **Command patterns** (with resume support):
-     - `ccw cli -p '[prompt]' --tool codex --mode write --cd [path]`
-     - `ccw cli -p '[prompt]' --resume ${previousCliId} --tool codex --mode write` (resume from previous)
-     - `ccw cli -p '[prompt]' --tool gemini --mode write --cd [path]` (write mode)
-   - **Resume mechanism**: When step depends on previous CLI execution, include `--resume` with previous execution ID
+2. **CLI Mode** (`meta.execution_config.method = "cli"`):
+   - Agent executes `pre_analysis`, then hands off full context to CLI via `buildCliHandoffPrompt()`
+   - CLI tool specified in `meta.execution_config.cli_tool` (codex/gemini/qwen)
+   - Leverages specialized CLI tools for complex reasoning
+   - **Use for**: Large-scale features, complex refactoring, or when userConfig.executionMethod = "cli"

-**Semantic CLI Tool Selection**:
+**Step Schema** (same for both modes):
+```json
+{
+  "step": 1,
+  "title": "Step title",
+  "description": "What to implement (may use [variable] placeholders from pre_analysis)",
+  "modification_points": ["Quantified changes: [list with counts]"],
+  "logic_flow": ["Implementation sequence"],
+  "depends_on": [0],
+  "output": "variable_name"
+}
+```

-Agent determines CLI tool usage per-step based on user semantics and task nature.
+**Required fields**: `step`, `title`, `description`, `modification_points`, `logic_flow`, `depends_on`, `output`

-**Source**: Scan `metadata.task_description` from context-package.json for CLI tool preferences.
+**IMPORTANT**: Do NOT add `command` field to implementation_approach steps. Execution routing is determined by task-level `meta.execution_config.method` only.

-**User Semantic Triggers** (patterns to detect in task_description):
- "use Codex/codex" → Add `command` field with Codex CLI
- "use Gemini/gemini" → Add `command` field with Gemini CLI
- "use Qwen/qwen" → Add `command` field with Qwen CLI
- "CLI execution" / "automated" → Infer appropriate CLI tool
-
-**Task-Based Selection** (when no explicit user preference):
- **Implementation/coding**: Codex preferred for autonomous development
- **Analysis/exploration**: Gemini preferred for large context analysis
- **Documentation**: Gemini/Qwen with write mode (`--mode write`)
- **Testing**: Depends on complexity - simple=agent, complex=Codex
-
-**Default Behavior**: Agent always executes the workflow. CLI commands are embedded in `implementation_approach` steps:
- Agent orchestrates task execution
- When step has `command` field, agent executes it via CCW CLI
- When step has no `command` field, agent implements directly
- This maintains agent control while leveraging CLI tool power
-
-**Key Principle**: The `command` field is **optional**. Agent decides based on user semantics and task complexity.
-
-**Examples**:
+**Example**:

 ```json
 [
-  // === DEFAULT MODE: Agent Execution (no command field) ===
  {
    "step": 1,
    "title": "Load and analyze role analyses",
@@ -644,8 +632,7 @@ Agent determines CLI tool usage per-step based on user semantics and task nature
    ],
    "depends_on": [1],
    "output": "implementation"
-  },
-
+  }
 ]
 ```

--- a/.claude/agents/code-developer.md
+++ b/.claude/agents/code-developer.md
@@ -202,33 +202,17 @@ for (const step of task.flow_control.pre_analysis || []) {
  preAnalysisResults[step.output_to] = result;
 }

-// Phase 2: Determine execution mode
-const hasLegacyCommands = task.flow_control.implementation_approach
-  .some(step => step.command);
+// Phase 2: Determine execution mode (based on task.meta.execution_config.method)
+// Two modes: 'cli' (call CLI tool) or 'agent' (execute directly)

-IF hasLegacyCommands:
-  // Backward compatibility: Old mode with step.command fields
-  FOR each step in implementation_approach[]:
-    IF step.command exists:
-      → Execute via Bash: Bash({ command: step.command, timeout: 3600000 })
-    ELSE:
-      → Agent direct implementation
-
-ELSE IF executionMethod === 'cli':
-  // New mode: CLI Handoff
-  → const cliPrompt = buildCliHandoffPrompt(preAnalysisResults, task)
+IF executionMethod === 'cli':
+  // CLI Handoff: Full context passed to CLI via buildCliHandoffPrompt
+  → const cliPrompt = buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)
  → const cliCommand = buildCliCommand(task, cliTool, cliPrompt)
  → Bash({ command: cliCommand, run_in_background: false, timeout: 3600000 })

-ELSE IF executionMethod === 'hybrid':
-  // Hybrid mode: Agent decides based on task complexity
-  → IF task is complex (multiple files, complex logic):
-      Use CLI Handoff (same as cli mode)
-    ELSE:
-      Use Agent direct implementation
-
 ELSE (executionMethod === 'agent'):
-  // Default: Agent direct implementation
+  // Execute implementation steps directly
  FOR each step in implementation_approach[]:
    1. Variable Substitution: Replace [variable_name] with preAnalysisResults
    2. Read modification_points[] as files to create/modify
@@ -253,26 +237,23 @@ function getDefaultCliTool() {
 }

 // Build CLI prompt from pre-analysis results and task
-function buildCliHandoffPrompt(preAnalysisResults, task) {
+function buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath) {
  const contextSection = Object.entries(preAnalysisResults)
    .map(([key, value]) => `### ${key}\n${value}`)
    .join('\n\n');

-  const approachSection = task.flow_control.implementation_approach
-    .map((step, i) => `
-### Step ${step.step}: ${step.title}
-${step.description}
-
-**Modification Points**:
-${step.modification_points?.map(m => `- ${m}`).join('\n') || 'N/A'}
-
-**Logic Flow**:
-${step.logic_flow?.map((l, j) => `${j + 1}. ${l}`).join('\n') || 'Follow modification points'}
-`).join('\n');
+  const conventions = task.context.shared_context?.conventions?.join(' | ') || '';
+  const constraints = `Follow existing patterns | No breaking changes${conventions ? ' | ' + conventions : ''}`;

  return `
 PURPOSE: ${task.title}
-Complete implementation based on pre-analyzed context.
+Complete implementation based on pre-analyzed context and task JSON.
+
+## TASK JSON
+Read full task definition: ${taskJsonPath}
+
+## TECH STACK
+${task.context.shared_context?.tech_stack?.map(t => `- ${t}`).join('\n') || 'Auto-detect from project files'}

 ## PRE-ANALYSIS CONTEXT
 ${contextSection}
@@ -280,17 +261,17 @@ ${contextSection}
 ## REQUIREMENTS
 ${task.context.requirements?.map(r => `- ${r}`).join('\n') || task.context.requirements}

-## IMPLEMENTATION APPROACH
-${approachSection}
-
 ## ACCEPTANCE CRITERIA
 ${task.context.acceptance?.map(a => `- ${a}`).join('\n') || task.context.acceptance}

 ## TARGET FILES
-${task.flow_control.target_files?.map(f => `- ${f}`).join('\n') || 'See modification points above'}
+${task.flow_control.target_files?.map(f => `- ${f}`).join('\n') || 'See task JSON modification_points'}
+
+## FOCUS PATHS
+${task.context.focus_paths?.map(p => `- ${p}`).join('\n') || 'See task JSON'}

 MODE: write
-CONSTRAINTS: Follow existing patterns | No breaking changes
+CONSTRAINTS: ${constraints}
 `.trim();
 }

@@ -319,7 +300,7 @@ function buildCliCommand(task, cliTool, cliPrompt) {
 **Execution Config Reference** (from task.meta.execution_config):
 | Field | Values | Description |
 |-------|--------|-------------|
-| `method` | `agent` / `cli` / `hybrid` | Execution mode (default: agent) |
+| `method` | `agent` / `cli` | Execution mode (default: agent) |
 | `cli_tool` | See `~/.claude/cli-tools.json` | CLI tool preference (first enabled tool as default) |
 | `enable_resume` | `true` / `false` | Enable CLI session resume |

--- a/.claude/agents/tdd-developer.md
+++ b/.claude/agents/tdd-developer.md
@@ -154,11 +154,15 @@ STEP 1: Parse Red Phase Requirements
  → Load existing test patterns from focus_paths

 STEP 2: Execute Red Phase Implementation
-  IF step.command exists:
-    → Execute CLI command with session resume
-    → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
+  const executionMethod = task.meta?.execution_config?.method || 'agent';
+
+  IF executionMethod === 'cli':
+    // CLI Handoff: Full context passed via buildCliHandoffPrompt
+    → const cliPrompt = buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)
+    → const cliCommand = buildCliCommand(task, cliTool, cliPrompt)
+    → Bash({ command: cliCommand, run_in_background: false, timeout: 3600000 })
  ELSE:
-    → Direct agent implementation
+    // Execute directly
    → Create test files in modification_points
    → Write test cases following test_cases enumeration
    → Use context.shared_context.conventions for test style
@@ -195,11 +199,16 @@ STEP 1: Parse Green Phase Requirements
  → Set max_iterations from meta.max_iterations (default: 3)

 STEP 2: Initial Implementation
-  IF step.command exists:
-    → Execute CLI command with session resume
-    → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
+  const executionMethod = task.meta?.execution_config?.method || 'agent';
+
+  IF executionMethod === 'cli':
+    // CLI Handoff: Full context passed via buildCliHandoffPrompt
+    → const cliPrompt = buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)
+    → const cliCommand = buildCliCommand(task, cliTool, cliPrompt)
+    → Bash({ command: cliCommand, run_in_background: false, timeout: 3600000 })
+
  ELSE:
-    → Direct agent implementation
+    // Execute implementation steps directly
    → Implement functions in modification_points
    → Follow logic_flow sequence
    → Use minimal code to pass tests (no over-engineering)
@@ -293,10 +302,15 @@ STEP 1: Parse Refactor Phase Requirements
  → Load refactoring scope from modification_points

 STEP 2: Execute Refactor Implementation
-  IF step.command exists:
-    → Execute CLI command with session resume
+  const executionMethod = task.meta?.execution_config?.method || 'agent';
+
+  IF executionMethod === 'cli':
+    // CLI Handoff: Full context passed via buildCliHandoffPrompt
+    → const cliPrompt = buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)
+    → const cliCommand = buildCliCommand(task, cliTool, cliPrompt)
+    → Bash({ command: cliCommand, run_in_background: false, timeout: 3600000 })
  ELSE:
-    → Direct agent refactoring
+    // Execute directly
    → Apply refactorings from logic_flow
    → Follow refactoring best practices:
      • Extract functions for clarity
@@ -326,47 +340,15 @@ STEP 3: Regression Testing (REQUIRED)

 ### 3. CLI Execution Integration

-**CLI Session Resumption** (when step.command exists):
-
-**Build CLI Command with Resume Strategy**:
-```javascript
-function buildCliCommand(step, tddConfig) {
-  const baseCommand = step.command  // From task JSON
-
-  // Parse cli_execution strategy
-  switch (tddConfig.cliStrategy) {
-    case "new":
-      // First task - start fresh conversation
-      return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write --id ${tddConfig.cliExecutionId}`
-
-    case "resume":
-      // Single child - continue same conversation
-      return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --tool ${tool} --mode write`
-
-    case "fork":
-      // Multiple children - branch with parent context
-      return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
-
-    case "merge_fork":
-      // Multiple parents - merge contexts
-      // resume_from is an array for merge_fork strategy
-      const mergeIds = Array.isArray(tddConfig.resumeFrom)
-        ? tddConfig.resumeFrom.join(',')
-        : tddConfig.resumeFrom
-      return `ccw cli -p "${baseCommand}" --resume ${mergeIds} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
-
-    default:
-      // Fallback - no resume
-      return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write`
-  }
-}
-```
+**CLI Functions** (inherited from code-developer):
+- `buildCliHandoffPrompt(preAnalysisResults, task, taskJsonPath)` - Assembles CLI prompt with full context
+- `buildCliCommand(task, cliTool, cliPrompt)` - Builds CLI command with resume strategy

 **Execute CLI Command**:
 ```javascript
 // TDD agent runs in foreground - can receive hook callbacks
 Bash(
-  command=buildCliCommand(step, tddConfig),
+  command=buildCliCommand(task, cliTool, cliPrompt),
  timeout=3600000,  // 60 min for CLI execution
  run_in_background=false  // Agent can receive task completion hooks
 )
@@ -504,7 +486,7 @@ Before completing any TDD task, verify:
 - Use test-fix cycle in Green phase
 - Auto-revert on max iterations failure
 - Generate TDD-enhanced summaries
- Use CLI resume strategies when step.command exists
+- Use CLI resume strategies when meta.execution_config.method is "cli"
 - Log all test-fix iterations to .process/

 **Bash Tool (CLI Execution in TDD Agent)**:
--- a/.claude/agents/test-fix-agent.md
+++ b/.claude/agents/test-fix-agent.md
@@ -83,15 +83,15 @@ When task JSON contains implementation_approach array:
   - `description`: Detailed description with variable references
   - `modification_points`: Test and code modification targets
   - `logic_flow`: Test-fix iteration sequence
-   - `command`: Optional CLI command (only when explicitly specified)
   - `depends_on`: Array of step numbers that must complete first
   - `output`: Variable name for this step's output
 5. **Execution Mode Selection**:
-   - IF `command` field exists → Execute CLI command via Bash tool
-   - ELSE (no command) → Agent direct execution:
-     - Parse `modification_points` as files to modify
-     - Follow `logic_flow` for test-fix iteration
-     - Use test_commands from flow_control for test execution
+   - Based on `meta.execution_config.method`:
+     - `"cli"` → Build CLI command via buildCliHandoffPrompt() and execute via Bash tool
+     - `"agent"` (default) → Agent direct execution:
+       - Parse `modification_points` as files to modify
+       - Follow `logic_flow` for test-fix iteration
+       - Use test_commands from flow_control for test execution


 ### 1. Context Assessment & Test Discovery