alfredolopez80/task-batch

/task-batch - Autonomous Batch Task Execution (v2.88)

Continuous autonomous execution of task lists with PRD parsing, automatic task decomposition, and completion validation. Runs until ALL tasks reach VERIFIED_DONE or major failure occurs.

Based on research from:

• Sugar - 24/7 autonomous layer for AI coding agents
• Daedalus/Talos - Task queue daemon with dependency resolution
• Continuous Autonomous Task Loop Pattern
• claude-queue - Priority-based task queuing

Quick Start

# From PRD file
/task-batch docs/prd/feature-x.prq.md

# From task list file
/task-batch tasks/sprint-backlog.md

# Inline tasks (semicolon-separated)
/task-batch "Add authentication; Implement user profile; Add password reset"

# With priority ordering
/task-batch tasks/features.md --priority

# With specific teammates
/task-batch tasks/backend.md --teammates coder,reviewer,tester

Core Design Principles

1. Continuous Autonomous Execution

• NO user interaction until all tasks complete (except critical failures)
• Fresh context per task - each task starts with clean context to avoid contamination
• Auto-commit after each VERIFIED_DONE task
• Intelligent rate limit handling - exponential backoff with configurable delays

2. Stop Conditions

| Condition | Action | |-----------|--------| | All tasks VERIFIED_DONE | STOP - Output summary, delete team | | No internet connectivity | STOP - Report error, save state | | Token limit reached | STOP - Save progress, report position | | System crash/error | STOP - Emergency save, report diagnostics | | Max iterations reached | FAIL - CRITICAL ERROR: This indicates infinite loop, report all incomplete tasks | | Tasks remaining at exit | FAIL - CRITICAL ERROR: NEVER exit with pending tasks unless critical failure | | Normal user questions | CONTINUE - Queue for end-of-batch response |

⚠️ CRITICAL RULE: NO PARTIAL SUCCESS

The skill MUST NEVER report success with incomplete tasks.

❌ WRONG: "Completed 10 of 17 tasks" → Summary → Exit 0
✅ RIGHT: "Completed 10 of 17 tasks" → Continue execution until ALL 17 done
✅ RIGHT: "Cannot continue due to [critical failure]" → Report error → Exit 1

If execution cannot continue (blocked dependencies, critical failure), the skill MUST:

1. Report explicit FAILURE status
2. List all incomplete tasks with reasons
3. Exit with non-zero code
4. Save state for manual recovery

3. Task Execution Model (MULTIPLE TASKS)

CRITICAL: This skill handles MULTIPLE tasks, not just one task.

+------------------------------------------------------------------+
|                    TASK-BATCH EXECUTION MODEL                     |
|                   (MULTIPLE TASKS - DEFAULT MODE)                 |
+------------------------------------------------------------------+
|                                                                   |
|   +----------+    +-------------+    +----------------+           |
|   |  PARSE   |--->| PRIORITIZE  |--->| DECOMPOSE      |           |
|   |  Input   |    | (optional)  |    | Complex Tasks  |           |
|   +----------+    +-------------+    +-------+--------+           |
|                                              |                    |
|   +------------------------------------------v---------------+   |
|   |              TASK QUEUE (N TASKS)                          |   |
|   |                                                            |   |
|   |   [Task1]    [Task2]    [Task3]    [Task4]    [TaskN]     |   |
|   |   Criteria  Criteria  Criteria  Criteria  Criteria       |   |
|   |   ✅ ✓✓✓    ✅ ✓✓✓    ⏳ ...     ⏳ ...     ⏳ ...        |   |
|   +---------------------------+-------------------------------+   |
|                               |                                   |
|   +---------------------------v-------------------------------+   |
|   |            EXECUTION LOOP (FOR EACH TASK)                  |   |
|   |                                                            |   |
|   |   FOR EACH task IN task_queue:                            |   |
|   |     +--------+   +------------+   +---------------+        |   |
|   |     | VALIDATE|-->| ORCHESTRATE|-->|CHECK CRITERIA|        |   |
|   |     | Criteria|   | (10-step)  |   | (ALL must ✓) |        |   |
|   |     +--------+   +------------+   +-------+-------+        |   |
|   |                                                  |         |   |
|   |                                    ALL MET? <--YES--NO-->  |   |
|   |                                        |        RETRY      |   |
|   |                                        v                   |   |
|   |                               +---------------+            |   |
|   |                               | VERIFIED_DONE |            |   |
|   |                               |  + NEXT TASK  |            |   |
|   |                               +---------------+            |   |
|   +------------------------------------------------------------+   |
+------------------------------------------------------------------+   |
|   |                                       YES<--+-->NO         |   |
|   |                                        |      |            |   |
|   |                         +--------------+      |            |   |
|   |                         v                     v            |   |
|   |                  +-----------+        +------------+       |   |
|   |                  | AUTO-COMMIT|        | RETRY      |       |   |
|   |                  | + NEXT    |        | (max 3)    |       |   |
|   |                  +-----------+        +------------+       |   |
|   |                                                            |   |
|   +------------------------------------------------------------+   |
|                                                                   |
+------------------------------------------------------------------+

