execute-batch

vinzenz's avatarfrom vinzenz

Handles one batch of tasks. Spawns task agents in parallel using git worktrees, waits for completion, and updates state.

⭐3stars🔀0forks📁View on GitHub🕐Updated Jan 11, 2026⬇️1downloads

When & Why to Use This Skill

The Batch Execution Agent is a high-performance Claude skill designed for advanced agent orchestration and parallel task management. It enables the simultaneous execution of multiple independent tasks by spawning specialized sub-agents within isolated git worktrees. By automating the entire lifecycle of batch processing—including state tracking, parallel spawning, result aggregation, and intelligent retry logic—this skill significantly accelerates complex software development cycles and large-scale project implementations while maintaining environment isolation.

Use Cases

  • Parallel Feature Implementation: Simultaneously developing multiple independent modules or components of a software project to drastically reduce total development time.
  • Large-Scale Automated Refactoring: Executing repository-wide code improvements across different directories in parallel, ensuring isolated verification for each change via git worktrees.
  • Batch Bug Resolution: Efficiently addressing a backlog of independent bug reports by assigning each to a dedicated sub-agent operating in a clean, isolated environment.
  • Automated Documentation Updates: Spawning multiple agents to update technical documentation across different project layers or services concurrently.
  • Distributed Testing and QA: Orchestrating complex testing workflows where multiple test suites need to run in parallel across different branches or environments.
nameexecute-batch
descriptionHandles one batch of tasks. Spawns task agents in parallel using git worktrees, waits for completion, and updates state.
contextfork
allowed-toolsRead Write Bash Task Glob TaskOutput
modelclaude-sonnet-4-5

Batch Execution Agent

You coordinate the parallel execution of a batch of independent tasks. Each task runs in its own git worktree via the Task tool.

Input Arguments

Parse these from the prompt:

Argument Required Description
--tasks-path <path> Yes Path to tasks directory
--task-ids <ids> Yes Comma-separated task IDs (e.g., "L1-001,L1-002,L1-006")
--project-path <path> Yes Main project directory
--worktree-dir <path> Yes Directory for worktrees
--batch-number <N> Yes Batch number within layer
--layer <name> Yes Layer name (for status reporting)

Execution Flow

Step 1: Parse Task IDs

Split the comma-separated task IDs:

--task-ids "L1-001,L1-002,L1-006"
→ ["L1-001", "L1-002", "L1-006"]

Step 2: Load State

Read execute-state.json to get current state for each task:

cat {tasks_path}/execute-state.json

Check each task's status:

  • If pending: Will create new worktree
  • If in_progress with worktree: Will resume with existing worktree
  • If failed: Will retry with retry feedback

Step 3: Find Task Files

For each task ID, locate the task XML file:

find {tasks_path} -name "{task_id}-*.xml" -type f

Example: L1-001 → docs/tasks/voice-prd/1-foundation/L1-001-create-enums.xml

Step 4: Spawn Task Agents in Parallel

CRITICAL: Launch ALL task agents in a SINGLE message using multiple Task tool calls.

For each task, invoke the Task tool:

Task(
  subagent_type: "task-implementer",
  prompt: <task execution prompt>,
  run_in_background: true,
  description: "Execute task {task_id}"
)

Task execution prompt template:

You are executing task {task_id} using the /execute-task skill.

Execute the following command:
/execute-task --task-file {task_file_path} --project-path {project_path} --worktree-dir {worktree_dir} --attempt {attempt}

{IF RETRY:}
--worktree-path {existing_worktree_path}
--retry-feedback '{retry_feedback_json}'
{END IF}

Return the RESULT JSON when complete.

Example - launching 3 tasks in parallel:

In a SINGLE message, call Task tool 3 times:

<Task>
  <subagent_type>task-implementer</subagent_type>
  <run_in_background>true</run_in_background>
  <description>Execute task L1-001</description>
  <prompt>Execute /execute-task --task-file .../L1-001-create-enums.xml ...</prompt>
</Task>

<Task>
  <subagent_type>task-implementer</subagent_type>
  <run_in_background>true</run_in_background>
  <description>Execute task L1-002</description>
  <prompt>Execute /execute-task --task-file .../L1-002-create-model.xml ...</prompt>
</Task>

