Claude-Code-Workflow/.claude/commands/workflow/tools/test-task-generate.md

name, description, argument-hint, examples

name	description	argument-hint	examples
test-task-generate	Autonomous test-fix task generation using action-planning-agent with test-fix-retest cycle specification and discovery phase	[--use-codex] [--cli-execute] --session WFS-test-session-id	/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 /workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth

Autonomous Test Task Generation Command

Overview

Autonomous test-fix task JSON 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 specialized test-fix tasks with comprehensive test-fix-retest cycle specification.

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 test research
• Pre-Selected Templates: Command selects correct test template based on --cli-execute flag before invoking agent
• Agent Simplicity: Agent receives pre-selected template and focuses only on content generation
• Path Clarity: All focus_paths prefer absolute paths (e.g., D:\\project\\src\\module), or clear relative paths from project root
• Test-First: Generate comprehensive test coverage before execution
• Iterative Refinement: Test-fix-retest cycle until all tests pass
• Surgical Fixes: Minimal code changes, no refactoring during test fixes
• Auto-Revert: Rollback all changes if max iterations reached

Execution Modes

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

Test Fix (IMPL-002)

• Manual Mode (Default): Gemini diagnosis → user applies fixes
• Codex Mode (--use-codex): Gemini diagnosis → Codex applies fixes with resume mechanism

Execution Lifecycle

Phase 1: Discovery & Context Loading

⚡ Memory-First Rule: Skip file loading if documents already in conversation memory

Agent Context Package:

{
  "session_id": "WFS-test-[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": "test_session",
  "use_codex": true | false,  // Determined by --use-codex flag
  "session_metadata": {
    // If in memory: use cached content
    // Else: Load from .workflow/{test-session-id}/workflow-session.json
  },
  "test_analysis_results_path": ".workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md",
  "test_analysis_results": {
    // If in memory: use cached content
    // Else: Load from TEST_ANALYSIS_RESULTS.md
  },
  "test_context_package_path": ".workflow/{test-session-id}/.process/test-context-package.json",
  "test_context_package": {
    // Existing test patterns and coverage analysis
  },
  "source_session_id": "[source-session-id]",  // if exists
  "source_session_summaries": {
    // Implementation context from source session
  },
  "mcp_capabilities": {
    "code_index": true,
    "exa_code": true,
    "exa_web": true
  }
}

Discovery Actions:

1. Load Test Session Context (if not in memory)

   if (!memory.has("workflow-session.json")) {
     Read(.workflow/{test-session-id}/workflow-session.json)
   }
   

2. Load TEST_ANALYSIS_RESULTS.md (if not in memory, REQUIRED)

   if (!memory.has("TEST_ANALYSIS_RESULTS.md")) {
     Read(.workflow/{test-session-id}/.process/TEST_ANALYSIS_RESULTS.md)
   }
   

3. Load Test Context Package (if not in memory)

   if (!memory.has("test-context-package.json")) {
     Read(.workflow/{test-session-id}/.process/test-context-package.json)
   }
   

4. Load Source Session Summaries (if source_session_id exists)

   if (sessionMetadata.source_session_id) {
     const summaryFiles = Bash("find .workflow/{source-session-id}/.summaries/ -name 'IMPL-*-summary.md'")
     summaryFiles.forEach(file => Read(file))
   }
   

5. Code Analysis with Native Tools (optional - enhance understanding)

   # Find test files and patterns
   find . -name "*test*" -type f
   rg "describe|it\(|test\(" -g "*.ts"
   

6. MCP External Research (optional - gather test best practices)

   // Get external test examples and patterns
   mcp__exa__get_code_context_exa(
     query="TypeScript test generation best practices jest",
     tokensNum="dynamic"
   )
   

Phase 2: Agent Execution (Document Generation)

Pre-Agent Template Selection (Command decides path before invoking agent):

// Command checks flag and selects template PATH (not content)
const templatePath = hasCliExecuteFlag
  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";

