How do I install the Workflow Test Fix Cycle skill?

Run npx skillmds@latest add tomevault-io/workflow-test-fix-cycle in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

What does the Workflow Test Fix Cycle skill do?

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\". Use when this capability is needed. It is listed under DevOps & Infra on SkillMD.

Is Workflow Test Fix Cycle safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Workflow Test Fix Cycle?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Workflow Test Fix Cycle free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Workflow Test Fix Cycle?

tomevault-io (@tomevault-io) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Workflow Test Fix Cycle by tomevault-io

Name: Workflow Test Fix Cycle
Author: tomevault-io

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

Two-Phase Pipeline: Generation (Phase 1) creates session + tasks, Execution (Phase 2) runs iterative fix cycles
Pure Orchestrator: Dispatch to phase docs, parse outputs, pass context between phases
Phase 1 Auto-Continue: Sub-phases within Phase 1 run autonomously
Subagent Lifecycle: Explicit lifecycle management with spawn_agent → wait_agent → close_agent
Progressive Test Layers: L0 (Static) → L1 (Unit) → L2 (Integration) → L3 (E2E)
AI Code Issue Detection: Validates against common AI-generated code problems
Intelligent Strategy Engine: conservative → aggressive → surgical based on iteration context
CLI Fallback Chain: Gemini → Qwen → Codex for analysis resilience
Progressive Testing: Affected tests during iterations, full suite for final validation
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_agent

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

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

if (result.timed_out) {
  // Handle timeout - can use assign_task to prompt completion
}

assign_task

Assign new work to active subagent (for clarification or follow-up).

assign_task({
  target: agentId,
  items: [{ type: "text", text: `
## 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

Start Immediately: First action is functions.update_plan initialization
No Preliminary Analysis: Do not read files before Phase 1
Parse Every Output: Extract data from each phase/sub-phase for the next
Within-Phase Auto-Continue: Sub-phases within a phase run automatically; Phase 2 iterations run automatically once started
Phase Loading: Read phase doc on-demand (phases/01-*.md, phases/02-*.md)
Task Attachment Model: Sub-tasks ATTACH → execute → COLLAPSE
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
Phase 2 Continuous: Once user approves, Phase 2 runs continuously until pass rate >= 95% or max iterations reached
Explicit Lifecycle: Always close_agent after wait_agent 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:

Create Test Session → testSessionId
Gather Test Context (spawn_agent → wait_agent → close_agent) → contextPath
Test Generation Analysis (spawn_agent → wait_agent → close_agent) → TEST_ANALYSIS_RESULTS.md
Generate Test Tasks (spawn_agent → wait_agent → close_agent) → IMPL-001.json, IMPL-001.3.json, IMPL-001.5.json, IMPL-002.json, IMPL_PLAN.md, TODO_LIST.md
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:

Discovery - Load session, tasks, iteration state
Main Loop - Execute tasks → Test → Analyze failures → Fix → Re-test
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

Initialization (MANDATORY)

// Initialize progress tracking after input parsing
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "in_progress" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "pending" }
])

Phase Transitions

// After Phase 1 completes (before mandatory confirmation gate)
functions.update_plan([
  { id: "phase-1", status: "completed" },
  { id: "phase-2", status: "in_progress" }
])

// After Phase 2 completes (pass rate >= 95% or max iterations)
functions.update_plan([{ id: "phase-2", status: "completed" }])

Resume Mode

// When --resume-session skips Phase 1
functions.update_plan([
  { id: "phase-1", title: "Phase 1: Test-Fix Generation", status: "completed" },
  { id: "phase-2", title: "Phase 2: Test-Cycle Execution", status: "in_progress" }
])

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_agent({ targets: [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 functions.update_plan 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_agent → 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_agent → close_agent
Track iterations via functions.update_plan
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)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.

Workflow Test Fix Cycle

File contents

Workflow Test-Fix Cycle

Architecture Overview

Key Design Principles

Auto Mode

Subagent API Reference

spawn_agent

wait_agent

assign_task

close_agent

Usage

Test Strategy Overview

Execution Flow

Core Rules

Phase Execution

Phase 1: Test-Fix Generation

Phase 2: Test-Cycle Execution

Output Artifacts

Directory Structure

Progress Tracking

Initialization (MANDATORY)

Phase Transitions

Resume Mode

Error Handling

Coordinator Checklist

Related Skills

Frequently asked questions

Workflow Test Fix Cycle

File contents

Workflow Test-Fix Cycle

Architecture Overview

Key Design Principles

Auto Mode

Subagent API Reference

spawn_agent

wait_agent

assign_task

close_agent

Usage

Test Strategy Overview

Execution Flow

Core Rules

Phase Execution

Phase 1: Test-Fix Generation

Phase 2: Test-Cycle Execution

Output Artifacts

Directory Structure

Progress Tracking

Initialization (MANDATORY)

Phase Transitions

Resume Mode

Error Handling

Coordinator Checklist

Related Skills

Related skills

Frequently asked questions

How do I install the Workflow Test Fix Cycle skill?

What does the Workflow Test Fix Cycle skill do?

Is Workflow Test Fix Cycle safe to use?

Which AI agents work with Workflow Test Fix Cycle?

Is Workflow Test Fix Cycle free to use?

Who published Workflow Test Fix Cycle?