Input Formats

1. PRD File Format (.prq.md or .md)

# Feature: User Authentication

## Priority: HIGH

## Overview
Implement OAuth2 authentication with Google provider.

## Tasks
- [ ] P1: Create OAuth2 service module
- [ ] P1: Add Google OAuth provider configuration
- [ ] P2: Implement login callback handler
- [ ] P2: Add session management
- [ ] P3: Create authentication middleware
- [ ] P3: Write unit tests

## Dependencies
- P2 tasks depend on P1 tasks completion

## Acceptance Criteria
- Users can login with Google
- Sessions persist for 7 days
- All tests pass

2. Task List Format

# Sprint Backlog - Week 12

## Backend Tasks
1. [P1] Implement rate limiting with Redis
2. [P1] Add input validation to all endpoints
3. [P2] Create API documentation with OpenAPI
4. [P2] Add request logging middleware

## Frontend Tasks
5. [P1] Fix login form validation
6. [P2] Add loading states to buttons
7. [P3] Implement dark mode toggle

3. Inline Tasks

/task-batch "Add user schema; Create CRUD endpoints; Add validation"

4. JSON Task File

{
  "batch_name": "auth-feature",
  "tasks": [
    {
      "id": "auth-001",
      "description": "Create OAuth2 service",
      "priority": 1,
      "dependencies": [],
      "acceptance_criteria": ["Module exists", "Exports configured client"]
    },
    {
      "id": "auth-002",
      "description": "Add Google provider",
      "priority": 1,
      "dependencies": ["auth-001"],
      "acceptance_criteria": ["Google OAuth configured", "Test passes"]
    }
  ],
  "config": {
    "max_retries": 3,
    "auto_commit": true,
    "stop_on_failure": false
  }
}

Execution Workflow

Phase 1: PARSE

Parse input into structured task list:

# Parse logic
Input Type Detection:
  - .prq.md or .md ending → PRD Parser
  - .json ending → JSON Parser
  - tasks/ directory → Multi-file Parser
  - Inline text → Inline Parser

Task Extraction:
  - Extract task descriptions
  - Parse priority markers (P1/P2/P3 or HIGH/MEDIUM/LOW)
  - Identify dependencies
  - Extract acceptance criteria

Phase 2: PRIORITIZE (Optional)

When --priority flag is set:

Priority Rules:
  1. Explicit priority markers (P1 > P2 > P3)
  2. Dependency order (dependencies first)
  3. File order (as listed in input)
  4. Estimated effort (smaller tasks first when same priority)

Phase 3: DECOMPOSE

For tasks with complexity > 6:

Decomposition Rules:
  - Split into subtasks if:
    - Task has multiple deliverables
    - Task spans multiple files
    - Task requires different expertise
  - Create subtask dependencies
  - Preserve original acceptance criteria

Vertical Slices Mode (--slices) (v3.0)

When invoked with --slices, decompose features into vertical slices instead of horizontal layers:

/task-batch tasks.md --slices

Each slice includes ALL layers for ONE feature:

1. API/Backend — endpoint, handler, validation
2. UI/Frontend — component, styling, design tokens
3. Tests — unit + integration for that slice
4. Spec verification — exit criteria from spec

Example: "user login" becomes:

• Slice 1: POST /login + login form + test
• Slice 2: Session management + protected route + test
• Slice 3: Error handling + a11y + test

Each slice is independently deployable and testable. Invoke /spec for each slice if complexity > 6.

Phase 4: EXECUTE (Main Loop)

# Pseudocode for execution loop
task_queue = parse_and_prioritize(input)
completed_tasks = []
failed_tasks = []
iteration = 0
max_iterations = len(task_queue) * 5  # Safety limit

