Introduction

Wiggum is a CLI tool and MCP server that generates structured task files for autonomous AI coding loops. It codifies the Ralph Wiggum loop pattern — an orchestrator agent that drives subagents through a dependency-ordered task list until an entire project is implemented, hands-off.

What it does

Given a structured plan definition (TOML), Wiggum produces:

• Task files (tasks/T{NN}-{slug}.md) — Structured markdown specs with goals, dependencies, implementation guidance, test requirements, preflight commands, and exit criteria
• Progress tracker (PROGRESS.md) — A phase/task table with status tracking and learnings
• Orchestrator prompt (orchestrator.prompt.md) — The agent-mode prompt that drives the loop
• Implementation plan (IMPLEMENTATION_PLAN.md) — Architecture overview for subagent context
• Agents manifest (AGENTS.md) — Agent role definitions

Why it exists

Setting up an AI orchestration loop currently requires hand-authoring all of these artifacts. The structural and mechanical parts — numbering, dependency wiring, progress tables, preflight commands, orchestrator boilerplate — should be generated. The creative parts — what to build, architecture decisions, implementation details — come from the user.

Design principles

• Agent-agnostic — Wiggum generates artifacts, not agent invocations. Works with any AI coding tool that can read markdown.
• Scaffold, don’t execute — Wiggum produces plans and task files. Execution is someone else’s job.
• Language-aware — Ships with profiles for Rust, Go, TypeScript, Python, Java, C#, Kotlin, Swift, Ruby, and Elixir, providing sensible defaults for build, test, and lint commands.

Getting Started

This section covers installing Wiggum and creating your first plan.

Prerequisites

• Rust toolchain (1.85+) if building from source
• A project idea with a rough architecture in mind

Overview

The typical workflow:

1. Create a plan — Either interactively with wiggum init or by writing a plan.toml by hand
2. Generate artifacts — Run wiggum generate plan.toml to produce task files, progress tracker, and orchestrator prompt
3. Run the loop — Use your preferred AI coding tool with the generated orchestrator prompt to execute tasks sequentially

Continue to Installation to get Wiggum on your system, or jump to Quick Start if you already have it installed.

Installation

From crates.io

cargo install wiggum

From source

git clone https://github.com/greysquirr3l/wiggum.git
cd wiggum
cargo install --path .

Verify installation

wiggum --version

Quick Start

1. Create a plan interactively

wiggum init

This walks you through project setup — name, description, language, architecture style, phases, and tasks — and writes a plan.toml.

2. Or bootstrap from an existing project

If you already have a project directory, Wiggum can detect the language, build system, and structure to create a starter plan:

wiggum bootstrap /path/to/project

3. Validate the plan

wiggum validate plan.toml --lint

This checks that the dependency graph is a valid DAG and runs lint rules to catch common plan quality issues.

4. Preview what will be generated

wiggum generate plan.toml --dry-run --estimate-tokens

5. Generate artifacts

wiggum generate plan.toml

This produces the task files, PROGRESS.md, IMPLEMENTATION_PLAN.md, and orchestrator.prompt.md in your project directory.

6. Run the loop

Open your AI coding tool, load the generated orchestrator.prompt.md as the agent prompt, and let it work through the tasks.

Plan Definition

Wiggum plans are defined in TOML files. A plan describes your project metadata, phases, tasks, preflight commands, and orchestrator configuration.

Minimal example

[project]
name = "my-app"
description = "A web API for widget management"
language = "rust"
path = "/path/to/project"

[[phases]]
name = "Foundation"
order = 1

[[phases.tasks]]
slug = "project-setup"
title = "Initialize project structure"
goal = "Set up the repo with build tooling and CI"
depends_on = []

[[phases.tasks]]
slug = "domain-model"
title = "Define domain entities"
goal = "Create the core domain types and traits"
depends_on = ["project-setup"]

Sections

• Project Configuration — Project metadata and language settings
• Phases and Tasks — Organizing work into phases with dependency-ordered tasks
• Preflight and Orchestrator — Build/test/lint commands and orchestrator persona

Project Configuration

The [project] section defines your project metadata.

Fields

Example

[project]
name = "my-api"
description = "A REST API for managing inventory"
language = "rust"
path = "/home/user/projects/my-api"
architecture = "hexagonal"

Language

The language field determines which language profile is used for default build, test, and lint commands, as well as template hints like file patterns and documentation style.

Supported values: rust, go, typescript, python, java, csharp, kotlin, swift, ruby, elixir.

Architecture

