refactor: Replace CLI execution flags with semantic-driven tool selection

- Remove --cli-execute flag from plan.md, tdd-plan.md, task-generate-agent.md, task-generate-tdd.md - Remove --use-codex flag from test-gen.md, test-fix-gen.md, test-task-generate.md - Remove meta.use_codex from task JSON schema in action-planning-agent.md and cli-planning-agent.md - Add "Semantic CLI Tool Selection" section to action-planning-agent.md - Document explicit source: metadata.task_description from context-package.json - Update test-fix-agent.md execution mode documentation - Update action-plan-verify.md to remove use_codex validation - Sync SKILL reference copies via analyze_commands.py CLI tool usage now determined semantically from user's task description (e.g., "use Codex for implementation") instead of explicit flags. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2026-02-12 02:37:45 +08:00 · 2025-11-29 15:59:01 +08:00
parent 09114f59c8
commit 132eec900c
32 changed files with 1080 additions and 1050 deletions
--- a/.claude/skills/command-guide/reference/agents/action-planning-agent.md
+++ b/.claude/skills/command-guide/reference/agents/action-planning-agent.md
@@ -43,7 +43,6 @@ You are a pure execution agent specialized in creating actionable implementation
  - `context_package_path`: Context package with brainstorming artifacts catalog
 - **Metadata**: Simple values
  - `session_id`: Workflow session identifier (WFS-[topic])
-  - `execution_mode`: agent-mode | cli-execute-mode
  - `mcp_capabilities`: Available MCP tools (exa_code, exa_web, code_index)

 **Legacy Support** (backward compatibility):
@@ -244,8 +243,7 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
    "type": "test-gen|test-fix",
    "agent": "@code-developer|@test-fix-agent",
    "test_framework": "jest|vitest|pytest|junit|mocha",
-    "coverage_target": "80%",
-    "use_codex": true|false
+    "coverage_target": "80%"
  }
 }
 ```
@@ -253,7 +251,8 @@ Generate individual `.task/IMPL-*.json` files with the following structure:
 **Test-Specific Fields**:
 - `test_framework`: Existing test framework from project (required for test tasks)
 - `coverage_target`: Target code coverage percentage (optional)
- `use_codex`: Whether to use Codex for automated fixes in test-fix tasks (optional, default: false)
+
+**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`.

 #### Context Object

@@ -485,15 +484,31 @@ The `implementation_approach` supports **two execution modes** based on the pres
     - `bash(codex --full-auto exec '[task]' resume --last --skip-git-repo-check -s danger-full-access)` (multi-step)
     - `bash(cd [path] && gemini -p '[prompt]' --approval-mode yolo)` (write mode)

-**Mode Selection Strategy**:
- **Default to agent execution** for most tasks
- **Use CLI mode** when:
-  - User explicitly requests CLI tool (codex/gemini/qwen)
-  - Task requires multi-step autonomous reasoning beyond agent capability
-  - Complex refactoring needs specialized tool analysis
-  - Building on previous CLI execution context (use `resume --last`)
+**Semantic CLI Tool Selection**:

-**Key Principle**: The `command` field is **optional**. Agent must decide based on task complexity and user preference.
+Agent determines CLI tool usage per-step based on user semantics and task nature.
+
+**Source**: Scan `metadata.task_description` from context-package.json for CLI tool preferences.
+
+**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 (`--approval-mode yolo`)
+- **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 Bash
+- 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**:

