/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 (LAST-RESORT fallback, Issue #1487)**: Only when the gitignored-`.claude` deadlock cannot be resolved by worktree mode's STEP B1 sync (see lines below). The strict ordering is: (1) FIRST attempt worktree mode with the STEP B1 sync (`cp settings.json` + `cp -rf hooks/` + `cp -rf config/` from the parent repo into the fresh worktree) — this mitigation exists precisely to make worktrees viable when `.claude/*` is gitignored; (2) ONLY fall back to `--no-worktree` if the STEP B1 sync is impossible (no parent `.claude/` present, the sync `cp` errored, or the parent tree has no synced `.claude/hooks/` to copy). Do NOT reach for `--no-worktree` as the first response to the gitignored-`.claude` symptom — worktree isolation (clean rollback, no shared-tree race with concurrent sessions) is worth preserving whenever the sync mitigation works. autonomous-dev itself is the canonical case where the sync path succeeds; `--no-worktree` remains available for consumer repos whose parent `.claude/` cannot be synced.
• **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). **Single-issue warning (Issue #1487)**: If a single-issue run selects `--no-worktree`, the coordinator MUST surface a WARNING to the operator (NOT silently switch modes) explaining that `--no-worktree` is scoped to multi-issue clusters and asking for explicit confirmation before proceeding. Silent acceptance of `--no-worktree` for a single-issue run is a mode-selection bug — the coordinator either blocks with an actionable message ("`--no-worktree` is multi-issue-only; drop the flag, add more issues, or confirm explicitly") or, when running non-interactively, emits the warning to `.claude/local/drain_notifications.jsonl` and reverts to worktree+STEP-B1-sync mode.

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 detect