The optional architecture field provides hints to the generated task files about how code should be organized. This influences implementation guidance in the generated artifacts.

Phases and Tasks

Work in a Wiggum plan is organized into phases, each containing one or more tasks. Tasks are dependency-ordered across the entire plan, forming a directed acyclic graph (DAG).

Phases

Phases are logical groupings. They appear in PROGRESS.md as section headers but don’t affect task ordering — dependencies do.

[[phases]]
name = "Foundation"
order = 1

[[phases]]
name = "Core Features"
order = 2

Tasks

Tasks are defined within their parent phase. Each task becomes a T{NN}-{slug}.md file.

[[phases.tasks]]
slug = "api-routes"
title = "Define API route handlers"
goal = "Implement REST endpoints for CRUD operations"
depends_on = ["domain-model", "database-adapter"]

Task fields

Task numbering

Tasks are numbered sequentially across all phases: T01, T02, T03, and so on. The ordering follows phase order first, then task order within each phase, but dependencies can cross phase boundaries.

Dependency graph

Wiggum validates that task dependencies form a valid DAG (no cycles). Use wiggum validate plan.toml to check before generating.

Preflight and Orchestrator

Preflight commands

The [preflight] section defines the commands that subagents run to verify their work. Language-specific defaults are provided automatically based on the project language, but you can override them.

[preflight]
build = "cargo build --workspace"
test = "cargo test --workspace"
lint = "cargo clippy --workspace -- -D warnings"

If omitted, Wiggum uses the defaults from the selected language profile.

Orchestrator configuration

The [orchestrator] section configures the generated orchestrator prompt.

[orchestrator]
persona = "You are a senior Rust software engineer"
rules = [
    "Never log tokens at any log level",
    "Keep domain crate free of I/O dependencies",
    "Rust edition 2024, stable toolchain",
]

Fields

CLI Reference

wiggum init

Interactively create a new plan file.

wiggum init [--plan <path>]

wiggum generate

Generate all artifacts from a plan file.

wiggum generate <plan> [OPTIONS]

wiggum validate

Validate a plan file without generating artifacts.

wiggum validate <plan> [--lint]

wiggum add-task

Add a task to an existing plan file interactively.

wiggum add-task <plan>

wiggum bootstrap

Bootstrap a plan from an existing project directory. Detects language, build system, and project structure.

wiggum bootstrap [path] [OPTIONS]

wiggum serve

Start the MCP server for agent integration.

wiggum serve --mcp

wiggum report

Generate a post-execution report from PROGRESS.md.

wiggum report [OPTIONS]

wiggum watch

Watch PROGRESS.md for live progress updates.

wiggum watch [OPTIONS]

MCP Server

Wiggum can run as an MCP (Model Context Protocol) server, allowing AI agents to invoke Wiggum’s capabilities mid-session.

Starting the server

wiggum serve --mcp

This starts the MCP server using stdio transport.

Integration

To use Wiggum as an MCP server with your AI coding tool, add it to your MCP configuration. For example, in VS Code’s MCP settings:

{
  "servers": {
    "wiggum": {
      "command": "wiggum",
      "args": ["serve", "--mcp"]
    }
  }
}

This enables agents to generate plans and task scaffolds directly within a coding session, without leaving the editor.

The Ralph Wiggum Loop

The Ralph Wiggum loop is an orchestration pattern for autonomous AI coding. An orchestrator agent drives subagents through a dependency-ordered task list until an entire project is implemented.

How it works

1. The orchestrator reads PROGRESS.md to find the next incomplete task
2. It spawns a subagent with the corresponding task file as context
3. The subagent implements the task, runs preflight checks (build, test, lint), and commits
4. The orchestrator marks the task complete in PROGRESS.md and records any learnings
5. Repeat until all tasks are done

Why it works

• Bounded context — Each subagent only sees one task file, keeping the prompt focused and reducing hallucination
• Dependency ordering — Tasks are topologically sorted, so each subagent builds on verified prior work
• Preflight gates — Every task must pass build/test/lint before being marked complete
• Learnings accumulate — The progress tracker captures insights from each task, providing growing context

Origin

The pattern was proven on the Yakko project, a Rust Microsoft Teams TUI client where 13 tasks across 7 phases were executed sequentially by subagents in a single automated session.

Wiggum makes this pattern reproducible for any project by generating the required artifacts from a structured plan definition.

Language Profiles

Wiggum ships with built-in profiles for 10 programming languages. Each profile provides sensible defaults for build commands, test patterns, documentation style, and error handling conventions.

