wgm

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

wgm is a portable Agent Skill. It has been run end to end on GitHub Copilot CLI, and is contract-fit on the documented behavior of Claude Code, OpenAI Codex CLI, Gemini CLI, Cursor, and OpenCode — with Pi and Aider degrading in named ways. Which is which, and on what evidence, is recorded in compatibility/harnesses.json and explained in harness portability. 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.

Maintainers can inspect the repository and record local, evidence-backed memory without making a model call or reading credentials.

Prerequisites: Python 3.10+ and Git; no credentials or network access are required. Run the commands from the repository root:

python3 scripts/stage10_memory.py inspect --root .
python3 scripts/stage10_memory.py lint --root .
bash scripts/test-stage10-memory.sh

inspect writes .wgm/stage10/observations.jsonl and .wgm/stage10/brief.md and exits 0 on success. lint exits 0 for a current, valid brief and nonzero when records are malformed, suspicious, or stale. The canonical memory gate is bash scripts/test-stage10-memory.sh; inspect/lint are the real-checkout refresh and diagnostic commands. The brief is the human entry point; raw JSONL is the machine source. The brief is bounded to 120 lines and 16,000 bytes. If lint reports changed sources, rerun inspect; if the current harness is unknown, do not infer it from executable presence. The offline Stage 10 qualification, routing, experiment comparison, learned-policy comparison, and end-to-end gates are documented in docs/reference/stage10.md; the inspection allowlist is SAFE_ENV_KEYS in scripts/stage10_memory.py. Live execution, branch/worktree creation, PR creation, and policy activation remain explicit human-authorized boundaries.

Offline/fixture-only: the shipped Stage 10 harnesses do not silently call providers, create branches or PRs, merge, deploy, publish, or activate policy.

To record a validated lesson after a green check:

python3 scripts/stage10_memory.py record --kind lesson --standing validated --scope task \
  --summary 'The validation target is the cheapest backpressure.' \
  --source 'CONTRIBUTING.md:40' --evidence 'command:make validate'

Promotion is stricter: corroborated needs two independent evidence references, and promoted additionally needs a human-approved: evidence reference. Token-shaped values are refused; rewrite them as <redacted> before recording. For the current Stage 10 scope and artifact authority, read .wgm/IMPLEMENTATION_PLAN.md, .wgm/specs/CONTEXT.md, and .wgm/stage10/brief.md after inspect. These are local dogfood artifacts and are intentionally not part of the shipped template tree.

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. This also installs the three companion skills, teach-me, quiz-me, and rugged (opt out with --no-companions).

New to wgm? Get started walks install through a first validated build in eight steps.

# 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. grill, analyze, plan, and review are single-phase entry points and always stop at their phase gate; a trailing only is accepted for emphasis and is redundant for them. build resumes the loop and may continue across iterations unless capped. 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 can build software faster than its operator can understand it. You take delivery of a working repo and own code you cannot explain. Three companion skills close that gap and stress-test the result — they install alongside wgm automatically (opt out with --no-companions / -NoCompanions) and work on any repo, not just one wgm built.

teach-me and quiz-me are deliberately a pair: teach-me produces the feeling of understanding; only quiz-me tells you whether it was real. Two rules make the score mean something:

• Cite or don't claim — every statement teach-me makes about your repo carries a path:line citation, and it runs the build rather than repeating what the README claims. No citation, no claim.
• Holdout questions — quiz-me draws from what the tour did not literally show you, the same anti-gaming discipline as wgm's holdout scenarios. It also reports anything you were confidently wrong about separately from "I don't know" — the first is a future incident, the second is just a gap.

rugged is a different kind of companion: it never edits anything, and it judges robustness, not comprehension. wgm invokes it at Plan-exit and Review as a required gate, with an inline fallback when the companion is unavailable. See Companion skills for its full lifecycle and the development-practice metaphor its name comes from.

Artifacts land in .wgm/learning/ (teach-me/quiz-me) and .wgm/rugged/ (rugged), so a later session resumes instead of re-surveying. None of the three modify your code — except teach-me's one first-change exercise, which is reverted by default.

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 lifecycle 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. A compatible host dispatcher owns the persona launch and report gate; the portable runner does not pretend to provide that host service. Every action item is labeled strictly Agent action or Operator action and the report is indexed with the docs corpus (references/docs-audit.md).
• Harness capability contract — "runs on any compatible agent" was unfalsifiable, so wgm now publishes a machine-checked record instead: one entry per harness with its skill-discovery paths, non-interactive invocation contract, subagent capability, named fallback, adapter status, per-OS evidence, and source URLs. Exactly four statuses exist — Verified (discovery and invocation and an end-to-end journey are on record), Expected, Degraded, Unknown — and scripts/check-harnesses.sh fails closed on anything else (references/harness-portability.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).
• Stage 8+ growth — wgm is independently assessed as an operational Stage 8.5 / Stage 9 candidate: it can improve its own control plane from evidence, but still requires human/host gates for consent, review, promotion, and rollback. See the growth-stage record and the external Gas Town stages model.
• 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 index: docs/.

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 · telemetry · stage10-memory · 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 · harness-portability · PLUGIN_PROTOCOL · plugin-integration
├── compatibility/    # harnesses.json — the per-harness capability/evidence record (gated by scripts/check-harnesses.sh) · agent-adapters.json — the canonical-role -> host-agent-format mapping
├── adapters/         # host translations of the role subagents, derived from .github/agents/ by scripts/sync-agent-adapters.sh (claude/agents/ today)
├── 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) · audit.sh (portable docs-audit dispatcher) · harvest-hive.sh (hive courier) · devcontainer.sh (local sandbox) · check-trailers.sh (commit governance) · check-doc-sync.sh (doc drift) · check-harnesses.sh (harness contract) · sync-agent-adapters.sh (role adapters) · install.sh · install.ps1
├── companions/       # teach-me (learn a repo) · quiz-me (be tested on it) · rugged (stress-test a design) — installed as sibling skills
├── .github/agents/   # the twelve role-specialized subagents (the swarm), incl. the docs-audit swarm + wgm-hermes — canonical source for every host adapter
└── docs/             # get-started/ · operator/ · companions/ · agent/ · reference/ · style-guide · plans/ · audit/

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