From 132eec900cb773406e838be3886d76df0c9ef254 Mon Sep 17 00:00:00 2001 From: catlog22 Date: Sat, 29 Nov 2025 15:59:01 +0800 Subject: [PATCH] refactor: Replace CLI execution flags with semantic-driven tool selection MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Remove --cli-execute flag from plan.md, tdd-plan.md, task-generate-agent.md, task-generate-tdd.md - Remove --use-codex flag from test-gen.md, test-fix-gen.md, test-task-generate.md - Remove meta.use_codex from task JSON schema in action-planning-agent.md and cli-planning-agent.md - Add "Semantic CLI Tool Selection" section to action-planning-agent.md - Document explicit source: metadata.task_description from context-package.json - Update test-fix-agent.md execution mode documentation - Update action-plan-verify.md to remove use_codex validation - Sync SKILL reference copies via analyze_commands.py CLI tool usage now determined semantically from user's task description (e.g., "use Codex for implementation") instead of explicit flags. ๐Ÿค– Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .claude/agents/action-planning-agent.md | 39 +- .claude/agents/cli-planning-agent.md | 4 +- .claude/agents/code-developer.md | 2 - .claude/agents/test-fix-agent.md | 10 +- .../commands/workflow/action-plan-verify.md | 2 +- .claude/commands/workflow/plan.md | 19 +- .claude/commands/workflow/tdd-plan.md | 15 +- .claude/commands/workflow/test-fix-gen.md | 48 +- .claude/commands/workflow/test-gen.md | 34 +- .../workflow/tools/task-generate-agent.md | 14 +- .../workflow/tools/task-generate-tdd.md | 38 +- .../workflow/tools/test-task-generate.md | 56 +- .../command-guide/index/all-commands.json | 16 +- .../command-guide/index/by-category.json | 16 +- .../command-guide/index/by-use-case.json | 16 +- .../index/essential-commands.json | 4 +- .../reference/agents/action-planning-agent.md | 39 +- .../reference/agents/cli-planning-agent.md | 4 +- .../reference/agents/code-developer.md | 2 - .../reference/agents/context-search-agent.md | 109 +- .../reference/agents/test-fix-agent.md | 10 +- .../commands/workflow/action-plan-verify.md | 2 +- .../reference/commands/workflow/lite-fix.md | 1182 +++++++---------- .../reference/commands/workflow/plan.md | 19 +- .../reference/commands/workflow/tdd-plan.md | 15 +- .../commands/workflow/test-fix-gen.md | 48 +- .../reference/commands/workflow/test-gen.md | 34 +- .../workflow/tools/conflict-resolution.md | 31 +- .../commands/workflow/tools/context-gather.md | 183 ++- .../workflow/tools/task-generate-agent.md | 25 +- .../workflow/tools/task-generate-tdd.md | 38 +- .../workflow/tools/test-task-generate.md | 56 +- 32 files changed, 1080 insertions(+), 1050 deletions(-) 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)