- For: anyone hitting a snag installing or running wgm.
- First move: every wgm gate prints a
Gate check: block naming the failed item. Read that
before anything else — it usually names the fix.
- How this page is organized: by stage — Install · Companions · Loop · Validation · Artifacts ·
Contributing. Each entry is symptom, cause, resolution.
- Most common three: the skill is not listed (wrong directory name, or the session needs a
restart);
build refuses to start (no IMPLEMENTATION_PLAN.md yet); the loop never stops (pass a
max, or drop a STOP sentinel).
- Next: Installation · Run the loop ·
Reference.
Three checks resolve most reports:
- Read the gate output. wgm prints
Gate check: with a PASS or FAIL per item at every phase
boundary. The failing item names the problem.
- Restart the agent session. Skills are scanned at session start, so a freshly installed skill
is invisible to an already-running session.
- Confirm the directory name. The skill folder must be named exactly
wgm, matching the name:
field in its SKILL.md frontmatter. The same rule applies to teach-me and quiz-me.
| |
|---|
| Symptom | The install reports success, but the client does not offer /wgm. |
| Cause | The folder is not where the client scans, the directory name does not match the skill name, or the session has not re-scanned. |
| Resolution | Confirm the path against the table in Installation. Ensure the directory is named exactly wgm. Restart the agent session. For project scope, start the agent from that project's root. |
| |
|---|
| Symptom | The piped installer exits silently or reports a 404. |
| Cause | The repository must be public for the unauthenticated one-liner to fetch. curl -f also exits silently on a 404, so a failed install can look like a no-op. |
| Resolution | Install from a clone instead: git clone … && ./scripts/install.sh. To see the real status, re-run the raw URL without -f. |
| |
|---|
| Symptom | The installer reports a fetch failure. |
| Cause | When piped with no local checkout, the installers self-fetch. This message means both the tarball download and the git clone fallback failed. |
| Resolution | Check connectivity, the --ref you passed, and WGM_REPO / WGM_REF. Or install from a clone. See Installers reference. |
| |
|---|
| Symptom | wgm works in WSL but a native-Windows agent cannot see it. |
| Cause | The mirror runs for user-scope installs only — not --project or --dir — and is skipped by --no-windows. It may also have failed to resolve your Windows home. |
| Resolution | Read the installer's note line. If it says it could not resolve your Windows home, pass --windows-home /mnt/c/Users/you. Confirm your Windows agent scans %USERPROFILE%\.agents\skills\wgm. |
| |
|---|
| Symptom | A PowerShell install produced a Linux-side install. |
| Cause | On Windows with a WSL distro present, a user-scope install.ps1 delegates to the bash installer in WSL on purpose, so both homes are covered. |
| Resolution | Pass -NoWsl for a native-Windows install, or -WslDistro NAME to pick a distro. |
| |
|---|
| Symptom | A warning about junction creation during install. |
| Cause | Creating a junction can require elevated privileges. |
| Resolution | None needed — install.ps1 falls back to a copy automatically and warns. Pass -Method copy to skip the attempt entirely. |
Re-run the same installer. wgm refreshes a directory it recognizes as its own in place, with no
--force needed, and adds the Windows mirror if it was missing. From a clone, make update pulls
and reinstalls in one step.
| |
|---|
| Symptom | /wgm works but /teach-me or /quiz-me is not offered. |
| Cause | The install used --no-companions or -NoCompanions, or it ran from a source tree predating the companions, or the client has not re-scanned. |
| Resolution | Re-run the installer without the opt-out flag and restart the session. Confirm SKILLS_DIR/teach-me/SKILL.md and SKILLS_DIR/quiz-me/SKILL.md exist — they must be siblings of wgm, not nested inside it. |
| |
|---|
| Symptom | That line appears during install. |
| Cause | The source tree or tarball has no companions/ directory — an older release. |
| Resolution | Install from a newer ref: --ref main, or --ref latest for the newest published release. |
| |
|---|
| Symptom | loop.sh or swarm.sh exits 2 immediately. |
| Cause | No agent command was supplied. |
| Resolution | Set WGM_AGENT, pass --agent "CMD", or append -- copilot -p --allow-all-tools. See Choosing the agent. |
| |
|---|
| Symptom | build, review, or preflight exits 1 before doing anything. |
| Cause | Those modes need a plan on disk; they are not allowed to invent one. |
| Resolution | Run a plan pass first: ./scripts/loop.sh plan --request "…", or /wgm plan. |
| |
|---|
| Symptom | build keeps iterating indefinitely. |
| Cause | build defaults to unlimited iterations. |
| Resolution | Pass a max (build 20), cap it with --max-runtime-seconds or --idle-timeout, create a .wgm/STOP sentinel, or press Ctrl+C. In a healthy run the agent drops the sentinel itself when no must-have task remains. |
| |
|---|
| Symptom | A stall never escalates to the stronger model. |
| Cause | Escalation engages only when both --frugal-agent and a main --agent are set. |
| Resolution | Set both, and check --escalate-after (default 2). See Stall recovery. |
| |
|---|
| Symptom | The loop exits before iteration 1 with a message that the agent did not create the disposable marker. |
| Cause | The headless agent can read the workspace but cannot write to it, or the invocation used a constrained/no-tools mode. |
| Resolution | Grant the invocation write access or use a full-shell agent, then rerun. --dry-run does not test this; a real build or plan always probes before spending the first iteration. |
| |
|---|
| Symptom | A build exits non-zero after successful agent invocations that leave IMPLEMENTATION_PLAN.md unchanged. |
| Cause | Exit status alone is not evidence of useful work; the agent may have produced prose without an artifact or stopped without recording progress. |
| Resolution | Inspect the agent log and plan, fix the task or permission problem, then rerun. Increase --max-no-progress-iterations only when a plan-preserving iteration is intentional and documented. |
| |
|---|
| Symptom | The loop reports Agent timed out after Ns and records a failed iteration. |
| Cause | --agent-timeout-seconds N reached its limit. On hosts without GNU timeout or gtimeout, the loop states that it is using the cooperative fallback instead of pretending to terminate the process. |
| Resolution | Inspect the agent output, lower the task scope, or increase the explicit timeout. Use a host with GNU timeout/gtimeout when hard process-group termination is required. |
| |
|---|
| Symptom | A single phase exits non-zero with Phase artifact missing. |
| Cause | The agent process returned zero without creating the plan or genes artifact promised by the phase. |
| Resolution | Inspect the agent's write/tool permissions and rerun with a full-shell invocation. Do not treat a prose handoff as a substitute for the named file. |
| |
|---|
| Symptom | A commit-mode loop refuses to start or refuses to stage a path. |
| Cause | --commit takes exclusive ownership and will not sweep pre-existing or undeclared edits into an iteration commit. |
| Resolution | Move human edits to another worktree or commit them before starting. The agent must declare each intentional repository-relative file in the iteration ownership manifest; never bypass the refusal with git add -A. |
| |
|---|
| Symptom | Changes land outside the task's stated scope. |
| Cause | The task's spec or plan entry is too loose to steer on. |
| Resolution | Add a sign rather than hand-holding each step: tighten the spec, add a note to AGENTS.md, or split the task smaller. wgm steers on patterns plus backpressure. |
| |
|---|
| Symptom | A lane exits immediately with a guard message. |
| Cause | The lane was not in its assigned worktree and branch. The guard refuses to let it mutate the wrong tree. |
| Resolution | This is working as intended. Check for a leftover worktree or branch from a prior run — make clean-worktrees clears both. |
| |
|---|
| Symptom | The swarm summary marks a lane as failed even though the lane process exited zero. |
| Cause | swarm.sh verifies the artifact after waiting; a task lane with no reachable commit is a silent no-op, not a success. |
| Resolution | Read .wgm/swarm-logs/*.log, confirm the agent invocation has tool/write permission, and rerun the lane. Do not merge or report a zero-commit lane as completed. |
| |
|---|
| Symptom | The loop keeps iterating without converging. |
| Cause | Usually an ambiguous scenario expectation, or a demo path that is not actually wired up. |
| Resolution | Inspect the weakest scenario recorded in IMPLEMENTATION_PLAN.md. Sharpen the expectation, or split the task. For a rough prototype, lower --threshold. See Scenarios and scoring. |
| |
|---|
| Symptom | Scenario validation cannot reach the service. |
| Cause | No container engine, or a port or readiness problem. |
| Resolution | Confirm podman or docker is installed, or pass --container explicitly. Check the readiness wait and that the published port is free. See Containers. |
| |
|---|
| Symptom | An isolated re-run is green; the full gate is red. |
| Cause | The difference between the two runs is the bug — commonly a teardown race where buffered output is discarded before a consumer reads it. |
| Resolution | Do not treat the isolated pass as the answer. Inspect lifecycle ordering, synchronize producer teardown to consumer acknowledgement, stress the exact test repeatedly, then rerun the complete gate. Only a green full suite clears it. |
| |
|---|
| Symptom | An isolated staged build reports a missing artifact. |
| Cause | A globally shared build-target override was inherited, so the build emitted outside the stage-local path the verifier checks. This is a harness misconfiguration, not a product defect. |
| Resolution | Clear or scope ambient target overrides before the build, or set an explicit stage-local target directory. Record the clean rerun separately from product failures. |
| |
|---|
| Symptom | Artifacts appear in .wgm/ rather than where you expected. |
| Cause | The safety rule: when the root already has AGENTS.md, IMPLEMENTATION_PLAN.md, or specs/, wgm writes its own copies under .wgm/ so it never clobbers yours. |
| Resolution | Working as intended. See Artifacts. |
| |
|---|
| Symptom | A consent question appears before anything else on a new project. |
| Cause | .github/wgm-hive.yml does not exist yet. Its absence is what defines "a new project" for consent. |
| Resolution | Answer once. The file is written either way and never asked about again. consent: false keeps every lesson local. See the consent file. |
| |
|---|
| Symptom | make validate is red before you changed anything. |
| Cause | Usually a missing development dependency. |
| Resolution | Check the contributor prerequisites in Requirements. shellcheck is needed for lint, jq for docs. |
| |
|---|
| Symptom | The evals gate exits 2 rather than 0 or 1. |
| Cause | jq is not on PATH. Exit 2 means misconfigured, distinct from 1 for a real failure. |
| Resolution | Install jq. |
| |
|---|
| Symptom | check-docs.sh flags a link you can follow in your editor. |
| Cause | Links are resolved relative to the file containing them. A path that works from the repository root often does not work from a nested page. |
| Resolution | Count the ../ hops from the linking file. From docs/reference/, the repository root is two levels up. |
- Re-read the protocol in
SKILL.md. Every gate prints a Gate check: block
naming exactly which item failed.
- Look up the exact flag in the reference.
- Open an issue. If wgm behaved plausibly but wrongly, use the heuristic report template — that
kind of report is how its heuristics improve.