Claude-Code-Workflow/.claude/commands/workflow/test-gen.md

name, description, usage, argument-hint, examples, allowed-tools

name	description	usage	argument-hint	examples	allowed-tools
test-gen	Create independent test-fix workflow session by analyzing completed implementation	/workflow:test-gen <source-session-id>	<source-session-id>	/workflow:test-gen WFS-user-auth /workflow:test-gen WFS-api-refactor	SlashCommand(*), TodoWrite(*), Read(*), Bash(*)

Workflow Test Generation Command (/workflow:test-gen)

Coordinator Role

This command is a pure orchestrator: Creates an independent test-fix workflow session for validating a completed implementation. It reuses the standard planning toolchain with automatic cross-session context gathering.

Core Principles:

• Session Isolation: Creates new WFS-test-[source] session to keep verification separate from implementation
• 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

Execution Flow:

1. Initialize TodoWrite → Create test session → Parse session ID
2. Gather cross-session context (automatic) → Parse context path
3. Analyze implementation with concept-enhanced → Parse ANALYSIS_RESULTS.md
4. Generate test task from analysis → Return summary

Core Rules

1. Start Immediately: First action is TodoWrite initialization, second action is Phase 1 test session creation
2. No Preliminary Analysis: Do not read files or analyze before Phase 1
3. Parse Every Output: Extract required data from each phase for next phase
4. Sequential Execution: Each phase depends on previous phase's output
5. Complete All Phases: Do not return to user until Phase 4 completes (execution triggered separately)
6. Track Progress: Update TodoWrite after every phase completion
7. Automatic Detection: context-gather auto-detects test session and gathers source session context

4-Phase Execution

Phase 1: Create Test Session

Command: SlashCommand(command="/workflow:session:start --new \"Test validation for [sourceSessionId]\"")

Input: sourceSessionId from user argument (e.g., WFS-user-auth)

Expected Behavior:

• Creates new session with pattern WFS-test-[source-slug] (e.g., WFS-test-user-auth)
• Writes metadata to workflow-session.json:
  • workflow_type: "test_session"
  • source_session_id: "[sourceSessionId]"
• Returns new session ID for subsequent phases

Parse Output:

• Extract: new test session ID (store as testSessionId)
• Pattern: WFS-test-[slug]

Validation:

• Source session .workflow/[sourceSessionId]/ exists
• Source session has completed IMPL tasks (.summaries/IMPL-*-summary.md)
• New test session directory created
• Metadata includes workflow_type and source_session_id

TodoWrite: Mark phase 1 completed, phase 2 in_progress

---

Phase 2: Gather Cross-Session Context

Command: SlashCommand(command="/workflow:tools:context-gather --session [testSessionId]")

Input: testSessionId from Phase 1 (e.g., WFS-test-user-auth)

Automatic Detection:

• context-gather reads .workflow/[testSessionId]/workflow-session.json
• Detects workflow_type: "test_session"
• Automatically uses source_session_id to gather source session context
• No need for manual --source-session parameter

Cross-Session Context Collection (Automatic):

• Implementation summaries: .workflow/[sourceSessionId]/.summaries/IMPL-*-summary.md
• Code changes: git log --since=[source_session_created_at] for changed files
• Original plan: .workflow/[sourceSessionId]/IMPL_PLAN.md
• Test files: Discovered via MCP code-index tools

Parse Output:

• Extract: context package path (store as contextPath)
• Pattern: .workflow/[testSessionId]/.process/context-package.json

Validation:

• Context package created in test session directory
• Contains source session artifacts (summaries, changed files)
• Includes test file inventory

TodoWrite: Mark phase 2 completed, phase 3 in_progress

---

Phase 3: Implementation Analysis

Command: SlashCommand(command="/workflow:tools:concept-enhanced --session [testSessionId] --context [contextPath]")

Input:

• testSessionId from Phase 1 (e.g., WFS-test-user-auth)
• contextPath from Phase 2 (e.g., .workflow/WFS-test-user-auth/.process/context-package.json)

Analysis Focus:

• Review implementation summaries from source session
• Identify test files and coverage gaps
• Assess test execution strategy (unit, integration, e2e)
• Determine failure diagnosis approach
• Recommend code quality improvements

Expected Behavior:

• Reads context-package.json with cross-session artifacts
• Executes parallel analysis (Gemini for test strategy, optional Codex for validation)
• Generates comprehensive test execution strategy
• Identifies code modification targets for test fixes
• Provides feasibility assessment for test validation

Parse Output:

• Verify .workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md created
• Contains test strategy and execution plan
• Lists code modification targets (format: file:function:lines or file)
• Includes risk assessment and optimization recommendations

Validation:

• File .workflow/[testSessionId]/.process/ANALYSIS_RESULTS.md exists
• Contains complete analysis sections:
  • Current State Analysis (test coverage, existing tests)
  • Proposed Solution Design (test execution strategy)
  • Implementation Strategy (code targets, feasibility)
  • Solution Optimization (performance, quality)
  • Critical Success Factors (acceptance criteria)

TodoWrite: Mark phase 3 completed, phase 4 in_progress

---

Phase 4: Generate Test Task

Command: SlashCommand(command="/workflow:tools:task-generate --session [testSessionId]")

Input: testSessionId from Phase 1

Expected Behavior:

• Reads ANALYSIS_RESULTS.md from Phase 3
• Extracts test strategy and code modification targets
• Generates IMPL-001.json (reusing standard format) with:
  • meta.type: "test-fix" (enables @test-fix-agent assignment)
  • meta.agent: "@test-fix-agent"
  • context.requirements: Test execution requirements from analysis
  • context.focus_paths: Test files and source files from analysis
  • context.acceptance: All tests pass criteria
  • flow_control.pre_analysis: Load source session summaries
  • flow_control.implementation_approach: Test execution strategy from ANALYSIS_RESULTS.md
  • flow_control.target_files: Code modification targets from analysis

Parse Output:

• Verify .workflow/[testSessionId]/.task/IMPL-001.json exists
• Verify .workflow/[testSessionId]/IMPL_PLAN.md created
• Verify .workflow/[testSessionId]/TODO_LIST.md created

Validation:

• Task JSON has id: "IMPL-001" and meta.type: "test-fix"
• IMPL_PLAN.md contains test validation strategy from ANALYSIS_RESULTS.md
• TODO_LIST.md shows IMPL-001 task
• flow_control includes code targets and test strategy
• Task is ready for /workflow:execute

TodoWrite: Mark phase 4 completed

Return to User:

Independent test-fix workflow created successfully!

Source Session: [sourceSessionId]
Test Session: [testSessionId]
Task Created: IMPL-001 (test-fix)

Next Steps:
1. Review test plan: .workflow/[testSessionId]/IMPL_PLAN.md
2. Execute validation: /workflow:execute
3. Monitor progress: /workflow:status

The @test-fix-agent will:
- Execute all tests
- Diagnose any failures
- Fix code until tests pass

---

TodoWrite Pattern

// Initialize (before Phase 1)
TodoWrite({todos: [
  {"content": "Create independent test session", "status": "in_progress", "activeForm": "Creating test session"},
  {"content": "Gather cross-session context", "status": "pending", "activeForm": "Gathering cross-session context"},
  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
]})

// After Phase 1
TodoWrite({todos: [
  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
  {"content": "Gather cross-session context", "status": "in_progress", "activeForm": "Gathering cross-session context"},
  {"content": "Analyze implementation for test strategy", "status": "pending", "activeForm": "Analyzing implementation"},
  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
]})

// After Phase 2
TodoWrite({todos: [
  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
  {"content": "Analyze implementation for test strategy", "status": "in_progress", "activeForm": "Analyzing implementation"},
  {"content": "Generate test validation task", "status": "pending", "activeForm": "Generating test validation task"}
]})

// After Phase 3
TodoWrite({todos: [
  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
  {"content": "Generate test validation task", "status": "in_progress", "activeForm": "Generating test validation task"}
]})

// After Phase 4
TodoWrite({todos: [
  {"content": "Create independent test session", "status": "completed", "activeForm": "Creating test session"},
  {"content": "Gather cross-session context", "status": "completed", "activeForm": "Gathering cross-session context"},
  {"content": "Analyze implementation for test strategy", "status": "completed", "activeForm": "Analyzing implementation"},
  {"content": "Generate test validation task", "status": "completed", "activeForm": "Generating test validation task"}
]})

Data Flow

User: /workflow:test-gen WFS-user-auth
    ↓
Phase 1: session-start --new "Test validation for WFS-user-auth"
    ↓ Creates: WFS-test-user-auth session
    ↓ Writes: workflow-session.json with workflow_type="test_session", source_session_id="WFS-user-auth"
    ↓ Output: testSessionId = "WFS-test-user-auth"
    ↓
Phase 2: context-gather --session WFS-test-user-auth
    ↓ Auto-detects: test session type from workflow-session.json
    ↓ Auto-reads: source_session_id = "WFS-user-auth"
    ↓ Gathers: Cross-session context (summaries, code changes, tests)
    ↓ Output: .workflow/WFS-test-user-auth/.process/context-package.json
    ↓