Agent Invocation:

Task(
  subagent_type="action-planning-agent",
  description="Generate test-fix task JSON and implementation plan",
  prompt=`
## Execution Context

**Session ID**: WFS-test-{session-id}
**Workflow Type**: Test Session
**Execution Mode**: {agent-mode | cli-execute-mode}
**Task JSON Template Path**: {template_path}
**Use Codex**: {true | false}

## Phase 1: Discovery Results (Provided Context)

### Test Session Metadata
{session_metadata_content}
- source_session_id: {source_session_id} (if exists)
- workflow_type: "test_session"

### TEST_ANALYSIS_RESULTS.md (REQUIRED)
{test_analysis_results_content}
- Coverage Assessment
- Test Framework & Conventions
- Test Requirements by File
- Test Generation Strategy
- Implementation Targets
- Success Criteria

### Test Context Package
{test_context_package_summary}
- Existing test patterns, framework config, coverage analysis

### Source Session Implementation Context (Optional)
{source_session_summaries}
- Implementation context from completed session

### MCP Analysis Results (Optional)
**Code Structure**: {mcp_code_index_results}
**External Research**: {mcp_exa_research_results}

## Phase 2: Test Task Document Generation

**Agent Configuration Reference**: All test task generation rules, test-fix cycle structure, quality standards, and execution details are defined in action-planning-agent.

Refer to: @.claude/agents/action-planning-agent.md for:
- Test Task Decomposition Standards
- Test-Fix-Retest Cycle Requirements
- 5-Field Task JSON Schema
- IMPL_PLAN.md Structure (Test variant)
- TODO_LIST.md Format
- Test Execution Flow & Quality Validation

### Test-Specific Requirements Summary

#### Task Structure Philosophy
- **Minimum 2 tasks**: IMPL-001 (test generation) + IMPL-002 (test execution & fix)
- **Expandable**: Add IMPL-003+ for complex projects (per-module, integration, etc.)
- IMPL-001: Uses @code-developer or CLI execution
- IMPL-002: Uses @test-fix-agent with iterative fix cycle

#### Test-Fix Cycle Configuration
- **Max Iterations**: 5 (for IMPL-002)
- **Diagnosis Tool**: Gemini with bug-fix template
- **Fix Application**: Manual (default) or Codex (if --use-codex flag)
- **Cycle Pattern**: test → gemini_diagnose → manual_fix (or codex) → retest
- **Exit Conditions**: All tests pass OR max iterations reached (auto-revert)

#### Required Outputs Summary

##### 1. Test Task JSON Files (.task/IMPL-*.json)
- **Location**: `.workflow/{test-session-id}/.task/`
- **Template**: Read from `{template_path}` (pre-selected by command based on `--cli-execute` flag)
- **Schema**: 5-field structure with test-specific metadata
  - IMPL-001: `meta.type: "test-gen"`, `meta.agent: "@code-developer"`
  - IMPL-002: `meta.type: "test-fix"`, `meta.agent: "@test-fix-agent"`, `meta.use_codex: {use_codex}`
  - `flow_control`: Test generation approach (IMPL-001) or test-fix cycle (IMPL-002)
- **Details**: See action-planning-agent.md § Test Task JSON Generation

##### 2. IMPL_PLAN.md (Test Variant)
- **Location**: `.workflow/{test-session-id}/IMPL_PLAN.md`
- **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
- **Test-Specific Frontmatter**: workflow_type="test_session", test_framework, source_session_id
- **Test-Fix-Retest Cycle Section**: Iterative fix cycle with Gemini diagnosis
- **Details**: See action-planning-agent.md § Test Implementation Plan Creation

##### 3. TODO_LIST.md
- **Location**: `.workflow/{test-session-id}/TODO_LIST.md`
- **Format**: Task list with test generation and execution phases
- **Status**: [ ] (pending), [x] (completed)
- **Details**: See action-planning-agent.md § TODO List Generation

### Agent Execution Summary

**Key Steps** (Detailed instructions in action-planning-agent.md):
1. Load task JSON template from provided path
2. Parse TEST_ANALYSIS_RESULTS.md for test requirements
3. Generate IMPL-001 (test generation) task JSON
4. Generate IMPL-002 (test execution & fix) task JSON with use_codex flag
5. Generate additional IMPL-*.json if project complexity requires
6. Create IMPL_PLAN.md using test template variant
7. Generate TODO_LIST.md with test task indicators
8. Update session state with test metadata

**Quality Gates** (Full checklist in action-planning-agent.md):
- ✓ Minimum 2 tasks created (IMPL-001 + IMPL-002)
- ✓ IMPL-001 has test generation approach from TEST_ANALYSIS_RESULTS.md
- ✓ IMPL-002 has test-fix cycle with correct use_codex flag
- ✓ Test framework configuration integrated
- ✓ Source session context referenced (if exists)
- ✓ MCP tool integration added
- ✓ Documents follow test template structure

## Output

Generate all three documents and report completion status:
- Test task JSON files created: N files (minimum 2)
- Test requirements integrated: TEST_ANALYSIS_RESULTS.md
- Test context integrated: existing patterns and coverage
- Source session context: {source_session_id} summaries (if exists)
- MCP enhancements: code-index, exa-research
- Session ready for test execution: /workflow:execute or /workflow:test-cycle-execute
`
)

