Long Task Execution Framework

Robust protocol for executing tasks that take multiple hours with confidence.

Core Principles

1. Atomicity: Every task must be decomposed into atomic sub-tasks < 10 minutes
2. Validation: Validate after every change, before every checkpoint
3. Checkpointing: Create checkpoint after every completed atomic task
4. Recovery: Automatic retry → rollback → escalate on failures
5. Determinism: Use scripts for critical operations (not LLM decisions)

Atomic Task Requirements

Each atomic task MUST:

• Take < 10 minutes to execute
• Have clear, verifiable success criteria
• Be independently rollback-able
• Have explicit dependencies listed
• Have a rollback plan defined

Validation Protocol

After Every Code Change:

npx tsc --noEmit --skipLibCheck    # TypeScript (2-5s)
npx eslint src --max-warnings 0    # Linting (1-3s)

After Atomic Task Completion:

bash .claude/framework/validation-gate.sh atomic

Before Final Completion:

bash .claude/framework/validation-gate.sh final

NEVER continue if validation fails. Stop and recover.

Checkpoint Strategy

Create checkpoint:

• ✅ AFTER each atomic task completes successfully
• ✅ BEFORE risky operations (migrations, major refactors)
• ✅ Every 15 minutes MAX (even if task incomplete)
• ❌ NEVER on validation failures
• ❌ NEVER during rollback
• 📁 Snapshot stored at .claude/checkpoints/{id}/snapshot/ (excludes .claude/checkpoints, .git, node_modules)

Checkpoint naming:

• Pattern: ckpt_{taskId}_{atomicTaskId}_{timestamp}
• Example: ckpt_sprint-1_task1.3_1729612345

Checkpoint metadata:

Include context:

• Decisions made ("Chose approach X over Y because...")
• Blockers encountered
• Files changed
• Next task

Recovery Protocol

On failure, execute in order:

Level 1: Retry (3 attempts max)

node .claude/framework/recovery.js --task-id=X --error='{"type":"...","message":"..."}'

• Same approach, maybe transient error
• Agent retries task automatically

Level 2: Rollback

• Restore to last valid checkpoint
• Try alternative approach
• Agent retries with different strategy

Level 3: Escalate

• Mark task as BLOCKED
• Notify human with error details and options
• Wait for manual intervention

State Machine

Valid state transitions:

INITIALIZED → PLANNING
PLANNING → PLANNED | FAILED
PLANNED → EXECUTING
EXECUTING → VALIDATING | FAILED
VALIDATING → CHECKPOINTING | FAILED
CHECKPOINTING → EXECUTING | COMPLETED
FAILED → ROLLING_BACK | ABANDONED
ROLLING_BACK → EXECUTING | ABANDONED

Invalid transitions are errors.

Scripts Reference

All scripts are in .claude/framework/:

# Logger (structured JSON logs)
node logger.js --event=EVENT_NAME --data='{"key":"value"}'

# Checkpoint Manager
node checkpoint-manager.js create --task-id=X --context='{"decisions":"..."}'
node checkpoint-manager.js restore --checkpoint-id=ckpt_xyz
node checkpoint-manager.js list

# Validation Gates
bash validation-gate.sh atomic       # Fast: tsc + eslint
bash validation-gate.sh checkpoint   # Medium: + tests
bash validation-gate.sh final        # Full: + build (optional)

# Recovery
node recovery.js --task-id=X --error='{"type":"...","message":"..."}'

# Conditional Hook (called by hooks automatically)
node conditional-hook.js validate-ts
node conditional-hook.js checkpoint
node conditional-hook.js final-validation

Execution Loop

FOR EACH atomic task WHERE status !== 'completed':
  1. Mark task as 'in_progress' (TodoWrite)
  2. Execute task (write code, modify files)
     → Write hook triggers: validate-ts
  3. Validate explicitly: validation-gate.sh atomic
  4. If validation fails: call recovery.js
  5. Mark task as 'completed' (TodoWrite)
     → TodoWrite hook triggers: checkpoint (automatic)
  6. Continue to next task

WHEN all tasks done:
  7. Final validation: validation-gate.sh final
  8. Create final checkpoint
  9. Generate report
  10. Mark task as COMPLETED

Success Criteria

A long task is successfully completed when:

1. ✅ All atomic tasks status = 'completed'
2. ✅ Final validation passes (TypeScript + ESLint + Tests)
3. ✅ Final checkpoint created
4. ✅ Execution report generated
5. ✅ Zero blockers or unresolved errors

Iron Laws

1. NEVER skip task decomposition - Long task WITHOUT atomic tasks = BLOCKED
2. NEVER continue on validation failure - Failed validation = STOP + RECOVER
3. NEVER exceed maxTime (10min) - If task takes longer = something is wrong, STOP
4. ALWAYS checkpoint after completed task - No exceptions
5. ALWAYS use state machine - Invalid transitions = ERROR
6. ALWAYS log structured - Every event, every decision (JSON format)
7. NEVER lose context - Checkpoints carry FULL context
8. ALWAYS self-heal - Try recovery before escalating to human

Performance Targets

• Validation per task: < 5 seconds (npx tsc --noEmit)
• Checkpoint creation: < 1 second
• Recovery decision: < 30 seconds
• Total overhead: < 5% of execution time

Use npx tsc --noEmit instead of npm run build for validation (90% faster).