Supported languages

What profiles provide

Each language profile includes:

• Build success phrase — The expected output indicating a successful build (e.g., “Compiling” for Rust, “Build complete” for Go)
• Test file pattern — Where test files are typically found (e.g., tests/ for Rust, *_test.go for Go)
• Doc style — Documentation conventions (e.g., /// doc comments for Rust, GoDoc for Go)
• Error handling — Idiomatic error handling approach (e.g., Result<T, E> for Rust, error return values for Go)

These values are injected into generated task files and exit criteria templates, making the output idiomatic for the target language.

Overriding defaults

You can override the default preflight commands in your plan’s [preflight] section. The language profile defaults are used only when no explicit override is provided.

Generated Artifacts

When you run wiggum generate, the following artifacts are produced in your project directory.

Task files — tasks/T{NN}-{slug}.md

Each task becomes a numbered markdown file with a consistent structure:

• Goal — What the task accomplishes
• Dependencies — Which tasks must be complete first
• Project Context — Where this fits in the architecture
• Implementation — Guidance, file paths, type signatures, code snippets
• Tests — What to test and where
• Preflight — Commands to run before marking complete
• Exit Criteria — Verifiable conditions for completion

Progress tracker — PROGRESS.md

A markdown table tracking all phases and tasks with status columns:

Includes a learnings column where the orchestrator records insights from each completed task.

Implementation plan — IMPLEMENTATION_PLAN.md

A high-level architecture document derived from your plan’s project description and phase structure. Subagents reference this for context about how their task fits into the overall project.

Orchestrator prompt — orchestrator.prompt.md

The agent-mode prompt that drives the Ralph Wiggum loop. It tells the orchestrator how to read progress, spawn subagents, verify their output, and update the tracker.

Agents manifest — AGENTS.md

Defines agent roles and capabilities. Can be skipped with --skip-agents-md.

Parallel groups

If tasks have no mutual dependencies, Wiggum identifies them as parallelizable and notes this in the generated progress tracker.

Contributing

Contributions to Wiggum are welcome.

Building from source

git clone https://github.com/greysquirr3l/wiggum.git
cd wiggum
cargo build

Running tests

cargo test --workspace

Linting

cargo clippy --workspace -- -D warnings
cargo fmt -- --check

Code style

• Rust edition 2024, MSRV 1.85
• Strict clippy: pedantic, nursery, cargo, and perf lints as warnings
• unwrap(), expect(), panic!(), and indexing with [] are denied — use Result and .get() instead
• Dual licensed under MIT and Apache-2.0

Project structure

src/
├── adapters/    # CLI, filesystem, VCS, MCP server
├── domain/      # Plan model, DAG validation, language profiles, linting
├── generation/  # Template rendering, task/progress generation
├── error.rs     # Error types
├── ports.rs     # Port traits (hexagonal architecture)
├── lib.rs       # Library root
└── main.rs      # CLI entry point

Architecture

Wiggum follows a hexagonal (ports and adapters) architecture.

Layers

Domain (src/domain/)

Pure business logic with no I/O dependencies:

• Plan model — The Plan struct parsed from TOML, with phases, tasks, and project metadata
• DAG validation — Topological sort and cycle detection on the task dependency graph
• Language profiles — Built-in profiles for 10 programming languages
• Lint rules — Plan quality checks (e.g., missing descriptions, unreachable tasks)

Ports (src/ports.rs)

Trait definitions for I/O boundaries:

• PlanReader — Reading plan files from the filesystem

Adapters (src/adapters/)

Concrete implementations of ports and external integrations:

• CLI — Clap-based command definitions
• Filesystem — File reading/writing
• VCS — Git integration for reports
• MCP — Model Context Protocol server (stdio transport)
• Init — Interactive plan creation
• Bootstrap — Project detection and plan generation

Generation (src/generation/)

Template-based artifact rendering:

• Task files — Tera templates producing T{NN}-{slug}.md files
• Progress tracker — PROGRESS.md generation with parallel group annotations
• Orchestrator prompt — Agent-mode prompt rendering
• Implementation plan — Architecture overview generation
• Token estimation — Approximate token counts for generated content

Data flow

Plan TOML → Parse → Validate DAG → Generate artifacts
                                      ├── PROGRESS.md
                                      ├── orchestrator.prompt.md
                                      ├── IMPLEMENTATION_PLAN.md
                                      ├── AGENTS.md
                                      └── tasks/T{NN}-{slug}.md