Agent-Skills.md

Agent Skills: Workflow Test-Fix Cycle

End-to-end test-fix workflow generate test sessions with progressive layers (L0-L3), then execute iterative fix cycles until pass rate >= 95%. Combines test-fix-gen and test-cycle-execute into a unified pipeline. Triggers on \"workflow:test-fix-cycle\".

UncategorizedID: catlog22/claude-code-workflow/workflow-test-fix-cycle

Repository

catlog22/claude-code-workflow
catlog22License: MIT
1,610136

Install this agent skill to your local

pnpm dlx add-skill https://github.com/catlog22/Claude-Code-Workflow/tree/HEAD/.codex/skills/workflow-test-fix-cycle

Skill Files

Browse the full folder contents for workflow-test-fix-cycle.

Download Skill

Loading file tree…

.codex/skills/workflow-test-fix-cycle/SKILL.md

Skill Metadata

Name
workflow-test-fix-cycle
Description
"End-to-end test-fix workflow generate test sessions with progressive layers (L0-L3), then execute iterative fix cycles until pass rate >= 95%. Combines test-fix-gen and test-cycle-execute into a unified pipeline. Triggers on \"workflow:test-fix-cycle\"."

Workflow Test-Fix Cycle

End-to-end test-fix workflow pipeline: generate test sessions with progressive layers (L0-L3), AI code validation, and task generation (Phase 1), then execute iterative fix cycles with adaptive strategy engine until pass rate >= 95% (Phase 2).

Architecture Overview

┌────────────────────────────────────────────────────────────────────────────┐
│  Workflow Test-Fix Cycle Orchestrator (SKILL.md)                            │
│  → Full pipeline: Test generation + Iterative execution                     │
│  → Phase dispatch: Read phase docs, execute, pass context                   │
└───────────────┬────────────────────────────────────────────────────────────┘
                │
   ┌────────────┴────────────────────────┐
   ↓                                     ↓
┌─────────────────────────┐   ┌─────────────────────────────┐
│ Phase 1: Test-Fix Gen   │   │ Phase 2: Test-Cycle Execute  │
│ phases/01-test-fix-gen  │   │ phases/02-test-cycle-execute │
│ 5 sub-phases:           │   │ 3 stages:                    │
│ ① Create Session        │   │ ① Discovery                  │
│ ② Gather Context        │   │ ② Main Loop (iterate)        │
│ ③ Test Analysis (Gemini)│   │ ③ Completion                 │
│ ④ Generate Tasks        │   │                              │
│ ⑤ Summary               │   │ Agents (via spawn_agent):    │
│                         │   │ @cli-planning-agent           │
│ Agents (via spawn_agent)│   │ @test-fix-agent               │
│ @test-context-search    │   │                              │
│ @context-search         │   │ Strategy: conservative →      │
│ @cli-execution          │   │ aggressive → surgical          │
│ @action-planning        │   │                              │
└────────┬────────────────┘   └────────────┬──────────────────┘
         ↓                                 ↓
   IMPL-001..002.json              Pass Rate >= 95%
   TEST_ANALYSIS_RESULTS.md        Auto-complete session

Task Pipeline:
┌──────────────┐    ┌─────────────────┐    ┌─────────────────┐    ┌──────────────┐
│  IMPL-001    │───→│  IMPL-001.3     │───→│  IMPL-001.5     │───→│  IMPL-002    │
│  Test Gen    │    │  Code Validate  │    │  Quality Gate   │    │  Test & Fix  │
│  L1-L3       │    │  L0 + AI Issues │    │  Coverage 80%+  │    │  Max 10 iter │
│@code-developer│   │ @test-fix-agent │    │ @test-fix-agent │    │@test-fix-agent│
└──────────────┘    └─────────────────┘    └─────────────────┘    └──────────────┘
                                                                        │
                                                              Fix Loop: │
                                                    ┌──────────────────┘
                                                    ↓
                                              ┌──────────┐
                                              │ @cli-plan│───→ IMPL-fix-N.json
                                              │  agent   │
                                              ├──────────┤
                                              │@test-fix │───→ Apply & re-test
                                              │  agent   │
                                              └──────────┘

