Overview

Inspired by Claude Code's /batch skill (announced by Boris Cherny, Feb 27 2026 — tweet), this proposes a batch skill for orchestrating large-scale, parallelizable code migrations using isolated git worktrees. The workflow decomposes a migration into 5-30 independent work units, spawns one agent per unit in a separate git worktree, and each agent independently implements, tests, and creates a PR.

Claude Code's implementation was reverse-engineered from the compiled binary (v2.1.63) — the full internal prompts and worker instructions are documented below. This is a more complex capability than the simplify skill because it requires git worktree management and exceeds the current delegate_task batch limit of 3 concurrent children. However, Hermes already has the infrastructure via background process spawning (terminal(background=true) + process tool) and git worktree patterns documented in the codex skill.

Research Findings

How Claude Code's /batch Works

The skill operates in three phases with an explicit user approval gate:

Phase 1: Research and Plan

1. Scope understanding: Launches foreground "Explore" sub-agents to research what the migration touches — files, patterns, call sites, conventions
2. Decomposition: Breaks work into 5-30 independent units, each must be:
   • Independently implementable in an isolated git worktree (no shared state with siblings)
   • Mergeable on its own without depending on another unit's PR
   • Roughly uniform in size (split large units, merge trivial ones)
   • Sliced per-directory or per-module (not arbitrary file lists)
3. E2E test recipe: Determines how workers verify their changes end-to-end:
   • Browser automation for UI changes
   • CLI/tmux for CLI changes
   • Dev server + curl for API changes
   • Existing integration test suite
   • Asks user if no concrete path found
4. Plan document: Summary of research, numbered work units (title, files, description), e2e recipe, worker instruction template
5. User approval gate: Plan must be approved before proceeding

Phase 2: Spawn Workers

