/batch-implement - Overnight Feature Queue

Process multiple features fully unattended - queue them up, let it run overnight, wake up to completed work. Survives auto-compaction via externalized state.

Usage

# Start new batch from file
/batch-implement features.txt

# Start new batch from GitHub issues (requires gh CLI)
/batch-implement --issues 72 73 74

# Continue after crash
/batch-implement --resume <batch-id>

Prerequisites for --issues flag:

• gh CLI v2.0+ installed (brew install gh, apt install gh, or winget install GitHub.cli)
• Authentication: gh auth login (one-time setup)

State Management (v3.1.0+):

• Persistent state file: .claude/batch_state.json
• Compaction-resilient: Survives auto-compaction via externalized state
• Crash recovery: Continue with --resume <batch-id> flag
• Progress tracking: Completed features, failed features, processing history

Input Formats

Option 1: File-Based

Plain text file, one feature per line:

# Authentication
Add user login with JWT
Add password reset flow

# API features
Add rate limiting to endpoints
Add API versioning

Rules:

• One feature per line
• Lines starting with # are comments (skipped)
• Empty lines are skipped
• Keep features under 500 characters each

Option 2: GitHub Issues (NEW in v3.2.0)

Fetch issue titles directly from GitHub:

/batch-implement --issues 72 73 74

How it works:

1. Parse issue numbers from arguments
2. Validate issue numbers (positive integers, max 100 issues)
3. Fetch issue titles via gh CLI: gh issue view <number> --json title
4. Format as features: "Issue #72: [title from GitHub]"
5. Create batch state with issue_numbers and source_type='issues'

Requirements:

• gh CLI v2.0+ installed and authenticated
• Valid issue numbers in current repository
• Network connectivity to GitHub

Graceful Degradation:

• If issue not found: Skip and continue with remaining issues
• If gh CLI not installed: Error message with installation instructions
• If authentication missing: Error message with gh auth login instructions

Mutually Exclusive: Cannot use both <file> and --issues in same command

How It Works

State-based workflow (v3.1.0+):

1. Read features.txt
2. Parse features (skip comments, empty lines, duplicates)
3. Create batch state → Save to .claude/batch_state.json
4. For each feature:
   • /auto-implement {feature}
   • Update batch state (mark feature complete)
   • Next feature
5. Cleanup state file on success

Compaction-Resilient Design: All critical state is externalized (batch_state.json, git commits, GitHub issues, codebase). If Claude Code auto-compacts during long batches, processing continues seamlessly - each feature bootstraps fresh from external state, not conversation memory. Use --resume only for crash recovery.

Crash Recovery: If batch is interrupted:

• State file persists: .claude/batch_state.json
• Contains: completed features, current index, failed features, processing history
• Continue: /batch-implement --resume <batch-id>
• System automatically skips completed features and continues from current index

State File Example (File-based):

{
  "batch_id": "batch-20251116-123456",
  "features_file": "/path/to/features.txt",
  "total_features": 10,
  "current_index": 3,
  "completed_features": [0, 1, 2],
  "failed_features": [],
  "context_token_estimate": 145000,
  "auto_clear_count": 2,
  "auto_clear_events": [
    {"feature_index": 2, "tokens_before": 155000, "timestamp": "2025-11-16T10:30:00Z"}
  ],
  "status": "in_progress",
  "issue_numbers": null,
  "source_type": "file"
}

State File Example (GitHub Issues):

{
  "batch_id": "batch-20251116-140000",
  "features_file": "",
  "features": [
    "Issue #72: Add logging feature",
    "Issue #73: Fix batch processing bug",
    "Issue #74: Update documentation"
  ],
  "total_features": 3,
  "current_index": 1,
  "completed_features": [0],
  "failed_features": [],
  "context_token_estimate": 85000,
  "auto_clear_count": 0,
  "auto_clear_events": [],
  "status": "in_progress",
  "issue_numbers": [72, 73, 74],
  "source_type": "issues"
}

New Fields (v3.2.0):

• issue_numbers: List of GitHub issue numbers (null for file-based batches)
• source_type: Either "file" or "issues" (tracks batch source)

---

Implementation

Invoke the batch orchestration workflow to process features sequentially with automatic context management.

You (Claude) orchestrate this workflow - read features, loop through each one, invoke /auto-implement, next.

ARGUMENTS: {{ARGUMENTS}} (path to features.txt)

Python Libraries (use via Bash tool):