Key Design Principles

  1. Two-Phase Pipeline: Generation (Phase 1) creates session + tasks, Execution (Phase 2) runs iterative fix cycles
  2. Pure Orchestrator: Dispatch to phase docs, parse outputs, pass context between phases
  3. Phase 1 Auto-Continue: Sub-phases within Phase 1 run autonomously
  4. Subagent Lifecycle: Explicit lifecycle management with spawn_agent → wait → close_agent
  5. Progressive Test Layers: L0 (Static) → L1 (Unit) → L2 (Integration) → L3 (E2E)
  6. AI Code Issue Detection: Validates against common AI-generated code problems
  7. Intelligent Strategy Engine: conservative → aggressive → surgical based on iteration context
  8. CLI Fallback Chain: Gemini → Qwen → Codex for analysis resilience
  9. Progressive Testing: Affected tests during iterations, full suite for final validation
  10. Role Path Loading: Subagent roles loaded via path reference in MANDATORY FIRST STEPS

Auto Mode

Phase 1 generates test session and tasks. Phase 2 executes iterative fix cycles until pass rate >= 95% or max iterations reached. Between Phase 1 and Phase 2, you MUST stop and wait for user confirmation before proceeding to execution. Phase 2 runs autonomously once approved.

Subagent API Reference

spawn_agent

Create a new subagent with task assignment.

const agentId = spawn_agent({
  agent_type: "{agent_type}",
  message: `
## TASK ASSIGNMENT

### MANDATORY FIRST STEPS (Agent Execute)
1. Run: `ccw spec load --category "planning execution"`

## TASK CONTEXT
${taskContext}

## DELIVERABLES
${deliverables}
`
})

wait

Get results from subagent (only way to retrieve results).

const result = wait({
  ids: [agentId],
  timeout_ms: 600000  // 10 minutes
})

if (result.timed_out) {
  // Handle timeout - can continue waiting or send_input to prompt completion
}

send_input

Continue interaction with active subagent (for clarification or follow-up).

send_input({
  id: agentId,
  message: `
## CLARIFICATION ANSWERS
${answers}

## NEXT STEP
Continue with plan generation.
`
})

close_agent

Clean up subagent resources (irreversible).

close_agent({ id: agentId })

Usage

workflow-test-fix-cycle <input> [options]

# Input (Phase 1 - Test Generation)
source-session-id    WFS-* session ID (Session Mode - test validation for completed implementation)
feature description  Text description of what to test (Prompt Mode)
/path/to/file.md     Path to requirements file (Prompt Mode)

# Options (Phase 2 - Cycle Execution)
--max-iterations=N   Custom iteration limit (default: 10)

# Examples
workflow-test-fix-cycle WFS-user-auth-v2                                              # Session Mode
workflow-test-fix-cycle "Test the user authentication API endpoints in src/auth/api.ts" # Prompt Mode - text
workflow-test-fix-cycle ./docs/api-requirements.md                                     # Prompt Mode - file
workflow-test-fix-cycle "Test user registration" --max-iterations=15                    # With custom iterations

# Resume (Phase 2 only - session already created)
workflow-test-fix-cycle --resume-session="WFS-test-user-auth"                          # Resume interrupted session

Quality Gate: Test pass rate >= 95% (criticality-aware) or 100% Max Iterations: 10 (default, adjustable) CLI Tools: Gemini → Qwen → Codex (fallback chain)

Test Strategy Overview

Progressive Test Layers (L0-L3):

| Layer | Name | Focus | |-------|------|-------| | L0 | Static Analysis | Compilation, imports, types, AI code issues | | L1 | Unit Tests | Function/class behavior (happy/negative/edge cases) | | L2 | Integration Tests | Component interactions, API contracts, failure modes | | L3 | E2E Tests | User journeys, critical paths (optional) |

