Claudius Maximus

Set up autonomous Claude Code loops based on the Ralph Wiggum pattern - running Claude repeatedly with no memory between sessions until all tasks are complete.

How It Works

┌─────────────────────────────────────────────────────────────┐
│                    Claudius Loop                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   Iteration N:                                              │
│   ├─ Claude starts fresh (no memory)                        │
│   ├─ Reads PRD.md (requirements + tasks)                    │
│   ├─ Reads progress.txt (what's done)                       │
│   ├─ Picks next incomplete task                             │
│   ├─ Implements task                                        │
│   ├─ Runs verification (tests, lint, etc)                   │
│   ├─ Updates progress.txt                                   │
│   ├─ Commits + Pushes                                       │
│   ├─ Outputs: <iteration_complete>                          │
│   └─ Runner kills process                                   │
│       ↓                                                     │
│   Iteration N+1: (fresh session)                            │
│   └─ Repeat until <workflow_complete>                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Key insight: Each iteration runs in a fresh Claude session. Progress is tracked externally in files. This eliminates context rot - Claude operates at peak intelligence every time.

When Invoked: Full Automation Workflow

When this skill is invoked, your goal is to fully automate setting up a Claudius loop in the user's project. This involves:

1. Proactive Scanning - Find relevant context before asking questions
2. Extensive Interview - Ask MANY questions via AskUserQuestion tool
3. Generate Artifacts - Create PRD.md, progress.txt, and customized runner

CRITICAL: Never be conservative with questions. Missing details leads to bad PRDs.

Phase 1: Proactive Scanning

Before interviewing the user, scan the project to understand context:

Agent Documentation

Look for existing agent guidance:

CLAUDE.md, GEMINI.md, AGENTS.md, AGENT.md, README.md
.claude/settings.json
docs/*.md, .docs/*.md

Extract: code standards, testing requirements, commit conventions, tech stack.

Existing Sub-Agents

Scan for existing sub-agents (these work in CLI via --agents flag):

.claude/agents/*.md
~/.claude/agents/*.md

For each agent found, extract from its YAML frontmatter:

• name - agent identifier
• description - what it does
• tools - allowed tools list
• model - which model to use
• The prompt (content after frontmatter)

Existing Skills

Scan for skills the agent could use:

.claude/skills/*/SKILL.md

NOTE: Skills may or may not be fully available in headless mode. As a backup, create a "skill shim" in the PRD that lists skills by name + path. Skills use progressive disclosure - don't bulk read, start with SKILL.md.

List each skill found with:

• Skill name
• Brief description (from SKILL.md frontmatter)
• Path to SKILL.md
• When it should be invoked

Build/Test Commands

Look for:

package.json (scripts section)
Makefile, Taskfile.yml
pyproject.toml, setup.py

Identify: test command, lint command, typecheck command, build command.

Existing PRD Files

Check if there's already a PRD:

PRD.md, prd.md, PLAN.md, TODO.md

Phase 2: Interview the User

ALWAYS use AskUserQuestion tool. Do NOT ask questions in plain text.

Ask questions in logical groups. Never skip a category.

Category 1: Project Context

• What is this project? (brief description)
• What tech stack is used?
• What are you trying to accomplish with this Claudius loop?
• Is this a new feature, refactor, test coverage, or something else?

Category 2: Task Breakdown

• What are the specific tasks that need to be done?
• Should I help break down a large task into smaller pieces?
• What order should tasks be completed in? (dependencies?)
• How would you describe "done" for each task?

Category 3: Constraints (Fail Conditions)

These are critical. Ask explicitly:

• What files/directories should the agent NOT modify?
• What actions are absolutely forbidden? Examples:
• Don't deploy to production
• Don't change database schema
• Don't add new dependencies
• Don't modify certain files
• Are there any external services the agent should NOT interact with?

Category 4: Pass Conditions

• What MUST be true for the entire workflow to be complete?
• What verification commands must pass? (tests, lint, typecheck)
• Is there a coverage threshold?
• Are there specific acceptance criteria?

Present discovered skills:

• "I found these skills: [list]. Which should be available to the loop agent?"
• "When should each skill be invoked?"

Category 6: Sub-Agents (if any found)

Sub-agents can be passed to Claude via the --agents CLI flag.

Present discovered agents:

• "I found these sub-agents: [list with descriptions]. Which should be included in the loop?"
• "For each selected agent, when should the loop agent invoke it?"

Explain that selected agents will be converted to JSON and passed via --agents flag.

Category 7: Git Workflow

• Should I create a new branch for this work? (Recommended: yes)
• What should the branch be named?
• Should commits be pushed after each task? (Recommended: yes)

Category 8: Iteration Limits

• How many iterations maximum? Recommendations:
• Small tasks: 5-10
• Medium features: 20-30
• Large complex work: 50-100
• Do you want max-turns per iteration? (safety limit on agentic actions)

Category 9: Quality Bar

• Is this production code or prototype?
• What level of test coverage is expected?
• Should the agent write tests for new code?
• Any specific coding standards to follow?

Phase 3: Generate Artifacts

After gathering all information, generate these files in the project directory:

1. PRD.md

Use the template from templates/PRD_TEMPLATE.md. Include:

• Project context
• Task checklist (with [ ] checkboxes)
• Constraints (hard boundaries)
• Pass conditions
• Verification commands
• Skill shim (if skills discovered)
• Git workflow notes

2. progress.txt

Create an empty progress file:

# Progress Log

3. Agents JSON (if agents selected)

Convert selected sub-agents to JSON for the --agents CLI flag:

From agent .md file:

---
name: code-reviewer
description: Reviews code for quality
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze code and provide feedback.

To JSON:

{
  "code-reviewer": {
    "description": "Reviews code for quality",
    "prompt": "You are a code reviewer. Analyze code and provide feedback.",
    "tools": ["Read", "Glob", "Grep"],
    "model": "sonnet"
  }
}

4. claudius_runner.py (customized)

CRITICAL: Do NOT generate this file from scratch. Output capture and signal handling are complex and fragile on different OSs (especially Windows).

1. COPY the script from scripts/claudius_runner.py in this skill folder to the user's project root.

• Use cp (Linux/Mac) or copy (Windows) or read_file + write_to_file.

1. MODIFY the SYSTEM_PROMPT constant in the copied file to include:

• Project-specific context
• Custom constraints
• Skill references

Phase 4: Confirm and Launch

Before the user runs the loop:

1. Confirm the PRD - Present a summary of what will be done
2. Verify git state - Is the repo clean? Is the branch created?
3. Explain the command:

   python claudius_runner.py <max_iterations>

1. Set expectations - Loops can take hours for complex work

Skill Shim Mechanism

Since user skills are NOT available in headless mode, include this in the PRD:

## Available Skills (Read When Needed)

> Skills use **progressive disclosure**. Don't bulk-read all files.
> Start with SKILL.md and branch out as needed.

| Skill Name | When to Use | Path |
|------------|-------------|------|
| my-skill | When doing X | `.claude/skills/my-skill/SKILL.md` |

The loop agent can then manually read skill files with the Read tool when relevant.

Signal Protocol

The runner script monitors Claude's output for these signals:

The agent MUST output exactly one of these after each task.

Files Reference

Quick Reference: Claude CLI Flags

claude -p "prompt" --dangerously-skip-permissions --no-session-persistence

Common Loop Types