Autonomous Task Runner Skill

Description

This skill implements a dual-agent autonomous execution pattern for long-running tasks. A coordinator agent tracks progress and dispatches work, while worker agents execute individual steps. State is persisted to disk so work can continue seamlessly across interrupted sessions.

Instructions

When the user asks you to run a task autonomously, follow this pattern:

State File Structure

Create .claude/autonomous-state.json to track progress:

Copy
{
  "taskId": "migrate-to-esm-20250325",
  "description": "Migrate all CommonJS modules to ESM",
  "status": "in-progress",
  "startedAt": "2025-03-25T10:00:00Z",
  "lastUpdatedAt": "2025-03-25T10:15:00Z",
  "totalSteps": 12,
  "completedSteps": 5,
  "steps": [
    { "id": 1, "name": "Audit require() calls", "status": "done", "output": "Found 47 files" },
    { "id": 2, "name": "Update package.json type", "status": "done" },
    { "id": 3, "name": "Convert src/utils/", "status": "done", "filesModified": 8 },
    { "id": 4, "name": "Convert src/services/", "status": "done", "filesModified": 12 },
    { "id": 5, "name": "Convert src/routes/", "status": "done", "filesModified": 6 },
    { "id": 6, "name": "Convert src/middleware/", "status": "pending" },
    { "id": 7, "name": "Update test imports", "status": "pending" },
    { "id": 8, "name": "Fix circular dependencies", "status": "pending" },
    { "id": 9, "name": "Update build config", "status": "pending" },
    { "id": 10, "name": "Run test suite", "status": "pending" },
    { "id": 11, "name": "Fix failing tests", "status": "pending" },
    { "id": 12, "name": "Final verification", "status": "pending" }
  ],
  "errors": [],
  "checkpoints": [
    { "stepId": 5, "commitHash": "abc123", "message": "ESM conversion: routes complete" }
  ]
}

Coordinator Agent Behavior

1. Check for existing state file at session start
2. If found, read it and resume from the last incomplete step
3. If not found, create a new execution plan
4. After each step:
   • Update state file
   • Create a git commit checkpoint (every 3-5 steps)
   • Verify the project still builds/passes tests
5. If a step fails:
   • Log the error in state
   • Attempt a fix (max 2 retries)
   • If still failing, mark as blocked and continue to next independent step

Session Continuation

When starting a new session:

Reading autonomous state... Found task: "Migrate all CommonJS modules to ESM"
Progress: 5/12 steps complete (42%)
Last activity: 2025-03-25T10:15:00Z
Resuming from step 6: "Convert src/middleware/"

Rules

• ALWAYS persist state to .claude/autonomous-state.json after every step
• Create git checkpoint commits regularly (every 3-5 completed steps)
• If tests fail after a step, fix before proceeding
• Maximum 2 retry attempts per failed step before marking as blocked
• Never skip verification steps (build, lint, test)
• If the user interrupts, save state immediately so next session can resume
• Clean up the state file when the task completes successfully
• Log all errors with enough context to debug later

Examples

User: Autonomously migrate our codebase to TypeScript strict mode Action: Create step plan (audit, configure, fix each directory, verify), execute with checkpoints

User: Continue the migration Action: Read state file, report progress, resume from last incomplete step

User: What's the status of the autonomous task? Action: Read state file, report completion percentage, blocked items, and next steps