An Agent Skill that turns a rough request into working software.

wgm is a portable Agent Skill any compatible coding agent (GitHub Copilot, Claude Code, OpenAI Codex, VS Code agent mode) can load. Point it at a half-formed idea and it runs a disciplined lifecycle:

Triage → Grill → Plan → Preflight → Loop(Analyze → Implement → Validate → Review → Record) → Ship/Handoff

It fuses two proven ideas:

• Grill — interview you relentlessly, one question at a time, until the plan is unambiguous (after grill-me).
• Ralph loop — one task per iteration, a persistent plan as shared state, steered by a deterministic pass/fail signal (after the Ralph playbook).

The result is an agent that aligns first, plans on disk, and then builds in small, test-validated steps instead of one hopeful mega-edit.

A skill is just a folder containing SKILL.md. Install it once for your user (global — the default) or per project, on Linux, macOS, Windows, or WSL.

# Linux / macOS / WSL
curl -fsSL https://raw.githubusercontent.com/agent-frontier/wgm/main/scripts/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/agent-frontier/wgm/main/scripts/install.ps1 | iex

Both default to a user-level install into the cross-client ~/.agents/skills/wgm, plus any client dirs they detect (~/.claude, ~/.copilot). The piped script self-fetches the repo (so it must be public); it installs main by default — pin a branch, tag, or latest (the newest published release) with WGM_REF / --ref, where a tag or latest installs the validated release tarball. For all flags, clone the repo and run the script.

git clone https://github.com/agent-frontier/wgm && cd wgm
./scripts/install.sh                 # user-level, auto-detect clients (default)
./scripts/install.sh --project       # into ./.agents/skills (+ ./.claude)
./scripts/install.sh --client all    # agents + claude + copilot
./scripts/install.sh --dry-run       # preview; change nothing
./scripts/install.sh --uninstall     # remove it again

pwsh scripts/install.ps1 -Client all
powershell -File scripts\install.ps1 -Project
pwsh scripts/install.ps1 -Uninstall

WSL ⇄ Windows: inside WSL the installer also mirrors into your Windows home so Windows-side agents see wgm (skip with --no-windows); on Windows with WSL present, install.ps1 hands off to the bash installer in WSL (-NoWsl to install natively). Re-run to update an existing install.

Then confirm it's discoverable in your agent (e.g. /skills) and invoke /wgm. To install by hand, just copy the wgm/ folder into any skills dir your client scans.

If it does not appear right away, restart or reload your agent client; many clients rescan skills on startup or workspace reload.

Invoke as a slash command with an optional mode and a request:

/wgm <request>           # full lifecycle on the request
/wgm <mode> [only] ...   # scope to a phase

Modes: grill, analyze, plan, build (alias loop), review. A trailing only runs that single phase and stops; without only, a mode starts at that phase and continues forward. A leading word counts as a mode only if it's a known keyword followed by only, :, or end of input — so /wgm build the auth module is treated as a request, not build mode.

Your first run, end to end — /wgm add a dark-mode toggle:

1. Grill — wgm asks one focused question at a time (e.g. "persist the choice in localStorage — good?"), each with a recommended answer, so you can often just reply "yes."
2. Plan — it writes specs/, blind holdout scenarios/, and an IMPLEMENTATION_PLAN.md to disk, then self-checks them for gaps before writing any code.
3. Build — it advances one task per iteration, running your checks after each, until the plan is done and an LLM judge is satisfied — then hands back a clean, buildable repo.

wgm keeps durable state on disk so any fresh agent can resume:

