batch

name	batch
description	Execute batch operations on multiple files in parallel. Automatically discovers files, splits into chunks, and processes with parallel worker agents. Use `/batch` followed by operation and file pattern.
argument-hint	<operation> <file-pattern>
allowedTools	["task","glob","grep_search","read_file","edit","write_file","run_shell_command","ask_user_question"]

/batch - Parallel Batch Operations

You are orchestrating a batch operation across multiple files. Your job is to:

1. Parse the user's request to understand the target files and operation
2. Discover matching files using glob
3. Split files into chunks for parallel processing
4. Launch multiple worker agents to process files concurrently
5. Aggregate results and present a summary

Step 1: Parse Intent and Discover Files

First, parse the user's request to identify:

• Target pattern: glob pattern for files (e.g., src/**/*.ts, **/*.js)
• Operation: what to do with each file (e.g., "add JSDoc comments", "convert to TypeScript")

If the user didn't specify a pattern, infer it from context or ask for clarification.

Use the glob tool to discover matching files.

If no files match the pattern:

• Inform the user that no files were found for the given pattern
• Suggest checking the pattern or broadening the search scope
• Do not proceed with an empty batch

Apply these common exclusions automatically:

• node_modules/**
• dist/**
• build/**
• .git/**
• **/*.test.ts, **/*.test.js
• **/*.spec.ts, **/*.spec.js
• **/__tests__/**
• **/test/**, **/tests/**
• **/package-lock.json
• **/yarn.lock
• **/*.min.js
• Binary files (images, fonts, etc.)
• Files larger than 500KB (check size if needed)

Important: If more than 50 files match, inform the user with the exact count and the file list, then proceed. The user can cancel (Ctrl+C) if needed. If the count exceeds 100 files, warn the user and suggest a more specific pattern instead of proceeding.

Step 2: Chunk Files for Parallel Processing

Split the discovered files into chunks based on these rules:

Total Files	Chunk Count	Files Per Chunk
1-5	1	All files
6-15	2	3-8 each
16-30	3	~10 each
31-50	4	~10-12 each
51-75	5	~10-15 each
76-100	5	~15-20 each

Chunking algorithm:

• Minimum chunk size: 3 files (avoid over-parallelization for small batches)
• Maximum chunk size: 15 files (ensure reasonable work per agent)
• Maximum parallel agents: 5 (API rate limit consideration)

Example: 24 files → 3 chunks of ~8 files each

Step 3: Launch Parallel Worker Agents

Launch worker agents in parallel by invoking the task tool (the Agent tool) multiple times in a SINGLE message.

Note: The task tool in allowedTools is the Agent tool used to spawn worker agents.

Each worker agent should receive:

• The list of files to process (full paths)
• The operation to perform
• Clear instructions to report success/failure per file

Use the general-purpose subagent type for workers.

CRITICAL: All Agent tool calls MUST be in a single response to enable parallel execution. The system automatically runs multiple Agent calls concurrently.

Agent Prompt Template

For each chunk, use this prompt format:

You are a worker agent processing a batch of files.

**Operation**: [describe the operation, e.g., "Add JSDoc comments to all exported functions"]

**Files to process**:
- [file1.ts]
- [file2.ts]
- ...

**Instructions**:
1. Process each file independently
2. For each file, report one of:
   - SUCCESS: [file path] - [brief description of change]
   - FAILED: [file path] - [reason for failure]
   - SKIPPED: [file path] - [reason for skipping]
3. If a file fails or is skipped, continue with the next file - do not abort
4. At the end, provide a summary of what was done

**Constraints**:
- Do not modify test files unless explicitly requested
- Preserve existing code style and formatting
- Make minimal necessary changes to accomplish the operation

Example Invocation Pattern

Set run_in_background: false on every worker call so all results return inline for aggregation in Step 4.

<Agent tool call 1>
description: "Process batch chunk 1/3"
prompt: "You are a worker agent... [full prompt as above]"
subagent_type: "general-purpose"
run_in_background: false
</Agent tool call 1>

<Agent tool call 2>
description: "Process batch chunk 2/3"
prompt: "You are a worker agent... [full prompt as above]"
subagent_type: "general-purpose"
run_in_background: false
</Agent tool call 2>

<Agent tool call 3>
description: "Process batch chunk 3/3"
prompt: "You are a worker agent... [full prompt as above]"
subagent_type: "general-purpose"
run_in_background: false
</Agent tool call 3>

Step 4: Aggregate Results

After all worker agents complete, aggregate their results into a clear summary.

Output Format

### Batch Operation Complete

**Operation**: [description of what was done]
**Files discovered**: [total count]
**Chunks processed**: [number of parallel agents]
**Total time**: [duration if tracked]

| Status  | Count |
| ------- | ----- |
| Success | [N]   |
| Failed  | [N]   |
| Skipped | [N]   |

**Successful files**:

- [file1.ts] - [brief description]
- [file2.ts] - [brief description]
  ...

**Failed files** (if any):

- [file.ts]: [reason for failure]

**Skipped files** (if any):

- [file.ts]: [reason for skipping]

Handling Partial Failures

If some files failed but others succeeded:

• Clearly report which files succeeded
• List failures with specific reasons
• Suggest follow-up actions if appropriate

If all files failed:

• Report the common failure pattern
• Suggest potential fixes

Step 5: Error Handling

During Batch Processing

1. Single file failure: Don't abort the batch. The worker agent records the error and continues.
2. Agent failure: If a worker agent fails completely (timeout, crash), note the chunk as failed with reason.
3. User cancellation: If the user sends Ctrl+C, the system will cancel all pending agents gracefully.

Error Reporting

For each failed file, include:

• File path
• Specific error message or reason
• Suggested fix if obvious

Usage Examples

Example 1: Add License Headers

/batch Add Apache 2.0 license header to all .ts files in src/

Flow:

1. glob src/**/*.ts → find 45 files
2. Split into 4 chunks
3. Launch 4 parallel agents
4. Each agent adds the license header to its assigned files
5. Summary: 45 files processed, 45 succeeded, 0 failed

Example 2: Convert JavaScript to TypeScript

/batch Convert all .js files in utils/ to TypeScript

Flow:

1. glob utils/**/*.js → find 12 files
2. Split into 2 chunks
3. Launch 2 parallel agents
4. Each agent converts files and renames to .ts
5. Summary: 12 files processed, 10 succeeded, 2 failed (complex dynamic patterns)

Example 3: Fix Lint Errors

/batch Fix all @typescript-eslint/no-explicit-any errors in src/

Flow:

1. Use grep_search to find files containing : any pattern in src/
2. Filter to relevant files
3. Split into chunks and launch parallel agents
4. Each agent fixes the specific lint issue (replace any with proper types)
5. Summary: 8 files fixed

Constraints and Limits

Constraint	Value	Reason
Max files per batch	100	Prevent resource exhaustion
Max parallel agents	5	API rate limit consideration
Min files per agent	3	Avoid over-parallelization
Max files per agent	15	Ensure meaningful work
File size limit	500KB	Avoid context overflow

Dry-Run Mode

If the user wants to preview what will be changed without actually modifying files (e.g., "preview", "show me what would change", "dry run"):

1. Discover and list all matching files with counts
2. Show the planned operation for each file
3. Display the chunking strategy
4. Ask the user if they want to proceed with the actual changes
5. If user confirms, execute the batch operation

Example:

/batch preview adding JSDoc comments to src/**/*.ts

Expected output:

### Dry-Run Preview

**Operation**: Add JSDoc comments to all .ts files in src/

**Files discovered**: 24 files

**Chunking plan**:
| Chunk | Files |
|-------|-------|
| 1     | src/utils/a.ts, b.ts, c.ts, ... (8 files) |
| 2     | src/components/x.ts, y.ts, ... (8 files) |
| 3     | src/services/m.ts, n.ts, ... (8 files) |

**Planned operation per file**:
- Add JSDoc comments to all exported functions
- Preserve existing code style

Proceed? (y/n)