Phase 3: concept-enhanced --session WFS-test-user-auth --context context-package.json
    ↓ Reads: context-package.json with cross-session artifacts
    ↓ Executes: Parallel analysis (Gemini test strategy + optional Codex validation)
    ↓ Analyzes: Test coverage, execution strategy, code targets
    ↓ Output: .workflow/WFS-test-user-auth/.process/ANALYSIS_RESULTS.md
    ↓
Phase 4: task-generate --session WFS-test-user-auth
    ↓ Reads: ANALYSIS_RESULTS.md with test strategy and code targets
    ↓ Generates: IMPL-001.json with meta.type="test-fix"
    ↓ Output: Task, plan, and todo files in test session
    ↓
Return: Summary with next steps (user triggers /workflow:execute separately)

Session Metadata Design

Test Session (WFS-test-user-auth/workflow-session.json):

{
  "session_id": "WFS-test-user-auth",
  "project": "Test validation for user authentication implementation",
  "status": "planning",
  "created_at": "2025-10-03T12:00:00Z",
  "workflow_type": "test_session",
  "source_session_id": "WFS-user-auth"
}

Automatic Cross-Session Context Collection

When context-gather detects workflow_type: "test_session":

Collected from Source Session (.workflow/WFS-user-auth/):

• Implementation summaries: .summaries/IMPL-*-summary.md
• Code changes: git log --since=[source_created_at] --name-only
• Original plan: IMPL_PLAN.md
• Task definitions: .task/IMPL-*.json

Collected from Current Project:

• Test files: mcp__code-index__find_files(pattern="*.test.*")
• Test configuration: package.json, jest.config.js, etc.
• Source files: Based on changed files from git log

Task Generation Output

task-generate creates IMPL-001.json (reusing standard format) with:

{
  "id": "IMPL-001",
  "title": "Execute and validate tests for [sourceSessionId]",
  "status": "pending",
  "meta": {
    "type": "test-fix",
    "agent": "@test-fix-agent"
  },
  "context": {
    "requirements": [
      "Execute complete test suite for all implemented modules",
      "Diagnose and fix any test failures",
      "Ensure all tests pass before completion"
    ],
    "focus_paths": ["src/**/*.test.ts", "src/**/implementation.ts"],
    "acceptance": [
      "All tests pass successfully",
      "No test failures or errors",
      "Code is approved and ready for deployment"
    ],
    "depends_on": [],
    "artifacts": []
  },
  "flow_control": {
    "pre_analysis": [
      {
        "step": "load_source_session_summaries",
        "action": "Load implementation summaries from source session",
        "commands": [
          "bash(find .workflow/[sourceSessionId]/.summaries/ -name 'IMPL-*-summary.md' 2>/dev/null)",
          "Read(.workflow/[sourceSessionId]/.summaries/IMPL-001-summary.md)"
        ],
        "output_to": "implementation_context",
        "on_error": "skip_optional"
      },
      {
        "step": "analyze_test_files",
        "action": "Identify test files and coverage",
        "commands": [
          "mcp__code-index__find_files(pattern=\"*.test.*\")",
          "mcp__code-index__search_code_advanced(pattern=\"test|describe|it\", file_pattern=\"*.test.*\")"
        ],
        "output_to": "test_inventory",
        "on_error": "fail"
      }
    ],
    "implementation_approach": {
      "task_description": "Execute tests and fix failures until all pass",
      "modification_points": [
        "Run test suite using detected framework",
        "Parse test output to identify failures",
        "Diagnose root cause of failures",
        "Modify source code to fix issues",
        "Re-run tests to verify fixes"
      ],
      "logic_flow": [
        "Load implementation context",
        "Identify test framework and configuration",
        "Execute complete test suite",
        "If failures: analyze error messages",
        "Fix source code based on diagnosis",
        "Re-run tests",
        "Repeat until all tests pass"
      ]
    },
    "target_files": ["src/**/*.test.ts", "src/**/implementation.ts"]
  }
}

Error Handling

Phase 1 Failures

• Source session not found: Return error "Source session [sourceSessionId] not found in .workflow/"
• Invalid source session: Return error "Source session [sourceSessionId] has no completed IMPL tasks"
• Session creation failed: Return error "Could not create test session. Check /workflow:session:start"

Phase 2 Failures

• Context gathering failed: Return error "Could not gather cross-session context. Check source session artifacts"
• No source artifacts: Return error "Source session has no implementation summaries or git history"

Phase 3 Failures

