┌─────────────────────────────────────────────────────────────┐
│                    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:

Proactive Scanning - Find relevant context before asking questions
Extensive Interview - Ask MANY questions via AskUserQuestion tool
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).

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.
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:

Confirm the PRD - Present a summary of what will be done
Verify git state - Is the repo clean? Is the branch created?

Explain the command:

python claudius_runner.py <max_iterations>

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:

Signal	Meaning	Runner Action
`<iteration_complete>`	Single task done, more tasks remain	Kill process, start next iteration
`<workflow_complete>`	All tasks done, PRD complete	Kill process, exit loop successfully

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

Files Reference

File	Purpose
`scripts/claudius_runner.py`	Main runner script
`templates/PRD_TEMPLATE.md`	Template for generating PRD
`templates/SYSTEM_PROMPT.md`	Template for system prompt
`references/cli-reference.md`	Claude CLI flags reference
`references/getting-started-with-ralph.md`	Original Ralph documentation
`references/tips-for-ai-coding-with-ralph-wiggum.md`	Advanced Ralph patterns

Quick Reference: Claude CLI Flags

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

Flag	Purpose
`-p`	Print mode - non-interactive output
`--dangerously-skip-permissions`	Auto-approve ALL actions
`--no-session-persistence`	Don't save session to disk
`--max-turns N`	Optional: limit agentic turns per iteration

Common Loop Types

Type	Use Case	Key Prompt Element
Feature PRD	Build features from requirements	Task checklist in PRD
Test Coverage	Increase coverage to target	Coverage report + threshold
Linting	Clean up code quality	`npm run lint` as feedback
Refactoring	Extract, restructure code	Specific refactor goals
Entropy	Find and fix code smells	"Scan for X, fix one per iteration"

claudius-maximus

Claudius Maximus

How It Works