while task_queue and iteration < max_iterations:
    # Rate limit check
    if rate_limit_detected():
        sleep(exponential_backoff())
        continue

    # Select next task (respecting dependencies)
    task = select_next_task(task_queue, completed_tasks)

    if task is None:
        # All remaining tasks blocked - THIS IS A FAILURE
        blocked_tasks = identify_blocked_reasons(task_queue, completed_tasks)
        report_failure("BLOCKED", blocked_tasks)
        exit 1  # FAILURE - cannot continue

    # Fresh context per task (via new subagent)
    result = execute_with_orchestrator(task)

    if result == VERIFIED_DONE:
        completed_tasks.append(task)
        task_queue.remove(task)
        auto_commit(task)

        # Update dependent tasks
        update_dependencies(task_queue, task)
    else:
        if task.retry_count < MAX_RETRIES:
            task.retry_count += 1
            # Re-queue with feedback
            task.feedback = result.errors
        else:
            failed_tasks.append(task)
            # DO NOT break - continue with remaining tasks
            # Unless stop_on_failure is explicitly set
            if config.stop_on_failure:
                break

    iteration++

# ══════════════════════════════════════════════════════════════════
# CRITICAL: FINAL VALIDATION - NO PARTIAL SUCCESS ALLOWED
# ══════════════════════════════════════════════════════════════════
if len(task_queue) > 0:
    # THERE ARE STILL PENDING TASKS - THIS IS A FAILURE
    print("❌ BATCH FAILED: Incomplete tasks remain")
    print(f"   Completed: {len(completed_tasks)}")
    print(f"   Pending:   {len(task_queue)}")
    print(f"   Failed:    {len(failed_tasks)}")
    for task in task_queue:
        print(f"   - {task.id}: {task.description}")
    exit 1  # EXPLICIT FAILURE

if len(failed_tasks) > 0:
    # SOME TASKS FAILED AFTER MAX RETRIES
    print("❌ BATCH FAILED: Tasks exceeded max retries")
    for task in failed_tasks:
        print(f"   - {task.id}: {task.description}")
        print(f"     Error: {task.last_error}")
    exit 1  # EXPLICIT FAILURE

# ALL TASKS COMPLETED SUCCESSFULLY
output_summary(completed_tasks, [])
exit 0  # SUCCESS

Phase 5: REPORT

Summary Output:
  - Total tasks: N
  - Completed: M
  - Failed: X
  - Skipped: Y (blocked by failures)

  - For each task:
    - Status: VERIFIED_DONE | FAILED | SKIPPED
    - Duration: XX minutes
    - Files modified: [list]
    - Commits: [sha1, sha2, ...]

  - For failed tasks:
    - Error details
    - Retry attempts
    - Suggested fixes

Team Coordination (Agent Teams)

Team Creation

# Automatic on skill invocation
TeamCreate:
  team_name: "task-batch-{timestamp}"
  description: "Batch execution: {batch_name}"
  agent_type: "orchestrator"

Task Distribution

# Create tasks in shared list
TaskCreate:
  subject: "{task_description}"
  description: "{full_task_details}"
  activeForm: "Executing: {task_description}"
  metadata:
    priority: "{priority}"
    dependencies: ["{dep_task_ids}"]
    acceptance_criteria: ["{criteria}"]

# Assign to appropriate teammate
TaskUpdate:
  taskId: "{id}"
  owner: "ralph-coder"  # or ralph-reviewer, ralph-tester

Teammate Spawning

# Spawn teammates based on task type
Task:
  subagent_type: "ralph-coder"
  team_name: "task-batch-{timestamp}"
  name: "batch-coder"
  prompt: |
    Execute task: {task_description}

    Acceptance Criteria:
    {acceptance_criteria}

    Context: Fresh execution, no prior context.

    Execute until VERIFIED_DONE or max retries reached.

Hook Integration

| Hook | Purpose | Exit 2 Behavior | |------|---------|-----------------| | teammate-idle-quality-gate.sh | Quality check before idle | Keep working with feedback | | task-completed-quality-gate.sh | Validate before completion | Prevent completion, retry | | ralph-subagent-start.sh | Load Ralph context | - | | batch-progress-tracker.sh | Track batch progress | Continue if tasks remain |

Progress Tracking

# Progress file: .ralph/batch/{batch_id}/progress.json
{
  "batch_id": "batch-20260215-123456",
  "started": "2026-02-15T12:00:00Z",
  "total_tasks": 10,
  "completed": 5,
  "failed": 1,
  "current_task": "auth-006",
  "estimated_completion": "2026-02-15T14:30:00Z"
}

Error Handling

