Execute multiple features sequentially (--issues <nums> or --resume <id>)
Process multiple features overnight with automatic retry and crash recovery. Queue features from a file or GitHub issues, then wake up to completed work.
/plugin marketplace add akaszubski/autonomous-dev/plugin install autonomous-dev@autonomous-devProcess multiple features fully unattended - queue them up, let it run overnight, wake up to completed work. Survives auto-compaction via externalized state.
# 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:
brew install gh, apt install gh, or winget install GitHub.cli)gh auth login (one-time setup)State Management (v3.1.0+):
.claude/batch_state.json--resume <batch-id> flagPlain 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:
# are comments (skipped)Fetch issue titles directly from GitHub:
/batch-implement --issues 72 73 74
How it works:
gh issue view <number> --json titleissue_numbers and source_type='issues'Requirements:
Graceful Degradation:
gh auth login instructionsMutually Exclusive: Cannot use both <file> and --issues in same command
State-based workflow (v3.1.0+):
.claude/batch_state.json/auto-implement {feature}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:
.claude/batch_state.json/batch-implement --resume <batch-id>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)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
)
Action: Use the Read tool to read the features file
Parse the content:
# (comments)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...
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:
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.
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:
Mark todo as in_progress using TodoWrite
Display progress:
========================================
Batch Progress: Feature M/N
========================================
Feature: {feature description}
Invoke /auto-implement using SlashCommand tool:
SlashCommand(command="/auto-implement {feature}")
Wait for completion (this runs the full autonomous workflow):
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():
FailureType.TRANSIENT or FailureType.PERMANENTb. Check retry consent using batch_retry_consent.is_retry_enabled():
c. Decide whether to retry using batch_retry_manager.should_retry_feature():
d. If should retry:
batch_retry_manager.record_retry_attempt()/auto-implement {feature} againe. If should NOT retry:
update_batch_progress(
state_file=get_batch_state_file(),
feature_index=feature_index,
status="failed",
error_message=sanitized_error_message,
)
Transient Failures (automatically retried):
Permanent Failures (never retried):
Safety Limits:
Mark todo as completed using TodoWrite (if feature succeeded)
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.
Continue to next feature
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.
========================================
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+):
~/.autonomous-dev/user_state.jsonBATCH_RETRY_ENABLED=true in .env to skip prompt.claude/audit/{batch_id}_retry_audit.jsonlfeatures.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.
========================================
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.
If a feature fails:
Continue-on-failure is default - one bad feature won't stop the batch.
GitHub Issues --issues flag errors:
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
Not authenticated:
ERROR: gh CLI not authenticated.
Run: gh auth login
Issue not found:
WARNING: Issue #999 not found, skipping...
Continuing with remaining issues: #72, #73, #74
Invalid issue numbers:
ERROR: Invalid issue number: -5
Issue numbers must be positive integers
Too many issues:
ERROR: Too many issues (150 provided, max 100)
Please split into multiple batches
Mutually exclusive arguments:
ERROR: Cannot use both <file> and --issues
Usage: /batch-implement <file> OR /batch-implement --issues <numbers>
Batch processing uses a compaction-resilient design that survives Claude Code's automatic context summarization.
batch_state.json, not conversation memoryEach /auto-implement is self-contained:
The conversation context is just a working buffer - all real state is externalized.
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:
What would be lost without the hook:
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
/clear + resume cycles needed--resume only needed for actual crashes, not context limits--resume <batch-id> only if Claude Code crashes/exitsVersion: 3.0.0 (Simple orchestration - no Python libraries) Issue: #75 (Batch implementation) Changed: Removed complex Python libraries, pure Claude orchestration