
remi-wiggum
Scaffold and run a Ralph/Wiggum-style iterative loop using a .wiggum/ folder
- version
- 0.3.0
Install
/plugin install remi-wiggum@remi-engineeringRun it inside Claude Code after adding the marketplace with /plugin marketplace add REMI-Agents/remi-engineering-marketplace.
Contents
Discovered from sourceCommands 4
Study .wiggum/specs/*, .wiggum/IMPLEMENTATION_PLAN.md, and .wiggum/TEST_PLAN.md. Pick the single most important incomplete item.
Before making changes, search the codebase ("don't assume not implemented"). Implement the item completely.
Testing expectations:
- Prefer adding/updating AUTOMATED tests for the new behavior.
- Run the appropriate baseline commands per
.wiggum/AGENTS.md(and/or.wiggum/config.json) as a sanity check. - Keep
.wiggum/TEST_PLAN.mdhonest: move items from “planned” to “covered” only when tests exist or checks have been performed.
Always update:
.wiggum/IMPLEMENTATION_PLAN.mdwith progress/learnings.wiggum/TEST_PLAN.mdwith what’s now covered and what remains
Do NOT automatically push to git remotes. If you create a commit, it should be local-only unless the user explicitly asks to push.
Portability note: Do not assume a specific agent CLI. This loop may run under Claude CLI or Codex CLI depending on .wiggum/config.json.
You are scaffolding a Ralph/Wiggum-style loop into the user's current repository.
Requirements
- Create a
.wiggum/folder at the repo root. - Put all loop artifacts under
.wiggum/. - Do not modify application code. Only create/update
.wiggum/*. - If files already exist, update them conservatively (do not delete user content).
Default assumptions
Assume this repo is usually a monorepo with:
- backend: Python (Poetry) + pytest
- frontend: Node (pnpm) with lint/build
However, you MUST auto-detect and write defaults based on the actual repo:
- If
pyproject.tomlexists: treat backend as present. - If
poetry.lockexists: use poetry commands. - If
pnpm-lock.yamlexists: treat frontend as present. - If neither backend nor frontend markers exist, scaffold config with placeholders.
Create or update these files
1) .wiggum/AGENTS.md
Write a short operational file with sections for:
- how to run tests
- how to lint/typecheck (if applicable)
- how to run the app
Include both backend and frontend placeholders.
2) .wiggum/config.json
Create a small, editable config that the runner and prompts can rely on.
It MUST include:
- a completion promise string (exact literal)
- backend verify commands (array of strings)
- frontend verify commands (array of strings)
- an execution engine configuration (Claude vs Codex) so the loop can run on a laptop OR a VPS
- a boolean (or string policy) indicating that some manual verification may remain, but automated tests are preferred
Engine fields (portable runner):
engine.name: one ofclaudeorcodexengine.model: optional model identifier (e.g.,gpt-5.2)engine.command: an array of strings representing the command to run the agent in non-interactive mode- The runner will append the prompt file via stdin (recommended), so the command should read from stdin.
Auto-detect and populate sensible defaults:
- backend (poetry + pytest):
poetry run pytest
- backend (no poetry.lock but pyproject exists):
python -m pytest
- frontend (pnpm):
pnpm lintpnpm build
Engine defaults:
- If
claudeis available, default to:- name:
claude - command:
["claude","-p"]
- name:
- If
codexis available (e.g. on a VPS), default to:- name:
codex - model:
gpt-5.2 - command: a placeholder that the user may need to adjust, e.g.
["codex", "--model", "gpt-5.2"]
- name:
If you cannot confirm the exact Codex flags in this repo, write a safe placeholder and clearly label it as user-editable.
3) .wiggum/IMPLEMENTATION_PLAN.md
Initialize as an empty plan with a heading and a short instruction that it is disposable and should be kept current.
4) .wiggum/TEST_PLAN.md
Create a template that the agent will keep updated. It should include:
- “Automated tests” section (expected to grow)
- “Manual checks (remaining)” section (allowed to be non-empty, but should be short and justified)
5) .wiggum/specs/00_overview.md
Create a starter spec that explains how specs should be written:
- JTBD style
- “one sentence without ‘and’”
- each concern gets its own spec file
6) .wiggum/PROMPT_plan.md
Write a planning prompt that:
- studies
.wiggum/specs/* - studies relevant repo code (do not assume missing)
- updates ONLY:
.wiggum/IMPLEMENTATION_PLAN.md.wiggum/TEST_PLAN.md(update planned tests/checks)
- does not implement any code
- uses
.wiggum/AGENTS.mdand.wiggum/config.jsonas operational context
7) .wiggum/PROMPT_build.md
Write a building prompt that:
- studies
.wiggum/specs/*,.wiggum/IMPLEMENTATION_PLAN.md, and.wiggum/TEST_PLAN.md - chooses the single most important incomplete plan item
- searches code before changing anything ("don't assume not implemented")
- implements the task
- adds/updates AUTOMATED tests for the new behavior whenever feasible
- updates
.wiggum/IMPLEMENTATION_PLAN.mdand.wiggum/TEST_PLAN.mdimmediately with learnings
Do NOT automatically push to git remotes. Include a short reminder about sandboxing/safety when granting tool permissions.
8) .wiggum/PROMPT_verify.md
Write a verification prompt that:
- reads
.wiggum/config.jsonfor verify commands - runs backend verify commands if configured
- runs frontend verify commands if configured
- checks that automated tests exist for the core feature behavior (not only a plan)
- allows a small “Manual checks (remaining)” list in
.wiggum/TEST_PLAN.md, but only if justified
When ALL verify commands pass AND verification is acceptable:
- output exactly the completion promise string from
.wiggum/config.json
Otherwise:
- do NOT output the promise
- update
.wiggum/TEST_PLAN.mdand/or.wiggum/IMPLEMENTATION_PLAN.mdwith what failed and what to do next
Note: PROMPT files should be engine-agnostic (no references to Claude-specific flags). The runner chooses Claude vs Codex.
9) .wiggum/loop.sh
Create an executable bash script that:
- accepts
plan,build, orverifyand an optional max-iterations number - is PORTABLE: it must not hardcode Claude
- read
.wiggum/config.jsonto decide which engine to run (Claude vs Codex) - execute the configured engine command (array) and feed the prompt file via stdin
- read
- writes logs under
.wiggum/runs/<timestamp>/iter-###/<phase>.log - after each iteration, checks logs for the completion promise and stops if found
- prints a short usage message
If you need to parse JSON in bash, use a tiny embedded python snippet (preferred) rather than adding a dependency on jq.
Do NOT default to --dangerously-skip-permissions. If you include it, make it opt-in via an env var.
After scaffolding
Print:
- which files were created/updated
- the exact commands the user should run next, e.g.:
bash .wiggum/loop.sh plan 1bash .wiggum/loop.sh buildbash .wiggum/loop.sh verify
Be concise.
Study .wiggum/specs/* and the repo code (do not assume missing).
Then update:
.wiggum/IMPLEMENTATION_PLAN.mdwith a prioritized, actionable task list.wiggum/TEST_PLAN.mdwith a feature-based verification plan (favor automated tests; allow a small justified manual remainder)
Do not implement code. Use .wiggum/AGENTS.md and .wiggum/config.json to understand how the repo is run/tested.
Output should be:
- a brief summary of the key gaps found
- confirmation that the two files were updated
You are reporting the current status of the Wiggum loop for the user's repository.
What to read (if present)
.wiggum/IMPLEMENTATION_PLAN.md.wiggum/TEST_PLAN.md.wiggum/config.json- newest
.wiggum/runs/*/summary.log(if any)
Output requirements
Be concise and structured.
- Scaffold status
- If
.wiggum/does not exist: say it is not initialized and recommend running the init command.
- Plan summary
- Summarize the top 1-3 remaining items from
.wiggum/IMPLEMENTATION_PLAN.md. - If the plan is empty, say so and recommend running a planning pass.
- Test coverage summary
- Summarize what’s covered by automated tests vs what manual checks remain (from
.wiggum/TEST_PLAN.md).
- Last run summary (if available)
- Mention the most recent run folder timestamp.
- Whether completion promise was detected.
- Any obvious failures (brief).
- Next action recommendation Recommend exactly one of these (based on what you found):
bash .wiggum/loop.sh plan 1bash .wiggum/loop.sh buildbash .wiggum/loop.sh verify
Do not modify any files.
Sponsors
Details
- Marketplace
- REMI-Agents/remi-engineering-marketplace
- Source
- plugins/remi-wiggum
- Category
- Community