# Failure classification
from plugins.autonomous_dev.lib.failure_classifier import (
    classify_failure,        # Classify errors as transient/permanent
    sanitize_error_message,  # Sanitize error messages for safe logging
    sanitize_feature_name,   # Sanitize feature names (CWE-117, CWE-22)
    FailureType,            # Enum: TRANSIENT, PERMANENT
)

# Retry management
from plugins.autonomous_dev.lib.batch_retry_manager import (
    BatchRetryManager,       # Orchestrate retry logic
    should_retry_feature,    # Decide if feature should be retried
    record_retry_attempt,    # Record a retry attempt
    MAX_RETRIES_PER_FEATURE, # Constant: 3
    MAX_TOTAL_RETRIES,       # Constant: 50
)

# Consent management
from plugins.autonomous_dev.lib.batch_retry_consent import (
    check_retry_consent,     # Check/prompt for user consent
    is_retry_enabled,        # Check if retry is enabled
)

# Batch state management (existing)
from plugins.autonomous_dev.lib.batch_state_manager import (
    create_batch_state, save_batch_state, load_batch_state, update_batch_progress
)

STEP 1: Read and Parse Features

Action: Use the Read tool to read the features file

Parse the content:

• Skip lines starting with # (comments)
• Skip empty lines (just whitespace)
• Skip duplicate features
• Collect unique features into a list

Display to user:

Found N features in features.txt:
  1. Feature one
  2. Feature two
  3. Feature three
  ...

Ready to process N features. This will run unattended.
Starting batch processing...

---

