ar4mirez/auto

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:

1. Starts with fresh context (no conversation history dependency)
2. Reads project state from files (prd.json, progress.md, CLAUDE.md)
3. Selects and implements one task
4. Commits changes and updates state
5. 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

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

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

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

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

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

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

---

Error Recovery

When the AI agent encounters errors:

1. Within iteration: Try to fix within the current iteration
2. Mark as blocked: If unfixable, set status to "blocked" with description
3. Document in progress.md: Append error details as LEARNING entry
4. 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.