Key Features:

  • AI Code Issue Detection - Validates against common AI-generated code problems (hallucinated imports, placeholder code, mock leakage, etc.)
  • Project Type Detection - Applies appropriate test templates (React, Node API, CLI, Library, etc.)
  • Quality Gates - IMPL-001.3 (code validation) and IMPL-001.5 (test quality) ensure high standards

Detailed specifications: See the test-task-generate workflow tool for complete L0-L3 requirements and quality thresholds.

Execution Flow

Input → Detect Mode (session | prompt | resume)
  │
  ├─ resume mode → Skip to Phase 2
  │
  └─ session/prompt mode → Phase 1
       │
Phase 1: Test-Fix Generation (phases/01-test-fix-gen.md)
  ├─ Sub-phase 1.1: Create Test Session → testSessionId
  ├─ Sub-phase 1.2: Gather Test Context (spawn_agent) → contextPath
  ├─ Sub-phase 1.3: Test Generation Analysis (spawn_agent → Gemini) → TEST_ANALYSIS_RESULTS.md
  ├─ Sub-phase 1.4: Generate Test Tasks (spawn_agent) → IMPL-*.json, IMPL_PLAN.md, TODO_LIST.md
  └─ Sub-phase 1.5: Phase 1 Summary
       │
  ⛔ MANDATORY CONFIRMATION GATE
  │   Present plan summary → request_user_input → User approves/cancels
  │   NEVER auto-proceed to Phase 2
       │
Phase 2: Test-Cycle Execution (phases/02-test-cycle-execute.md)
  ├─ Discovery: Load session, tasks, iteration state
  ├─ Main Loop (for each task):
  │   ├─ Execute → Test → Calculate pass_rate
  │   ├─ 100% → SUCCESS: Next task
  │   ├─ 95-99% + low criticality → PARTIAL SUCCESS: Approve
  │   └─ <95% → Fix Loop:
  │       ├─ Select strategy: conservative/aggressive/surgical
  │       ├─ spawn_agent(@cli-planning-agent) → IMPL-fix-N.json
  │       ├─ spawn_agent(@test-fix-agent) → Apply fix & re-test
  │       └─ Re-test → Back to decision
  └─ Completion: Final validation → Summary → Sync session state → Auto-complete session

Core Rules

  1. Start Immediately: First action is progress tracking initialization
  2. No Preliminary Analysis: Do not read files before Phase 1
  3. Parse Every Output: Extract data from each phase/sub-phase for the next
  4. Within-Phase Auto-Continue: Sub-phases within a phase run automatically; Phase 2 iterations run automatically once started
  5. Phase Loading: Read phase doc on-demand (phases/01-*.md, phases/02-*.md)
  6. Task Attachment Model: Sub-tasks ATTACH → execute → COLLAPSE
  7. MANDATORY CONFIRMATION GATE: After Phase 1 completes, you MUST stop and present the generated plan to the user. Wait for explicit user approval via request_user_input before starting Phase 2. NEVER auto-proceed from Phase 1 to Phase 2
  8. Phase 2 Continuous: Once user approves, Phase 2 runs continuously until pass rate >= 95% or max iterations reached
  9. Explicit Lifecycle: Always close_agent after wait completes to free resources

Phase Execution

Phase 1: Test-Fix Generation

Read: phases/01-test-fix-gen.md

5 sub-phases that create a test session and generate task JSONs:

  1. Create Test Session → testSessionId
  2. Gather Test Context (spawn_agent → wait → close_agent) → contextPath
  3. Test Generation Analysis (spawn_agent → wait → close_agent) → TEST_ANALYSIS_RESULTS.md
  4. Generate Test Tasks (spawn_agent → wait → close_agent) → IMPL-001.json, IMPL-001.3.json, IMPL-001.5.json, IMPL-002.json, IMPL_PLAN.md, TODO_LIST.md
  5. Phase 1 Summary → ⛔ MANDATORY: Present plan and wait for user confirmation before Phase 2

