arn-code-batch-implement

Arness Batch Implement

Orchestrate parallel worktree-isolated background agents to implement multiple features simultaneously. Each worker is a full independent session with all tools, operating in its own git worktree. The orchestrator (this skill) handles pre-flight validation, worker spawning, progress tracking, and handoff to batch-merge.

Key architectural constraint: This skill is a sequencer — it MUST NOT duplicate sub-skill logic. Workers handle all implementation details autonomously.

Pipeline position:

arn-code-batch-planning -> **arn-code-batch-implement** (pre-flight -> spawn workers -> track -> handoff) -> arn-code-batch-merge

Workflow

Step 0: Ensure Configuration

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-ensure-config/references/step-0-fast-path.md and follow its instructions. Extract from ## Arness:

• Plans directory -- base path where project plans are saved
• Code patterns -- path to the directory containing stored pattern documentation
• Template path -- path to the report template set (JSON templates)

Step 1: Pre-flight Validation

Read ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-batch-implement/references/preflight-validation.md and follow its procedure. The preflight reference handles scanning and returns a structured result. Based on that result:

If zero pending plans found: inform the user: "No pending plans found. Run /arn-code-batch-planning to plan features first." Exit.

If Git is no in ## Arness: "Batch implementation requires git for worktree-based parallel execution. Run /arn-implementing to implement features one at a time instead." STOP.

If gh/bkt auth not available (based on Platform): warn that PRs cannot be created — workers will commit but skip PR creation.

If uncommitted changes detected: warn and suggest committing first. Ask (using AskUserQuestion):

Uncommitted changes detected. Commit or stash before launching batch?

1. Proceed anyway

2. Cancel — I'll commit first

If Cancel, exit.

If not on main/master: plans should be on main (merged via the plans PR from batch-planning). Ask (using AskUserQuestion):

You're on branch [name], but plans should be on main. Checkout main?

1. Checkout main — run git checkout main && git pull

2. Proceed on this branch — I know what I'm doing

If Checkout main: git checkout main && git pull. Continue. If Proceed: continue on current branch.

Run git pull to ensure main is up to date with the latest plans.

Step 2: Pre-flight Summary

Present the validation results as a table:

Batch Implementation Pre-flight:

| # | Feature | Tier | Sketch | Est. Files | Overlap Warning |
|---|---------|------|--------|------------|-----------------|
| 1 | ...     | ...  | ...    | ...        | ...             |

Column values:

• Sketch: "ready" (manifest found with kept status), "recommended" (UI references but no sketch), "n/a" (no UI components)
• Overlap Warning: blank if none, or list of overlapping feature names

If file overlap detected between any features, show which features share files and note: "File overlap detected -- batch-merge will handle conflicts after implementation."

Show estimated context: "[N] features will be implemented in parallel, each as an independent session."

Inform the user about worktree location: "Workers run in pre-created worktrees at .claude/worktrees/arn-batch-<slug>/ on branches arn-batch/<slug>. Worktrees are preserved until the corresponding PR is merged; arn-code-batch-merge cleans them up after each successful merge."

Step 3: Launch Confirmation

Ask (using AskUserQuestion):

Launch [N] parallel implementations?

1. Launch all

2. Select subset

3. Cancel

• Launch all -- proceed with all pending features.
• Select subset -- present a multi-select (using AskUserQuestion with multiSelect: true) listing all pending features by name. Proceed with selected features only.
• Cancel -- exit.

Step 4: Pre-create Worktrees and Spawn Workers

The Agent tool's built-in isolation: "worktree" has known silent-failure modes (see upstream issues anthropics/claude-code#27881 and #39886) where concurrent spawns can skip worktree creation entirely and run agents directly in the main checkout. To eliminate this risk, the orchestrator pre-creates every worktree itself via git worktree add, then spawns agents without isolation and passes the absolute worktree path in the prompt.

Read the worker instructions template from ${CLAUDE_PLUGIN_ROOT}/skills/arn-code-batch-implement/references/worker-instructions.md.

Step 4a: Compute Worktree Slugs

For each selected feature, derive a slug from the feature name: lowercase, replace non-alphanumerics with -, collapse runs of -, trim leading/trailing -. Example: Auth Service v2 → auth-service-v2.

Empty-slug fallback: If sanitization produces an empty string (feature name was entirely non-alphanumeric, e.g., emojis or punctuation), substitute feature-<index> where <index> is the feature's 1-based position in the batch. This keeps provisioning deterministic instead of silently failing downstream.

Capture the repo root once:

REPO="$(git rev-parse --show-toplevel)"

For each slug, resolve three possible collisions before provisioning — a path may already be taken, a branch may already exist from a prior run, and stale worktree metadata may block creation:

1. Path collision. Check git -C "$REPO" worktree list --porcelain for an existing worktree at $REPO/.claude/worktrees/arn-batch-<slug>:
2. None: path is free, proceed to the branch check.
3. Exists on branch arn-batch/<slug> with clean status (git -C "$REPO/.claude/worktrees/arn-batch-<slug>" status --porcelain is empty): reuse it and mark this slug as "already provisioned" (skip Step 4b).
4. Otherwise (dirty worktree, different branch, unknown state): append -<n> starting at 2 and re-check until the path is free.

1. Branch collision. Once a path is free, check whether the target branch already exists: git -C "$REPO" show-ref --verify --quiet "refs/heads/arn-batch/<slug>". If it does (common when a worktree was manually deleted but the branch wasn't cleaned up), git worktree add -b will fail. Keep incrementing -<n> on the slug until both path AND branch are free.

Step 4b: Pre-create Worktrees Sequentially

For each slug that needs creation (i.e., wasn't marked "already provisioned" in Step 4a), run:

git -C "$REPO" worktree add "$REPO/.claude/worktrees/arn-batch-<slug>" -b "arn-batch/<slug>"

Capture exit code and stderr per feature. Verify success by confirming the path appears in git -C "$REPO" worktree list. Split the feature list into:

• ready: features with a valid worktree (newly created or reused).
• deferred: features whose git worktree add failed. Store the stderr for the retry step.

If all features land in deferred, report the errors and stop — something is broken globally (disk, permissions, corrupt .git/worktrees/). A retry loop cannot fix a systemic failure.

Step 4c: Spawn Parallel Workers (ready set)

For each feature in ready, spawn one Agent with:

• No isolation parameter — worktrees already exist.
• run_in_background: true.
• A self-contained prompt built from the worker-instructions template, filled with:
• {worktree_path}: the absolute path $REPO/.claude/worktrees/arn-batch-<slug>
• {feature_name}, {plan_path}, {tier}, {platform}, {code_patterns_path}, {template_path}, {sketch_manifest_path} as before.

ALL agents in the ready set MUST be spawned in a SINGLE message (multiple Agent tool calls in one response) so they run in parallel. Cap at 5 concurrent workers. If ready has more than 5 entries, batch into groups of 5: launch group 1, wait for completion, launch group 2, etc.

If a worker's Agent call returns a spawn error, move that fe