Agent Context Passing

Memory-Aware Context Assembly:

// Assemble context package for agent
const agentContext = {
  session_id: "WFS-test-[id]",
  workflow_type: "test_session",
  use_codex: hasUseCodexFlag,

  // Use memory if available, else load
  session_metadata: memory.has("workflow-session.json")
    ? memory.get("workflow-session.json")
    : Read(.workflow/WFS-test-[id]/workflow-session.json),

  test_analysis_results_path: ".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md",

  test_analysis_results: memory.has("TEST_ANALYSIS_RESULTS.md")
    ? memory.get("TEST_ANALYSIS_RESULTS.md")
    : Read(".workflow/WFS-test-[id]/.process/TEST_ANALYSIS_RESULTS.md"),

  test_context_package_path: ".workflow/WFS-test-[id]/.process/test-context-package.json",

  test_context_package: memory.has("test-context-package.json")
    ? memory.get("test-context-package.json")
    : Read(".workflow/WFS-test-[id]/.process/test-context-package.json"),

  // Load source session summaries if exists
  source_session_id: session_metadata.source_session_id || null,

  source_session_summaries: session_metadata.source_session_id
    ? loadSourceSummaries(session_metadata.source_session_id)
    : null,

  // Optional MCP enhancements
  mcp_analysis: executeMcpDiscovery()
}

Test Task Structure Reference

This section provides quick reference for test task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.

Quick Reference:

• Minimum 2 tasks: IMPL-001 (test-gen) + IMPL-002 (test-fix)
• Expandable for complex projects (IMPL-003+)
• IMPL-001: meta.agent: "@code-developer", test generation approach
• IMPL-002: meta.agent: "@test-fix-agent", meta.use_codex: {flag}, test-fix cycle
• See Phase 2 agent prompt for full schema and requirements

Output Files Structure

.workflow/WFS-test-[session]/
├── workflow-session.json           # Test session metadata
├── IMPL_PLAN.md                    # Test validation plan
├── TODO_LIST.md                    # Progress tracking
├── .task/
│   └── IMPL-001.json               # Test-fix task with cycle spec
├── .process/
│   ├── ANALYSIS_RESULTS.md         # From concept-enhanced (optional)
│   ├── context-package.json        # From context-gather
│   ├── initial-test.log            # Phase 1: Initial test results
│   ├── fix-iteration-1-diagnosis.md # Gemini diagnosis iteration 1
│   ├── fix-iteration-1-changes.log  # Codex changes iteration 1
│   ├── fix-iteration-1-retest.log   # Retest results iteration 1
│   ├── fix-iteration-N-*.md/log    # Subsequent iterations
│   └── final-test.log              # Phase 3: Final validation
└── .summaries/
    └── IMPL-001-summary.md         # Success report OR failure report

