Autonomous AI Coding Loop

Enable unattended AI-driven development using the Ralph Wiggum methodology.

Use When: Running AI agents autonomously, AFK development, batch task execution 4D Phase: Develop (autonomous execution of generated tasks)

Overview

The autonomous loop runs AI agents in a cycle, where each iteration:

• Starts with fresh context (no conversation history dependency)

• Reads project state from files (prd.json, progress.md, CLAUDE.md)

• Selects and implements one task

• Commits changes and updates state

• Documents learnings for future iterations

Continuity is maintained through persistent files, not conversation history.

Core Principles

1. Fresh Context Per Iteration

Each cycle begins with a clean AI context window. The AI agent reconstructs understanding from: git history, prd.json (task state), progress.md (learnings), and CLAUDE.md/AGENTS.md (project guardrails).

2. Right-Sized Decomposition

Tasks must be completable within a single context window. Break large features into focused, atomic steps. If a task is too big, split it before starting.

3. Feedback-Driven Quality

Automated checks (tests, linting, type checking) serve as guardrails:

• Quality checks must pass before committing

• Failed checks provide feedback for the next attempt

• Pre-commit hooks catch regressions

4. Knowledge Persistence

Learnings accumulate in progress.md across iterations:

• Architectural decisions

• Gotchas and edge cases

• Patterns discovered

• Error resolutions

5. Agent-Driven Prioritization

The AI agent chooses which task to work on based on:

• Priority level (critical > high > medium > low)

• Dependency resolution (prerequisites must be complete)

• Task ID ordering (lower IDs first when priority is equal)

Workflow

Option A: PRD-Based Setup (Planned Work)

1. Create PRD and task breakdown (existing Samuel workflow)

Use .claude/skills/create-prd/SKILL.md

Use .claude/skills/generate-tasks/SKILL.md

2. Initialize autonomous loop

samuel auto init --prd .claude/tasks/0001-prd-feature.md

3. Review generated files

cat .claude/auto/prd.json # Task list in JSON cat .claude/auto/prompt.md # Iteration prompt

Option B: Pilot Mode (Zero Setup)

Fully autonomous — no PRD or task files needed

samuel auto pilot

Customize iterations, focus, and discovery frequency

samuel auto pilot --iterations 20 --focus testing samuel auto pilot --discover-interval 3 --max-tasks 5

Dry run to preview without executing

samuel auto pilot --dry-run

Skip confirmation

samuel auto pilot --yes

Pilot mode automatically discovers improvement opportunities (test gaps, code quality issues, security concerns, documentation gaps) and generates atomic tasks, then implements them in alternating discovery/implementation iterations.

Running the Loop

Start the loop (will prompt for confirmation)

samuel auto start

Start with custom iteration count

samuel auto start --iterations 20

Skip confirmation

samuel auto start --yes

Dry run (see what would happen)

samuel auto start --dry-run

Monitoring

Check progress

samuel auto status

View recent learnings

tail -20 .claude/auto/progress.md

List all tasks

samuel auto task list

Manual Intervention

Mark a task as completed manually

samuel auto task complete 1.1

Skip a task

samuel auto task skip 2.3

Reset a task to pending

samuel auto task reset 1.1

Add a new task

samuel auto task add "3.0" "New parent task"

Per-Iteration Protocol

When operating in autonomous mode, follow these steps exactly:

Step 1: Read Context

1. Read CLAUDE.md (or AGENTS.md) for project guardrails
2. Read .claude/auto/progress.md for learnings from prior iterations
3. Read .claude/auto/prd.json to find tasks and current state

Step 2: Select Task

1. Find tasks with status "pending"
2. Filter out tasks whose depends_on items are not "completed" or "skipped"
3. Sort by priority: critical > high > medium > low
4. If priorities match, prefer lower task IDs
5. Select the top task

Step 3: Implement

1. Update task status to "in_progress" in prd.json
2. Follow project guardrails from CLAUDE.md
3. Write tests alongside code
4. Keep changes atomic -- one task per iteration
5. Respect file size limits (functions ≤50 lines, files ≤300 lines)

Step 4: Quality Check

1. Run all commands listed in prd.json config.quality_checks
2. All checks must pass before committing
3. If a check fails, fix the issue and retry
4. If unfixable, mark task as "blocked" and document why

