diff --git a/.claude/agents/action-planning-agent.md b/.claude/agents/action-planning-agent.md
index b8e68c53..441989d0 100644
--- a/.claude/agents/action-planning-agent.md
+++ b/.claude/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**:
diff --git a/.claude/agents/cli-planning-agent.md b/.claude/agents/cli-planning-agent.md
index 81cd3271..6abf8c3c 100644
--- a/.claude/agents/cli-planning-agent.md
+++ b/.claude/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}"
diff --git a/.claude/agents/code-developer.md b/.claude/agents/code-developer.md
index 0ba7baef..e01a0e28 100644
--- a/.claude/agents/code-developer.md
+++ b/.claude/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
diff --git a/.claude/agents/test-fix-agent.md b/.claude/agents/test-fix-agent.md
index b1cd94ff..2d6e3683 100644
--- a/.claude/agents/test-fix-agent.md
+++ b/.claude/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
diff --git a/.claude/commands/workflow/action-plan-verify.md b/.claude/commands/workflow/action-plan-verify.md
index 886b36f0..cc3933be 100644
--- a/.claude/commands/workflow/action-plan-verify.md
+++ b/.claude/commands/workflow/action-plan-verify.md
@@ -101,7 +101,7 @@ Load only minimal necessary context from each artifact:
- Dependencies (depends_on, blocks)
- Context (requirements, focus_paths, acceptance, artifacts)
- Flow control (pre_analysis, implementation_approach)
-- Meta (complexity, priority, use_codex)
+- Meta (complexity, priority)
### 3. Build Semantic Models
diff --git a/.claude/commands/workflow/plan.md b/.claude/commands/workflow/plan.md
index 1bbe991b..938fc719 100644
--- a/.claude/commands/workflow/plan.md
+++ b/.claude/commands/workflow/plan.md
@@ -1,7 +1,7 @@
---
name: plan
-description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
-argument-hint: "[--cli-execute] \"text description\"|file.md"
+description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs
+argument-hint: "\"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -69,7 +69,7 @@ Phase 3: Conflict Resolution (conditional)
└─ conflict_risk < medium → Skip to Phase 4
Phase 4: Task Generation
- └─ /workflow:tools:task-generate-agent --session sessionId [--cli-execute]
+ └─ /workflow:tools:task-generate-agent --session sessionId
└─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
Return:
@@ -273,15 +273,10 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
**Step 4.1: Dispatch** - Generate implementation plan and task JSONs
```javascript
-// Default (agent mode)
SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
-
-// With CLI execution (if --cli-execute flag present)
-SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId] --cli-execute")
```
-**Flag**:
-- `--cli-execute`: Generate tasks with Codex execution commands
+**CLI Execution Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description. If user specifies "use Codex/Gemini/Qwen for X", the agent embeds `command` fields in relevant `implementation_approach` steps.
**Input**: `sessionId` from Phase 1
@@ -423,7 +418,7 @@ Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
↓ Output: Modified brainstorm artifacts (NO report file)
↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
↓
-Phase 4: task-generate-agent --session sessionId [--cli-execute]
+Phase 4: task-generate-agent --session sessionId
↓ Input: sessionId + resolved brainstorm artifacts + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
↓
@@ -504,9 +499,7 @@ Return summary to user
- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
-- **Build Phase 4 command**:
- - Base command: `/workflow:tools:task-generate-agent --session [sessionId]`
- - Add `--cli-execute` if flag present
+- **Build Phase 4 command**: `/workflow:tools:task-generate-agent --session [sessionId]`
- Pass session ID to Phase 4 command
- Verify all Phase 4 outputs
- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
diff --git a/.claude/commands/workflow/tdd-plan.md b/.claude/commands/workflow/tdd-plan.md
index f86c1d6f..8fa85f33 100644
--- a/.claude/commands/workflow/tdd-plan.md
+++ b/.claude/commands/workflow/tdd-plan.md
@@ -1,7 +1,7 @@
---
name: tdd-plan
description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
-argument-hint: "[--cli-execute] \"feature description\"|file.md"
+argument-hint: "\"feature description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -11,9 +11,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
**This command is a pure orchestrator**: Dispatches 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
-**Execution Modes**:
-- **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
-- **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
+**CLI Tool Selection**: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
**Task Attachment Model**:
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
@@ -235,13 +233,11 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
**Step 5.1: Dispatch** - TDD task generation via action-planning-agent
```javascript
-// Agent Mode (default)
SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
-
-// CLI Mode (--cli-execute flag)
-SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId] --cli-execute")
```
+**Note**: CLI tool usage is determined semantically from user's task description.
+
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
**Validate**:
@@ -454,8 +450,7 @@ Convert user input to TDD-structured format:
- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 4: Memory optimization (if context approaching limits)
-- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
-- `/workflow:tools:task-generate-tdd --cli-execute` - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when `--cli-execute` flag used)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
diff --git a/.claude/commands/workflow/test-fix-gen.md b/.claude/commands/workflow/test-fix-gen.md
index 5c32fe76..ad559a92 100644
--- a/.claude/commands/workflow/test-fix-gen.md
+++ b/.claude/commands/workflow/test-fix-gen.md
@@ -1,7 +1,7 @@
---
name: test-fix-gen
description: Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning
-argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
+argument-hint: "(source-session-id | \"feature description\" | /path/to/file.md)"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -43,7 +43,7 @@ fi
- **Session Isolation**: Creates independent `WFS-test-[slug]` session
- **Context-First**: Gathers implementation context via appropriate method
- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
-- **Manual First**: Default to manual fixes, use `--use-codex` for automation
+- **Semantic CLI Selection**: CLI tool usage determined from user's task description
- **Automatic Detection**: Input pattern determines execution mode
### Coordinator Role
@@ -79,16 +79,14 @@ This command is a **pure planning coordinator**:
```bash
# Basic syntax
-/workflow:test-fix-gen [FLAGS]
-
-# Flags (optional)
---use-codex # Enable Codex automated fixes in IMPL-002
---cli-execute # Enable CLI execution in IMPL-001
+/workflow:test-fix-gen
# Input
# Session ID, description, or file path
```
+**Note**: CLI tool usage is determined semantically from the task description. To request CLI execution, include it in your description (e.g., "use Codex for automated fixes").
+
### Usage Examples
#### Session Mode
@@ -96,11 +94,8 @@ This command is a **pure planning coordinator**:
# Test validation for completed implementation
/workflow:test-fix-gen WFS-user-auth-v2
-# With automated fixes
-/workflow:test-fix-gen --use-codex WFS-api-endpoints
-
-# With CLI execution
-/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
+# With semantic CLI request
+/workflow:test-fix-gen WFS-api-endpoints # Add "use Codex" in description for automated fixes
```
#### Prompt Mode - Text Description
@@ -108,17 +103,14 @@ This command is a **pure planning coordinator**:
# Generate tests from feature description
/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
-# With automated fixes
-/workflow:test-fix-gen --use-codex "Test user registration and login flows"
+# With CLI execution (semantic)
+/workflow:test-fix-gen "Test user registration and login flows, use Codex for automated fixes"
```
#### Prompt Mode - File Reference
```bash
# Generate tests from requirements file
/workflow:test-fix-gen ./docs/api-requirements.md
-
-# With flags
-/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
```
### Mode Comparison
@@ -143,7 +135,7 @@ This command is a **pure planning coordinator**:
5. **Complete All Phases**: Do not return until Phase 5 completes
6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
7. **Automatic Detection**: Mode auto-detected from input pattern
-8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+8. **Semantic CLI Detection**: CLI tool usage determined from user's task description for Phase 4
9. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
@@ -283,13 +275,13 @@ For each targeted file/function, Gemini MUST generate:
**Step 4.1: Dispatch** - Generate test task JSONs
```javascript
-SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")
+SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
```
**Input**:
- `testSessionId` from Phase 1
-- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
-- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
+
+**Note**: CLI tool usage is determined semantically from user's task description.
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3 (multi-layered test plan)
@@ -422,7 +414,7 @@ CRITICAL - Next Steps:
- **Phase 2**: Mode-specific context gathering (session summaries vs codebase analysis)
- **Phase 3**: Multi-layered test requirements analysis (L0: Static, L1: Unit, L2: Integration, L3: E2E)
- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
-- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+- **Fix Mode Configuration**: CLI tool usage determined semantically from user's task description
---
@@ -521,16 +513,15 @@ If quality gate fails:
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex: true|false` (based on `--use-codex` flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
**Test-Fix Cycle Specification**:
**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
-- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
+- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → fix (agent or CLI) → retest
- **Tools Configuration** (orchestrator-controlled):
- Gemini for analysis with bug-fix template → surgical fix suggestions
- - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
+ - Agent fix application (default) OR CLI if `command` field present in implementation_approach
- **Exit Conditions** (orchestrator-enforced):
- Success: All tests pass
- Failure: Max iterations reached (5)
@@ -674,8 +665,7 @@ Key Points:
4. **Mode Selection**:
- Use **Session Mode** for completed workflow validation
- Use **Prompt Mode** for ad-hoc test generation
- - Use `--use-codex` for autonomous fix application
- - Use `--cli-execute` for enhanced generation capabilities
+ - Include "use Codex" in description for autonomous fix application
## Related Commands
@@ -688,9 +678,7 @@ Key Points:
- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
diff --git a/.claude/commands/workflow/test-gen.md b/.claude/commands/workflow/test-gen.md
index eb2561e9..99ea7d5e 100644
--- a/.claude/commands/workflow/test-gen.md
+++ b/.claude/commands/workflow/test-gen.md
@@ -1,7 +1,7 @@
---
name: test-gen
description: Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks
-argument-hint: "[--use-codex] [--cli-execute] source-session-id"
+argument-hint: "source-session-id"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -16,7 +16,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
- **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
-- **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
+- **Semantic CLI Selection**: CLI tool usage is determined by user's task description (e.g., "use Codex for fixes")
**Task Attachment Model**:
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
@@ -48,7 +48,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
-8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
+8. **Semantic CLI Selection**: CLI tool usage determined from user's task description, passed to Phase 4
9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
10. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
11. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
@@ -224,13 +224,13 @@ SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessi
**Step 4.1: Dispatch** - Generate test task JSON files and planning documents
```javascript
-SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")
+SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
```
**Input**:
- `testSessionId` from Phase 1
-- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
-- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
+
+**Note**: CLI tool usage for fixes is determined semantically from user's task description (e.g., "use Codex for automated fixes").
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
@@ -260,16 +260,15 @@ SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-ex
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex: true|false` (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- - **Cycle pattern**: test → gemini_diagnose → manual_fix (or codex if --use-codex) → retest
- - **Tools configuration**: Gemini for analysis with bug-fix template, manual or Codex for fixes
+ - **Cycle pattern**: test → gemini_diagnose → fix (agent or CLI based on `command` field) → retest
+ - **Tools configuration**: Gemini for analysis with bug-fix template, agent or CLI for fixes
- **Exit conditions**: Success (all pass) or failure (max iterations)
- `flow_control.implementation_approach.modification_points`: 3-phase execution flow
- Phase 1: Initial test execution
- - Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
+ - Phase 2: Iterative Gemini diagnosis + fixes (agent or CLI based on step's `command` field)
- Phase 3: Final validation and certification
@@ -327,7 +326,7 @@ Artifacts Created:
Test Framework: [detected framework]
Test Files to Generate: [count]
-Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
+Fix Mode: [Agent|CLI] (based on `command` field in implementation_approach steps)
Review Generated Artifacts:
- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
@@ -373,7 +372,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
- **Phase 2**: Cross-session context gathering from source implementation session
- **Phase 3**: Test requirements analysis with Gemini for generation strategy
- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
-- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+- **Fix Mode Configuration**: CLI tool usage determined semantically from user's task description
@@ -444,7 +443,7 @@ Generates two task definition files:
- Agent: @test-fix-agent
- Dependency: IMPL-001 must complete first
- Max iterations: 5
- - Fix mode: Manual or Codex (based on --use-codex flag)
+ - Fix mode: Agent or CLI (based on `command` field in implementation_approach)
See `/workflow:tools:test-task-generate` for complete task JSON schemas.
@@ -481,11 +480,10 @@ Created in `.workflow/active/WFS-test-[session]/`:
**IMPL-002.json Structure**:
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex`: true/false (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- Gemini diagnosis template
- - Fix application mode (manual/codex)
+ - Fix application mode (agent or CLI based on `command` field)
- Max iterations: 5
- `flow_control.implementation_approach.modification_points`: 3-phase flow
@@ -503,13 +501,11 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
-**Dispatched by This Command** (5 phases):
+**Dispatched by This Command** (4 phases):
- `/workflow:session:start` - Phase 1: Create independent test workflow session
- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
diff --git a/.claude/commands/workflow/tools/task-generate-agent.md b/.claude/commands/workflow/tools/task-generate-agent.md
index db6f3843..2590abbd 100644
--- a/.claude/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/commands/workflow/tools/task-generate-agent.md
@@ -1,10 +1,9 @@
---
name: task-generate-agent
description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
-argument-hint: "--session WFS-session-id [--cli-execute]"
+argument-hint: "--session WFS-session-id"
examples:
- /workflow:tools:task-generate-agent --session WFS-auth
- - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
---
# Generate Implementation Plan Command
@@ -26,7 +25,7 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
```
Input Parsing:
- ├─ Parse flags: --session, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Context Preparation (Command)
@@ -65,9 +64,10 @@ Phase 2: Planning Document Generation (Agent)
2. **Provide Metadata** (simple values):
- `session_id`
- - `execution_mode` (agent-mode | cli-execute-mode)
- `mcp_capabilities` (available MCP tools)
+**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags.
+
### Phase 2: Planning Document Generation (Agent Responsibility)
**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
@@ -97,9 +97,13 @@ Output:
## CONTEXT METADATA
Session ID: {session-id}
-Planning Mode: {agent-mode | cli-execute-mode}
MCP Capabilities: {exa_code, exa_web, code_index}
+## CLI TOOL SELECTION
+Determine CLI tool usage per-step based on user's task description:
+- If user specifies "use Codex/Gemini/Qwen for X" → Add command field to relevant steps
+- Default: Agent execution (no command field) unless user explicitly requests CLI
+
## EXPLORATION CONTEXT (from context-package.exploration_results)
- Load exploration_results from context-package.json
- Use aggregated_insights.critical_files for focus_paths generation
diff --git a/.claude/commands/workflow/tools/task-generate-tdd.md b/.claude/commands/workflow/tools/task-generate-tdd.md
index 7f8d4807..9bd76d75 100644
--- a/.claude/commands/workflow/tools/task-generate-tdd.md
+++ b/.claude/commands/workflow/tools/task-generate-tdd.md
@@ -1,24 +1,23 @@
---
name: task-generate-tdd
description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
-argument-hint: "--session WFS-session-id [--cli-execute]"
+argument-hint: "--session WFS-session-id"
examples:
- /workflow:tools:task-generate-tdd --session WFS-auth
- - /workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
---
# Autonomous TDD Task Generation Command
## Overview
-Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes. Generates complete Red-Green-Refactor cycles contained within each task.
+Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Generates complete Red-Green-Refactor cycles contained within each task.
## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
- **Memory-First**: Reuse loaded documents from conversation memory
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
-- **Pre-Selected Templates**: Command selects correct TDD template based on `--cli-execute` flag **before** invoking agent
-- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Semantic CLI Selection**: CLI tool usage determined from user's task description, not flags
+- **Agent Simplicity**: Agent generates content with semantic CLI detection
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
- **TDD-First**: Every feature starts with a failing test (Red phase)
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
@@ -57,7 +56,7 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
```
Input Parsing:
- ├─ Parse flags: --session, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Discovery & Context Loading (Memory-First)
@@ -69,7 +68,7 @@ Phase 1: Discovery & Context Loading (Memory-First)
└─ Optional: MCP external research
Phase 2: Agent Execution (Document Generation)
- ├─ Pre-agent template selection (agent-mode OR cli-execute-mode)
+ ├─ Pre-agent template selection (semantic CLI detection)
├─ Invoke action-planning-agent
├─ Generate TDD Task JSON Files (.task/IMPL-*.json)
│ └─ Each task: complete Red-Green-Refactor cycle internally
@@ -86,11 +85,8 @@ Phase 2: Agent Execution (Document Generation)
```javascript
{
"session_id": "WFS-[session-id]",
- "execution_mode": "agent-mode" | "cli-execute-mode", // Determined by flag
- "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
- | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
- // Path selected by command based on --cli-execute flag, agent reads it
"workflow_type": "tdd",
+ // Note: CLI tool usage is determined semantically by action-planning-agent based on user's task description
"session_metadata": {
// If in memory: use cached content
// Else: Load from .workflow/active//{session-id}/workflow-session.json
@@ -199,8 +195,7 @@ Task(
**Session ID**: WFS-{session-id}
**Workflow Type**: TDD
-**Execution Mode**: {agent-mode | cli-execute-mode}
-**Task JSON Template Path**: {template_path}
+**Note**: CLI tool usage is determined semantically from user's task description
## Phase 1: Discovery Results (Provided Context)
@@ -265,16 +260,15 @@ Refer to: @.claude/agents/action-planning-agent.md for:
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/active//{session-id}/.task/`
-- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure with TDD-specific metadata
- `meta.tdd_workflow`: true (REQUIRED)
- `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
- - `meta.use_codex`: false (manual fixes by default)
- `context.tdd_cycles`: Array with quantified test cases and coverage
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
1. Red Phase (`tdd_phase: "red"`): Write failing tests
2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
+ - CLI tool usage determined semantically (add `command` field when user requests CLI execution)
- **Details**: See action-planning-agent.md § TDD Task JSON Generation
##### 2. IMPL_PLAN.md (TDD Variant)
@@ -475,16 +469,14 @@ This section provides quick reference for TDD task JSON structure. For complete
**Basic Usage**:
```bash
-# Agent mode (default, autonomous execution)
+# Standard execution
/workflow:tools:task-generate-tdd --session WFS-auth
-# CLI tool mode (use Gemini/Qwen for generation)
-/workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
+# With semantic CLI request (include in task description)
+# e.g., "Generate TDD tasks for auth module, use Codex for implementation"
```
-**Execution Modes**:
-- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
-- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen with cli-mode task template
+**CLI Tool Selection**: Determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
**Output**:
- TDD task JSON files in `.task/` directory (IMPL-N.json format)
@@ -513,7 +505,7 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
3. **Success Path**: Tests pass → Complete task
4. **Failure Path**: Tests fail → Enter iterative fix cycle:
- **Gemini Diagnosis**: Analyze failures with bug-fix template
- - **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
+ - **Fix Application**: Agent (default) or CLI (if `command` field present)
- **Retest**: Verify fix resolves failures
- **Repeat**: Up to max_iterations (default: 3)
5. **Safety Net**: Auto-revert all changes if max iterations reached
@@ -522,5 +514,5 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
## Configuration Options
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
-- **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
+- **CLI tool usage**: Determined semantically from user's task description via `command` field in implementation_approach
diff --git a/.claude/commands/workflow/tools/test-task-generate.md b/.claude/commands/workflow/tools/test-task-generate.md
index 6287dbfe..47607d1d 100644
--- a/.claude/commands/workflow/tools/test-task-generate.md
+++ b/.claude/commands/workflow/tools/test-task-generate.md
@@ -1,11 +1,9 @@
---
name: test-task-generate
description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests
-argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
+argument-hint: "--session WFS-test-session-id"
examples:
- /workflow:tools:test-task-generate --session WFS-test-auth
- - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
- - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
---
# Generate Test Planning Documents Command
@@ -26,17 +24,17 @@ Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) u
### Test Generation (IMPL-001)
- **Agent Mode** (default): @code-developer generates tests within agent context
-- **CLI Execute Mode** (`--cli-execute`): Use Codex CLI for autonomous test generation
+- **CLI Mode**: Use CLI tools when `command` field present in implementation_approach (determined semantically)
### Test Execution & Fix (IMPL-002+)
-- **Manual Mode** (default): Gemini diagnosis → user applies fixes
-- **Codex Mode** (`--use-codex`): Gemini diagnosis → Codex applies fixes with resume mechanism
+- **Agent Mode** (default): Gemini diagnosis → agent applies fixes
+- **CLI Mode**: Gemini diagnosis → CLI applies fixes (when `command` field present in implementation_approach)
## Execution Process
```
Input Parsing:
- ├─ Parse flags: --session, --use-codex, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Context Preparation (Command)
@@ -44,7 +42,7 @@ Phase 1: Context Preparation (Command)
│ ├─ session_metadata_path
│ ├─ test_analysis_results_path (REQUIRED)
│ └─ test_context_package_path
- └─ Provide metadata (session_id, execution_mode, use_codex, source_session_id)
+ └─ Provide metadata (session_id, source_session_id)
Phase 2: Test Document Generation (Agent)
├─ Load TEST_ANALYSIS_RESULTS.md as primary requirements source
@@ -83,11 +81,11 @@ Phase 2: Test Document Generation (Agent)
2. **Provide Metadata** (simple values):
- `session_id`
- - `execution_mode` (agent-mode | cli-execute-mode)
- - `use_codex` flag (true | false)
- `source_session_id` (if exists)
- `mcp_capabilities` (available MCP tools)
+**Note**: CLI tool usage is now determined semantically from user's task description, not by flags.
+
### Phase 2: Test Document Generation (Agent Responsibility)
**Purpose**: Generate test-specific IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT test execution.
@@ -134,11 +132,14 @@ Output:
## CONTEXT METADATA
Session ID: {test-session-id}
Workflow Type: test_session
-Planning Mode: {agent-mode | cli-execute-mode}
-Use Codex: {true | false}
Source Session: {source-session-id} (if exists)
MCP Capabilities: {exa_code, exa_web, code_index}
+## CLI TOOL SELECTION
+Determine CLI tool usage per-step based on user's task description:
+- If user specifies "use Codex/Gemini/Qwen for X" → Add command field to relevant steps
+- Default: Agent execution (no command field) unless user explicitly requests CLI
+
## TEST-SPECIFIC REQUIREMENTS SUMMARY
(Detailed specifications in your agent definition)
@@ -149,25 +150,26 @@ MCP Capabilities: {exa_code, exa_web, code_index}
Task Configuration:
IMPL-001 (Test Generation):
- meta.type: "test-gen"
- - meta.agent: "@code-developer" (agent-mode) OR CLI execution (cli-execute-mode)
+ - meta.agent: "@code-developer"
- meta.test_framework: Specify existing framework (e.g., "jest", "vitest", "pytest")
- flow_control: Test generation strategy from TEST_ANALYSIS_RESULTS.md
+ - CLI execution: Add `command` field when user requests (determined semantically)
IMPL-002+ (Test Execution & Fix):
- meta.type: "test-fix"
- meta.agent: "@test-fix-agent"
- - meta.use_codex: true/false (based on flag)
- flow_control: Test-fix cycle with iteration limits and diagnosis configuration
+ - CLI execution: Add `command` field when user requests (determined semantically)
### Test-Fix Cycle Specification (IMPL-002+)
Required flow_control fields:
- max_iterations: 5
- diagnosis_tool: "gemini"
- diagnosis_template: "~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt"
- - fix_mode: "manual" OR "codex" (based on use_codex flag)
- cycle_pattern: "test → gemini_diagnose → fix → retest"
- exit_conditions: ["all_tests_pass", "max_iterations_reached"]
- auto_revert_on_failure: true
+ - CLI fix: Add `command` field when user specifies CLI tool usage
### Automation Framework Configuration
Select automation tools based on test requirements from TEST_ANALYSIS_RESULTS.md:
@@ -191,8 +193,9 @@ PRIMARY requirements source - extract and map to task JSONs:
## EXPECTED DELIVERABLES
1. Test Task JSON Files (.task/IMPL-*.json)
- 6-field schema with quantified requirements from TEST_ANALYSIS_RESULTS.md
- - Test-specific metadata: type, agent, use_codex, test_framework, coverage_target
+ - Test-specific metadata: type, agent, test_framework, coverage_target
- flow_control includes: reusable_test_tools, test_commands (from project config)
+ - CLI execution via `command` field when user requests (determined semantically)
- Artifact references from test-context-package.json
- Absolute paths in context.files_to_test
@@ -213,9 +216,9 @@ Hard Constraints:
- All requirements quantified from TEST_ANALYSIS_RESULTS.md
- Test framework matches existing project framework
- flow_control includes reusable_test_tools and test_commands from project
- - use_codex flag correctly set in IMPL-002+ tasks
- Absolute paths for all focus_paths
- Acceptance criteria include verification commands
+ - CLI `command` field added only when user explicitly requests CLI tool usage
## SUCCESS CRITERIA
- All test planning documents generated successfully
@@ -233,21 +236,18 @@ Hard Constraints:
### Usage Examples
```bash
-# Agent mode (default)
+# Standard execution
/workflow:tools:test-task-generate --session WFS-test-auth
-# With automated Codex fixes
-/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
-
-# CLI execution mode for test generation
-/workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+# With semantic CLI request (include in task description)
+# e.g., "Generate tests, use Codex for implementation and fixes"
```
-### Flag Behavior
-- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode test generation
-- **--use-codex**: `meta.use_codex=true` (Codex automated fixes in IMPL-002+)
-- **--cli-execute**: CLI tool execution mode for IMPL-001 test generation
-- **Both flags**: CLI generation + automated Codex fixes
+### CLI Tool Selection
+CLI tool usage is determined semantically from user's task description:
+- Include "use Codex" for automated fixes
+- Include "use Gemini" for analysis
+- Default: Agent execution (no `command` field)
### Output
- Test task JSON files in `.task/` directory (minimum 2)
diff --git a/.claude/skills/command-guide/index/all-commands.json b/.claude/skills/command-guide/index/all-commands.json
index 492062d1..ff6070aa 100644
--- a/.claude/skills/command-guide/index/all-commands.json
+++ b/.claude/skills/command-guide/index/all-commands.json
@@ -409,8 +409,8 @@
{
"name": "plan",
"command": "/workflow:plan",
- "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
- "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
+ "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs",
+ "arguments": "\\\"text description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -531,7 +531,7 @@
"name": "tdd-plan",
"command": "/workflow:tdd-plan",
"description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
- "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
+ "arguments": "\\\"feature description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -564,7 +564,7 @@
"name": "test-fix-gen",
"command": "/workflow:test-fix-gen",
"description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning",
- "arguments": "[--use-codex] [--cli-execute] (source-session-id | \\\"feature description\\\" | /path/to/file.md)",
+ "arguments": "(source-session-id | \\\"feature description\\\" | /path/to/file.md)",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
@@ -575,7 +575,7 @@
"name": "test-gen",
"command": "/workflow:test-gen",
"description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks",
- "arguments": "[--use-codex] [--cli-execute] source-session-id",
+ "arguments": "source-session-id",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
@@ -608,7 +608,7 @@
"name": "task-generate-agent",
"command": "/workflow:tools:task-generate-agent",
"description": "Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -619,7 +619,7 @@
"name": "task-generate-tdd",
"command": "/workflow:tools:task-generate-tdd",
"description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -663,7 +663,7 @@
"name": "test-task-generate",
"command": "/workflow:tools:test-task-generate",
"description": "Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests",
- "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
+ "arguments": "--session WFS-test-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
diff --git a/.claude/skills/command-guide/index/by-category.json b/.claude/skills/command-guide/index/by-category.json
index f7053298..145db695 100644
--- a/.claude/skills/command-guide/index/by-category.json
+++ b/.claude/skills/command-guide/index/by-category.json
@@ -295,8 +295,8 @@
{
"name": "plan",
"command": "/workflow:plan",
- "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
- "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
+ "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs",
+ "arguments": "\\\"text description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -373,7 +373,7 @@
"name": "tdd-plan",
"command": "/workflow:tdd-plan",
"description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
- "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
+ "arguments": "\\\"feature description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -406,7 +406,7 @@
"name": "test-fix-gen",
"command": "/workflow:test-fix-gen",
"description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning",
- "arguments": "[--use-codex] [--cli-execute] (source-session-id | \\\"feature description\\\" | /path/to/file.md)",
+ "arguments": "(source-session-id | \\\"feature description\\\" | /path/to/file.md)",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
@@ -417,7 +417,7 @@
"name": "test-gen",
"command": "/workflow:test-gen",
"description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks",
- "arguments": "[--use-codex] [--cli-execute] source-session-id",
+ "arguments": "source-session-id",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
@@ -632,7 +632,7 @@
"name": "task-generate-agent",
"command": "/workflow:tools:task-generate-agent",
"description": "Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -643,7 +643,7 @@
"name": "task-generate-tdd",
"command": "/workflow:tools:task-generate-tdd",
"description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -687,7 +687,7 @@
"name": "test-task-generate",
"command": "/workflow:tools:test-task-generate",
"description": "Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests",
- "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
+ "arguments": "--session WFS-test-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
diff --git a/.claude/skills/command-guide/index/by-use-case.json b/.claude/skills/command-guide/index/by-use-case.json
index 2c62960b..3eb17de0 100644
--- a/.claude/skills/command-guide/index/by-use-case.json
+++ b/.claude/skills/command-guide/index/by-use-case.json
@@ -469,8 +469,8 @@
{
"name": "plan",
"command": "/workflow:plan",
- "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
- "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
+ "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs",
+ "arguments": "\\\"text description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -492,7 +492,7 @@
"name": "tdd-plan",
"command": "/workflow:tdd-plan",
"description": "TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking",
- "arguments": "[--cli-execute] \\\"feature description\\\"|file.md",
+ "arguments": "\\\"feature description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
@@ -604,7 +604,7 @@
"name": "task-generate-agent",
"command": "/workflow:tools:task-generate-agent",
"description": "Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -615,7 +615,7 @@
"name": "task-generate-tdd",
"command": "/workflow:tools:task-generate-tdd",
"description": "Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation",
- "arguments": "--session WFS-session-id [--cli-execute]",
+ "arguments": "--session WFS-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -626,7 +626,7 @@
"name": "test-task-generate",
"command": "/workflow:tools:test-task-generate",
"description": "Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests",
- "arguments": "[--use-codex] [--cli-execute] --session WFS-test-session-id",
+ "arguments": "--session WFS-test-session-id",
"category": "workflow",
"subcategory": "tools",
"usage_scenario": "implementation",
@@ -742,7 +742,7 @@
"name": "test-fix-gen",
"command": "/workflow:test-fix-gen",
"description": "Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning",
- "arguments": "[--use-codex] [--cli-execute] (source-session-id | \\\"feature description\\\" | /path/to/file.md)",
+ "arguments": "(source-session-id | \\\"feature description\\\" | /path/to/file.md)",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
@@ -753,7 +753,7 @@
"name": "test-gen",
"command": "/workflow:test-gen",
"description": "Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks",
- "arguments": "[--use-codex] [--cli-execute] source-session-id",
+ "arguments": "source-session-id",
"category": "workflow",
"subcategory": null,
"usage_scenario": "testing",
diff --git a/.claude/skills/command-guide/index/essential-commands.json b/.claude/skills/command-guide/index/essential-commands.json
index 38dabd2e..4635552f 100644
--- a/.claude/skills/command-guide/index/essential-commands.json
+++ b/.claude/skills/command-guide/index/essential-commands.json
@@ -24,8 +24,8 @@
{
"name": "plan",
"command": "/workflow:plan",
- "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution",
- "arguments": "[--cli-execute] \\\"text description\\\"|file.md",
+ "description": "5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs",
+ "arguments": "\\\"text description\\\"|file.md",
"category": "workflow",
"subcategory": null,
"usage_scenario": "planning",
diff --git a/.claude/skills/command-guide/reference/agents/action-planning-agent.md b/.claude/skills/command-guide/reference/agents/action-planning-agent.md
index b8e68c53..441989d0 100644
--- 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**:
diff --git a/.claude/skills/command-guide/reference/agents/cli-planning-agent.md b/.claude/skills/command-guide/reference/agents/cli-planning-agent.md
index 81cd3271..6abf8c3c 100644
--- 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}"
diff --git a/.claude/skills/command-guide/reference/agents/code-developer.md b/.claude/skills/command-guide/reference/agents/code-developer.md
index 0ba7baef..e01a0e28 100644
--- 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
diff --git a/.claude/skills/command-guide/reference/agents/context-search-agent.md b/.claude/skills/command-guide/reference/agents/context-search-agent.md
index c387092e..9f050aa3 100644
--- 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
diff --git a/.claude/skills/command-guide/reference/agents/test-fix-agent.md b/.claude/skills/command-guide/reference/agents/test-fix-agent.md
index b1cd94ff..2d6e3683 100644
--- 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
diff --git a/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md b/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md
index 886b36f0..cc3933be 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/action-plan-verify.md
@@ -101,7 +101,7 @@ Load only minimal necessary context from each artifact:
- Dependencies (depends_on, blocks)
- Context (requirements, focus_paths, acceptance, artifacts)
- Flow control (pre_analysis, implementation_approach)
-- Meta (complexity, priority, use_codex)
+- Meta (complexity, priority)
### 3. Build Semantic Models
diff --git a/.claude/skills/command-guide/reference/commands/workflow/lite-fix.md b/.claude/skills/command-guide/reference/commands/workflow/lite-fix.md
index 3cc2277f..709cf778 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/lite-fix.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/lite-fix.md
@@ -2,794 +2,598 @@
name: lite-fix
description: Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents
argument-hint: "[--hotfix] \"bug description or issue reference\""
-allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Read(*), Bash(*)
+allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
---
# Workflow Lite-Fix Command (/workflow:lite-fix)
## Overview
-Fast-track bug fixing workflow optimized for quick diagnosis, targeted fixes, and streamlined verification. Automatically adjusts process complexity based on impact assessment.
+Intelligent lightweight bug fixing command with dynamic workflow adaptation based on severity assessment. Focuses on diagnosis phases (root cause analysis, impact assessment, fix planning, confirmation) and delegates execution to `/workflow:lite-execute`.
**Core capabilities:**
-- Rapid root cause diagnosis with intelligent code search
-- Automatic severity assessment and adaptive workflow
-- Fix strategy selection (immediate patch vs comprehensive refactor)
-- Risk-aware verification (smoke tests to full suite)
-- Optional hotfix mode for production incidents with branch management
-- Automatic follow-up task generation for hotfixes
+- Intelligent bug analysis with automatic severity detection
+- Dynamic code diagnosis (cli-explore-agent) for root cause identification
+- Interactive clarification after diagnosis to gather missing information
+- Adaptive fix planning strategy (direct Claude vs cli-lite-planning-agent) based on complexity
+- Two-step confirmation: fix-plan display -> multi-dimensional input collection
+- Execution dispatch with complete context handoff to lite-execute
## Usage
-### Command Syntax
```bash
/workflow:lite-fix [FLAGS]
# Flags
---hotfix, -h Production hotfix mode (creates hotfix branch, auto follow-up)
+--hotfix, -h Production hotfix mode (minimal diagnosis, fast fix)
# Arguments
- Bug description or issue reference (required)
-```
-
-### Modes
-
-| Mode | Time Budget | Use Case | Workflow Characteristics |
-|------|-------------|----------|--------------------------|
-| **Default** | Auto-adapt (15min-4h) | All standard bugs | Intelligent severity assessment + adaptive process |
-| **Hotfix** (`--hotfix`) | 15-30 min | Production outage | Minimal diagnosis + hotfix branch + auto follow-up |
-
-### Examples
-
-```bash
-# Default mode: Automatically adjusts based on impact
-/workflow:lite-fix "User avatar upload fails with 413 error"
-/workflow:lite-fix "Shopping cart randomly loses items at checkout"
-
-# Hotfix mode: Production incident
-/workflow:lite-fix --hotfix "Payment gateway 5xx errors"
+ Bug description, error message, or path to .md file (required)
```
## Execution Process
```
-Input Parsing:
- └─ Parse flags: --hotfix → hotfixMode = true | false
+Phase 1: Bug Analysis & Diagnosis
+ |- Parse input (description, error message, or .md file)
+ |- Intelligent severity pre-assessment (Low/Medium/High/Critical)
+ |- Diagnosis decision (auto-detect or --hotfix flag)
+ |- Context protection: If file reading >=50k chars -> force cli-explore-agent
+ +- Decision:
+ |- needsDiagnosis=true -> Launch parallel cli-explore-agents (1-4 based on severity)
+ +- needsDiagnosis=false (hotfix) -> Skip directly to Phase 3 (Fix Planning)
-Phase 1: Diagnosis & Root Cause Analysis
- └─ Decision (confidence-based):
- ├─ High confidence (specific error) → Direct grep search (5min)
- ├─ Medium confidence → cli-explore-agent focused search (10-15min)
- └─ Low confidence (vague) → cli-explore-agent broad search (20min)
- └─ Hotfix mode: Minimal search (Read suspected file + git blame)
+Phase 2: Clarification (optional)
+ |- Aggregate clarification_needs from all diagnosis angles
+ |- Deduplicate similar questions
+ +- Decision:
+ |- Has clarifications -> AskUserQuestion (max 4 questions)
+ +- No clarifications -> Skip to Phase 3
-Phase 2: Impact Assessment & Severity Auto-Detection
- └─ Calculate risk_score → Auto-determine severity
- ├─ ≥8.0 → critical
- ├─ ≥5.0 → high
- ├─ ≥3.0 → medium
- └─ <3.0 → low
- └─ Hotfix mode: Skip, assume critical
+Phase 3: Fix Planning (NO CODE EXECUTION - planning only)
+ +- Decision (based on Phase 1 severity):
+ |- Low/Medium -> Load schema: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json -> Direct Claude planning (following schema) -> fix-plan.json -> MUST proceed to Phase 4
+ +- High/Critical -> cli-lite-planning-agent -> fix-plan.json -> MUST proceed to Phase 4
-Phase 3: Fix Planning & Strategy Selection
- └─ Decision (by risk score):
- ├─ risk_score ≥5.0 or hotfix → Single best strategy (fastest)
- └─ risk_score <5.0 → Multiple strategy options for user selection
+Phase 4: Confirmation & Selection
+ |- Display fix-plan summary (tasks, severity, estimated time)
+ +- AskUserQuestion:
+ |- Confirm: Allow / Modify / Cancel
+ |- Execution: Agent / Codex / Auto
+ +- Review: Gemini / Agent / Skip
-Phase 4: Verification Strategy
- └─ Select test scope by risk score
- └─ Define branch strategy (feature vs hotfix)
-
-Phase 5: User Confirmation
- └─ Default mode: 3 dimensions (approach, execution, verification)
- └─ Hotfix mode: 2 dimensions (deploy confirmation, monitoring)
-
-Phase 6: Execution Dispatch
- ├─ Export Enhanced Task JSON
- ├─ Dispatch to lite-execute --in-memory
- └─ Hotfix mode: Generate follow-up tasks
+Phase 5: Dispatch
+ |- Build executionContext (fix-plan + diagnoses + clarifications + selections)
+ +- SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")
```
-### Phase Summary
+## Implementation
-| Phase | Default Mode | Hotfix Mode |
-|-------|--------------|-------------|
-| 1. Diagnosis | Adaptive search depth | Minimal (known issue) |
-| 2. Impact Assessment | Full risk scoring | Critical path only |
-| 3. Fix Planning | Strategy options based on complexity | Single surgical fix |
-| 4. Verification | Test level matches risk score | Smoke tests only |
-| 5. User Confirmation | 3 dimensions | 2 dimensions |
-| 6. Execution | Via lite-execute | Via lite-execute + monitoring |
+### Phase 1: Intelligent Multi-Angle Diagnosis
----
-
-## Detailed Phase Execution
-
-### Input Parsing
-
-**Parse --hotfix flag**:
+**Session Setup**:
```javascript
-const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h')
-const bugDescription = $ARGUMENTS.replace(/--hotfix|-h/g, '').trim()
-```
-
-### Phase 1: Diagnosis & Root Cause Analysis
-
-**Goal**: Identify root cause and affected code paths
-
-**Session Folder Setup**:
-```javascript
-// Generate session identifiers for artifact storage
const bugSlug = bug_description.toLowerCase().replace(/[^a-z0-9]+/g, '-').substring(0, 40)
const timestamp = new Date().toISOString().replace(/[:.]/g, '-')
-const shortTimestamp = timestamp.substring(0, 19).replace('T', '-') // YYYY-MM-DD-HH-mm-ss
+const shortTimestamp = timestamp.substring(0, 19).replace('T', '-')
const sessionId = `${bugSlug}-${shortTimestamp}`
const sessionFolder = `.workflow/.lite-fix/${sessionId}`
+
+bash(`mkdir -p ${sessionFolder}`)
```
-**Execution Strategy**:
-
-**Default Mode** - Adaptive search:
-- **High confidence keywords** (e.g., specific error messages): Direct grep search (5min)
-- **Medium confidence**: cli-explore-agent with focused search (10-15min)
-- **Low confidence** (vague symptoms): cli-explore-agent with broad search (20min)
-
+**Diagnosis Decision Logic**:
```javascript
-// Confidence-based strategy selection
-if (has_specific_error_message || has_file_path_hint) {
- // Quick targeted search
- grep -r '${error_message}' src/ --include='*.ts' -n | head -10
- git log --oneline --since='1 week ago' -- '*affected*'
-} else {
- // Deep exploration
- Task(subagent_type="cli-explore-agent", prompt=`
- Bug: ${bug_description}
- Execute diagnostic search:
- 1. Search error patterns and similar issues
- 2. Trace execution path in affected modules
- 3. Check recent changes
- Return: Root cause hypothesis, affected paths, reproduction steps
- `)
+const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h')
+
+needsDiagnosis = (
+ !hotfixMode &&
+ (
+ bug.lacks_specific_error_message ||
+ bug.requires_codebase_context ||
+ bug.needs_execution_tracing ||
+ bug.root_cause_unclear
+ )
+)
+
+if (!needsDiagnosis) {
+ // Skip to Phase 2 (Clarification) or Phase 3 (Fix Planning)
+ proceed_to_next_phase()
}
```
-**Hotfix Mode** - Minimal search:
-```bash
-Read(suspected_file) # User typically knows the file
-git blame ${suspected_file}
-```
+**Context Protection**: File reading >=50k chars -> force `needsDiagnosis=true` (delegate to cli-explore-agent)
-**Output Structure**:
+**Severity Pre-Assessment** (Intelligent Analysis):
```javascript
-diagnosisContext = {
- symptom: string,
- error_message: string | null,
- keywords: string[],
- confidence_level: "high" | "medium" | "low",
- root_cause: {
- file: "src/auth/tokenValidator.ts",
- line_range: "45-52",
- issue: "Token expiration check uses wrong comparison",
- introduced_by: "commit abc123"
- },
- reproduction_steps: ["Login", "Wait 15min", "Access protected route"],
- affected_scope: {
- users: "All authenticated users",
- features: ["login", "API access"],
- data_risk: "none"
- }
+// Analyzes bug severity based on:
+// - Symptoms: Error messages, crash reports, user complaints
+// - Scope: How many users/features are affected?
+// - Urgency: Production down vs minor inconvenience
+// - Impact: Data loss, security, business impact
+
+const severity = analyzeBugSeverity(bug_description)
+// Returns: 'Low' | 'Medium' | 'High' | 'Critical'
+// Low: Minor UI issue, localized, no data impact
+// Medium: Multiple users affected, degraded functionality
+// High: Significant functionality broken, many users affected
+// Critical: Production down, data loss risk, security issue
+
+// Angle assignment based on bug type (orchestrator decides, not agent)
+const DIAGNOSIS_ANGLE_PRESETS = {
+ runtime_error: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
+ performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
+ security: ['security', 'auth-patterns', 'dataflow', 'validation'],
+ data_corruption: ['data-integrity', 'state-management', 'transactions', 'validation'],
+ ui_bug: ['state-management', 'event-handling', 'rendering', 'data-binding'],
+ integration: ['api-contracts', 'error-handling', 'timeouts', 'fallbacks']
}
-// Save diagnosis results for CLI/agent access in lite-execute
-const diagnosisFile = `${sessionFolder}/diagnosis.json`
-Write(diagnosisFile, JSON.stringify(diagnosisContext, null, 2))
+function selectDiagnosisAngles(bugDescription, count) {
+ const text = bugDescription.toLowerCase()
+ let preset = 'runtime_error' // default
+
+ if (/slow|timeout|performance|lag|hang/.test(text)) preset = 'performance'
+ else if (/security|auth|permission|access|token/.test(text)) preset = 'security'
+ else if (/corrupt|data|lost|missing|inconsistent/.test(text)) preset = 'data_corruption'
+ else if (/ui|display|render|style|click|button/.test(text)) preset = 'ui_bug'
+ else if (/api|integration|connect|request|response/.test(text)) preset = 'integration'
+
+ return DIAGNOSIS_ANGLE_PRESETS[preset].slice(0, count)
+}
+
+const selectedAngles = selectDiagnosisAngles(bug_description, severity === 'Critical' ? 4 : (severity === 'High' ? 3 : (severity === 'Medium' ? 2 : 1)))
+
+console.log(`
+## Diagnosis Plan
+
+Bug Severity: ${severity}
+Selected Angles: ${selectedAngles.join(', ')}
+
+Launching ${selectedAngles.length} parallel diagnoses...
+`)
```
-**Output**: `diagnosisContext` (in-memory)
-**Artifact**: Saved to `{sessionFolder}/diagnosis.json` for CLI/agent use
+**Launch Parallel Diagnoses** - Orchestrator assigns angle to each agent:
-**TodoWrite**: Mark Phase 1 completed, Phase 2 in_progress
+```javascript
+// Launch agents with pre-assigned diagnosis angles
+const diagnosisTasks = selectedAngles.map((angle, index) =>
+ Task(
+ subagent_type="cli-explore-agent",
+ description=`Diagnose: ${angle}`,
+ prompt=`
+## Task Objective
+Execute **${angle}** diagnosis for bug root cause analysis. Analyze codebase from this specific angle to discover root cause, affected paths, and fix hints.
+
+## Assigned Context
+- **Diagnosis Angle**: ${angle}
+- **Bug Description**: ${bug_description}
+- **Diagnosis Index**: ${index + 1} of ${selectedAngles.length}
+- **Output File**: ${sessionFolder}/diagnosis-${angle}.json
+
+## MANDATORY FIRST STEPS (Execute by Agent)
+**You (cli-explore-agent) MUST execute these steps in order:**
+1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
+2. Run: rg -l "{error_keyword_from_bug}" --type ts (locate relevant files)
+3. Execute: cat ~/.claude/workflows/cli-templates/schemas/diagnosis-json-schema.json (get output schema reference)
+
+## Diagnosis Strategy (${angle} focus)
+
+**Step 1: Error Tracing** (Bash)
+- rg for error messages, stack traces, log patterns
+- git log --since='2 weeks ago' for recent changes
+- Trace execution path in affected modules
+
+**Step 2: Root Cause Analysis** (Gemini CLI)
+- What code paths lead to this ${angle} issue?
+- What edge cases are not handled from ${angle} perspective?
+- What recent changes might have introduced this bug?
+
+**Step 3: Write Output**
+- Consolidate ${angle} findings into JSON
+- Identify ${angle}-specific clarification needs
+- Provide fix hints based on ${angle} analysis
+
+## Expected Output
+
+**File**: ${sessionFolder}/diagnosis-${angle}.json
+
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
+
+**Required Fields** (all ${angle} focused):
+- symptom: Bug symptoms and error messages
+- root_cause: Root cause hypothesis from ${angle} perspective
+ **IMPORTANT**: Use structured format:
+ \`{file: "src/module/file.ts", line_range: "45-60", issue: "Description", confidence: 0.85}\`
+- affected_files: Files involved from ${angle} perspective
+ **IMPORTANT**: Use object format with relevance scores:
+ \`[{path: "src/file.ts", relevance: 0.85, rationale: "Contains ${angle} logic"}]\`
+- reproduction_steps: Steps to reproduce the bug
+- fix_hints: Suggested fix approaches from ${angle} viewpoint
+- dependencies: Dependencies relevant to ${angle} diagnosis
+- constraints: ${angle}-specific limitations affecting fix
+- clarification_needs: ${angle}-related ambiguities (with options array)
+- _metadata.diagnosis_angle: "${angle}"
+- _metadata.diagnosis_index: ${index + 1}
+
+## Success Criteria
+- [ ] Schema obtained via cat diagnosis-json-schema.json
+- [ ] get_modules_by_depth.sh executed
+- [ ] Root cause identified with confidence score
+- [ ] At least 3 affected files identified with ${angle} rationale
+- [ ] Fix hints are actionable (specific code changes, not generic advice)
+- [ ] Reproduction steps are verifiable
+- [ ] JSON output follows schema exactly
+- [ ] clarification_needs includes options array
+
+## Output
+Write: ${sessionFolder}/diagnosis-${angle}.json
+Return: 2-3 sentence summary of ${angle} diagnosis findings
+`
+ )
+)
+
+// Execute all diagnosis tasks in parallel
+```
+
+**Auto-discover Generated Diagnosis Files**:
+```javascript
+// After diagnoses complete, auto-discover all diagnosis-*.json files
+const diagnosisFiles = bash(`find ${sessionFolder} -name "diagnosis-*.json" -type f`)
+ .split('\n')
+ .filter(f => f.trim())
+
+// Read metadata to build manifest
+const diagnosisManifest = {
+ session_id: sessionId,
+ bug_description: bug_description,
+ timestamp: new Date().toISOString(),
+ severity: severity,
+ diagnosis_count: diagnosisFiles.length,
+ diagnoses: diagnosisFiles.map(file => {
+ const data = JSON.parse(Read(file))
+ const filename = path.basename(file)
+ return {
+ angle: data._metadata.diagnosis_angle,
+ file: filename,
+ path: file,
+ index: data._metadata.diagnosis_index
+ }
+ })
+}
+
+Write(`${sessionFolder}/diagnoses-manifest.json`, JSON.stringify(diagnosisManifest, null, 2))
+
+console.log(`
+## Diagnosis Complete
+
+Generated diagnosis files in ${sessionFolder}:
+${diagnosisManifest.diagnoses.map(d => `- diagnosis-${d.angle}.json (angle: ${d.angle})`).join('\n')}
+
+Manifest: diagnoses-manifest.json
+Angles diagnosed: ${diagnosisManifest.diagnoses.map(d => d.angle).join(', ')}
+`)
+```
+
+**Output**:
+- `${sessionFolder}/diagnosis-{angle1}.json`
+- `${sessionFolder}/diagnosis-{angle2}.json`
+- ... (1-4 files based on severity)
+- `${sessionFolder}/diagnoses-manifest.json`
---
-### Phase 2: Impact Assessment & Severity Auto-Detection
+### Phase 2: Clarification (Optional)
-**Goal**: Quantify blast radius and auto-determine severity
+**Skip if**: No diagnosis or `clarification_needs` is empty across all diagnoses
-**Risk Score Calculation**:
+**Aggregate clarification needs from all diagnosis angles**:
```javascript
-risk_score = (user_impact × 0.4) + (system_risk × 0.3) + (business_impact × 0.3)
+// Load manifest and all diagnosis files
+const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`))
+const diagnoses = manifest.diagnoses.map(diag => ({
+ angle: diag.angle,
+ data: JSON.parse(Read(diag.path))
+}))
-// Auto-severity mapping
-if (risk_score >= 8.0) severity = "critical"
-else if (risk_score >= 5.0) severity = "high"
-else if (risk_score >= 3.0) severity = "medium"
-else severity = "low"
-
-// Workflow adaptation
-if (severity >= "high") {
- diagnosis_depth = "focused"
- test_strategy = "smoke_and_critical"
- review_optional = true
-} else {
- diagnosis_depth = "comprehensive"
- test_strategy = "full_suite"
- review_optional = false
-}
-```
-
-**Assessment Output**:
-```javascript
-impactContext = {
- affected_users: {
- count: "5000 active users (100%)",
- severity: "high"
- },
- system_risk: {
- availability: "degraded_30%",
- cascading_failures: "possible_logout_storm"
- },
- business_impact: {
- revenue: "medium",
- reputation: "high",
- sla_breach: "yes"
- },
- risk_score: 7.1,
- severity: "high",
- workflow_adaptation: {
- test_strategy: "focused_integration",
- review_required: false,
- time_budget: "1_hour"
+// Aggregate clarification needs from all diagnoses
+const allClarifications = []
+diagnoses.forEach(diag => {
+ if (diag.data.clarification_needs?.length > 0) {
+ diag.data.clarification_needs.forEach(need => {
+ allClarifications.push({
+ ...need,
+ source_angle: diag.angle
+ })
+ })
}
+})
+
+// Deduplicate by question similarity
+function deduplicateClarifications(clarifications) {
+ const unique = []
+ clarifications.forEach(c => {
+ const isDuplicate = unique.some(u =>
+ u.question.toLowerCase() === c.question.toLowerCase()
+ )
+ if (!isDuplicate) unique.push(c)
+ })
+ return unique
}
-// Save impact assessment for CLI/agent access
-const impactFile = `${sessionFolder}/impact.json`
-Write(impactFile, JSON.stringify(impactContext, null, 2))
-```
+const uniqueClarifications = deduplicateClarifications(allClarifications)
-**Output**: `impactContext` (in-memory)
-**Artifact**: Saved to `{sessionFolder}/impact.json` for CLI/agent use
-
-**Hotfix Mode**: Skip detailed assessment, assume critical
-
-**TodoWrite**: Mark Phase 2 completed, Phase 3 in_progress
-
----
-
-### Phase 3: Fix Planning & Strategy Selection
-
-**Goal**: Generate fix options with trade-off analysis
-
-**Strategy Generation**:
-
-**Default Mode** - Complexity-adaptive:
-- **Low risk score (<5.0)**: Generate 2-3 strategy options for user selection
-- **High risk score (≥5.0)**: Generate single best strategy for speed
-
-```javascript
-strategies = generateFixStrategies(root_cause, risk_score)
-
-if (risk_score >= 5.0 || mode === "hotfix") {
- // Single best strategy
- return strategies[0] // Fastest viable fix
-} else {
- // Multiple options with trade-offs
- return strategies // Let user choose
-}
-```
-
-**Example Strategies**:
-```javascript
-// Low risk: Multiple options
-[
- {
- strategy: "immediate_patch",
- description: "Fix comparison operator",
- estimated_time: "15 minutes",
- risk: "low",
- pros: ["Quick fix"],
- cons: ["Doesn't address underlying issue"]
- },
- {
- strategy: "comprehensive_fix",
- description: "Refactor token validation logic",
- estimated_time: "2 hours",
- risk: "medium",
- pros: ["Addresses root cause"],
- cons: ["Longer implementation"]
- }
-]
-
-// High risk or hotfix: Single option
-{
- strategy: "surgical_fix",
- description: "Minimal change to fix comparison",
- files: ["src/auth/tokenValidator.ts:47"],
- estimated_time: "5 minutes",
- risk: "minimal"
-}
-```
-
-**Complexity Assessment**:
-```javascript
-if (complexity === "high" && risk_score < 5.0) {
- suggestCommand("/workflow:plan --mode bugfix")
- return // Escalate to full planning
-}
-
-// Save fix plan for CLI/agent access
-const planFile = `${sessionFolder}/fix-plan.json`
-Write(planFile, JSON.stringify(fixPlan, null, 2))
-```
-
-**Output**: `fixPlan` (in-memory)
-**Artifact**: Saved to `{sessionFolder}/fix-plan.json` for CLI/agent use
-
-**TodoWrite**: Mark Phase 3 completed, Phase 4 in_progress
-
----
-
-### Phase 4: Verification Strategy
-
-**Goal**: Define testing approach based on severity
-
-**Adaptive Test Strategy**:
-
-| Risk Score | Test Scope | Duration | Automation |
-|------------|------------|----------|------------|
-| **< 3.0** (Low) | Full test suite | 15-20 min | `npm test` |
-| **3.0-5.0** (Medium) | Focused integration | 8-12 min | `npm test -- affected-module.test.ts` |
-| **5.0-8.0** (High) | Smoke + critical | 5-8 min | `npm test -- critical.smoke.test.ts` |
-| **≥ 8.0** (Critical) | Smoke only | 2-5 min | `npm test -- smoke.test.ts` |
-| **Hotfix** | Production smoke | 2-3 min | `npm test -- production.smoke.test.ts` |
-
-**Branch Strategy**:
-
-**Default Mode**:
-```javascript
-{
- type: "feature_branch",
- base: "main",
- name: "fix/token-expiration-edge-case",
- merge_target: "main"
-}
-```
-
-**Hotfix Mode**:
-```javascript
-{
- type: "hotfix_branch",
- base: "production_tag_v2.3.1", // ⚠️ From production tag
- name: "hotfix/token-validation-fix",
- merge_target: ["main", "production"] // Dual merge
-}
-```
-
-**TodoWrite**: Mark Phase 4 completed, Phase 5 in_progress
-
----
-
-### Phase 5: User Confirmation & Execution Selection
-
-**Adaptive Confirmation Dimensions**:
-
-**Default Mode** - 3 dimensions (adapted by risk score):
-
-```javascript
-dimensions = [
- {
- question: "Confirm fix approach?",
- options: ["Proceed", "Modify", "Escalate to /workflow:plan"]
- },
- {
- question: "Execution method:",
- options: ["Agent", "CLI Tool (Codex/Gemini)", "Manual (plan only)"]
- },
- {
- question: "Verification level:",
- options: adaptedByRiskScore() // Auto-suggest based on Phase 2
- }
-]
-
-// If risk_score >= 5.0, auto-skip code review dimension
-// If risk_score < 5.0, add optional code review dimension
-if (risk_score < 5.0) {
- dimensions.push({
- question: "Post-fix review:",
- options: ["Gemini", "Skip"]
+if (uniqueClarifications.length > 0) {
+ AskUserQuestion({
+ questions: uniqueClarifications.map(need => ({
+ question: `[${need.source_angle}] ${need.question}\n\nContext: ${need.context}`,
+ header: need.source_angle,
+ multiSelect: false,
+ options: need.options.map(opt => ({
+ label: opt,
+ description: `Use ${opt} approach`
+ }))
+ }))
})
}
```
-**Hotfix Mode** - 2 dimensions (minimal):
-```javascript
-[
- {
- question: "Confirm hotfix deployment:",
- options: ["Deploy", "Stage First", "Abort"]
- },
- {
- question: "Post-deployment monitoring:",
- options: ["Real-time (15 min)", "Passive (alerts only)"]
- }
-]
-```
-
-**TodoWrite**: Mark Phase 5 completed, Phase 6 in_progress
+**Output**: `clarificationContext` (in-memory)
---
-### Phase 6: Execution Dispatch & Follow-up
+### Phase 3: Fix Planning
-**Export Enhanced Task JSON**:
+**Planning Strategy Selection** (based on Phase 1 severity):
+**IMPORTANT**: Phase 3 is **planning only** - NO code execution. All execution happens in Phase 5 via lite-execute.
+
+**Low/Medium Severity** - Direct planning by Claude:
```javascript
-const taskId = `BUGFIX-${shortTimestamp}`
-const taskFile = `${sessionFolder}/task.json`
+// Step 1: Read schema
+const schema = Bash(`cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json`)
-const enhancedTaskJson = {
- id: taskId,
- title: bug_description,
- status: "pending",
-
- meta: {
- type: "bugfix",
- created_at: new Date().toISOString(),
- severity: impactContext.severity,
- risk_score: impactContext.risk_score,
- estimated_time: fixPlan.estimated_time,
- workflow: mode === "hotfix" ? "lite-fix-hotfix" : "lite-fix",
- session_id: sessionId,
- session_folder: sessionFolder
- },
-
- context: {
- requirements: [bug_description],
- diagnosis: diagnosisContext,
- impact: impactContext,
- plan: fixPlan,
- verification_strategy: verificationStrategy,
- branch_strategy: branchStrategy
- }
+// Step 2: Generate fix-plan following schema (Claude directly, no agent)
+const fixPlan = {
+ summary: "...",
+ root_cause: "...",
+ strategy: "immediate_patch|comprehensive_fix|refactor",
+ tasks: [...], // Each task: { id, title, scope, ..., depends_on, complexity }
+ estimated_time: "...",
+ recommended_execution: "Agent",
+ severity: severity,
+ risk_level: "...",
+ _metadata: { timestamp: new Date().toISOString(), source: "direct-planning", planning_mode: "direct" }
}
-Write(taskFile, JSON.stringify(enhancedTaskJson, null, 2))
+// Step 3: Write fix-plan to session folder
+Write(`${sessionFolder}/fix-plan.json`, JSON.stringify(fixPlan, null, 2))
+
+// Step 4: MUST continue to Phase 4 (Confirmation) - DO NOT execute code here
```
-**Dispatch to lite-execute**:
+**High/Critical Severity** - Invoke cli-lite-planning-agent:
```javascript
+Task(
+ subagent_type="cli-lite-planning-agent",
+ description="Generate detailed fix plan",
+ prompt=`
+Generate fix plan and write fix-plan.json.
+
+## Output Schema Reference
+Execute: cat ~/.claude/workflows/cli-templates/schemas/fix-plan-json-schema.json (get schema reference before generating plan)
+
+## Bug Description
+${bug_description}
+
+## Multi-Angle Diagnosis Context
+
+${manifest.diagnoses.map(diag => `### Diagnosis: ${diag.angle} (${diag.file})
+Path: ${diag.path}
+
+Read this file for detailed ${diag.angle} analysis.`).join('\n\n')}
+
+Total diagnoses: ${manifest.diagnosis_count}
+Angles covered: ${manifest.diagnoses.map(d => d.angle).join(', ')}
+
+Manifest: ${sessionFolder}/diagnoses-manifest.json
+
+## User Clarifications
+${JSON.stringify(clarificationContext) || "None"}
+
+## Severity Level
+${severity}
+
+## Requirements
+Generate fix-plan.json with:
+- summary: 2-3 sentence overview of the fix
+- root_cause: Consolidated root cause from all diagnoses
+- strategy: "immediate_patch" | "comprehensive_fix" | "refactor"
+- tasks: 1-5 structured fix tasks (**IMPORTANT: group by fix area, NOT by file**)
+ - **Task Granularity Principle**: Each task = one complete fix unit
+ - title: action verb + target (e.g., "Fix token validation edge case")
+ - scope: module path (src/auth/) or feature name
+ - action: "Fix" | "Update" | "Refactor" | "Add" | "Delete"
+ - description
+ - modification_points: ALL files to modify for this fix (group related changes)
+ - implementation (2-5 steps covering all modification_points)
+ - verification (test criteria)
+ - depends_on: task IDs this task depends on (use sparingly)
+- estimated_time, recommended_execution, severity, risk_level
+- _metadata:
+ - timestamp, source, planning_mode
+ - diagnosis_angles: ${JSON.stringify(manifest.diagnoses.map(d => d.angle))}
+
+## Task Grouping Rules
+1. **Group by fix area**: All changes for one fix = one task (even if 2-3 files)
+2. **Avoid file-per-task**: Do NOT create separate tasks for each file
+3. **Substantial tasks**: Each task should represent 10-45 minutes of work
+4. **True dependencies only**: Only use depends_on when Task B cannot start without Task A's output
+5. **Prefer parallel**: Most tasks should be independent (no depends_on)
+
+## Execution
+1. Read ALL diagnosis files for comprehensive context
+2. Execute CLI planning using Gemini (Qwen fallback)
+3. Synthesize findings from multiple diagnosis angles
+4. Parse output and structure fix-plan
+5. Write JSON: Write('${sessionFolder}/fix-plan.json', jsonContent)
+6. Return brief completion summary
+`
+)
+```
+
+**Output**: `${sessionFolder}/fix-plan.json`
+
+---
+
+### Phase 4: Task Confirmation & Execution Selection
+
+**Step 4.1: Display Fix Plan**
+```javascript
+const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`))
+
+console.log(`
+## Fix Plan
+
+**Summary**: ${fixPlan.summary}
+**Root Cause**: ${fixPlan.root_cause}
+**Strategy**: ${fixPlan.strategy}
+
+**Tasks** (${fixPlan.tasks.length}):
+${fixPlan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')}
+
+**Severity**: ${fixPlan.severity}
+**Risk Level**: ${fixPlan.risk_level}
+**Estimated Time**: ${fixPlan.estimated_time}
+**Recommended**: ${fixPlan.recommended_execution}
+`)
+```
+
+**Step 4.2: Collect Confirmation**
+```javascript
+AskUserQuestion({
+ questions: [
+ {
+ question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`,
+ header: "Confirm",
+ multiSelect: true,
+ options: [
+ { label: "Allow", description: "Proceed as-is" },
+ { label: "Modify", description: "Adjust before execution" },
+ { label: "Cancel", description: "Abort workflow" }
+ ]
+ },
+ {
+ question: "Execution method:",
+ header: "Execution",
+ multiSelect: false,
+ options: [
+ { label: "Agent", description: "@code-developer agent" },
+ { label: "Codex", description: "codex CLI tool" },
+ { label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` }
+ ]
+ },
+ {
+ question: "Code review after fix?",
+ header: "Review",
+ multiSelect: false,
+ options: [
+ { label: "Gemini Review", description: "Gemini CLI" },
+ { label: "Agent Review", description: "@code-reviewer" },
+ { label: "Skip", description: "No review" }
+ ]
+ }
+ ]
+})
+```
+
+---
+
+### Phase 5: Dispatch to Execution
+
+**CRITICAL**: lite-fix NEVER executes code directly. ALL execution MUST go through lite-execute.
+
+**Step 5.1: Build executionContext**
+
+```javascript
+// Load manifest and all diagnosis files
+const manifest = JSON.parse(Read(`${sessionFolder}/diagnoses-manifest.json`))
+const diagnoses = {}
+
+manifest.diagnoses.forEach(diag => {
+ if (file_exists(diag.path)) {
+ diagnoses[diag.angle] = JSON.parse(Read(diag.path))
+ }
+})
+
+const fixPlan = JSON.parse(Read(`${sessionFolder}/fix-plan.json`))
+
executionContext = {
mode: "bugfix",
- severity: impactContext.severity,
+ severity: fixPlan.severity,
planObject: fixPlan,
- diagnosisContext: diagnosisContext,
- impactContext: impactContext,
- verificationStrategy: verificationStrategy,
- branchStrategy: branchStrategy,
- executionMethod: user_selection.execution_method,
-
- // Session artifacts location
+ diagnosisContext: diagnoses,
+ diagnosisAngles: manifest.diagnoses.map(d => d.angle),
+ diagnosisManifest: manifest,
+ clarificationContext: clarificationContext || null,
+ executionMethod: userSelection.execution_method,
+ codeReviewTool: userSelection.code_review_tool,
+ originalUserInput: bug_description,
session: {
id: sessionId,
folder: sessionFolder,
artifacts: {
- diagnosis: `${sessionFolder}/diagnosis.json`,
- impact: `${sessionFolder}/impact.json`,
- plan: `${sessionFolder}/fix-plan.json`,
- task: `${sessionFolder}/task.json`
- }
- }
-}
-
-SlashCommand("/workflow:lite-execute --in-memory --mode bugfix")
-```
-
-**Hotfix Auto Follow-up**:
-
-```javascript
-if (mode === "hotfix") {
- follow_up_tasks = [
- {
- id: `FOLLOWUP-${taskId}-comprehensive`,
- title: "Replace hotfix with comprehensive fix",
- priority: "high",
- due_date: "within_3_days",
- description: "Refactor quick hotfix into proper solution with full test coverage"
- },
- {
- id: `FOLLOWUP-${taskId}-postmortem`,
- title: "Incident postmortem",
- priority: "medium",
- due_date: "within_1_week",
- sections: ["Timeline", "Root cause", "Prevention measures"]
- }
- ]
-
- Write(`${sessionFolder}/followup.json`, follow_up_tasks)
-
- console.log(`
- ⚠️ Hotfix follow-up tasks generated:
- - Comprehensive fix: ${follow_up_tasks[0].id} (due in 3 days)
- - Postmortem: ${follow_up_tasks[1].id} (due in 1 week)
- - Location: ${sessionFolder}/followup.json
- `)
-}
-```
-
-**TodoWrite**: Mark Phase 6 completed
-
----
-
-## Data Structures
-
-### diagnosisContext
-```javascript
-{
- symptom: string,
- error_message: string | null,
- keywords: string[],
- confidence_level: "high" | "medium" | "low", // Search confidence
- root_cause: {
- file: string,
- line_range: string,
- issue: string,
- introduced_by: string
- },
- reproduction_steps: string[],
- affected_scope: {...}
-}
-```
-
-### impactContext
-```javascript
-{
- affected_users: { count: string, severity: string },
- system_risk: { availability: string, cascading_failures: string },
- business_impact: { revenue: string, reputation: string, sla_breach: string },
- risk_score: number, // 0-10
- severity: "low" | "medium" | "high" | "critical",
- workflow_adaptation: {
- diagnosis_depth: string,
- test_strategy: string,
- review_optional: boolean,
- time_budget: string
- }
-}
-```
-
-### fixPlan
-```javascript
-{
- strategy: string,
- summary: string,
- tasks: [{
- title: string,
- file: string,
- action: "Update" | "Create" | "Delete",
- implementation: string[],
- verification: string[]
- }],
- estimated_time: string,
- recommended_execution: "Agent" | "CLI" | "Manual"
-}
-```
-
-### executionContext
-
-Context passed to lite-execute via --in-memory (Phase 6):
-
-```javascript
-{
- mode: "bugfix",
- severity: "high" | "medium" | "low" | "critical",
-
- // Core data objects
- planObject: {...}, // Complete fixPlan (see above)
- diagnosisContext: {...}, // Complete diagnosisContext (see above)
- impactContext: {...}, // Complete impactContext (see above)
-
- // Verification and branch strategies
- verificationStrategy: {...},
- branchStrategy: {...},
- executionMethod: "Agent" | "CLI" | "Manual",
-
- // Session artifacts location (for lite-execute to access saved files)
- session: {
- id: string, // Session identifier: {bugSlug}-{shortTimestamp}
- folder: string, // Session folder path: .workflow/.lite-fix/{session-id}
- artifacts: {
- diagnosis: string, // diagnosis.json path
- impact: string, // impact.json path
- plan: string, // fix-plan.json path
- task: string // task.json path
+ diagnoses: manifest.diagnoses.map(diag => ({
+ angle: diag.angle,
+ path: diag.path
+ })),
+ diagnoses_manifest: `${sessionFolder}/diagnoses-manifest.json`,
+ fix_plan: `${sessionFolder}/fix-plan.json`
}
}
}
```
-### Enhanced Task JSON Export
+**Step 5.2: Dispatch**
-Task JSON structure exported in Phase 6:
-
-```json
-{
- "id": "BUGFIX-{timestamp}",
- "title": "Original bug description",
- "status": "pending",
-
- "meta": {
- "type": "bugfix",
- "created_at": "ISO timestamp",
- "severity": "low|medium|high|critical",
- "risk_score": 7.1,
- "estimated_time": "X minutes",
- "workflow": "lite-fix|lite-fix-hotfix",
- "session_id": "{bugSlug}-{shortTimestamp}",
- "session_folder": ".workflow/.lite-fix/{session-id}"
- },
-
- "context": {
- "requirements": ["Original bug description"],
- "diagnosis": {/* diagnosisContext */},
- "impact": {/* impactContext */},
- "plan": {/* fixPlan */},
- "verification_strategy": {/* test strategy */},
- "branch_strategy": {/* branch strategy */}
- }
-}
+```javascript
+SlashCommand(command="/workflow:lite-execute --in-memory --mode bugfix")
```
-**Schema Notes**:
-- Aligns with Enhanced Task JSON Schema (6-field structure)
-- `context_package_path` omitted (not used by lite-fix)
-- `flow_control` omitted (handled by lite-execute)
-
----
-
-## Best Practices
-
-### When to Use Default Mode
-
-**Use for all standard bugs:**
-- Automatically adapts to severity (no manual mode selection needed)
-- Risk score determines workflow complexity
-- Handles 90% of bug fixing scenarios
-
-**Typical scenarios:**
-- UI bugs, logic errors, edge cases
-- Performance issues (non-critical)
-- Integration failures
-- Data validation bugs
-
-### When to Use Hotfix Mode
-
-**Only use for production incidents:**
-- Production is down or critically degraded
-- Revenue/reputation at immediate risk
-- SLA breach occurring
-- Issue is well-understood (minimal diagnosis needed)
-
-**Hotfix characteristics:**
-- Creates hotfix branch from production tag
-- Minimal diagnosis (assumes known issue)
-- Smoke tests only
-- Auto-generates follow-up tasks
-- Requires incident tracking
-
-### Branching Strategy
-
-**Default Mode (feature branch)**:
-```bash
-# Standard feature branch workflow
-git checkout -b fix/issue-description main
-# ... implement fix
-git checkout main && git merge fix/issue-description
-```
-
-**Hotfix Mode (dual merge)**:
-```bash
-# ✅ Correct: Branch from production tag
-git checkout -b hotfix/fix-name v2.3.1
-
-# Merge to both targets
-git checkout main && git merge hotfix/fix-name
-git checkout production && git merge hotfix/fix-name
-git tag v2.3.2
-
-# ❌ Wrong: Branch from main
-git checkout -b hotfix/fix-name main # Contains unreleased code!
-```
-
----
-
-## Error Handling
-
-| Error | Cause | Resolution |
-|-------|-------|------------|
-| Root cause unclear | Vague symptoms | Extend diagnosis time or use /cli:mode:bug-diagnosis |
-| Multiple potential causes | Complex interaction | Use /cli:discuss-plan for analysis |
-| Fix too complex | High-risk refactor | Escalate to /workflow:plan --mode bugfix |
-| High risk score but unsure | Uncertain severity | Default mode will adapt, proceed normally |
-
----
-
## Session Folder Structure
-Each lite-fix execution creates a dedicated session folder to organize all artifacts:
-
```
-.workflow/.lite-fix/{bug-slug}-{short-timestamp}/
-├── diagnosis.json # Phase 1: Root cause analysis
-├── impact.json # Phase 2: Impact assessment
-├── fix-plan.json # Phase 3: Fix strategy
-├── task.json # Phase 6: Enhanced Task JSON
-└── followup.json # Hotfix mode only: Follow-up tasks
+.workflow/.lite-fix/{bug-slug}-{timestamp}/
+|- diagnosis-{angle1}.json # Diagnosis angle 1
+|- diagnosis-{angle2}.json # Diagnosis angle 2
+|- diagnosis-{angle3}.json # Diagnosis angle 3 (if applicable)
+|- diagnosis-{angle4}.json # Diagnosis angle 4 (if applicable)
+|- diagnoses-manifest.json # Diagnosis index
++- fix-plan.json # Fix plan
```
-**Folder Naming Convention**:
-- `{bug-slug}`: First 40 characters of bug description, lowercased, non-alphanumeric replaced with `-`
-- `{short-timestamp}`: YYYY-MM-DD-HH-mm-ss format
-- Example: `.workflow/.lite-fix/user-avatar-upload-fails-413-2025-01-15-14-30-45/`
-
-**File Contents**:
-- `diagnosis.json`: Complete diagnosisContext object (Phase 1)
-- `impact.json`: Complete impactContext object (Phase 2)
-- `fix-plan.json`: Complete fixPlan object (Phase 3)
-- `task.json`: Enhanced Task JSON with all context (Phase 6)
-- `followup.json`: Follow-up tasks (hotfix mode only)
-
-**Access Patterns**:
-- **lite-fix**: Creates folder and writes all artifacts during execution, passes paths via `executionContext.session.artifacts`
-- **lite-execute**: Reads artifact paths from `executionContext.session.artifacts`
-- **User**: Can inspect artifacts for debugging or reference
-- **Reuse**: Pass `task.json` path to `/workflow:lite-execute {path}` for re-execution
-
-
-
-**Legacy Cache** (deprecated, use session folder instead):
+**Example**:
```
-.workflow/.lite-fix-cache/
-└── diagnosis-cache/
- └── ${bug_hash}.json
+.workflow/.lite-fix/user-avatar-upload-fails-413-2025-11-25-14-30-25/
+|- diagnosis-error-handling.json
+|- diagnosis-dataflow.json
+|- diagnosis-validation.json
+|- diagnoses-manifest.json
++- fix-plan.json
```
+## Error Handling
-## Quality Gates
+| Error | Resolution |
+|-------|------------|
+| Diagnosis agent failure | Skip diagnosis, continue with bug description only |
+| Planning agent failure | Fallback to direct planning by Claude |
+| Clarification timeout | Use diagnosis findings as-is |
+| Confirmation timeout | Save context, display resume instructions |
+| Modify loop > 3 times | Suggest breaking task or using /workflow:plan |
+| Root cause unclear | Extend diagnosis time or use broader angles |
+| Too complex for lite-fix | Escalate to /workflow:plan --mode bugfix |
-**Before execution** (auto-checked):
-- [ ] Root cause identified (>70% confidence for default, >90% for hotfix)
-- [ ] Impact scope defined
-- [ ] Fix strategy reviewed
-- [ ] Verification plan matches risk level
-**Hotfix-specific**:
-- [ ] Production tag identified
-- [ ] Rollback plan documented
-- [ ] Follow-up tasks generated
-- [ ] Monitoring configured
-
----
-
-## When to Use lite-fix
-
-✅ **Perfect for:**
-- Any bug with clear symptoms
-- Localized fixes (1-5 files)
-- Known technology stack
-- Time-sensitive but not catastrophic (default mode adapts)
-- Production incidents (use --hotfix)
-
-❌ **Not suitable for:**
-- Root cause completely unclear → use `/cli:mode:bug-diagnosis` first
-- Requires architectural changes → use `/workflow:plan`
-- Complex legacy code without tests → use `/workflow:plan --legacy-refactor`
-- Performance deep-dive → use `/workflow:plan --performance-optimization`
-- Data migration → use `/workflow:plan --data-migration`
-
----
-
-**Last Updated**: 2025-11-20
-**Version**: 2.0.0
-**Status**: Design Document (Simplified)
diff --git a/.claude/skills/command-guide/reference/commands/workflow/plan.md b/.claude/skills/command-guide/reference/commands/workflow/plan.md
index 1bbe991b..938fc719 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/plan.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/plan.md
@@ -1,7 +1,7 @@
---
name: plan
-description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs with optional CLI auto-execution
-argument-hint: "[--cli-execute] \"text description\"|file.md"
+description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs
+argument-hint: "\"text description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -69,7 +69,7 @@ Phase 3: Conflict Resolution (conditional)
└─ conflict_risk < medium → Skip to Phase 4
Phase 4: Task Generation
- └─ /workflow:tools:task-generate-agent --session sessionId [--cli-execute]
+ └─ /workflow:tools:task-generate-agent --session sessionId
└─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
Return:
@@ -273,15 +273,10 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
**Step 4.1: Dispatch** - Generate implementation plan and task JSONs
```javascript
-// Default (agent mode)
SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId]")
-
-// With CLI execution (if --cli-execute flag present)
-SlashCommand(command="/workflow:tools:task-generate-agent --session [sessionId] --cli-execute")
```
-**Flag**:
-- `--cli-execute`: Generate tasks with Codex execution commands
+**CLI Execution Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description. If user specifies "use Codex/Gemini/Qwen for X", the agent embeds `command` fields in relevant `implementation_approach` steps.
**Input**: `sessionId` from Phase 1
@@ -423,7 +418,7 @@ Phase 3: conflict-resolution [AUTO-TRIGGERED if conflict_risk ≥ medium]
↓ Output: Modified brainstorm artifacts (NO report file)
↓ Skip if conflict_risk is none/low → proceed directly to Phase 4
↓
-Phase 4: task-generate-agent --session sessionId [--cli-execute]
+Phase 4: task-generate-agent --session sessionId
↓ Input: sessionId + resolved brainstorm artifacts + session memory
↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
↓
@@ -504,9 +499,7 @@ Return summary to user
- **If conflict_risk ≥ medium**: Launch Phase 3 conflict-resolution with sessionId and contextPath
- Wait for Phase 3 to finish executing (if executed), verify CONFLICT_RESOLUTION.md created
- **If conflict_risk is none/low**: Skip Phase 3, proceed directly to Phase 4
-- **Build Phase 4 command**:
- - Base command: `/workflow:tools:task-generate-agent --session [sessionId]`
- - Add `--cli-execute` if flag present
+- **Build Phase 4 command**: `/workflow:tools:task-generate-agent --session [sessionId]`
- Pass session ID to Phase 4 command
- Verify all Phase 4 outputs
- Update TodoWrite after each phase (dynamically adjust for Phase 3 presence)
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md b/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md
index f86c1d6f..8fa85f33 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md
@@ -1,7 +1,7 @@
---
name: tdd-plan
description: TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking
-argument-hint: "[--cli-execute] \"feature description\"|file.md"
+argument-hint: "\"feature description\"|file.md"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -11,9 +11,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
**This command is a pure orchestrator**: Dispatches 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.
-**Execution Modes**:
-- **Agent Mode** (default): Use `/workflow:tools:task-generate-tdd` (autonomous agent-driven)
-- **CLI Mode** (`--cli-execute`): Use `/workflow:tools:task-generate-tdd --cli-execute` (Gemini/Qwen)
+**CLI Tool Selection**: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
**Task Attachment Model**:
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
@@ -235,13 +233,11 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
**Step 5.1: Dispatch** - TDD task generation via action-planning-agent
```javascript
-// Agent Mode (default)
SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
-
-// CLI Mode (--cli-execute flag)
-SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId] --cli-execute")
```
+**Note**: CLI tool usage is determined semantically from user's task description.
+
**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
**Validate**:
@@ -454,8 +450,7 @@ Convert user input to TDD-structured format:
- `/workflow:tools:test-context-gather` - Phase 3: Analyze existing test patterns and coverage
- `/workflow:tools:conflict-resolution` - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
- `/compact` - Phase 4: Memory optimization (if context approaching limits)
-- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
-- `/workflow:tools:task-generate-tdd --cli-execute` - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when `--cli-execute` flag used)
+- `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
diff --git a/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md b/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md
index 5c32fe76..ad559a92 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/test-fix-gen.md
@@ -1,7 +1,7 @@
---
name: test-fix-gen
description: Create test-fix workflow session from session ID, description, or file path with test strategy generation and task planning
-argument-hint: "[--use-codex] [--cli-execute] (source-session-id | \"feature description\" | /path/to/file.md)"
+argument-hint: "(source-session-id | \"feature description\" | /path/to/file.md)"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -43,7 +43,7 @@ fi
- **Session Isolation**: Creates independent `WFS-test-[slug]` session
- **Context-First**: Gathers implementation context via appropriate method
- **Format Reuse**: Creates standard `IMPL-*.json` tasks with `meta.type: "test-fix"`
-- **Manual First**: Default to manual fixes, use `--use-codex` for automation
+- **Semantic CLI Selection**: CLI tool usage determined from user's task description
- **Automatic Detection**: Input pattern determines execution mode
### Coordinator Role
@@ -79,16 +79,14 @@ This command is a **pure planning coordinator**:
```bash
# Basic syntax
-/workflow:test-fix-gen [FLAGS]
-
-# Flags (optional)
---use-codex # Enable Codex automated fixes in IMPL-002
---cli-execute # Enable CLI execution in IMPL-001
+/workflow:test-fix-gen
# Input
# Session ID, description, or file path
```
+**Note**: CLI tool usage is determined semantically from the task description. To request CLI execution, include it in your description (e.g., "use Codex for automated fixes").
+
### Usage Examples
#### Session Mode
@@ -96,11 +94,8 @@ This command is a **pure planning coordinator**:
# Test validation for completed implementation
/workflow:test-fix-gen WFS-user-auth-v2
-# With automated fixes
-/workflow:test-fix-gen --use-codex WFS-api-endpoints
-
-# With CLI execution
-/workflow:test-fix-gen --cli-execute --use-codex WFS-payment-flow
+# With semantic CLI request
+/workflow:test-fix-gen WFS-api-endpoints # Add "use Codex" in description for automated fixes
```
#### Prompt Mode - Text Description
@@ -108,17 +103,14 @@ This command is a **pure planning coordinator**:
# Generate tests from feature description
/workflow:test-fix-gen "Test the user authentication API endpoints in src/auth/api.ts"
-# With automated fixes
-/workflow:test-fix-gen --use-codex "Test user registration and login flows"
+# With CLI execution (semantic)
+/workflow:test-fix-gen "Test user registration and login flows, use Codex for automated fixes"
```
#### Prompt Mode - File Reference
```bash
# Generate tests from requirements file
/workflow:test-fix-gen ./docs/api-requirements.md
-
-# With flags
-/workflow:test-fix-gen --use-codex --cli-execute ./specs/feature.md
```
### Mode Comparison
@@ -143,7 +135,7 @@ This command is a **pure planning coordinator**:
5. **Complete All Phases**: Do not return until Phase 5 completes
6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
7. **Automatic Detection**: Mode auto-detected from input pattern
-8. **Parse Flags**: Extract `--use-codex` and `--cli-execute` flags for Phase 4
+8. **Semantic CLI Detection**: CLI tool usage determined from user's task description for Phase 4
9. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
10. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
@@ -283,13 +275,13 @@ For each targeted file/function, Gemini MUST generate:
**Step 4.1: Dispatch** - Generate test task JSONs
```javascript
-SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")
+SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
```
**Input**:
- `testSessionId` from Phase 1
-- `--use-codex` flag (if present) - Controls IMPL-002 fix mode
-- `--cli-execute` flag (if present) - Controls IMPL-001 generation mode
+
+**Note**: CLI tool usage is determined semantically from user's task description.
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3 (multi-layered test plan)
@@ -422,7 +414,7 @@ CRITICAL - Next Steps:
- **Phase 2**: Mode-specific context gathering (session summaries vs codebase analysis)
- **Phase 3**: Multi-layered test requirements analysis (L0: Static, L1: Unit, L2: Integration, L3: E2E)
- **Phase 4**: Multi-task generation with quality gate (IMPL-001, IMPL-001.5-review, IMPL-002)
-- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+- **Fix Mode Configuration**: CLI tool usage determined semantically from user's task description
---
@@ -521,16 +513,15 @@ If quality gate fails:
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex: true|false` (based on `--use-codex` flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
**Test-Fix Cycle Specification**:
**Note**: This specification describes what test-cycle-execute orchestrator will do. The agent only executes single tasks.
-- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → manual_fix (or codex) → retest
+- **Cycle Pattern** (orchestrator-managed): test → gemini_diagnose → fix (agent or CLI) → retest
- **Tools Configuration** (orchestrator-controlled):
- Gemini for analysis with bug-fix template → surgical fix suggestions
- - Manual fix application (default) OR Codex if `--use-codex` flag (resume mechanism)
+ - Agent fix application (default) OR CLI if `command` field present in implementation_approach
- **Exit Conditions** (orchestrator-enforced):
- Success: All tests pass
- Failure: Max iterations reached (5)
@@ -674,8 +665,7 @@ Key Points:
4. **Mode Selection**:
- Use **Session Mode** for completed workflow validation
- Use **Prompt Mode** for ad-hoc test generation
- - Use `--use-codex` for autonomous fix application
- - Use `--cli-execute` for enhanced generation capabilities
+ - Include "use Codex" in description for autonomous fix application
## Related Commands
@@ -688,9 +678,7 @@ Key Points:
- `/workflow:tools:test-context-gather` - Phase 2 (Session Mode): Gather source session context
- `/workflow:tools:context-gather` - Phase 2 (Prompt Mode): Analyze codebase directly
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
diff --git a/.claude/skills/command-guide/reference/commands/workflow/test-gen.md b/.claude/skills/command-guide/reference/commands/workflow/test-gen.md
index eb2561e9..99ea7d5e 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/test-gen.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/test-gen.md
@@ -1,7 +1,7 @@
---
name: test-gen
description: Create independent test-fix workflow session from completed implementation session, analyzes code to generate test tasks
-argument-hint: "[--use-codex] [--cli-execute] source-session-id"
+argument-hint: "source-session-id"
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
---
@@ -16,7 +16,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
- **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
-- **Manual First**: Default to manual fixes, use `--use-codex` flag for automated Codex fix application
+- **Semantic CLI Selection**: CLI tool usage is determined by user's task description (e.g., "use Codex for fixes")
**Task Attachment Model**:
- SlashCommand dispatch **expands workflow** by attaching sub-tasks to current TodoWrite
@@ -48,7 +48,7 @@ allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
5. **Complete All Phases**: Do not return to user until Phase 5 completes (summary returned)
6. **Track Progress**: Update TodoWrite dynamically with task attachment/collapse pattern
7. **Automatic Detection**: context-gather auto-detects test session and gathers source session context
-8. **Parse --use-codex Flag**: Extract flag from arguments and pass to Phase 4 (test-task-generate)
+8. **Semantic CLI Selection**: CLI tool usage determined from user's task description, passed to Phase 4
9. **Command Boundary**: This command ends at Phase 5 summary. Test execution is NOT part of this command.
10. **Task Attachment Model**: SlashCommand dispatch **attaches** sub-tasks to current workflow. Orchestrator **executes** these attached tasks itself, then **collapses** them after completion
11. **⚠️ CRITICAL: DO NOT STOP**: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
@@ -224,13 +224,13 @@ SlashCommand(command="/workflow:tools:test-concept-enhanced --session [testSessi
**Step 4.1: Dispatch** - Generate test task JSON files and planning documents
```javascript
-SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-execute] --session [testSessionId]")
+SlashCommand(command="/workflow:tools:test-task-generate --session [testSessionId]")
```
**Input**:
- `testSessionId` from Phase 1
-- `--use-codex` flag (if present in original command) - Controls IMPL-002 fix mode
-- `--cli-execute` flag (if present in original command) - Controls IMPL-001 generation mode
+
+**Note**: CLI tool usage for fixes is determined semantically from user's task description (e.g., "use Codex for automated fixes").
**Expected Behavior**:
- Parse TEST_ANALYSIS_RESULTS.md from Phase 3
@@ -260,16 +260,15 @@ SlashCommand(command="/workflow:tools:test-task-generate [--use-codex] [--cli-ex
- Task ID: `IMPL-002`
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex: true|false` (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `context.requirements`: Execute and fix tests
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- - **Cycle pattern**: test → gemini_diagnose → manual_fix (or codex if --use-codex) → retest
- - **Tools configuration**: Gemini for analysis with bug-fix template, manual or Codex for fixes
+ - **Cycle pattern**: test → gemini_diagnose → fix (agent or CLI based on `command` field) → retest
+ - **Tools configuration**: Gemini for analysis with bug-fix template, agent or CLI for fixes
- **Exit conditions**: Success (all pass) or failure (max iterations)
- `flow_control.implementation_approach.modification_points`: 3-phase execution flow
- Phase 1: Initial test execution
- - Phase 2: Iterative Gemini diagnosis + manual/Codex fixes (based on flag)
+ - Phase 2: Iterative Gemini diagnosis + fixes (agent or CLI based on step's `command` field)
- Phase 3: Final validation and certification
@@ -327,7 +326,7 @@ Artifacts Created:
Test Framework: [detected framework]
Test Files to Generate: [count]
-Fix Mode: [Manual|Codex Automated] (based on --use-codex flag)
+Fix Mode: [Agent|CLI] (based on `command` field in implementation_approach steps)
Review Generated Artifacts:
- Test plan: .workflow/[testSessionId]/IMPL_PLAN.md
@@ -373,7 +372,7 @@ Ready for execution. Use appropriate workflow commands to proceed.
- **Phase 2**: Cross-session context gathering from source implementation session
- **Phase 3**: Test requirements analysis with Gemini for generation strategy
- **Phase 4**: Dual-task generation (IMPL-001 for test generation, IMPL-002 for test execution)
-- **Fix Mode Configuration**: `--use-codex` flag controls IMPL-002 fix mode (manual vs automated)
+- **Fix Mode Configuration**: CLI tool usage determined semantically from user's task description
@@ -444,7 +443,7 @@ Generates two task definition files:
- Agent: @test-fix-agent
- Dependency: IMPL-001 must complete first
- Max iterations: 5
- - Fix mode: Manual or Codex (based on --use-codex flag)
+ - Fix mode: Agent or CLI (based on `command` field in implementation_approach)
See `/workflow:tools:test-task-generate` for complete task JSON schemas.
@@ -481,11 +480,10 @@ Created in `.workflow/active/WFS-test-[session]/`:
**IMPL-002.json Structure**:
- `meta.type: "test-fix"`
- `meta.agent: "@test-fix-agent"`
-- `meta.use_codex`: true/false (based on --use-codex flag)
- `context.depends_on: ["IMPL-001"]`
- `flow_control.implementation_approach.test_fix_cycle`: Complete cycle specification
- Gemini diagnosis template
- - Fix application mode (manual/codex)
+ - Fix application mode (agent or CLI based on `command` field)
- Max iterations: 5
- `flow_control.implementation_approach.modification_points`: 3-phase flow
@@ -503,13 +501,11 @@ See `/workflow:tools:test-task-generate` for complete JSON schemas.
**Prerequisite Commands**:
- `/workflow:plan` or `/workflow:execute` - Complete implementation session that needs test validation
-**Dispatched by This Command** (5 phases):
+**Dispatched by This Command** (4 phases):
- `/workflow:session:start` - Phase 1: Create independent test workflow session
- `/workflow:tools:test-context-gather` - Phase 2: Analyze test coverage and gather source session context
- `/workflow:tools:test-concept-enhanced` - Phase 3: Generate test requirements and strategy using Gemini
-- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs using action-planning-agent (autonomous, default)
-- `/workflow:tools:test-task-generate --use-codex` - Phase 4: With automated Codex fixes for IMPL-002 (when `--use-codex` flag used)
-- `/workflow:tools:test-task-generate --cli-execute` - Phase 4: With CLI execution mode for IMPL-001 test generation (when `--cli-execute` flag used)
+- `/workflow:tools:test-task-generate` - Phase 4: Generate test task JSONs (CLI tool usage determined semantically)
**Follow-up Commands**:
- `/workflow:status` - Review generated test tasks
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md b/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
index f952c5c8..85650e86 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/conflict-resolution.md
@@ -114,35 +114,44 @@ Task(subagent_type="cli-execution-agent", prompt=`
- Risk: {conflict_risk}
- Files: {existing_files_list}
+ ## Exploration Context (from context-package.exploration_results)
+ - Exploration Count: ${contextPackage.exploration_results?.exploration_count || 0}
+ - Angles Analyzed: ${JSON.stringify(contextPackage.exploration_results?.angles || [])}
+ - Pre-identified Conflict Indicators: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.conflict_indicators || [])}
+ - Critical Files: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.critical_files?.map(f => f.path) || [])}
+ - All Patterns: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_patterns || [])}
+ - All Integration Points: ${JSON.stringify(contextPackage.exploration_results?.aggregated_insights?.all_integration_points || [])}
+
## Analysis Steps
### 1. Load Context
- Read existing files from conflict_detection.existing_files
- Load plan from .workflow/active/{session_id}/.process/context-package.json
+ - **NEW**: Load exploration_results and use aggregated_insights for enhanced analysis
- Extract role analyses and requirements
- ### 2. Execute CLI Analysis (Enhanced with Scenario Uniqueness Detection)
+ ### 2. Execute CLI Analysis (Enhanced with Exploration + Scenario Uniqueness)
Primary (Gemini):
cd {project_root} && gemini -p "
- PURPOSE: Detect conflicts between plan and codebase, including module scenario overlaps
+ PURPOSE: Detect conflicts between plan and codebase, using exploration insights
TASK:
- • Compare architectures
+ • **Review pre-identified conflict_indicators from exploration results**
+ • Compare architectures (use exploration key_patterns)
• Identify breaking API changes
• Detect data model incompatibilities
• Assess dependency conflicts
- • **NEW: Analyze module scenario uniqueness**
- - Extract new module functionality from plan
- - Search all existing modules with similar functionality
- - Compare scenario coverage and identify overlaps
+ • **Analyze module scenario uniqueness**
+ - Use exploration integration_points for precise locations
+ - Cross-validate with exploration critical_files
- Generate clarification questions for boundary definition
MODE: analysis
CONTEXT: @**/*.ts @**/*.js @**/*.tsx @**/*.jsx @.workflow/active/{session_id}/**/*
- EXPECTED: Conflict list with severity ratings, including ModuleOverlap conflicts with:
- - Existing module list with scenarios
- - Overlap analysis matrix
+ EXPECTED: Conflict list with severity ratings, including:
+ - Validation of exploration conflict_indicators
+ - ModuleOverlap conflicts with overlap_analysis
- Targeted clarification questions
- RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on breaking changes, migration needs, and functional overlaps | analysis=READ-ONLY
+ RULES: $(cat ~/.claude/workflows/cli-templates/prompts/analysis/02-analyze-code-patterns.txt) | Focus on breaking changes, migration needs, and functional overlaps | Prioritize exploration-identified conflicts | analysis=READ-ONLY
"
Fallback: Qwen (same prompt) → Claude (manual analysis)
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md b/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
index 38277387..b34e53d7 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/context-gather.md
@@ -36,24 +36,23 @@ Step 1: Context-Package Detection
├─ Valid package exists → Return existing (skip execution)
└─ No valid package → Continue to Step 2
-Step 2: Invoke Context-Search Agent
- ├─ Phase 1: Initialization & Pre-Analysis
- │ ├─ Load project.json as primary context
- │ ├─ Initialize code-index
- │ └─ Classify complexity
- ├─ Phase 2: Multi-Source Discovery
- │ ├─ Track 1: Historical archive analysis
- │ ├─ Track 2: Reference documentation
- │ ├─ Track 3: Web examples (Exa MCP)
- │ └─ Track 4: Codebase analysis (5-layer)
- └─ Phase 3: Synthesis & Packaging
- ├─ Apply relevance scoring
- ├─ Integrate brainstorm artifacts
- ├─ Perform conflict detection
- └─ Generate context-package.json
+Step 2: Complexity Assessment & Parallel Explore (NEW)
+ ├─ Analyze task_description → classify Low/Medium/High
+ ├─ Select exploration angles (1-4 based on complexity)
+ ├─ Launch N cli-explore-agents in parallel
+ │ └─ Each outputs: exploration-{angle}.json
+ └─ Generate explorations-manifest.json
-Step 3: Output Verification
- └─ Verify context-package.json created
+Step 3: Invoke Context-Search Agent (with exploration input)
+ ├─ Phase 1: Initialization & Pre-Analysis
+ ├─ Phase 2: Multi-Source Discovery
+ │ ├─ Track 0: Exploration Synthesis (prioritize & deduplicate)
+ │ ├─ Track 1-4: Existing tracks
+ └─ Phase 3: Synthesis & Packaging
+ └─ Generate context-package.json with exploration_results
+
+Step 4: Output Verification
+ └─ Verify context-package.json contains exploration_results
```
## Execution Flow
@@ -80,10 +79,139 @@ if (file_exists(contextPackagePath)) {
}
```
-### Step 2: Invoke Context-Search Agent
+### Step 2: Complexity Assessment & Parallel Explore
**Only execute if Step 1 finds no valid package**
+```javascript
+// 2.1 Complexity Assessment
+function analyzeTaskComplexity(taskDescription) {
+ const text = taskDescription.toLowerCase();
+ if (/architect|refactor|restructure|modular|cross-module/.test(text)) return 'High';
+ if (/multiple|several|integrate|migrate|extend/.test(text)) return 'Medium';
+ return 'Low';
+}
+
+const ANGLE_PRESETS = {
+ architecture: ['architecture', 'dependencies', 'modularity', 'integration-points'],
+ security: ['security', 'auth-patterns', 'dataflow', 'validation'],
+ performance: ['performance', 'bottlenecks', 'caching', 'data-access'],
+ bugfix: ['error-handling', 'dataflow', 'state-management', 'edge-cases'],
+ feature: ['patterns', 'integration-points', 'testing', 'dependencies'],
+ refactor: ['architecture', 'patterns', 'dependencies', 'testing']
+};
+
+function selectAngles(taskDescription, complexity) {
+ const text = taskDescription.toLowerCase();
+ let preset = 'feature';
+ if (/refactor|architect|restructure/.test(text)) preset = 'architecture';
+ else if (/security|auth|permission/.test(text)) preset = 'security';
+ else if (/performance|slow|optimi/.test(text)) preset = 'performance';
+ else if (/fix|bug|error|issue/.test(text)) preset = 'bugfix';
+
+ const count = complexity === 'High' ? 4 : (complexity === 'Medium' ? 3 : 1);
+ return ANGLE_PRESETS[preset].slice(0, count);
+}
+
+const complexity = analyzeTaskComplexity(task_description);
+const selectedAngles = selectAngles(task_description, complexity);
+const sessionFolder = `.workflow/active/${session_id}/.process`;
+
+// 2.2 Launch Parallel Explore Agents
+const explorationTasks = selectedAngles.map((angle, index) =>
+ Task(
+ subagent_type="cli-explore-agent",
+ description=`Explore: ${angle}`,
+ prompt=`
+## Task Objective
+Execute **${angle}** exploration for task planning context. Analyze codebase from this specific angle to discover relevant structure, patterns, and constraints.
+
+## Assigned Context
+- **Exploration Angle**: ${angle}
+- **Task Description**: ${task_description}
+- **Session ID**: ${session_id}
+- **Exploration Index**: ${index + 1} of ${selectedAngles.length}
+- **Output File**: ${sessionFolder}/exploration-${angle}.json
+
+## MANDATORY FIRST STEPS (Execute by Agent)
+**You (cli-explore-agent) MUST execute these steps in order:**
+1. Run: ~/.claude/scripts/get_modules_by_depth.sh (project structure)
+2. Run: rg -l "{keyword_from_task}" --type ts (locate relevant files)
+3. Execute: cat ~/.claude/workflows/cli-templates/schemas/explore-json-schema.json (get output schema reference)
+
+## Exploration Strategy (${angle} focus)
+
+**Step 1: Structural Scan** (Bash)
+- get_modules_by_depth.sh → identify modules related to ${angle}
+- find/rg → locate files relevant to ${angle} aspect
+- Analyze imports/dependencies from ${angle} perspective
+
+**Step 2: Semantic Analysis** (Gemini CLI)
+- How does existing code handle ${angle} concerns?
+- What patterns are used for ${angle}?
+- Where would new code integrate from ${angle} viewpoint?
+
+**Step 3: Write Output**
+- Consolidate ${angle} findings into JSON
+- Identify ${angle}-specific clarification needs
+
+## Expected Output
+
+**File**: ${sessionFolder}/exploration-${angle}.json
+
+**Schema Reference**: Schema obtained in MANDATORY FIRST STEPS step 3, follow schema exactly
+
+**Required Fields** (all ${angle} focused):
+- project_structure: Modules/architecture relevant to ${angle}
+- relevant_files: Files affected from ${angle} perspective
+ **IMPORTANT**: Use object format with relevance scores for synthesis:
+ \`[{path: "src/file.ts", relevance: 0.85, rationale: "Core ${angle} logic"}]\`
+ Scores: 0.7+ high priority, 0.5-0.7 medium, <0.5 low
+- patterns: ${angle}-related patterns to follow
+- dependencies: Dependencies relevant to ${angle}
+- integration_points: Where to integrate from ${angle} viewpoint (include file:line locations)
+- constraints: ${angle}-specific limitations/conventions
+- clarification_needs: ${angle}-related ambiguities (with options array)
+- _metadata.exploration_angle: "${angle}"
+
+## Success Criteria
+- [ ] Schema obtained via cat explore-json-schema.json
+- [ ] get_modules_by_depth.sh executed
+- [ ] At least 3 relevant files identified with ${angle} rationale
+- [ ] Patterns are actionable (code examples, not generic advice)
+- [ ] Integration points include file:line locations
+- [ ] Constraints are project-specific to ${angle}
+- [ ] JSON output follows schema exactly
+- [ ] clarification_needs includes options array
+
+## Output
+Write: ${sessionFolder}/exploration-${angle}.json
+Return: 2-3 sentence summary of ${angle} findings
+`
+ )
+);
+
+// 2.3 Generate Manifest after all complete
+const explorationFiles = bash(`find ${sessionFolder} -name "exploration-*.json" -type f`).split('\n').filter(f => f.trim());
+const explorationManifest = {
+ session_id,
+ task_description,
+ timestamp: new Date().toISOString(),
+ complexity,
+ exploration_count: selectedAngles.length,
+ angles_explored: selectedAngles,
+ explorations: explorationFiles.map(file => {
+ const data = JSON.parse(Read(file));
+ return { angle: data._metadata.exploration_angle, file: file.split('/').pop(), path: file, index: data._metadata.exploration_index };
+ })
+};
+Write(`${sessionFolder}/explorations-manifest.json`, JSON.stringify(explorationManifest, null, 2));
+```
+
+### Step 3: Invoke Context-Search Agent
+
+**Only execute after Step 2 completes**
+
```javascript
Task(
subagent_type="context-search-agent",
@@ -97,6 +225,12 @@ Task(
- **Task Description**: ${task_description}
- **Output Path**: .workflow/${session_id}/.process/context-package.json
+## Exploration Input (from Step 2)
+- **Manifest**: ${sessionFolder}/explorations-manifest.json
+- **Exploration Count**: ${explorationManifest.exploration_count}
+- **Angles**: ${explorationManifest.angles_explored.join(', ')}
+- **Complexity**: ${complexity}
+
## Mission
Execute complete context-search-agent workflow for implementation planning:
@@ -107,7 +241,8 @@ Execute complete context-search-agent workflow for implementation planning:
4. **Analysis**: Extract keywords, determine scope, classify complexity based on task description and project state
### Phase 2: Multi-Source Context Discovery
-Execute all 4 discovery tracks:
+Execute all discovery tracks:
+- **Track 0**: Exploration Synthesis (load ${sessionFolder}/explorations-manifest.json, prioritize critical_files, deduplicate patterns/integration_points)
- **Track 1**: Historical archive analysis (query manifest.json for lessons learned)
- **Track 2**: Reference documentation (CLAUDE.md, architecture docs)
- **Track 3**: Web examples (use Exa MCP for unfamiliar tech/APIs)
@@ -130,6 +265,7 @@ Complete context-package.json with:
- **dependencies**: {internal[], external[]} with dependency graph
- **brainstorm_artifacts**: {guidance_specification, role_analyses[], synthesis_output} with content
- **conflict_detection**: {risk_level, risk_factors, affected_modules[], mitigation_strategy, historical_conflicts[]}
+- **exploration_results**: {manifest_path, exploration_count, angles, explorations[], aggregated_insights} (from Track 0)
## Quality Validation
Before completion verify:
@@ -146,7 +282,7 @@ Report completion with statistics.
)
```
-### Step 3: Output Verification
+### Step 4: Output Verification
After agent completes, verify output:
@@ -156,6 +292,12 @@ const outputPath = `.workflow/${session_id}/.process/context-package.json`;
if (!file_exists(outputPath)) {
throw new Error("❌ Agent failed to generate context-package.json");
}
+
+// Verify exploration_results included
+const pkg = JSON.parse(Read(outputPath));
+if (pkg.exploration_results?.exploration_count > 0) {
+ console.log(`✅ Exploration results aggregated: ${pkg.exploration_results.exploration_count} angles`);
+}
```
## Parameter Reference
@@ -176,6 +318,7 @@ Refer to `context-search-agent.md` Phase 3.7 for complete `context-package.json`
- **dependencies**: Internal and external dependency graphs
- **brainstorm_artifacts**: Brainstorm documents with full content (if exists)
- **conflict_detection**: Risk assessment with mitigation strategies and historical conflicts
+- **exploration_results**: Aggregated exploration insights (from parallel explore phase)
## Historical Archive Analysis
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
index 4d7f0b62..2590abbd 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-agent.md
@@ -1,10 +1,9 @@
---
name: task-generate-agent
description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
-argument-hint: "--session WFS-session-id [--cli-execute]"
+argument-hint: "--session WFS-session-id"
examples:
- /workflow:tools:task-generate-agent --session WFS-auth
- - /workflow:tools:task-generate-agent --session WFS-auth --cli-execute
---
# Generate Implementation Plan Command
@@ -26,7 +25,7 @@ Generate implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.
```
Input Parsing:
- ├─ Parse flags: --session, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Context Preparation (Command)
@@ -65,9 +64,10 @@ Phase 2: Planning Document Generation (Agent)
2. **Provide Metadata** (simple values):
- `session_id`
- - `execution_mode` (agent-mode | cli-execute-mode)
- `mcp_capabilities` (available MCP tools)
+**Note**: CLI tool usage is now determined semantically by action-planning-agent based on user's task description, not by flags.
+
### Phase 2: Planning Document Generation (Agent Responsibility)
**Purpose**: Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT code implementation.
@@ -97,15 +97,28 @@ Output:
## CONTEXT METADATA
Session ID: {session-id}
-Planning Mode: {agent-mode | cli-execute-mode}
MCP Capabilities: {exa_code, exa_web, code_index}
+## CLI TOOL SELECTION
+Determine CLI tool usage per-step based on user's task description:
+- If user specifies "use Codex/Gemini/Qwen for X" → Add command field to relevant steps
+- Default: Agent execution (no command field) unless user explicitly requests CLI
+
+## EXPLORATION CONTEXT (from context-package.exploration_results)
+- Load exploration_results from context-package.json
+- Use aggregated_insights.critical_files for focus_paths generation
+- Apply aggregated_insights.constraints to acceptance criteria
+- Reference aggregated_insights.all_patterns for implementation approach
+- Use aggregated_insights.all_integration_points for precise modification locations
+- Use conflict_indicators for risk-aware task sequencing
+
## EXPECTED DELIVERABLES
1. Task JSON Files (.task/IMPL-*.json)
- 6-field schema (id, title, status, context_package_path, meta, context, flow_control)
- Quantified requirements with explicit counts
- Artifacts integration from context package
- - Flow control with pre_analysis steps
+ - **focus_paths enhanced with exploration critical_files**
+ - Flow control with pre_analysis steps (include exploration integration_points analysis)
2. Implementation Plan (IMPL_PLAN.md)
- Context analysis and artifact references
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
index 7f8d4807..9bd76d75 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/task-generate-tdd.md
@@ -1,24 +1,23 @@
---
name: task-generate-tdd
description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
-argument-hint: "--session WFS-session-id [--cli-execute]"
+argument-hint: "--session WFS-session-id"
examples:
- /workflow:tools:task-generate-tdd --session WFS-auth
- - /workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
---
# Autonomous TDD Task Generation Command
## Overview
-Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Supports both agent-driven execution (default) and CLI tool execution modes. Generates complete Red-Green-Refactor cycles contained within each task.
+Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent with two-phase execution: discovery and document generation. Generates complete Red-Green-Refactor cycles contained within each task.
## Core Philosophy
- **Agent-Driven**: Delegate execution to action-planning-agent for autonomous operation
- **Two-Phase Flow**: Discovery (context gathering) → Output (document generation)
- **Memory-First**: Reuse loaded documents from conversation memory
- **MCP-Enhanced**: Use MCP tools for advanced code analysis and research
-- **Pre-Selected Templates**: Command selects correct TDD template based on `--cli-execute` flag **before** invoking agent
-- **Agent Simplicity**: Agent receives pre-selected template and focuses only on content generation
+- **Semantic CLI Selection**: CLI tool usage determined from user's task description, not flags
+- **Agent Simplicity**: Agent generates content with semantic CLI detection
- **Path Clarity**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
- **TDD-First**: Every feature starts with a failing test (Red phase)
- **Feature-Complete Tasks**: Each task contains complete Red-Green-Refactor cycle
@@ -57,7 +56,7 @@ Autonomous TDD task JSON and IMPL_PLAN.md generation using action-planning-agent
```
Input Parsing:
- ├─ Parse flags: --session, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Discovery & Context Loading (Memory-First)
@@ -69,7 +68,7 @@ Phase 1: Discovery & Context Loading (Memory-First)
└─ Optional: MCP external research
Phase 2: Agent Execution (Document Generation)
- ├─ Pre-agent template selection (agent-mode OR cli-execute-mode)
+ ├─ Pre-agent template selection (semantic CLI detection)
├─ Invoke action-planning-agent
├─ Generate TDD Task JSON Files (.task/IMPL-*.json)
│ └─ Each task: complete Red-Green-Refactor cycle internally
@@ -86,11 +85,8 @@ Phase 2: Agent Execution (Document Generation)
```javascript
{
"session_id": "WFS-[session-id]",
- "execution_mode": "agent-mode" | "cli-execute-mode", // Determined by flag
- "task_json_template_path": "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt"
- | "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt",
- // Path selected by command based on --cli-execute flag, agent reads it
"workflow_type": "tdd",
+ // Note: CLI tool usage is determined semantically by action-planning-agent based on user's task description
"session_metadata": {
// If in memory: use cached content
// Else: Load from .workflow/active//{session-id}/workflow-session.json
@@ -199,8 +195,7 @@ Task(
**Session ID**: WFS-{session-id}
**Workflow Type**: TDD
-**Execution Mode**: {agent-mode | cli-execute-mode}
-**Task JSON Template Path**: {template_path}
+**Note**: CLI tool usage is determined semantically from user's task description
## Phase 1: Discovery Results (Provided Context)
@@ -265,16 +260,15 @@ Refer to: @.claude/agents/action-planning-agent.md for:
##### 1. TDD Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/active//{session-id}/.task/`
-- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure with TDD-specific metadata
- `meta.tdd_workflow`: true (REQUIRED)
- `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
- - `meta.use_codex`: false (manual fixes by default)
- `context.tdd_cycles`: Array with quantified test cases and coverage
- `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
1. Red Phase (`tdd_phase: "red"`): Write failing tests
2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
+ - CLI tool usage determined semantically (add `command` field when user requests CLI execution)
- **Details**: See action-planning-agent.md § TDD Task JSON Generation
##### 2. IMPL_PLAN.md (TDD Variant)
@@ -475,16 +469,14 @@ This section provides quick reference for TDD task JSON structure. For complete
**Basic Usage**:
```bash
-# Agent mode (default, autonomous execution)
+# Standard execution
/workflow:tools:task-generate-tdd --session WFS-auth
-# CLI tool mode (use Gemini/Qwen for generation)
-/workflow:tools:task-generate-tdd --session WFS-auth --cli-execute
+# With semantic CLI request (include in task description)
+# e.g., "Generate TDD tasks for auth module, use Codex for implementation"
```
-**Execution Modes**:
-- **Agent mode** (default): Uses `action-planning-agent` with agent-mode task template
-- **CLI mode** (`--cli-execute`): Uses Gemini/Qwen with cli-mode task template
+**CLI Tool Selection**: Determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.
**Output**:
- TDD task JSON files in `.task/` directory (IMPL-N.json format)
@@ -513,7 +505,7 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
3. **Success Path**: Tests pass → Complete task
4. **Failure Path**: Tests fail → Enter iterative fix cycle:
- **Gemini Diagnosis**: Analyze failures with bug-fix template
- - **Fix Application**: Manual (default) or Codex (if meta.use_codex=true)
+ - **Fix Application**: Agent (default) or CLI (if `command` field present)
- **Retest**: Verify fix resolves failures
- **Repeat**: Up to max_iterations (default: 3)
5. **Safety Net**: Auto-revert all changes if max iterations reached
@@ -522,5 +514,5 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
## Configuration Options
- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
-- **meta.use_codex**: Enable Codex automated fixes (default: false, manual)
+- **CLI tool usage**: Determined semantically from user's task description via `command` field in implementation_approach
diff --git a/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md b/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
index 6287dbfe..47607d1d 100644
--- a/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
+++ b/.claude/skills/command-guide/reference/commands/workflow/tools/test-task-generate.md
@@ -1,11 +1,9 @@
---
name: test-task-generate
description: Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) using action-planning-agent - produces test planning artifacts, does NOT execute tests
-argument-hint: "[--use-codex] [--cli-execute] --session WFS-test-session-id"
+argument-hint: "--session WFS-test-session-id"
examples:
- /workflow:tools:test-task-generate --session WFS-test-auth
- - /workflow:tools:test-task-generate --use-codex --session WFS-test-auth
- - /workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
---
# Generate Test Planning Documents Command
@@ -26,17 +24,17 @@ Generate test planning documents (IMPL_PLAN.md, test task JSONs, TODO_LIST.md) u
### Test Generation (IMPL-001)
- **Agent Mode** (default): @code-developer generates tests within agent context
-- **CLI Execute Mode** (`--cli-execute`): Use Codex CLI for autonomous test generation
+- **CLI Mode**: Use CLI tools when `command` field present in implementation_approach (determined semantically)
### Test Execution & Fix (IMPL-002+)
-- **Manual Mode** (default): Gemini diagnosis → user applies fixes
-- **Codex Mode** (`--use-codex`): Gemini diagnosis → Codex applies fixes with resume mechanism
+- **Agent Mode** (default): Gemini diagnosis → agent applies fixes
+- **CLI Mode**: Gemini diagnosis → CLI applies fixes (when `command` field present in implementation_approach)
## Execution Process
```
Input Parsing:
- ├─ Parse flags: --session, --use-codex, --cli-execute
+ ├─ Parse flags: --session
└─ Validation: session_id REQUIRED
Phase 1: Context Preparation (Command)
@@ -44,7 +42,7 @@ Phase 1: Context Preparation (Command)
│ ├─ session_metadata_path
│ ├─ test_analysis_results_path (REQUIRED)
│ └─ test_context_package_path
- └─ Provide metadata (session_id, execution_mode, use_codex, source_session_id)
+ └─ Provide metadata (session_id, source_session_id)
Phase 2: Test Document Generation (Agent)
├─ Load TEST_ANALYSIS_RESULTS.md as primary requirements source
@@ -83,11 +81,11 @@ Phase 2: Test Document Generation (Agent)
2. **Provide Metadata** (simple values):
- `session_id`
- - `execution_mode` (agent-mode | cli-execute-mode)
- - `use_codex` flag (true | false)
- `source_session_id` (if exists)
- `mcp_capabilities` (available MCP tools)
+**Note**: CLI tool usage is now determined semantically from user's task description, not by flags.
+
### Phase 2: Test Document Generation (Agent Responsibility)
**Purpose**: Generate test-specific IMPL_PLAN.md, task JSONs, and TODO_LIST.md - planning documents only, NOT test execution.
@@ -134,11 +132,14 @@ Output:
## CONTEXT METADATA
Session ID: {test-session-id}
Workflow Type: test_session
-Planning Mode: {agent-mode | cli-execute-mode}
-Use Codex: {true | false}
Source Session: {source-session-id} (if exists)
MCP Capabilities: {exa_code, exa_web, code_index}
+## CLI TOOL SELECTION
+Determine CLI tool usage per-step based on user's task description:
+- If user specifies "use Codex/Gemini/Qwen for X" → Add command field to relevant steps
+- Default: Agent execution (no command field) unless user explicitly requests CLI
+
## TEST-SPECIFIC REQUIREMENTS SUMMARY
(Detailed specifications in your agent definition)
@@ -149,25 +150,26 @@ MCP Capabilities: {exa_code, exa_web, code_index}
Task Configuration:
IMPL-001 (Test Generation):
- meta.type: "test-gen"
- - meta.agent: "@code-developer" (agent-mode) OR CLI execution (cli-execute-mode)
+ - meta.agent: "@code-developer"
- meta.test_framework: Specify existing framework (e.g., "jest", "vitest", "pytest")
- flow_control: Test generation strategy from TEST_ANALYSIS_RESULTS.md
+ - CLI execution: Add `command` field when user requests (determined semantically)
IMPL-002+ (Test Execution & Fix):
- meta.type: "test-fix"
- meta.agent: "@test-fix-agent"
- - meta.use_codex: true/false (based on flag)
- flow_control: Test-fix cycle with iteration limits and diagnosis configuration
+ - CLI execution: Add `command` field when user requests (determined semantically)
### Test-Fix Cycle Specification (IMPL-002+)
Required flow_control fields:
- max_iterations: 5
- diagnosis_tool: "gemini"
- diagnosis_template: "~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt"
- - fix_mode: "manual" OR "codex" (based on use_codex flag)
- cycle_pattern: "test → gemini_diagnose → fix → retest"
- exit_conditions: ["all_tests_pass", "max_iterations_reached"]
- auto_revert_on_failure: true
+ - CLI fix: Add `command` field when user specifies CLI tool usage
### Automation Framework Configuration
Select automation tools based on test requirements from TEST_ANALYSIS_RESULTS.md:
@@ -191,8 +193,9 @@ PRIMARY requirements source - extract and map to task JSONs:
## EXPECTED DELIVERABLES
1. Test Task JSON Files (.task/IMPL-*.json)
- 6-field schema with quantified requirements from TEST_ANALYSIS_RESULTS.md
- - Test-specific metadata: type, agent, use_codex, test_framework, coverage_target
+ - Test-specific metadata: type, agent, test_framework, coverage_target
- flow_control includes: reusable_test_tools, test_commands (from project config)
+ - CLI execution via `command` field when user requests (determined semantically)
- Artifact references from test-context-package.json
- Absolute paths in context.files_to_test
@@ -213,9 +216,9 @@ Hard Constraints:
- All requirements quantified from TEST_ANALYSIS_RESULTS.md
- Test framework matches existing project framework
- flow_control includes reusable_test_tools and test_commands from project
- - use_codex flag correctly set in IMPL-002+ tasks
- Absolute paths for all focus_paths
- Acceptance criteria include verification commands
+ - CLI `command` field added only when user explicitly requests CLI tool usage
## SUCCESS CRITERIA
- All test planning documents generated successfully
@@ -233,21 +236,18 @@ Hard Constraints:
### Usage Examples
```bash
-# Agent mode (default)
+# Standard execution
/workflow:tools:test-task-generate --session WFS-test-auth
-# With automated Codex fixes
-/workflow:tools:test-task-generate --use-codex --session WFS-test-auth
-
-# CLI execution mode for test generation
-/workflow:tools:test-task-generate --cli-execute --session WFS-test-auth
+# With semantic CLI request (include in task description)
+# e.g., "Generate tests, use Codex for implementation and fixes"
```
-### Flag Behavior
-- **No flags**: `meta.use_codex=false` (manual fixes), agent-mode test generation
-- **--use-codex**: `meta.use_codex=true` (Codex automated fixes in IMPL-002+)
-- **--cli-execute**: CLI tool execution mode for IMPL-001 test generation
-- **Both flags**: CLI generation + automated Codex fixes
+### CLI Tool Selection
+CLI tool usage is determined semantically from user's task description:
+- Include "use Codex" for automated fixes
+- Include "use Gemini" for analysis
+- Default: Agent execution (no `command` field)
### Output
- Test task JSON files in `.task/` directory (minimum 2)