👾 Mario DevX

Named after Super Mario because (1) it never stops running, (2) it repeatedly smashes its face into the same level until it learns where the invisible blocks are, and (3) because Italians always do it better 🇮🇹.

It does not "have a conversation" about shipping. It ships, fails a gate, reads the receipt, and tries again. If you're looking for vibes, inspirational essays, or a 200-message thread that ends with "should work," you're in the wrong repo.

Mario DevX is an OpenCode plugin that runs Ralph-style, file-based, deterministic agent loops inside the OpenCode TUI.

Why you'll like it

• Smart planning, deterministic execution: LLM-driven PRD interview adapts to your project (no rigid forms), but task execution is strictly deterministic—quality gates must pass, verifiable output stored on disk (.mario/*), not fragile chat memory.
• Strict verifier output (PASS|FAIL + next actions) so failures are actionable.
• Incremental scope management (/mario-devx:add, /mario-devx:replan) without restarting from scratch.

Loop overview

30-second quickstart

mkdir my-project && cd my-project && git init && \
curl -fsSL https://raw.githubusercontent.com/valerio-mc/mario-devx/main/install.sh | bash && \
opencode .

Then in OpenCode:

/mario-devx:new your idea
/mario-devx:run 1

Motivations

Coding agents are great until the chat becomes the product: long threads, stale assumptions, and "it passed on vibes".

Mario DevX forces the only kind of memory that actually helps:

1. Put the truth on disk (.mario/), not in the chat.
2. Ship in small slices (one task per iteration).
3. Add backpressure (quality gates + strict judge) so the loop stops when it should.

Commands

/mario-devx:new <idea>    # PRD wizard -> seeds .mario/prd.json (requirements + tasks)
/mario-devx:run <N>       # run up to N iterations (for N > 1, continues across task failures; stops early only on global blockers/exhausted tasks)
/mario-devx:add <feature> # add a new feature request and decompose into new tasks
/mario-devx:replan        # regenerate open-task plan from backlog requests
/mario-devx:status        # what's running + focus task + last verdict + next action
/mario-devx:doctor        # healthcheck + concrete fixes

Control vs Work session

+-----------------------+        +---------------------------+        +---------------------+
| Control Session (you) |  --->  | Work Session (mario-devx) |  --->  | Canonical State     |
| (runs slash commands) |        | (build + verify + judge)  |        | (.mario/* on disk)  |
+-----------------------+        +---------------------------+        +---------------------+

First run

1. Create a repo and install mario-devx (same command as quickstart).
2. Start OpenCode: opencode .
3. Bootstrap: /mario-devx:new my brilliant idea
4. Execute one slice: /mario-devx:run 1

The PRD wizard is LLM-driven and asks one high-leverage question at a time. You answer like a normal human; it writes requirements, quality gates, and tasks to .mario/prd.json so nobody has to archaeologically excavate your chat history later.

How it works

• /mario-devx:run executes in two ephemeral phases: work (build/repair) then verify.
• For run N with N > 1, mario-devx executes up to N iterations and continues across per-task BLOCKED outcomes; it stops early only for global blockers or when no runnable tasks remain.
• Batch-mode task selection priority is blocked -> in_progress -> open (while respecting task dependencies).
• Verification pipeline is strict: deterministic gates -> UI verification (when enabled) -> LLM verifier.
• When UI verification is enabled for a web app, mario-devx bootstraps missing agent-browser prerequisites first and keeps the run blocked until the installer finishes.
• Repair prompts include a deterministic backpressure payload from tasks[].lastAttempt.gates.failure (command, exit code, fingerprint, clipped output) so the model gets concrete failure receipts, not just exit codes.
• Semantic repair reads repo-local UI evidence paths from tasks[].lastAttempt.ui.evidence when UI verification failed, so the model can inspect artifacts directly instead of relying on clipped inline excerpts.
• Repair idle waits persist factual blocker detail as WORK_SESSION_IDLE_TIMEOUT or WORK_SESSION_IDLE_ABORTED rather than collapsing into a generic infrastructure failure.
• Tasks complete only on verifier PASS; otherwise they are blocked with concrete next actions instead of motivational poetry.
• Progress streams back to your control session as throttled toasts (text + tool lifecycle + patch updates).
• Toast streaming is on by default; set STREAM_WORK=0 and/or STREAM_VERIFY=0 in .mario/AGENTS.md to disable.
• run.lock heartbeats in .mario/state/ use runId ownership and state reconciliation, so stale locks are reclaimed instead of wedging future runs.

Agent knobs

.mario/AGENTS.md supports phase-agent and stream controls:

WORK_AGENT='build'
VERIFY_AGENT='build'
STREAM_WORK=1
STREAM_VERIFY=1

• WORK_AGENT: agent used for build/repair prompts.
• VERIFY_AGENT: agent used for verifier prompts.
• STREAM_WORK / STREAM_VERIFY: toast streaming toggles (1 on, 0 off).

Frontend verification

When the PRD wizard marks a project as frontend work, mario-devx syncs that UI verification choice into .mario/AGENTS.md (UI_VERIFY=1 when the wizard says yes, otherwise UI_VERIFY=0), keeps UI_VERIFY_REQUIRED aligned when UI verification is enabled, and auto-installs missing agent-browser prerequisites in the background (non-interactive first). While that bootstrap is running, /mario-devx:run stays blocked and points you at the install log so UI verification starts from a known-good toolchain. It then stores UI evidence under tasks[].lastAttempt.ui so "works on my machine" has receipts.

UI evidence includes accessibility snapshots, console/errors, and an optional screenshot. mario-devx persists all UI evidence as repo-local files under .mario/state/ui-evidence/<taskId>/, and tasks[].lastAttempt.ui.evidence stores only those repository-local paths. When UI startup fails, mario-devx keeps the recorded next actions subtype-aware (lock held, port conflict, unreachable URL) instead of prescribing one specific shell command.

Verifier output is stored under tasks[].lastAttempt.judge as structured JSON (status, reason, nextActions). Deterministic gate failure receipts are stored under tasks[].lastAttempt.gates.failure (command, exitCode, fingerprint, outputExcerpt).

What gets created

In your project:

.mario/
  prd.json                   # requirements + planning + tasks + backlog + verification policy
  AGENTS.md                  # harness knobs (UI_VERIFY*, WORK_AGENT, VERIFY_AGENT, STREAM_WORK, STREAM_VERIFY)
  state/state.json           # internal state (iteration + run status)
  state/run.lock             # active-run lock + heartbeat
  state/mario-devx.log       # centralized structured run/tool logs (auto-capped at 50MB)
  state/ui-evidence/         # UI verification artifacts (per-task; prd.json stores repo-local evidence paths only)

In this repo:

.opencode/plugins/mario-devx/   # OpenCode plugin source + assets

Git hygiene

If you don't want internal state in git, add this to your repo .gitignore:

.mario/state/

Troubleshooting

Issue	Quick fix
Run blocked before coding starts	Check .mario/prd.json for missing tasks or qualityGates, fix reality, then rerun /mario-devx:run 1.
Run says another run is in progress (run.lock)	Run /mario-devx:doctor to auto-clear stale locks, then rerun /mario-devx:run 1.
Run blocked with WORK_SESSION_NO_PROGRESS	The same gate failure repeated while tracked source/config files did not change. Read tasks[].lastAttempt.gates.failure.outputExcerpt in .mario/prd.json and run.repair.backpressure entries in .mario/state/mario-devx.log, then rerun /mario-devx:run 1.
Run blocked with WORK_SESSION_IDLE_TIMEOUT or WORK_SESSION_IDLE_ABORTED	Read tasks[].lastAttempt.judge.reason for the factual idle-wait detail, then inspect .mario/state/mario-devx.log for work-session idle diagnostics before rerunning /mario-devx:run 1.
Run blocked with repeated verifier findings	The verifier is surfacing the same actionable failure again. Read tasks[].lastAttempt.judge.reason and tasks[].lastAttempt.judge.nextActions, then make explicit edits that address that evidence instead of broad refinements.
UI verification fails to start	Read tasks[].lastAttempt.ui.note, tasks[].lastAttempt.judge.nextActions, and .mario/state/ui-evidence/<taskId>/dev-server.log for subtype/log-tail details.
Anything weird / stuck / transport-y	Run /mario-devx:doctor and attach .mario/state/mario-devx.log, .mario/state/state.json, .mario/prd.json so we debug facts, not folklore.

Acknowledgements

• Geoffrey Huntley + playbook
• Resource index
• agent-browser (Vercel)

License

MIT. See LICENSE.