--- a/.claude/skills/command-guide/reference/agents/cli-planning-agent.md
+++ b/.claude/skills/command-guide/reference/agents/cli-planning-agent.md
@@ -66,8 +66,7 @@ You are a specialized execution agent that bridges CLI analysis tools with task
  "task_config": {
    "agent": "@test-fix-agent",
    "type": "test-fix-iteration",
-    "max_iterations": 5,
-    "use_codex": false
+    "max_iterations": 5
  }
 }
 ```
@@ -263,7 +262,6 @@ function extractModificationPoints() {
    "analysis_report": ".process/iteration-{iteration}-analysis.md",
    "cli_output": ".process/iteration-{iteration}-cli-output.txt",
    "max_iterations": "{task_config.max_iterations}",
-    "use_codex": "{task_config.use_codex}",
    "parent_task": "{parent_task_id}",
    "created_by": "@cli-planning-agent",
    "created_at": "{timestamp}"
--- a/.claude/skills/command-guide/reference/agents/code-developer.md
+++ b/.claude/skills/command-guide/reference/agents/code-developer.md
@@ -24,8 +24,6 @@ You are a code execution specialist focused on implementing high-quality, produc
 - **Context-driven** - Use provided context and existing code patterns
 - **Quality over speed** - Write boring, reliable code that works

-
-
 ## Execution Process

 ### 1. Context Assessment
--- a/.claude/skills/command-guide/reference/agents/context-search-agent.md
+++ b/.claude/skills/command-guide/reference/agents/context-search-agent.md
@@ -100,10 +100,88 @@ if (!memory.has("README.md")) Read(README.md)

 ### Phase 2: Multi-Source Context Discovery

-Execute all 3 tracks in parallel for comprehensive coverage.
+Execute all tracks in parallel for comprehensive coverage.

 **Note**: Historical archive analysis (querying `.workflow/archives/manifest.json`) is optional and should be performed if the manifest exists. Inject findings into `conflict_detection.historical_conflicts[]`.

+#### Track 0: Exploration Synthesis (Optional)
+
+**Trigger**: When `explorations-manifest.json` exists in session `.process/` folder
+
+**Purpose**: Transform raw exploration data into prioritized, deduplicated insights. This is NOT simple aggregation - it synthesizes `critical_files` (priority-ranked), deduplicates patterns/integration_points, and generates `conflict_indicators`.
+
+```javascript
+// Check for exploration results from context-gather parallel explore phase
+const manifestPath = `.workflow/active/${session_id}/.process/explorations-manifest.json`;
+if (file_exists(manifestPath)) {
+  const manifest = JSON.parse(Read(manifestPath));
+
+  // Load full exploration data from each file
+  const explorationData = manifest.explorations.map(exp => ({
+    ...exp,
+    data: JSON.parse(Read(exp.path))
+  }));
+
+  // Build explorations array with summaries
+  const explorations = explorationData.map(exp => ({
+    angle: exp.angle,
+    file: exp.file,
+    path: exp.path,
+    index: exp.data._metadata?.exploration_index || exp.index,
+    summary: {
+      relevant_files_count: exp.data.relevant_files?.length || 0,
+      key_patterns: exp.data.patterns,
+      integration_points: exp.data.integration_points
+    }
+  }));
+
+  // SYNTHESIS (not aggregation): Transform raw data into prioritized insights
+  const aggregated_insights = {
+    // CRITICAL: Synthesize priority-ranked critical_files from multiple relevant_files lists
+    // - Deduplicate by path
+    // - Rank by: mention count across angles + individual relevance scores
+    // - Top 10-15 files only (focused, actionable)
+    critical_files: synthesizeCriticalFiles(explorationData.flatMap(e => e.data.relevant_files || [])),
+
+    // SYNTHESIS: Generate conflict indicators from pattern mismatches, constraint violations
+    conflict_indicators: synthesizeConflictIndicators(explorationData),
+
+    // Deduplicate clarification questions (merge similar questions)
+    clarification_needs: deduplicateQuestions(explorationData.flatMap(e => e.data.clarification_needs || [])),
+
+    // Preserve source attribution for traceability
+    constraints: explorationData.map(e => ({ constraint: e.data.constraints, source_angle: e.angle })).filter(c => c.constraint),
+
+    // Deduplicate patterns across angles (merge identical patterns)
+    all_patterns: deduplicatePatterns(explorationData.map(e => ({ patterns: e.data.patterns, source_angle: e.angle }))),
+
+    // Deduplicate integration points (merge by file:line location)
+    all_integration_points: deduplicateIntegrationPoints(explorationData.map(e => ({ points: e.data.integration_points, source_angle: e.angle })))
+  };
+
+  // Store for Phase 3 packaging
+  exploration_results = { manifest_path: manifestPath, exploration_count: manifest.exploration_count,
+                         complexity: manifest.complexity, angles: manifest.angles_explored,
+                         explorations, aggregated_insights };
+}
+
+// Synthesis helper functions (conceptual)
+function synthesizeCriticalFiles(allRelevantFiles) {
+  // 1. Group by path
+  // 2. Count mentions across angles
+  // 3. Average relevance scores
+  // 4. Rank by: (mention_count * 0.6) + (avg_relevance * 0.4)
+  // 5. Return top 10-15 with mentioned_by_angles attribution
+}
+
+function synthesizeConflictIndicators(explorationData) {
+  // 1. Detect pattern mismatches across angles
+  // 2. Identify constraint violations
+  // 3. Flag files mentioned with conflicting integration approaches
+  // 4. Assign severity: critical/high/medium/low
+}
+```
+
 #### Track 1: Reference Documentation

 Extract from Phase 0 loaded docs:
@@ -393,10 +471,39 @@ Calculate risk level based on:
    },
    "affected_modules": ["auth", "user-model", "middleware"],
    "mitigation_strategy": "Incremental refactoring with backward compatibility"
+  },
+  "exploration_results": {
+    "manifest_path": ".workflow/active/{session}/.process/explorations-manifest.json",
+    "exploration_count": 3,
+    "complexity": "Medium",
+    "angles": ["architecture", "dependencies", "testing"],
+    "explorations": [
+      {
+        "angle": "architecture",
+        "file": "exploration-architecture.json",
+        "path": ".workflow/active/{session}/.process/exploration-architecture.json",
+        "index": 1,
+        "summary": {
+          "relevant_files_count": 5,
+          "key_patterns": "Service layer with DI",
+          "integration_points": "Container.registerService:45-60"
+        }
+      }
+    ],
+    "aggregated_insights": {
+      "critical_files": [{"path": "src/auth/AuthService.ts", "relevance": 0.95, "mentioned_by_angles": ["architecture"]}],
+      "conflict_indicators": [{"type": "pattern_mismatch", "description": "...", "source_angle": "architecture", "severity": "medium"}],
+      "clarification_needs": [{"question": "...", "context": "...", "options": [], "source_angle": "architecture"}],
+      "constraints": [{"constraint": "Must follow existing DI pattern", "source_angle": "architecture"}],
+      "all_patterns": [{"patterns": "Service layer with DI", "source_angle": "architecture"}],
+      "all_integration_points": [{"points": "Container.registerService:45-60", "source_angle": "architecture"}]
+    }
  }
 }
 ```

