/implement-batch

name: implement-batch
description: Batch processing mode for /implement command
version: 1.0.0
user-invocable: false
user_facing: false

BATCH FILE MODE

> The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119).

Implementation

Invoke the implementer agent to process each feature in the batch file sequentially with worktree isolation.

Process

Process multiple features from a file with automatic worktree isolation.

No-Worktree Mode (Issue #1133)

When `--no-worktree` is added to `--batch` or `--issues`, the batch runs **in-place on the current branch** instead of creating a git worktree:

• **When to use**: Repos where `.claude/*` is gitignored — `git worktree add` produces a worktree with empty `.claude/hooks/` and `.claude/config/`, deadlocking the PreToolUse hook stack. autonomous-dev itself is the canonical example.
• **What it does**: Skips `git worktree add`, runs the per-issue pipeline serially on the current branch, produces **one commit per issue** (per-issue commit format: `feat(scope): #N <title>\n\nCloses #N`), then opens a **single multi-issue PR** via `open_cluster_pr()` at the end of the batch (PR title: `feat: cluster #N1+#N2+...`).
• **HARD GATE — `Closes #N` enforcement (drain-queue durability plan)**: For EVERY per-issue commit the body MUST include `Closes #N` (case-insensitive) for the issue currently being processed. The synthesis step MUST inject `Closes #N` before invoking `git commit` if the drafted message lacks it. The hook gate at `plugins/autonomous-dev/hooks/unified_pre_tool.py` (`_check_drain_pending_commit_gate`) deterministically blocks any `git commit` that fails this check when a `.claude/local/drain_pending.json` marker is present (set by `/drain-queue` STEP 3.6). The same enforcement applies to the batch-cluster commit at the end of `--no-worktree` mode: ALL N in the cluster MUST appear as `Closes #N` lines in the cluster commit body, not just the first.
• **Signaling**: Sets `BATCH_NO_WORKTREE=1` in the environment. The `unified_pre_tool.py` `_is_batch_context(cwd)` helper recognizes this env var alongside the `.worktrees/batch-*` cwd signal, so all batch hook gates (CIA completion, doc-master completion, agent completeness) keep firing.
• **Pre-condition (HARD GATE)**: Working tree MUST be clean. The pre-staged check is extended to ALSO block on `git diff --name-only` (unstaged tracked changes), not just `git diff --cached`. In-place mode runs `git reset --hard HEAD` between failed issues, which would otherwise silently discard local work.
• **Cleanup on per-issue failure**: `git reset --hard HEAD` reverts tracked-file changes for that issue. `.claude/` files are gitignored — they are untracked from git's perspective and are therefore NOT touched by `git reset --hard`.
• **Batch state**: Persisted at `<cwd>/.claude/batch_state.json` with `"no_worktree": true` so `--resume` can re-enter the in-place flow.
• **NOT for**: single-issue runs, `--fix`, `--light`, `--resume` (resume reads the stored state's `no_worktree` flag automatically).

Batch Mode Progress Protocol

Batch mode adds two layers on top of the full pipeline's progress protocol:

**Batch Header** — output at start of batch:

========================================
BATCH START — N features
Mode: acceptance-first | Worktree: .worktrees/$BATCH_ID
========================================

**Per-Feature Header** — output before each feature's pipeline:

----------------------------------------
Feature M/N — "feature description"
----------------------------------------

**Per-Feature Footer** — output after each feature's pipeline:

  Feature M/N complete (Xs) | Tests: P passed | Running total: M/N done

Within each feature, follow the full pipeline's step banner and agent completion format.

**Batch Summary Timing** — enhance STEP B5 with per-feature timing:

  Feature 1: "description"       2:30
  Feature 2: "description"       3:15
  Feature 3: "description"       FAILED (reason)

**STEP B0: Pre-Staged Files Check — HARD GATE**

**Progress**: Output batch header after worktree creation. Output gate result for pre-staged check.

STAGED_FILES=$(git diff --cached --name-only 2>/dev/null)
if [ -n "$STAGED_FILES" ]; then
  echo "BLOCKED: Pre-staged files detected"
  echo "$STAGED_FILES"
fi

If `STAGED_FILES` is non-empty: **BLOCK** the pipeline. Display:

BLOCKED — Pre-staged files detected.

The following files are already staged from a previous session:
[list files]

Pre-staged files propagate into worktrees, contaminating batch isolation.

Options:
A) Unstage: git reset HEAD
B) Commit first: git commit -m "wip: staged changes from previous session"
C) Review: git diff --cached

Do NOT proceed to STEP B1 until the staging area is clean.

**FORBIDDEN**:

• ❌ Proceeding with pre-staged files present
• ❌ Silently unstaging files without user confirmation
• ❌ Creating worktrees with pre-staged files in the index

**STEP B1: Create Worktree**

**Progress**: Capture `BATCH_START=$(date +%s)` after worktree creation.

Before processing features, create an isolated worktree and change to it:

# Generate batch ID
BATCH_ID="batch-$(date +%Y%m%d-%H%M%S)"

# Create worktree (requires git worktree support)
git worktree add ".worktrees/$BATCH_ID" HEAD

# Change to worktree directory (automatic in create_batch_worktree)
cd .worktrees/$BATCH_ID

# Store absolute worktree path for agent prompts (CRITICAL!)
WORKTREE_PATH="$(pwd)"

# Sync settings, hooks, and config from parent repo (worktree gets stale copy at creation time)
PARENT_REPO="$(git -C "$WORKTREE_PATH" rev-parse --path-format=absolute --git-common-dir | sed 's|/.git$||')"
cp "$PARENT_REPO/.claude/settings.json" "$WORKTREE_PATH/.claude/settings.json" 2>/dev/null || true
cp -rf "$PARENT_REPO/.claude/hooks/" "$WORKTREE_PATH/.claude/hooks/" 2>/dev/null || true
cp -rf "$PA