• One background agent per work unit, all launched simultaneously
• Each agent uses isolation: "worktree" — creates a fresh git worktree from main
• Worktrees stored in .claude/worktrees/
• Each worker's prompt is fully self-contained including:
  • Overall goal (user's original instruction)
  • This unit's specific task (title, file list, change description)
  • Codebase conventions discovered during research
  • E2E test recipe
  • Standard worker instructions (see below)

Worker Instructions (copied verbatim from binary):

After you finish implementing the change:
1. Simplify — Invoke the simplify skill to review and clean up your changes.
2. Run unit tests — Run the project's test suite. If tests fail, fix them.
3. Test end-to-end — Follow the e2e test recipe from the coordinator's prompt.
4. Commit and push — Commit all changes with a clear message, push the branch,
   and create a PR with `gh pr create`. Use a descriptive title.
5. Report — End with a single line: `PR: <url>` so the coordinator can track it.
   If no PR was created, end with `PR: none — <reason>`.

Phase 3: Track Progress

• Renders a status table tracking each work unit
• Updates as workers complete: running → done / failed
• Parses PR: <url> from each worker's output
• Final summary: "22/24 units landed as PRs"

Key Design Decisions

1. Worktree isolation: Git worktrees share the .git directory but have independent working trees. Workers can't interfere with each other.
2. Self-contained prompts: Workers get NO shared context — everything they need is in their prompt. This makes them truly independent.
3. User approval gate: The plan phase prevents runaway migrations. User reviews the decomposition before any work begins.
4. Workers run simplify: Each worker self-reviews using the simplify skill before committing, ensuring quality without coordinator overhead.
5. Manual-only invocation: disableModelInvocation: true — the agent never auto-triggers batch, only explicit user request.

Current State in Hermes Agent

What we have:

• delegate_task batch mode: Up to 3 concurrent sub-agents — insufficient for 5-30 workers. MAX_CONCURRENT_CHILDREN = 3 is hardcoded in tools/delegate_tool.py
• hermes-agent skill: Documents spawning independent Hermes processes via terminal(background=true) — this bypasses the 3-child limit and provides true process isolation
• codex skill: Documents git worktree patterns: git worktree add -b branch /tmp/workdir main, launch agent in workdir, cleanup after
• subagent-driven-development skill: Serial task execution with review stages — complementary but not parallel
• process tool: Full background process management (poll, log, wait, kill) — needed for tracking workers
• todo tool: Can track work units and status
• No existing migration orchestration workflow

Gap: No skill that combines plan → approve → parallel-spawn-in-worktrees → track-and-summarize for large-scale code migrations.

Key constraint: delegate_task maxes at 3 children, but we can work around this:

1. Background hermes processes (preferred): Spawn hermes -q "prompt" processes via terminal(background=true), each in a git worktree. The parent tracks via process(poll/log). Already documented in the hermes-agent skill.
2. Sequential delegate_task batches: Run batches of 3 until all units complete. Slower but simpler.
3. Make MAX_CONCURRENT_CHILDREN configurable: Add a config.yaml option. Medium-effort core change.

Implementation Plan

Skill vs. Tool Classification

This should be a bundled skill because:

• It can be expressed as instructions + existing tools (terminal, process, delegate_task, git commands, gh CLI)
• The worktree management is shell commands (git worktree add/remove)
• Worker spawning uses existing terminal(background=true) or delegate_task
• No custom Python integration or API key management needed
• Per CONTRIBUTING.md: capabilities expressible as instructions + shell commands = skill
• It's broadly useful — code migrations are a universal developer need

What We'd Need

1. A new skill at skills/software-development/batch-migration/SKILL.md
2. The skill triggers on phrases like "batch migrate", "migrate X to Y across the codebase", "bulk refactor"
3. Git worktree management instructions in the skill
4. Worker prompt template in the skill
5. Progress tracking pattern using todo tool or rendered status table

Phased Rollout

Phase 1: Core Batch Orchestration - MVP

• Skill with three-phase workflow: plan → approve (via clarify tool) → execute
• Use terminal(background=true) to spawn hermes-agent processes in git worktrees
• Each worker gets self-contained prompt with task + conventions + test recipe
• Parent tracks via process(poll) and reports final status
• Limit to 5-10 workers initially for stability
• Workers commit, push, create PRs via gh pr create

Phase 2: Enhanced Worker Management

• Dynamic scaling based on task count and system resources
• Worker failure recovery (detect stuck workers, restart or reassign)
• Integration with simplify skill (workers run simplify before committing)
• Progress dashboard with real-time status updates
• Conflict detection (warn if two workers' changes overlap)

Phase 3: Advanced Features

• Integration with Feature: Multi-Agent Architecture — Orchestration, Cooperation, Specialized Roles & Resilient Workflows #344 (Multi-Agent Architecture) — use workflow DAG for dependencies
• Integration with Feature: Acceptance Criteria & Independent Judge for Sub-agent Delegation (inspired by OpenPlanter) #356 (Acceptance Criteria) — judge model evaluates each worker's PR
• Auto-merge capability for clean PRs that pass CI
• Resumable migrations (checkpoint state, restart failed units)
• Cross-platform support (ensure workers work on CLI, Telegram, Discord)

Technical Design Details

Git Worktree Lifecycle

# Setup (per worker)
git worktree add .hermes/worktrees/unit-01 -b batch/unit-01 main

# Worker operates in isolated directory
cd .hermes/worktrees/unit-01
# ... make changes, test, commit ...
git push -u origin batch/unit-01
gh pr create --title "Batch: Unit 01 - Migrate X to Y" --body "..."

# Cleanup (after all workers complete)
git worktree remove .hermes/worktrees/unit-01
git branch -d batch/unit-01  # only if PR merged

Worker Spawning Pattern

# Using hermes-agent subprocess (preferred - bypasses 3-child limit)
terminal(
    command='hermes -q "You are a batch migration worker. [full self-contained prompt]"',
    background=True,
    workdir='.hermes/worktrees/unit-01'
)

# Alternative: Using delegate_task in sequential batches of 3
delegate_task(tasks=[
    {"goal": "Worker 1 prompt", "context": "..."},
    {"goal": "Worker 2 prompt", "context": "..."},
    {"goal": "Worker 3 prompt", "context": "..."},
])
# Then next batch of 3...

Progress Tracking

The parent agent maintains a status table using the todo tool or direct text rendering:

| # | Unit                          | Status  | PR                        |
|---|-------------------------------|---------|---------------------------|
| 1 | Migrate src/auth/ to React    | done    | github.com/.../pull/42    |
| 2 | Migrate src/dashboard/ ...    | running | —                         |
| 3 | Migrate src/settings/ ...     | failed  | PR: none — test failure   |

Pros & Cons

Pros

• Massive parallelism: 5-30 independent workers vs. serial implementation = dramatic speedup for large migrations
• Safe isolation: Git worktrees prevent workers from interfering with each other
• Quality built in: Each worker self-reviews (simplify) and tests before creating a PR
• Human oversight: Plan approval gate prevents runaway changes
• Leverages existing infrastructure: hermes-agent subprocess spawning, git worktrees, gh CLI, process tool — all already available
• Independent PRs: Each unit produces a separate PR that can be reviewed and merged independently

Cons / Risks

• Resource intensive: 10-30 concurrent hermes processes = significant CPU, memory, and API costs
• Complexity: Three-phase orchestration with background process management is the most complex skill pattern
• Git worktree edge cases: Worktrees can have issues with submodules, untracked files, or unusual git configurations
• Worker divergence: Workers may make inconsistent stylistic choices without shared context
• PR sprawl: 30 PRs from a single migration can overwhelm code review
• Rate limits: Many concurrent API calls may hit provider rate limits
• Cleanup: Failed runs may leave orphaned worktrees or branches

Open Questions

• What's the right default concurrency limit? (5? 10? system-resource-based?)
• Should workers share any state (e.g., a conventions file) or be fully isolated?
• How should the user approve the plan — via clarify tool or file-based review?
• Should there be a --dry-run mode that shows the plan but doesn't execute?
• How to handle partially failed migrations (10/15 PRs created)?
• Should we increase MAX_CONCURRENT_CHILDREN in delegate_tool.py or rely on subprocess spawning?
• How to handle migrations where units aren't truly independent (e.g., shared type definitions)?

References

• Boris Cherny's announcement: https://x.com/bcherny (Feb 27, 2026)
• Claude Code Skills docs: https://code.claude.com/docs/en/skills
• Claude Code CHANGELOG: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md
• Internal prompts and worker instructions extracted from Claude Code v2.1.63 binary
• Existing codex skill git worktree pattern: skills/autonomous-ai-agents/codex/SKILL.md
• Existing hermes-agent skill subprocess spawning: skills/autonomous-ai-agents/hermes-agent/SKILL.md
• Related: Feature: Multi-Agent Architecture — Orchestration, Cooperation, Specialized Roles & Resilient Workflows #344 (Multi-Agent Architecture), Feature: Acceptance Criteria & Independent Judge for Sub-agent Delegation (inspired by OpenPlanter) #356 (Acceptance Criteria), Feature: Inception Prompting — Hardened Sub-Agent Prompts Against Delegation Failures (inspired by CAMEL-AI) #375 (Inception Prompting)
• Related: Simplify Skill issue (companion to this issue — workers invoke simplify)