+**Note**: `exploration_results` is populated when exploration files exist (from context-gather parallel explore phase). If no explorations, this field is omitted or empty.
+


 ## Quality Validation
--- a/.claude/skills/command-guide/reference/agents/test-fix-agent.md
+++ b/.claude/skills/command-guide/reference/agents/test-fix-agent.md
@@ -142,9 +142,9 @@ run_test_layer "L1-unit" "$UNIT_CMD"

 ### 3. Failure Diagnosis & Fixing Loop

-**Execution Modes**:
+**Execution Modes** (determined by `flow_control.implementation_approach`):

-**A. Manual Mode (Default, meta.use_codex=false)**:
+**A. Agent Mode (Default, no `command` field in steps)**:
 ```
 WHILE tests are failing AND iterations < max_iterations:
    1. Use Gemini to diagnose failure (bug-fix template)
@@ -155,17 +155,17 @@ WHILE tests are failing AND iterations < max_iterations:
 END WHILE
 ```

-**B. Codex Mode (meta.use_codex=true)**:
+**B. CLI Mode (`command` field present in implementation_approach steps)**:
 ```
 WHILE tests are failing AND iterations < max_iterations:
    1. Use Gemini to diagnose failure (bug-fix template)
-    2. Use Codex to apply fixes automatically with resume mechanism
+    2. Execute `command` field (e.g., Codex) to apply fixes automatically
    3. Re-run test suite
    4. Verify fix doesn't break other tests
 END WHILE
 ```

-**Codex Resume in Test-Fix Cycle** (when `meta.use_codex=true`):
+**Codex Resume in Test-Fix Cycle** (when step has `command` with Codex):
 - First iteration: Start new Codex session with full context
 - Subsequent iterations: Use `resume --last` to maintain fix history and apply consistent strategies