Agents Used (via spawn_agent):

  • test_context_search_agent (agent_type: test_context_search_agent) - Context gathering (Session Mode)
  • context_search_agent (agent_type: context_search_agent) - Context gathering (Prompt Mode)
  • cli_execution_agent (agent_type: cli_execution_agent) - Test analysis with Gemini
  • action_planning_agent (agent_type: action_planning_agent) - Task JSON generation

Phase 2: Test-Cycle Execution

Read: phases/02-test-cycle-execute.md

3-stage iterative execution with adaptive strategy:

  1. Discovery - Load session, tasks, iteration state
  2. Main Loop - Execute tasks → Test → Analyze failures → Fix → Re-test
  3. Completion - Final validation → Summary → Auto-complete session

Agents Used (via spawn_agent):

  • cli_planning_agent (agent_type: cli_planning_agent) - Failure analysis, root cause extraction, fix task generation
  • test_fix_agent (agent_type: test_fix_agent) - Test execution, code fixes, criticality assignment

Strategy Engine: conservative (iteration 1-2) → aggressive (pass >80%) → surgical (regression)

Output Artifacts

Directory Structure

{projectRoot}/.workflow/active/WFS-test-[session]/
├── workflow-session.json              # Session metadata
├── IMPL_PLAN.md                       # Test generation and execution strategy
├── TODO_LIST.md                       # Task checklist
├── .task/
│   ├── IMPL-001.json                  # Test understanding & generation
│   ├── IMPL-001.3-validation.json     # Code validation gate
│   ├── IMPL-001.5-review.json         # Test quality gate
│   ├── IMPL-002.json                  # Test execution & fix cycle
│   └── IMPL-fix-{N}.json             # Generated fix tasks (Phase 2)
├── .process/
│   ├── [test-]context-package.json    # Context and coverage analysis
│   ├── TEST_ANALYSIS_RESULTS.md       # Test requirements and strategy (L0-L3)
│   ├── iteration-state.json           # Current iteration + strategy + stuck tests
│   ├── test-results.json              # Latest results (pass_rate, criticality)
│   ├── test-output.log                # Full test output
│   ├── fix-history.json               # All fix attempts
│   ├── iteration-{N}-analysis.md      # CLI analysis report
│   └── iteration-{N}-cli-output.txt
└── .summaries/iteration-summaries/

Progress Tracking Pattern

Phase 1 (Generation):

[
  { content: "Phase 1: Test-Fix Generation", status: "in_progress" },
  { content: "  1.1 Create Test Session", status: "completed" },
  { content: "  1.2 Gather Test Context", status: "in_progress" },
  { content: "  1.3 Test Generation Analysis", status: "pending" },
  { content: "  1.4 Generate Test Tasks", status: "pending" },
  { content: "  1.5 Phase Summary", status: "pending" },
  { content: "Phase 2: Test-Cycle Execution", status: "pending" }
]

Phase 2 (Execution):

[
  { content: "Phase 1: Test-Fix Generation", status: "completed" },
  { content: "Phase 2: Test-Cycle Execution", status: "in_progress" },
  { content: "  Execute IMPL-001: Generate tests [code-developer]", status: "completed" },
  { content: "  Execute IMPL-002: Test & Fix Cycle [ITERATION]", status: "in_progress" },
  { content: "    → Iteration 1: Initial test (pass: 70%, conservative)", status: "completed" },
  { content: "    → Iteration 2: Fix validation (pass: 82%, conservative)", status: "completed" },
  { content: "    → Iteration 3: Batch fix auth (pass: 89%, aggressive)", status: "in_progress" }
]

