Leo Wiggum v2 - Autonomous AI Coding Loop

Phased, skill-aware autonomous coding loop with browser validation, structured memory, and quality ratcheting. Works on any project or from scratch.

How It Works

1. Phase 0 — Discovery/Scaffold: Analyze codebase or scaffold a new project
2. Phase 1 — Foundation: Core infrastructure stories (schema, auth, config)
3. Phase 2 — Features: Story-based implementation with dependency ordering
4. Phase 3 — Polish & Validation: Integration validation, browser smoke tests, cleanup
5. Each iteration agent receives skill assignments and structured memory from previous iterations
6. Memory persists via .leo/ directory (prd.json, memory.json, quality-metrics.json, screenshots)

Usage

Parse from user input:

• prompt (required): Feature or project description
• --max-iterations N: Max iterations (default: 15)
• --branch name: Git branch (default: leo/<feature-slug>)
• --greenfield: Force greenfield scaffolding mode
• --headed: Run browser validation in headed mode (visible)

Step 1: Discovery / Scaffold

Existing Project

1. Read CLAUDE.md if exists
2. Detect tech stack by checking: package.json, Cargo.toml, pyproject.toml, go.mod, requirements.txt, Makefile, etc.
3. Explore code structure with Glob/Grep to understand patterns
4. Identify and populate techStack in PRD:
   • language, framework
   • buildCmd, testCmd, lintCmd, typecheckCmd
   • devServerCmd, devServerUrl
5. Run baseline quality check (typecheck, tests, lint) and record in quality-metrics.json

Greenfield (--greenfield flag or no recognizable project files)

1. Infer desired stack from the user's prompt (or ask if unclear)
2. Generate scaffold story as first Phase 1 story (US-000: Initialize project scaffold)
3. ALL other stories dependsOn: ["US-000"]
4. Set techStack with expected commands for the chosen framework
5. Quality baseline is captured AFTER the scaffold story passes

Step 2: Generate Phased User Stories

Break the feature/project into stories organized by phase. Each story must be completable in ONE iteration.

Skill Assignment

Assign 1-3 skills per story based on its content:

Skill	When to Assign
code	Always — general implementation
database	Schema changes, migrations, seed data
api	API endpoint creation or modification
ui	Frontend component work
browser	Story has visual output to validate
test	Test-focused or test-heavy stories

Right-Sized Stories

• Add database model + migration
• Add single UI component or page
• Create one API endpoint
• Add form with validation
• Write tests for one module

Too Big (must split)

• "Build entire dashboard" -> split into individual pages/components
• "Add authentication" -> split into model, API, UI, tests
• "Refactor API" -> split by domain/router

Dependency Graph

• Stories declare dependsOn: ["US-XXX"] for explicit ordering
• The iteration loop only picks stories whose dependencies are all passed
• Avoid circular dependencies

Browser Validation

For UI stories, add validation.type: "browser" with steps:

{
  "validation": {
    "type": "browser",
    "browserSteps": [
      { "action": "open", "target": "http://localhost:3000/page" },
      { "action": "wait", "target": "--text 'Expected Text'" },
      { "action": "snapshot", "expect": "description of what should be visible" },
      { "action": "screenshot", "path": ".leo/screenshots/US-XXX.png" }
    ]
  }
}

Step 3: Create .leo/ Directory

Initialize the following files in .leo/:

.leo/prd.json

{
  "version": 2,
  "project": "<project name>",
  "branchName": "leo/<feature-slug>",
  "description": "<feature/project description>",
  "techStack": {
    "language": "<detected>",
    "framework": "<detected>",
    "buildCmd": "<detected or null>",
    "testCmd": "<detected or null>",
    "lintCmd": "<detected or null>",
    "typecheckCmd": "<detected or null>",
    "devServerCmd": "<detected or null>",
    "devServerUrl": "<detected or null>"
  },
  "phases": [
    { "id": "phase-0", "name": "Discovery", "type": "discovery", "status": "complete" },
    { "id": "phase-1", "name": "Foundation", "status": "pending" },
    { "id": "phase-2", "name": "Features", "status": "pending" },
    { "id": "phase-3", "name": "Polish", "status": "pending" }
  ],
  "stories": [
    {
      "id": "US-001",
      "title": "<title>",
      "description": "As a <user>, I want <goal>, so that <benefit>",
      "phase": "phase-1",
      "priority": 1,
      "skills": ["code", "database"],
      "dependsOn": [],
      "status": "pending",
      "failureCount": 0,
      "maxRetries": 3,
      "acceptanceCriteria": [
        "<criterion 1>",
        "<criterion 2>"
      ],
      "validation": {
        "type": "none",
        "browserSteps": []
      },
      "notes": "",
      "lastFailure": null
    }
  ]
}

.leo/memory.json

{
  "patterns": [],
  "decisions": [],
  "failures": [],
  "environment": {}
}

.leo/quality-metrics.json

Run the project's quality commands and capture baseline:

{
  "baseline": {
    "typescriptErrors": 0,
    "testCount": 0,
    "testPassRate": 1.0,
    "lintErrors": 0,
    "buildSuccess": true
  },
  "snapshots": [],
  "ratchetRules": {
    "typescriptErrors": "no-increase",
    "testCount": "no-decrease",
    "testPassRate": "no-decrease",
    "lintErrors": "no-increase",
    "buildSuccess": "must-be-true"
  }
}

For greenfield projects, set all baseline values to 0/true (baseline captured after scaffold story).

Also create .leo/screenshots/ directory.

Step 4: Show Summary & Confirm

Display to the user:

• Phase breakdown with story counts per phase
• Dependency graph (which stories block which)
• Skill distribution across stories
• Quality baseline (if existing project)
• Branch name
• Max iterations
• Command that will run

Step 5: Start Loop

Ask user to confirm, then run:

${CLAUDE_PLUGIN_ROOT}/scripts/leo-wiggum.sh <max_iterations>

Pass --headed if user requested visible browser.

CRITICAL: After starting the script, END your response immediately. The script spawns NEW Claude Code sessions — your job is done.

Monitoring

• Terminal: phase/iteration progress, quality gate results
• .leo/prd.json: story statuses and failure info
• .leo/memory.json: structured learnings, patterns, decisions, failures
• .leo/quality-metrics.json: metric trends across iterations
• .leo/screenshots/: visual proof from browser validation
• git log: commits per story