STEP 1.5: Analyze Dependencies and Optimize Order (NEW - Issue #157)

Action: Analyze feature dependencies and optimize execution order

Import the analyzer:

from plugins.autonomous_dev.lib.feature_dependency_analyzer import (
    analyze_dependencies,
    topological_sort,
    visualize_graph,
    get_execution_order_stats
)

Analyze and optimize:

try:
    # Analyze dependencies
    deps = analyze_dependencies(features)

    # Get optimized order
    feature_order = topological_sort(features, deps)

    # Get statistics
    stats = get_execution_order_stats(features, deps, feature_order)

    # Generate visualization
    graph = visualize_graph(features, deps)

    # Update batch state with dependency info
    state.feature_dependencies = deps
    state.feature_order = feature_order
    state.analysis_metadata = {
        "stats": stats,
        "analyzed_at": datetime.utcnow().isoformat(),
        "total_dependencies": sum(len(d) for d in deps.values()),
    }

    # Display dependency graph to user
    print("\nDependency Analysis Complete:")
    print(f"  Total dependencies detected: {stats['total_dependencies']}")
    print(f"  Independent features: {stats['independent_features']}")
    print(f"  Dependent features: {stats['dependent_features']}")
    print(f"\n{graph}")

except Exception as e:
    # Graceful degradation - use original order if analysis fails
    print(f"\nDependency analysis failed: {e}")
    print("Continuing with original order...")
    feature_order = list(range(len(features)))
    state.feature_order = feature_order
    state.feature_dependencies = {i: [] for i in range(len(features))}
    state.analysis_metadata = {"error": str(e), "fallback": "original_order"}

Why this matters:

• Executes features in dependency order (tests after implementation, dependent features after prerequisites)
• Reduces failures from missing dependencies
• Provides visual feedback on feature relationships
• Gracefully degrades to original order if analysis fails

---

STEP 2: Create Todo List

Action: Use TodoWrite tool to create todo items for tracking

Create one todo per feature:

[
  {"content": "Feature 1", "status": "pending", "activeForm": "Processing Feature 1"},
  {"content": "Feature 2", "status": "pending", "activeForm": "Processing Feature 2"},
  ...
]

This gives visual progress tracking during batch execution.

---

STEP 3: Process Each Feature

Action: Loop through features in optimized order

For each feature index in state.feature_order (uses dependency-optimized order from STEP 1.5):

Get the feature: feature = features[feature_index]

For each feature:

1. Mark todo as in_progress using TodoWrite

2. Display progress:

   ========================================
   Batch Progress: Feature M/N
   ========================================
   Feature: {feature description}
   

3. Invoke /auto-implement using SlashCommand tool:

   SlashCommand(command="/auto-implement {feature}")
   

   Wait for completion (this runs the full autonomous workflow):

   • Alignment check
   • Research
   • Planning
   • TDD tests
   • Implementation
   • Review + Security + Docs (parallel)
   • Git automation (if enabled)

4. Check for failure and retry if needed (Issue #89, v3.33.0+):

   If /auto-implement failed:

   a. Classify failure type using failure_classifier.classify_failure():

   • Check error message against patterns
   • Return FailureType.TRANSIENT or FailureType.PERMANENT

   b. Check retry consent using batch_retry_consent.is_retry_enabled():

   • First-run: Prompt user for consent (save to ~/.autonomous-dev/user_state.json)
   • Subsequent runs: Use saved consent state
   • Environment override: Check BATCH_RETRY_ENABLED env var

   c. Decide whether to retry using batch_retry_manager.should_retry_feature():

   • Check user consent (highest priority)
   • Check global retry limit (max 50 total retries)
   • Check circuit breaker (5 consecutive failures → pause)
   • Check failure type (permanent → don't retry)
   • Check per-feature retry limit (max 3 retries per feature)

   d. If should retry:

   • Record retry attempt using batch_retry_manager.record_retry_attempt()
   • Display retry message: "⚠️ Transient failure detected. Retrying ({retry_count}/{MAX_RETRIES_PER_FEATURE})..."
   • Invoke /auto-implement {feature} again
   • Loop back to step 4 (check for failure again)

   e. If should NOT retry:

   • Update batch state with failure:

     update_batch_progress(
         state_file=get_batch_state_file(),
         feature_index=feature_index,
         status="failed",
         error_message=sanitized_error_message,
     )
     

   • Log to audit file (.claude/audit/{batch_id}_retry_audit.jsonl)
   • Display failure message with reason
   • Continue to next feature

   Transient Failures (automatically retried):

   • ConnectionError, TimeoutError, HTTPError
   • API rate limits (429 Too Many Requests)
   • Temporary network issues

   Permanent Failures (never retried):

   • SyntaxError, ImportError, AttributeError, TypeError
   • Test failures (AssertionError)
   • Validation errors

   Safety Limits:

   • Max 3 retries per feature
   • Max 50 total retries across batch
   • Circuit breaker after 5 consecutive failures

5. Mark todo as completed using TodoWrite (if feature succeeded)

6. Update batch state (CRITICAL for compaction-resilience):

   # After EVERY feature (success or failure), update the persistent state
   from plugins.autonomous_dev.lib.batch_state_manager import update_batch_progress
   from plugins.autonomous_dev.lib.path_utils import get_batch_state_file
   
   update_batch_progress(
       state_file=get_batch_state_file(),
       feature_index=feature_index,
       status="completed",  # or "failed" if feature failed
       context_token_delta=0,  # optional token tracking
   )
   

   Why this is critical: If Claude Code auto-compacts context, the SessionStart hook reads batch_state.json to determine progress. Without this update, the batch restarts from the beginning after compaction.

7. Continue to next feature

---

STEP 4: Summary Report

Action: After all features processed, display summary

========================================
BATCH COMPLETE
========================================

Total features: N
Completed successfully: M
Failed: (N - M)

Time: {estimate based on typical /auto-implement duration}

All features have been processed.
Check git commits for individual feature implementations.
========================================

---

Prerequisites for Unattended Operation

Required environment variables (set in .env file):

# Auto-approve tool calls (no permission prompts)
MCP_AUTO_APPROVE=true

# Auto git operations (commit, push, PR)
AUTO_GIT_ENABLED=true
AUTO_GIT_PUSH=true
AUTO_GIT_PR=false  # Optional - set true if you want auto PRs

# Automatic retry for transient failures (NEW in v3.33.0)
# First-run: Interactive prompt (saved to ~/.autonomous-dev/user_state.json)
# Override: Set BATCH_RETRY_ENABLED=true to skip prompt
BATCH_RETRY_ENABLED=true  # Optional - enable automatic retry

Without these, permission prompts will interrupt the workflow.

Automatic Retry (v3.33.0+):

• First Run: You'll be prompted to enable automatic retry
• Consent Storage: Your choice is saved to ~/.autonomous-dev/user_state.json
• Environment Override: Set BATCH_RETRY_ENABLED=true in .env to skip prompt
• Safety: Max 3 retries per feature, max 50 total retries, circuit breaker after 5 consecutive failures
• Audit: All retry attempts logged to .claude/audit/{batch_id}_retry_audit.jsonl

---

Example

features.txt:

# Bug fixes
Fix login timeout issue
Fix memory leak in background jobs

# New features
Add email notifications
Add export to CSV
Add dark mode toggle

Command:

/batch-implement features.txt

Output:

Found 5 features in features.txt:
  1. Fix login timeout issue
  2. Fix memory leak in background jobs
  3. Add email notifications
  4. Add export to CSV
  5. Add dark mode toggle

Starting batch processing...

========================================
Batch Progress: Feature 1/5
========================================
Feature: Fix login timeout issue

[/auto-implement runs full workflow...]
[Context cleared]

========================================
Batch Progress: Feature 2/5
========================================
Feature: Fix memory leak in background jobs

[/auto-implement runs full workflow...]
[Context cleared]

...

========================================
BATCH COMPLETE
========================================

Total features: 5
Completed successfully: 5
Failed: 0

All features have been processed.
========================================

---

Timing

Per feature: ~20-30 minutes (same as single /auto-implement)

Batch of 10 features: ~3-5 hours Batch of 20 features: ~6-10 hours (perfect for overnight)

Recommendation: Queue 10-20 features max per batch.

---

Error Handling

If a feature fails:

• Mark todo as failed (not completed)
• Continue to next feature (don't abort entire batch)
• Report failures in summary

Continue-on-failure is default - one bad feature won't stop the batch.

GitHub Issues --issues flag errors:

1. gh CLI not installed:

   ERROR: gh CLI not found.
   
   Install gh CLI:
     macOS: brew install gh
     Ubuntu: apt install gh
     Windows: winget install GitHub.cli
   

2. Not authenticated:

   ERROR: gh CLI not authenticated.
   
   Run: gh auth login
   

3. Issue not found:

   WARNING: Issue #999 not found, skipping...
   Continuing with remaining issues: #72, #73, #74
   

4. Invalid issue numbers:

   ERROR: Invalid issue number: -5
   Issue numbers must be positive integers
   

5. Too many issues:

   ERROR: Too many issues (150 provided, max 100)
   Please split into multiple batches
   

6. Mutually exclusive arguments:

   ERROR: Cannot use both <file> and --issues
   Usage: /batch-implement <file> OR /batch-implement --issues <numbers>
   

---

Context Management Strategy

Batch processing uses a compaction-resilient design that survives Claude Code's automatic context summarization.

How It Works

1. Fully unattended: All features run without manual intervention
2. Externalized state: Progress tracked in batch_state.json, not conversation memory
3. Auto-compaction safe: When Claude Code summarizes context, processing continues
4. Each feature bootstraps fresh: Reads issue from GitHub, reads codebase, implements
5. Git commits preserve work: Every completed feature is committed before moving on
6. SessionStart hook: Re-injects workflow methodology after compaction (NEW)

Why This Works

Each /auto-implement is self-contained:

• Fetches requirements from GitHub issue (not memory)
• Reads current codebase state (not memory)
• Implements based on what it reads
• Commits to git (permanent)
• Updates batch_state.json (permanent)

The conversation context is just a working buffer - all real state is externalized.

Compaction Recovery (SessionStart Hook)

When Claude Code auto-compacts context (at 64-75% capacity), it may lose the instruction to use /auto-implement for each feature. The SessionStart hook with "compact" matcher automatically re-injects the workflow methodology:

# Hook file: plugins/autonomous-dev/hooks/SessionStart-batch-recovery.sh
# Fires AFTER compaction completes
# Re-injects: "Use /auto-implement for each feature"

What survives compaction:

• ✅ Completed git commits
• ✅ batch_state.json (externalized)
• ✅ File changes
• ✅ Workflow methodology (via SessionStart hook)

What would be lost without the hook:

• ❌ "Use /auto-implement" instruction
• ❌ Procedural context
• ❌ Pipeline requirements

The hook reads batch_state.json and displays:

**BATCH PROCESSING RESUMED AFTER COMPACTION**

Batch ID: batch-20251223-...
Progress: Feature 42 of 81

CRITICAL WORKFLOW REQUIREMENT:
- Use /auto-implement for EACH remaining feature
- NEVER implement directly

Benefits

• Truly unattended: No manual /clear + resume cycles needed
• Unlimited batch sizes: 50+ features run continuously
• Methodology preserved: SessionStart hook survives compaction
• Crash recovery: --resume only needed for actual crashes, not context limits
• Production tested: Externalized state proven reliable

---

Tips

1. Start small: Test with 2-3 features first to verify setup
2. Check .env: Ensure MCP_AUTO_APPROVE=true and AUTO_GIT_ENABLED=true
3. Feature order: Put critical features first (in case batch interrupted)
4. Feature size: Keep features small and focused (easier to debug failures)
5. Large batches: 50+ features run fully unattended (compaction-resilient design)
6. Crash recovery: Use --resume <batch-id> only if Claude Code crashes/exits

---

Version: 3.0.0 (Simple orchestration - no Python libraries) Issue: #75 (Batch implementation) Changed: Removed complex Python libraries, pure Claude orchestration