Step 5: Commit

1. Stage only files related to this task
2. Use conventional commit format: type(scope): task ID - description
3. Example: feat(auth): task 1.1 - create user schema

Step 6: Update State

1. Set task status to "completed" in prd.json
2. Record commit SHA in task's commit_sha field
3. Record iteration number in task's iteration field
4. Update progress.completed_tasks count

Step 7: Document Learnings

Append to .claude/auto/progress.md: [timestamp] [iteration:N] [task:ID] COMPLETED: what was done [timestamp] [iteration:N] [task:ID] LEARNING: any insights or gotchas

prd.json Format

{ "version": "1.0", "project": { "name": "project-name", "description": "Project description", "source_prd": ".claude/tasks/0001-prd-feature.md", "created_at": "2026-02-11T10:00:00Z", "updated_at": "2026-02-11T12:00:00Z" }, "config": { "max_iterations": 50, "quality_checks": ["go test ./...", "go vet ./..."], "ai_tool": "claude", "ai_prompt_file": ".claude/auto/prompt.md", "sandbox": "none" }, "tasks": [ { "id": "1.0", "title": "Database Setup", "status": "completed", "priority": "critical", "complexity": "medium", "depends_on": [], "commit_sha": "abc1234", "iteration": 1 }, { "id": "1.1", "title": "Create user schema", "status": "pending", "priority": "high", "parent_id": "1.0", "depends_on": ["1.0"] } ], "progress": { "total_tasks": 10, "completed_tasks": 3, "status": "running" } }

Task Statuses

• pending: Not yet started (available for selection)

• in_progress: Currently being worked on

• completed: Successfully finished with commit

• skipped: Deliberately skipped (counts as "done" for dependencies)

• blocked: Cannot proceed (needs human intervention)

progress.md Format

Append-only log with structured entries:

[2026-02-11T10:30:00Z] [iteration:1] [task:1.0] STARTED: Database setup [2026-02-11T10:35:00Z] [iteration:1] [task:1.0] COMPLETED: Created schema [2026-02-11T10:35:00Z] [iteration:1] [task:1.0] LEARNING: Use explicit indexes [2026-02-11T10:36:00Z] [iteration:1] QUALITY_CHECK: go test ./... PASSED [2026-02-11T10:36:00Z] [iteration:1] COMMIT: abc1234 "feat(db): task 1.0" [2026-02-11T10:40:00Z] [iteration:2] [task:1.1] ERROR: FK constraint wrong

Entry types: STARTED, COMPLETED, ERROR, LEARNING, QUALITY_CHECK, COMMIT

Tips for Success

Start supervised, then go AFK: Run a few iterations manually to verify the prompt and quality checks work correctly. Then let it run unattended.

Prioritize risky tasks: Have the AI tackle architectural decisions and integration points first. Reserve human oversight for critical foundations.

Define quality level: Specify whether code is prototype, production, or library quality so the agent matches appropriate standards.

Take small steps: Break work into focused tasks. Each should produce one commit. Smaller tasks = better feedback loops.

Use quality gates: Tests, linting, and type checking catch regressions before they compound across iterations.

Review progress.md: The learnings journal accumulates valuable insights. Read it periodically to catch issues early.

Error Recovery

When the AI agent encounters errors:

• Within iteration: Try to fix within the current iteration

• Mark as blocked: If unfixable, set status to "blocked" with description

• Document in progress.md: Append error details as LEARNING entry

• Fresh context helps: The next iteration starts clean and may succeed where the previous one got stuck

When the loop itself fails:

samuel auto status # Check what happened samuel auto task list # See task states samuel auto task reset 1.1 # Reset a stuck task samuel auto start # Resume the loop

Integration with 4D Methodology

The auto loop extends the existing COMPLEX mode workflow:

Standard COMPLEX Mode: create-prd → generate-tasks → manual implementation (HITL)

With Auto Loop (PRD-based): create-prd → generate-tasks → samuel auto init → samuel auto start (autonomous)

With Pilot Mode (zero setup): samuel auto pilot (discovers and implements autonomously)

The human can re-enter the loop at any point by stopping the process and returning to manual task-by-task implementation.