<Task>
  <subagent_type>task-implementer</subagent_type>
  <run_in_background>true</run_in_background>
  <description>Execute task L1-006</description>
  <prompt>Execute /execute-task --task-file .../L1-006-setup-config.xml ...</prompt>
</Task>

Step 5: Wait for Completion

After launching all tasks, use TaskOutput to wait for each:

TaskOutput(task_id: "{task_1_id}", block: true, timeout: 600000)
TaskOutput(task_id: "{task_2_id}", block: true, timeout: 600000)
TaskOutput(task_id: "{task_3_id}", block: true, timeout: 600000)

Timeout: 10 minutes per task (600000ms)

Step 6: Collect Results

Parse the RESULT JSON from each task agent:

Success result:

{
  "task_id": "L1-001",
  "status": "verified",
  "attempt": 1,
  "worktree_path": "/path/.worktrees/L1-001",
  "branch": "worktree-L1-001",
  "commit_hash": "abc1234",
  "files_created": ["app/models/enums.py"],
  "verification_summary": "3/3 steps passed"
}

Failure result (will retry):

{
  "task_id": "L1-002",
  "status": "failed",
  "attempt": 2,
  "worktree_path": "/path/.worktrees/L1-002",
  "error": {
    "type": "verification_failed",
    "step": "pytest tests/...",
    "message": "1 test failed"
  },
  "retry_feedback": "Fix validation in create_project"
}

Abandoned result (max retries):

{
  "task_id": "L1-003",
  "status": "abandoned",
  "attempt": 5,
  "worktree_path": "/path/.worktrees/L1-003",
  "final_error": "Still failing after 5 attempts"
}

Step 7: Update State

Read current state, update each task, write back:

# For each task result:
if result["status"] == "verified":
    state["tasks"][task_id]["status"] = "verified"
    state["tasks"][task_id]["completed_at"] = now()
    state["merge_queue"].append({
        "task_id": task_id,
        "priority": next_priority,
        "status": "ready"
    })

elif result["status"] == "failed":
    state["tasks"][task_id]["status"] = "failed"
    state["tasks"][task_id]["errors"].append(result["error"])

elif result["status"] == "abandoned":
    state["tasks"][task_id]["status"] = "abandoned"
    state["abandoned"].append(task_id)

Write updated state:

echo '{updated_state_json}' > {tasks_path}/execute-state.json

Step 8: Report Batch Status

Output batch completion summary:

[BATCH {layer} #{batch_number}] Complete
  Verified: L1-001, L1-002
  Failed: L1-003 (attempt 2, will retry)
  Abandoned: none

Merge queue: 2 tasks ready

Step 9: Return Batch Result

Output structured result for layer agent:

{
  "batch_number": 1,
  "layer": "1-foundation",
  "tasks_total": 3,
  "verified": ["L1-001", "L1-002"],
  "failed": ["L1-003"],
  "abandoned": [],
  "merge_queue_ready": 2,
  "should_stop": false
}

If any task is abandoned:

{
  "batch_number": 1,
  "layer": "1-foundation",
  "tasks_total": 3,
  "verified": ["L1-001"],
  "failed": [],
  "abandoned": ["L1-002"],
  "merge_queue_ready": 1,
  "should_stop": true,
  "stop_reason": "Task L1-002 abandoned after 5 attempts"
}

Parallel Execution Rules

  1. All tasks in single message: Launch ALL Task tool calls in ONE message
  2. True parallelism: Use run_in_background: true
  3. Independent tasks only: Batch should only contain tasks with no inter-dependencies
  4. Resource awareness: Respect --max-parallel limit from layer agent

Error Handling

Task Agent Timeout

If TaskOutput times out:

  • Mark task as failed with timeout error
  • Include in retry queue for next batch

Task Agent Crash

If Task tool returns error:

  • Log the error
  • Mark task as failed
  • Include in retry queue

State Write Failure

If state file can't be written:

  • Retry write up to 3 times
  • If still failing, output error and let layer agent handle

Output Format

End with structured result:

BATCH_RESULT:
{json object}

The layer agent parses this to update layer state and decide next steps.

Status Line Format

For minimal output mode:

[BATCH 1-foundation #1] L1-001 ✓, L1-002 ✓, L1-006 ✓ (3/3)

With failures:

[BATCH 2-backend #2] L2-003 ✓, L2-004 ✗ (attempt 2), L2-005 ✓ (2/3)