• specs/* — what to build and why (incl. the "magic moment" and smallest end-to-end slice)
• IMPLEMENTATION_PLAN.md — the prioritized task list (the loop's memory)
• AGENTS.md — a lean "how to build & validate" guide
• docs/audit/* — the docs-audit paper trail (committed, never gitignored by default — see Capabilities)

Safety: wgm never overwrites an existing AGENTS.md. If your repo already has any of these files, it writes its own under .wgm/ instead (.wgm/IMPLEMENTATION_PLAN.md, .wgm/specs/, .wgm/AGENTS.md). Greenfield repos use the root directly.

wgm fuses grilling + the Ralph loop with holdout-scenario judging (after octopusgarden), so a build converges on genuinely correct software instead of teaching to the test.

flowchart LR
  G[Grill] --> P[Plan plus consistency check]
  P --> F{Preflight ready?}
  F -- no --> G
  F -- yes --> A
  subgraph Loop
    direction LR
    A[Analyze] --> I[Implement] --> V[Validate and judge] --> R[Review] --> Rec[Record]
  end
  V -- score below target --> W[Wonder, Reflect, escalate]
  W --> A
  Rec -- target met and checks green --> S[Ship]

• Holdout scenarios — YAML user-journeys graded blind; the implement step never reads them (Plan writes them; Validate/Review judge against them) (references/scenarios.md).
• Satisfaction scoring — an LLM judge scores 0–100; converge to a threshold (default 95) (references/scoring.md).
• Preflight — a readiness gate (≥ 80) before any code is written.
• Scale-adaptive tracks — Triage right-sizes the ceremony to the work: Quick (small fix → inline check, skip holdout scenarios + Preflight), Standard (the default — the full lifecycle), or Full (large / greenfield / high-risk → adds holdout scenarios, stratified scoring, and containerized validation) (SKILL.md).
• Constitution — project-wide principles (quality, testing, security) every spec and task is checked against at the Plan gate (assets/constitution.template.md).
• Consistency gate + no-placeholder rigor — before any code, a cross-artifact check (specs ↔ plan ↔ scenarios ↔ constitution) catches contradictions and requirement↔task gaps, and every task must name exact files and a runnable validation command.
• Stratified validation — converge tier 1 → 2 → 3 so easy passes can't hide hard failures.
• Wonder / reflect + model escalation — structured stall recovery; start frugal, escalate on a stall (references/stall-recovery.md).
• Standing loop guardrails — search-before-implement (no duplicate work) and document-why-each-test (no orphan deletions) on every iteration (references/ralph-loop.md).
• Memories — a token-budgeted .wgm/memories.md recalled in Analyze and appended in Record, so fresh-context iterations don't relearn the same gotchas, stalls, or dead ends (assets/memories.template.md).
• Context rotation — when the window fills, summarize progress into the plan + memories and rotate to fresh context rather than grinding on a degraded one (references/ralph-loop.md).
• Two-stage subagent review (the role swarm) — twelve role-specialized agents in total (griller · implementer · spec + quality reviewers · validator · diagnostician · the five-role docs-audit swarm · wgm-hermes, the hive courier); the two code reviewers run independently and preserve dissent — a minority concern is recorded, never collapsed into a silent PASS (references/subagents.md).
• Docs-audit paper trail — a mandatory, automatic audit of documentation quality (not just structure) from four vantage points — junior dev, senior dev, principal dev, PM — consolidated by a technical-writer role into one committed report per run. Every action item is labeled strictly Agent action or Operator action (never by persona), and the report is indexed the same way this README indexes its own docs. No need to ask for it — it runs automatically at Ship/Handoff (references/docs-audit.md).
• Trigger eval — a hand-curated should/should-not-trigger fixture that catches drift in SKILL.md's mode-parsing rule and the "Use this when"/"Do NOT use this when" boundary (references/trigger-eval.md).
• Output-quality evals — given wgm does trigger, is the result actually good? A structured evals/evals.json fixture (prompt + expected output + assertions), schema-checked by scripts/check-evals.sh, graded by a maintainer or scripts/grade-evals.sh (an opt-in, real grader-agent + non-regression gate — see references/evals.md).
• EARS acceptance criteria — Easy Approach to Requirements Syntax: phrase each criterion in a testable trigger/state/response shape (e.g. "When X, the system shall Y") so a check or judge can settle it (references/artifacts.md).
• Domain glossary — an optional specs/CONTEXT.md of canonical names keeps naming consistent across fresh-context iterations (assets/context.template.md).
• Token economy — human-facing artifacts stay readable, while agent-only state may use single-token keys (TOON, a compact serialization for agent-only files) to shrink what the agent must reread each iteration (references/artifacts.md).
• Self-improvement flywheel (the Hive Growth Loop) — at handoff, harvest a durable, sanitized, always-anonymized lesson from every source (this build's memories, consolidated swarm-stream memories, this project's own GitHub Issues, cross-pollinated external research) and, once a project consents once via a committed .github/wgm-hive.yml, report it upstream automatically — no further per-run asking — so wgm grows from every codebase (references/self-improvement.md).
• Gene transfusion — seed the build from an exemplar codebase (references/gene-transfusion.md).
• OCI validation — run scenarios against the app in a Podman-first (Docker-fallback) container (references/validation-env.md).
• Local devcontainer sandbox — run the loop itself isolated in a disk-conscious local devcontainer (one shared image across every project, never a per-project build) via loop.sh --devcontainer (references/devcontainers.md).

Full design docs live in docs/, split by operator and agent concerns.

In a single agent session, context accumulates — the opposite of what makes Ralph strong. For large or ambiguous builds, run the loop with a genuinely fresh context per iteration using the bundled adapter. It's host-agnostic: you tell it how to invoke your agent.

# Tell it how to run your agent — either a shell-evaluated command…
export WGM_AGENT='claude --dangerously-skip-permissions -p'   # prompt appended as last arg
./scripts/loop.sh plan --request "build a small CLI todo app"  # one planning pass
./scripts/loop.sh build 20            # up to 20 build iterations, fresh context each time
./scripts/loop.sh build 20 --threshold 95 --stratified --container podman
export WGM_FRUGAL_AGENT='claude -p'   # cheap model; escalates to $WGM_AGENT on a stall
./scripts/loop.sh extract --source ../exemplar  # gene transfusion from an exemplar repo
./scripts/loop.sh build only          # exactly one iteration
./scripts/loop.sh build --dry-run     # preview the prompt/command; run nothing
./scripts/loop.sh build --devcontainer  # run the whole loop sandboxed (one shared image; see below)
# …or pass the agent argv after `--` (invoked without eval — safest):
./scripts/loop.sh build -- claude -p

Worktree swarm (parallel git worktrees): scripts/swarm.sh fans the loop out across several branches at once — one stream per task (--tasks FILE) or N identical streams (-n N), each on its own wgm/swarm/N branch to merge back. (Parallelism across tasks — distinct from the role swarm of subagents in Capabilities above.) See docs/operator/running-the-loop.md.

• Modes match the skill: grill | analyze | plan | preflight | build | review | extract (plus only for a single pass).
• build/review refuse to run without an IMPLEMENTATION_PLAN.md.
• No automatic commits or pushes unless you pass --commit — but the agent does edit files during a normal (non-dry) run.
• In build mode the agent is told to drop a STOP sentinel when no must-have task remains, so the loop self-terminates. Stop anytime with Ctrl+C or by creating STOP / .wgm/STOP. See ./scripts/loop.sh --help.
• Guard long autonomous runs with --max-runtime-seconds, --idle-timeout, --checkpoint-interval (auto-commit), --max-cost (stop once cumulative spend from --cost-cmd hits a ceiling), and a --notify "CMD" lifecycle hook.
• Survive transient failures: the loop retries a failed agent call with exponential backoff + jitter (--max-retries) and trips a circuit breaker after N consecutive failures (--max-consecutive-failures) instead of dying on the first hiccup.
• Measure the run: --metrics FILE logs a per-iteration TSV (duration, progress, result), with a pluggable --cost-cmd for token/cost — for data-driven runs.
• Sandbox the loop itself: --devcontainer re-execs the whole invocation inside a disk-conscious local devcontainer via scripts/devcontainer.sh — one shared, prebuilt image reused across every project (never a per-project build). See docs/operator/devcontainers.md.
• Works from any project: the loop ships with the installed skill and acts on your current directory — run ~/.agents/skills/wgm/scripts/loop.sh (or your install path) from your project's root. The ./scripts/loop.sh examples above assume you're inside this repo.

Run the loop only in an environment you're comfortable letting an agent operate in autonomously (a sandbox or disposable workspace). Autonomous loops bypass per-step approvals by design.

wgm/
├── SKILL.md          # the protocol the agent follows
├── README.md         # this file
├── references/       # grilling · ralph-loop · memory-patterns · subagents · artifacts · scenarios · scoring · stall-recovery · hard-to-test-domains · gene-transfusion · validation-env · devcontainers · self-improvement · issue-intake · heuristics · docs-audit · adr · trigger-eval · evals · local-models · PLUGIN_PROTOCOL · plugin-integration
├── assets/           # spec · scenario · IMPLEMENTATION_PLAN · AGENTS · constitution · context · memories · genes · docs-audit-report · adr · morning-report · sprint-status · evals · plugin-template · wgm.example.yml · wgm-hive.template.yml · state.toon · devcontainer/ templates
├── scripts/          # loop.sh (Ralph loop) · swarm.sh (parallel worktrees) · harvest-hive.sh (hive courier) · devcontainer.sh (local sandbox) · install.sh · install.ps1
├── .github/agents/   # the twelve role-specialized subagents (the swarm), incl. the docs-audit swarm + wgm-hermes
└── docs/             # operator/ · agent/ · plans/ · audit/ guides (Mermaid diagrams)

• CONTRIBUTING.md — How to contribute, development prerequisites, and the backpressure suite.
• CODE_OF_CONDUCT.md — Our community standards and enforcement.
• SECURITY.md — How to report security vulnerabilities and our safety model.
• Heuristic / learning report — Share a sanitized trace so wgm can improve its heuristics and docs, including our own dogfood runs.

• main is the canonical release line.
• The SKILL.md frontmatter version is the public skill version; a release tag must match it exactly, prefixed with v (version 0.3 → tag v0.3).
• To cut a release: push the matching tag — git tag v0.3 && git push origin v0.3. .github/workflows/release.yml then verifies the tag against SKILL.md, re-runs shellcheck + skills-ref + the docs check, packages wgm-v0.3.tar.gz (plus a stable-named wgm.tar.gz for …/releases/latest/download), and publishes a GitHub release with auto-generated notes.
• Pin installs with WGM_REF / --ref when you want a specific release or commit instead of the moving main branch — e.g. WGM_REF=latest for the newest release, or WGM_REF=v0.3 for a specific one. A tag or latest fetches the published release tarball; any other ref uses the codeload source archive.
• CI validates every push and pull request before release promotion.

Inspired by Matt Pocock's grill-me and Geoffrey Huntley's Ralph methodology as distilled in how-to-ralph-wiggum. Licensed under MIT — see LICENSE.