Error Handling

Input Validation Errors

Error	Cause	Resolution
Not a test session	Missing workflow_type: "test_session"	Verify session created by test-gen
Source session not found	Invalid source_session_id	Check source session exists
No implementation summaries	Source session incomplete	Ensure source session has completed tasks

Test Framework Discovery Errors

Error	Cause	Resolution
No test command found	Unknown framework	Manual test command specification
No test files found	Tests not written	Request user to write tests first
Test dependencies missing	Incomplete setup	Run dependency installation

Generation Errors

Error	Cause	Resolution
Invalid JSON structure	Template error	Fix task generation logic
Missing required fields	Incomplete metadata	Validate session metadata

Integration & Usage

Command Chain

• Called By: /workflow:test-gen (Phase 4), /workflow:test-fix-gen (Phase 4)
• Invokes: action-planning-agent for autonomous task generation
• Followed By: /workflow:execute or /workflow:test-cycle-execute (user-triggered)

Basic Usage

# Agent mode (default, autonomous execution)
/workflow:tools:test-task-generate --session WFS-test-auth

# With automated Codex fixes for IMPL-002
/workflow:tools:test-task-generate --use-codex --session WFS-test-auth

# CLI execution mode for IMPL-001 test generation
/workflow:tools:test-task-generate --cli-execute --session WFS-test-auth

# Both flags combined
/workflow:tools:test-task-generate --cli-execute --use-codex --session WFS-test-auth

Execution Modes

• Agent mode (default): Uses action-planning-agent with agent-mode task template
• CLI mode (--cli-execute): Uses Gemini/Qwen/Codex with cli-mode task template for IMPL-001
• Codex fixes (--use-codex): Enables automated fixes in IMPL-002 task

Flag Behavior

• No flags: meta.use_codex=false (manual fixes), agent-mode generation
• --use-codex: meta.use_codex=true (Codex automated fixes with resume mechanism in IMPL-002)
• --cli-execute: Uses CLI tool execution mode for IMPL-001 test generation
• Both flags: CLI generation + automated Codex fixes

Output

• Test task JSON files in .task/ directory (minimum 2: IMPL-001.json + IMPL-002.json)
• IMPL_PLAN.md with test generation and fix cycle strategy
• TODO_LIST.md with test task indicators
• Session state updated with test metadata
• MCP enhancements integrated (if available)

Agent Execution Notes

The @test-fix-agent will execute the task by following the flow_control.implementation_approach specification:

1. Load task JSON: Read complete test-fix task from .task/IMPL-002.json
2. Check meta.use_codex: Determine fix mode (manual or automated)
3. Execute pre_analysis: Load source context, discover framework, analyze tests
4. Phase 1: Run initial test suite
5. Phase 2: If failures, enter iterative loop:
   • Use Gemini for diagnosis (analysis mode with bug-fix template)
   • Check meta.use_codex flag:
     • If false (default): Present fix suggestions to user for manual application
     • If true (--use-codex): Use Codex resume for automated fixes (maintains context)
   • Retest and check for regressions
   • Repeat max 5 times
6. Phase 3: Generate summary and certify code
7. Error Recovery: Revert changes if max iterations reached

Bug Diagnosis Template: Uses ~/.claude/workflows/cli-templates/prompts/analysis/01-diagnose-bug-root-cause.txt template for systematic root cause analysis, code path tracing, and targeted fix recommendations.

Codex Usage: The agent uses codex exec "..." resume --last pattern ONLY when meta.use_codex=true (--use-codex flag present) to maintain conversation context across multiple fix iterations, ensuring consistency and learning from previous attempts.