Rate Limit Handling

Rate Limit Detection:
  - API response: 429 Too Many Requests
  - Error message contains "rate limit"
  - Timeout exceeded

Recovery:
  - Initial backoff: 60 seconds
  - Max backoff: 300 seconds (5 minutes)
  - Backoff multiplier: 2x
  - Max retries: 5

  On max retries exceeded:
    - Save state
    - Report error
    - STOP batch execution

Task Failure Handling

Task Failure Options:
  stop_on_failure: false  # Continue with remaining tasks
  stop_on_failure: true   # Stop entire batch

Failure Recovery:
  1. Log error details
  2. Capture current state
  3. If retry_count < MAX_RETRIES:
     - Add feedback to task
     - Re-queue for retry
  4. Else:
     - Mark as FAILED
     - Skip dependent tasks

Critical Failure Detection

Critical Failures (STOP immediately):
  - No network connectivity (ping failed)
  - Token limit reached (>95% context used)
  - System crash (unhandled exception)
  - Authentication failure
  - Repository corruption

Non-Critical Failures (CONTINUE):
  - Single task failure (if stop_on_failure=false)
  - Test failure (triggers retry)
  - Lint errors (triggers retry)
  - Type errors (triggers retry)

CLI Commands

# Basic batch execution
ralph batch tasks/features.md

# With priority ordering
ralph batch tasks/sprint.md --priority

# Stop on first failure
ralph batch tasks/critical.md --stop-on-failure

# Resume interrupted batch
ralph batch --resume batch-20260215-123456

# Check batch status
ralph batch --status batch-20260215-123456

# List running batches
ralph batch --list

# Cancel running batch
ralph batch --cancel batch-20260215-123456

Configuration

Default Configuration

# ~/.ralph/config/batch.yaml
batch:
  max_iterations_multiplier: 5  # max_iter = task_count * multiplier
  max_retries_per_task: 3
  auto_commit: true
  stop_on_failure: false
  priority_enabled: false

rate_limits:
  initial_backoff_seconds: 60
  max_backoff_seconds: 300
  backoff_multiplier: 2
  max_retries: 5

teammates:
  default: [coder, reviewer]
  complex: [coder, reviewer, tester]
  critical: [coder, reviewer, tester, security]

hooks:
  progress_tracking: true
  quality_gates: true

Per-Batch Override

# In task file frontmatter
---
batch:
  max_retries: 5
  stop_on_failure: true
  teammates: [coder, tester]
---

Completion Criteria

VERIFIED_DONE (Per Task)

Each task requires ALL:

1. Implementation complete
2. CORRECTNESS passed (syntax, logic)
3. QUALITY passed (types, linting)
4. SECURITY passed (no vulnerabilities)
5. Acceptance criteria verified
6. Auto-commit successful

BATCH_COMPLETE (Full Batch)

Requires ALL:

1. All tasks processed (VERIFIED_DONE or FAILED)
2. Summary report generated
3. Git history clean (commits for each task)
4. Team deleted
5. Progress file archived

Anti-Patterns

• NEVER stop for non-critical user questions (queue them)
• NEVER use infinite loops (always set max_iterations)
• NEVER skip quality gates (defeats VERIFIED_DONE)
• NEVER share context between tasks (contamination risk)
• NEVER ignore rate limits (will cause failures)
• NEVER commit without VERIFIED_DONE (incomplete work)
• ⚠️ CRITICAL: NEVER report success with incomplete tasks

The "Partial Success" Anti-Pattern

❌ WRONG BEHAVIOR:
  Output: "Completed Tasks (10 of 17)"
  Output: "Remaining Tasks (7)"
  Action: Exit 0 (success)

✅ CORRECT BEHAVIOR:
  Option A: Continue execution until ALL 17 tasks complete
  Option B: If cannot continue:
    Output: "❌ BATCH FAILED: Cannot continue"
    Output: "Completed: 10, Pending: 7, Failed: 0"
    Output: "Reason: [blocked dependency | critical error | token limit]"
    Exit: 1 (failure)

If you find yourself about to output a summary with remaining tasks:

1. STOP - do not output success
2. Either continue execution OR report explicit failure
3. Partial completion = FAILURE, not success

Comparison: /task-batch vs /orchestrator vs /iterate