• Analysis failed: Return error "Implementation analysis failed. Check context package and ANALYSIS_RESULTS.md"
• No test strategy: Return error "Could not determine test execution strategy from analysis"
• Missing code targets: Warning only, proceed with general test task

Phase 4 Failures

• Task generation failed: Retry once, then return error with details
• Invalid task structure: Return error with JSON validation details

Workflow Integration

Complete Flow Example

1. Implementation Phase (prior to test-gen)
   /workflow:plan "Build auth system"
   → Creates WFS-auth session
   → @code-developer implements + writes tests
   → Creates IMPL-001-summary.md in WFS-auth

2. Test Generation Phase (test-gen)
   /workflow:test-gen WFS-auth
   Phase 1: session-start → Creates WFS-test-auth session
   Phase 2: context-gather → Gathers from WFS-auth, creates context-package.json
   Phase 3: concept-enhanced → Analyzes implementation, creates ANALYSIS_RESULTS.md
   Phase 4: task-generate → Creates IMPL-001.json with meta.type="test-fix"
   Returns: Summary with next steps

3. Test Execution Phase (user-triggered)
   /workflow:execute
   → Detects active session: WFS-test-auth
   → @test-fix-agent picks up IMPL-001 (test-fix type)
   → Runs test suite
   → Diagnoses failures (if any)
   → Fixes source code
   → Re-runs tests
   → All pass → Code approved ✅

Output Files Created

In Test Session (.workflow/WFS-test-auth/):

• workflow-session.json - Contains workflow_type and source_session_id
• .process/context-package.json - Cross-session context from WFS-auth
• .process/ANALYSIS_RESULTS.md - Test strategy and code targets from concept-enhanced
• .task/IMPL-001.json - Test-fix task definition
• IMPL_PLAN.md - Test validation plan (from ANALYSIS_RESULTS.md)
• TODO_LIST.md - Task checklist
• .summaries/IMPL-001-summary.md - Created by @test-fix-agent after completion

Best Practices

1. Run after implementation complete: Ensure source session has completed IMPL tasks and summaries
2. Check git commits: Implementation changes should be committed for accurate git log analysis
3. Verify test files exist: Source implementation should include test files
4. Independent sessions: Test session is separate from implementation session for clean separation
5. Monitor execution: Use /workflow:status to track test-fix progress after /workflow:execute

Coordinator Checklist

✅ Initialize TodoWrite before any command (4 phases) ✅ Phase 1: Create test session with source session ID ✅ Parse new test session ID from Phase 1 output ✅ Phase 2: Run context-gather (auto-detects test session, no extra params) ✅ Verify context-package.json contains cross-session artifacts ✅ Phase 3: Run concept-enhanced with session and context path ✅ Verify ANALYSIS_RESULTS.md contains test strategy and code targets ✅ Phase 4: Run task-generate to create IMPL-001.json ✅ Verify task has meta.type="test-fix" and meta.agent="@test-fix-agent" ✅ Verify flow_control includes analysis insights and code targets ✅ Update TodoWrite after each phase ✅ Return summary after Phase 4 (execution is separate user action)

Required Tool Modifications

/workflow:session:start

• Support --new flag for test session creation
• Auto-detect test session pattern from task description
• Write workflow_type: "test_session" and source_session_id to metadata

/workflow:tools:context-gather

• Read session metadata to detect workflow_type: "test_session"
• Auto-extract source_session_id from metadata
• Gather cross-session context from source session artifacts
• Include git log analysis from source session creation time

/workflow:tools:concept-enhanced

• No changes required (already supports cross-session context analysis)
• Will automatically analyze test strategy based on context-package.json
• Generates ANALYSIS_RESULTS.md with code targets and test execution plan

/workflow:tools:task-generate

• Recognize test session context and generate appropriate task
• Create IMPL-001.json with meta.type: "test-fix"
• Extract test strategy from ANALYSIS_RESULTS.md
• Include code targets and cross-session references in flow_control

/workflow:execute

• No changes required (already dispatches by meta.agent)

Related Commands

• /workflow:plan - Create implementation workflow (run before test-gen)
• /workflow:session:start - Phase 1 tool for test session creation
• /workflow:tools:context-gather - Phase 2 tool for cross-session context collection
• /workflow:tools:concept-enhanced - Phase 3 tool for implementation analysis and test strategy
• /workflow:tools:task-generate - Phase 4 tool for test task creation
• /workflow:execute - Execute test-fix workflow (user-triggered after test-gen)
• /workflow:status - Check workflow progress
• @test-fix-agent - Agent that executes and fixes tests