Update Rules:

  • Phase 1: Attach/collapse sub-phase tasks within Phase 1
  • Phase 2: Add iteration items with strategy and pass rate
  • Mark completed after each phase/iteration
  • Update parent task when all complete

Error Handling

| Phase | Scenario | Action | |-------|----------|--------| | 1.1 | Source session not found (session mode) | Return error with session ID | | 1.1 | No completed IMPL tasks (session mode) | Return error, source incomplete | | 1.2 | Context gathering failed | Return error, check source artifacts | | 1.2 | Agent timeout | Retry with extended timeout, close_agent, then return error | | 1.3 | Gemini analysis failed | Return error, check context package | | 1.4 | Task generation failed | Retry once, then return error | | 2 | Test execution error | Log, retry with error context | | 2 | CLI analysis failure | Fallback: Gemini → Qwen → Codex → manual | | 2 | Agent execution error | Save state, close_agent, retry with simplified context | | 2 | Max iterations reached | Generate failure report, mark blocked | | 2 | Regression detected | Rollback last fix, switch to surgical strategy | | 2 | Stuck tests detected | Continue with alternative strategy, document in failure report |

Lifecycle Error Handling:

try {
  const agentId = spawn_agent({ message: "..." });
  const result = wait({ ids: [agentId], timeout_ms: 600000 });
  // ... process result ...
  close_agent({ id: agentId });
} catch (error) {
  if (agentId) close_agent({ id: agentId });
  throw error;
}

Coordinator Checklist

Phase 1 (Generation):

  • Detect input type (session ID / description / file path / resume)
  • Initialize progress tracking with 2 top-level phases
  • Read phases/01-test-fix-gen.md for detailed sub-phase execution
  • Execute 5 sub-phases with spawn_agent → wait → close_agent lifecycle
  • Verify all Phase 1 outputs (4+ task JSONs, IMPL_PLAN.md, TODO_LIST.md)
  • Ensure all agents are closed after each sub-phase completes
  • ⛔ MANDATORY: Present plan summary and request_user_input for confirmation
    • Show: session ID, task count, test layers, quality gates
    • Options: "Proceed to Execution" / "Review Plan" / "Cancel"
    • If "Cancel" → return, do NOT start Phase 2
    • If "Review Plan" → display IMPL_PLAN.md, then return
    • Only proceed to Phase 2 if user selects "Proceed to Execution"

Phase 2 (Execution):

  • Read phases/02-test-cycle-execute.md for detailed execution logic
  • Load session state and task queue
  • Execute iterative test-fix cycles with spawn_agent → wait → close_agent
  • Track iterations in progress tracking
  • Auto-complete session on success (pass rate >= 95%)
  • Ensure all agents are closed after each iteration

Resume Mode:

  • If --resume-session provided, skip Phase 1
  • Load existing session directly into Phase 2

Related Skills

Prerequisite Skills:

  • workflow-plan or workflow-execute - Complete implementation (Session Mode)
  • None for Prompt Mode

Phase 1 Agents (used by phases/01-test-fix-gen.md via spawn_agent):

  • test_context_search_agent (agent_type: test_context_search_agent) - Test coverage analysis (Session Mode)
  • context_search_agent (agent_type: context_search_agent) - Codebase analysis (Prompt Mode)
  • cli_execution_agent (agent_type: cli_execution_agent) - Test requirements with Gemini
  • action_planning_agent (agent_type: action_planning_agent) - Task JSON generation

Phase 2 Agents (used by phases/02-test-cycle-execute.md via spawn_agent):

  • cli_planning_agent (agent_type: cli_planning_agent) - CLI analysis, root cause extraction, task generation
  • test_fix_agent (agent_type: test_fix_agent) - Test execution, code fixes, criticality assignment

Follow-up:

  • Session sync: $session-sync -y "Test-fix cycle complete: {pass_rate}% pass rate"
  • Session auto-complete on success
  • Issue creation for follow-up work (post-completion expansion)