| Feature | /task-batch | /orchestrator | /iterate | |---------|-------------|---------------|-------| | Input | Multiple tasks | Single task | Single task | | Execution | Continuous until all done | Single workflow | Iterative refinement | | User Interaction | Minimal (critical only) | Full clarification | Iteration prompts | | Stop Condition | All complete OR critical failure | VERIFIED_DONE | VERIFIED_DONE or max iter | | Task Decomposition | Automatic | Manual (in plan) | N/A | | PRD Support | Native | Via clarify | N/A | | Priority Ordering | Yes | No | No | | Best For | Batch features, PRD execution | Complex single tasks | Quality refinement |

Agent Teams Integration (v2.88)

Optimal Scenario: Integrated (Agent Teams + Custom Subagents)

Why Scenario C for This Skill

• Batch coordination requires tracking multiple tasks across teammates
• Quality gates essential for VERIFIED_DONE on each task
• Specialized agents (ralph-coder, ralph-reviewer, ralph-tester) for different task types
• Shared task list enables dependency management and progress tracking
• Continuous execution benefits from team coordination without user intervention

Configuration

1. TeamCreate: Create team "task-batch-{batch-id}" on invocation
2. TaskCreate: Create task for each item in batch
3. Spawn: Use ralph-coder for implementation, ralph-reviewer for validation
4. Hooks: TeammateIdle + TaskCompleted for quality validation
5. Coordination: Shared task list at ~/.claude/tasks/task-batch-{id}/

VERIFIED_DONE Guarantee with Hooks

| Hook | Event | Purpose | |------|-------|---------| | teammate-idle-quality-gate.sh | TeammateIdle | Prevent idle if tasks remain | | task-completed-quality-gate.sh | TaskCompleted | Validate task before marking complete | | ralph-subagent-stop.sh | SubagentStop | Quality gate when teammate stops | | batch-progress-tracker.sh | PostToolUse | Update batch progress file |

Exit 2 Behavior: Hooks return exit 2 to force continuation when:

• More tasks remain in queue
• Quality gates failed but retries available
• Dependency tasks not yet complete

Related Skills

• /orchestrator - Base 10-step workflow (used internally)
• /iterate - Iterative refinement pattern
• /gates - Quality validation gates
• /clarify - Requirement clarification (used for PRD parsing)
• /retrospective - Post-batch analysis

Action Reporting (v2.93.0)

Esta skill genera reportes automáticos completos para trazabilidad:

Reporte Automático

Cuando esta skill completa, se genera automáticamente:

1. En la conversación de Claude: Resultados visibles
2. En el repositorio: docs/actions/task-batch/{timestamp}.md
3. Metadatos JSON: .claude/metadata/actions/task-batch/{timestamp}.json

Contenido del Reporte

Cada reporte incluye:

• ✅ Summary: Descripción de la tarea ejecutada
• ✅ Execution Details: Duración, iteraciones, archivos modificados
• ✅ Results: Errores encontrados, recomendaciones
• ✅ Next Steps: Próximas acciones sugeridas

Ver Reportes Anteriores

# Listar todos los reportes de esta skill
ls -lt docs/actions/task-batch/

# Ver el reporte más reciente
cat $(ls -t docs/actions/task-batch/*.md | head -1)

# Buscar reportes fallidos
grep -l "Status: FAILED" docs/actions/task-batch/*.md

Generación Manual (Opcional)

source .claude/lib/action-report-lib.sh
start_action_report "task-batch" "Task description"
# ... ejecución ...
complete_action_report "success" "Summary" "Recommendations"

Referencias del Sistema

• Action Reports System - Documentación completa

• action-report-lib.sh - Librería helper

• action-report-generator.sh - Generador

• Sugar - Autonomous AI Coding

• Daedalus/Talos - Task Queue Daemon

• Continuous Autonomous Task Loop Pattern

• claude-queue - Priority Task Queuing

• Awesome Agentic Patterns

• Unified Architecture v2.88

• Claude Code Agent Teams Documentation

Anti-Rationalization (Extended v3.0)

See master table: docs/reference/anti-rationalization.md

| Excuse | Rebuttal | |---|---| | "Partial success is acceptable" | Each task has completion criteria. Meet them. | | "This task depends on another, skipping" | Document the dependency, don't skip. | | "The PRD doesn't have completion criteria" | No criteria = task rejected. Ask for them. | | "I'll batch-commit at the end" | Auto-commit after EACH completed task. | | "The context is too stale, starting fresh" | Fresh context per task is built in. Use it. | | "This task is a duplicate of a previous one" | Verify with the PRD before skipping. Duplicates have different scopes. | | "The batch is taking too long, trimming scope" | Scope is set by the PRD. Trim with user approval only. |