wgm documentation

wgm turns a rough request into working software: a relentless requirements interview, a persistent plan, and a build loop steered by deterministic pass/fail checks.

New here? Start with Get started.

Local development first

If you are changing wgm itself, start with the local-development SOP. It lists the contributor prerequisites and the canonical repository gate:

make validate

This index covers wgm's public engine and contributor workflow. Challenge-specific material belongs in the separate project repository that uses wgm, not in this repository's documentation set.

Find your path

I want to…	Go to
Install wgm and run my first build	Get started
See a complete worked example	Your first build
Check what I need installed	Requirements
Drive the loop myself, autonomously	Run the loop
Understand a repository wgm built me	Companion skills
Look up an exact flag or file path	Reference
Fix something that went wrong	Troubleshooting
Understand why wgm works this way	Concepts
Track wgm's maturity and growth	Stage 8+ growth record
Contribute to wgm itself	Contributing · Style guide

Documentation sections

Section	Type	For
Get started	Journey	First-time setup, end to end
Operator guide	Tasks	Running, validating, and troubleshooting wgm
Companion skills	Tasks	teach-me, quiz-me, and rugged
Concepts	Concepts	How the protocol thinks — written for the agent, readable by you
Reference	Reference	Exact flags, defaults, paths, exit codes
Stage 10 offline orchestration	Reference	Evidence-first memory, qualification, routing, comparison, local PR handoff, and authority boundaries

The authoritative protocol is SKILL.md. These docs explain the why and the how behind it. The terse, load-every-iteration rules live in references/; the pages here link to them rather than duplicating them.

The lifecycle at a glance

flowchart TD
  T[Triage] --> G[Grill]
  G --> P[Plan: specs + scenarios]
  P --> F{Preflight ready >= 80?}
  F -- no --> G
  F -- yes --> L
  subgraph L [Build loop — one task per iteration]
    direction TB
    A[Analyze] --> I[Implement]
    I --> V[Validate + judge]
    V --> R[Review]
    R --> Rec[Record]
  end
  V -- stall --> WR[Wonder / Reflect / escalate]
  WR --> A
  Rec -->|tasks done AND satisfaction >= threshold| S[Ship / Handoff]
  Rec -->|more work| A

Every phase ends at a gate that prints PASS or FAIL per item. Gates are not advisory — a FAIL stops the lifecycle rather than degrading it.

Get started

Page	Covers
Get started	The eight-step journey from nothing installed to a shipped build
Requirements	Required, optional, and per-platform prerequisites
Your first build	A complete worked example with every gate shown

Operator guide

Page	Covers
Overview	The operator journey and where to start
Playbook	The per-build SOP, a per-gate PASS/FAIL cheat sheet, reading a docs-audit report
Installation	Linux, macOS, Windows, WSL; user versus project scope
Run the loop	loop.sh and the worktree swarm, limits, retries, thresholds, escalation
Containers	Podman and OCI validation for scenarios needing a live service
Devcontainers	Sandboxing the loop itself, disk-consciously
Troubleshooting	Symptom, cause, and resolution by stage

Concepts: how wgm thinks

Page	Covers
Lifecycle	The phase and gate state machine
Attractor loop	Convergence: generate, test, score, feed back
Scenarios and scoring	Holdout scenarios, judging, satisfaction, tiers
Stall recovery	Wonder and reflect, then model escalation
Gene transfusion	Seeding a build from an exemplar codebase

Deeper mechanics live in references/, written for the agent: subagents (the twelve role-specialized roles and dissent-preserving review) · telemetry (three clocks, and why parked lane time is never "agent-hours") · docs-audit (four personas plus a consolidating writer) · self-improvement (the Hive Growth Loop and its consent gate) · issue-intake (backlog discovery and tracker traceability) · heuristics (the curated ledger of landed lessons) · trigger-eval and evals (wgm's own self-tests).

Reference

Page	Covers
Reference index	Quick answers and the full lookup map
loop.sh	Modes, every flag, environment variables, exit codes
swarm.sh	Parallel streams, partitioning rules, telemetry output
Installers	install.sh and install.ps1, targets, verification
Gates	Every check and harness, and what each proves
Artifacts	Every file wgm reads and writes

Contributing to the docs

Style guide — page types, the executive-overview block, admonitions, and the rules scripts/check-docs.sh enforces automatically.

Plans and roadmap

Design records, kept for provenance rather than as current instructions:

• Complete plans index — the full dated inventory and status policy.
• 2026-08-20 — Stage 8+ growth record — why wgm is assessed as Stage 9 emerging/supervised, what is already orchestrated, and what full self-improvement autonomy still requires.
• 2026-06-16 — competitive analysis and improvement roadmap — how wgm compares to Spec Kit, BMAD, Superpowers, Ralph Orchestrator, agent-os, and grill-me (all tiers shipped).
• 2026-06-16 — wgm vs the Ralph ecosystem — tracking wgm against the loop runners catalogued in awesome-ralph.
• 2026-06-16 — the growth flywheel — harvesting lessons from every codebase and promoting the durable ones back into the skill.
• 2026-07-05 — prefer true Ralph, plus a disk-conscious sandbox — biasing Triage toward Ralph-full, and scripts/devcontainer.sh.
• 2026-07-05 — growth health check — an honest assessment that recent growth had become self-referential, feeding the real-dogfood cadence guardrail.
• 2026-07-06 — the Hive Growth Loop — one funnel, mandatory anonymization, and a one-time committed consent gate.
• 2026-07-08 — SkillOpt's grading discipline — why wgm built a dependency-free grading gate instead of taking a runtime dependency.

Post-merge audit reports live in audit/.

Provenance

wgm fuses grill-me, the Ralph loop, and holdout-scenario judging after octopusgarden.