dream-loop

What It Does

dream-loop is a single agent skill for producing visually impressive 3D scenes, games, and apps. The agent first generates or accepts a "dream" target screenshot using image generation, then builds the product toward that screenshot, then submits live screenshots to an independent judge subagent that scores the gap on a 10-point rubric, looping until the score or stall rules say stop. A 49-line SKILL.md routes to one of two mutually exclusive workflows by subscription tier: a Plus workflow where a small orchestrator model drives stronger subagents at low reasoning effort to conserve quota, and a Pro workflow where one strong model builds and judges in a loop. Two executable helpers back the loop: a zero-dependency Fal.ai batch client for image-to-3D asset generation and a local preview server with a PNG capture endpoint. The skill targets developers running coding agents with image generation and vision, and the README states it has only been tested with GPT-6 Astra in Codex.

The Good

The Fal batch helper treats paid API calls with more care than most production tooling. In 172 lines with zero dependencies, scripts/fal-batch.mjs enforces an offline preflight that catches the two documented footguns (the wrong Trellis route and H3.1 options pasted onto Trellis), refuses to resubmit any job that was accepted or whose acceptance is uncertain, validates downloaded models as complete GLB 2.0 files by magic bytes and declared length, writes outputs atomically through a .part rename, locks the job file against concurrent runs, and redacts credentials, data URIs, and payloads from every error string it persists. All of this is covered by 9 node:test suites with mocked fetch that pass in 103 milliseconds, including cases like "uncertain submissions are not retried automatically" and "invalid inputs never reach the paid submission API."

The two-workflow split reflects real operational thinking, not filler. The Plus workflow instructs a large orchestrator model to stop and ask the user to switch to a smaller one, then drives stronger subagents at the lowest reasoning effort with fresh empty contexts, an explicit no-fork rule, and a hard 3-loop checkpoint before asking the user to review. The Pro workflow's judge prompt scores composition, lighting, and materials out of 3 each plus details out of 1, demands named and fixable gaps rather than vague impressions, and the exit criteria implement two-level stall detection: three rounds without a full point of improvement triggers an architectural rethink, and a failed rethink triggers a stop that hands the decision to the user instead of burning more tokens.

The knowledge docs are dated, verified, and honest. references/fal.md pins two working recipes (tripo3d/h3.1/image-to-3d at roughly $0.30 per asset for hero props, fal-ai/trellis at roughly $0.02 for dressing) with a note that they were checked against the official schemas on 2026-09-09; both schema URLs and the queue documentation URL returned HTTP 200 during this review. The README is honest about scope: prerequisites name image generation, vision, and subagents, it says Blender is optional and only needed for custom modeling, and it admits the skill is only tested with one model on one host. The install also ships its own .gitignore containing .dream-loop/ so the agent's working directory does not pollute your repository.

The Bad

Four broken links sit exactly where the money path lives. Both references/plus-mode/assets-3d.md and references/pro-mode/assets-3d.md link to fal.md as fal.md, which resolves to references/plus-mode/fal.md and references/pro-mode/fal.md, neither of which exists; the real file is one directory up at references/fal.md. That link is referenced twice per file (lines 15 and 19 in pro-mode, 17 and 21 in plus-mode), and it is the sole pointer from the asset-sourcing ladder to the verified Fal recipes the helper depends on. An agent that resolves links relative to the document it is reading lands on a missing file at the moment it is deciding how to spend API credits.

Every install carries a 7MB demo GIF that the agent never uses. assets/vesper-preview.gif is 6,976,947 bytes and accounts for 99.6 percent of the 6.7MB installed payload; the 11 functional files total about 44KB. The GIF documents the README example and does nothing at runtime, yet the universal installer copies it into .hermes/skills/dream-loop/ (or the equivalent for your agent) on every machine. Moving it behind a README link or an external URL would cut install weight by a factor of roughly 160.

Maturity signals are thin for the star count. The repo is 4 days old with 5 commits from one author, no tags, no releases, no CHANGELOG, no version field anywhere, no CI, and one open issue (a typo fix in the judge guidelines, unanswered since 2026-09-09). The README's bare install command, npx skills add achimala/dream-loop, exits 0 and installs nothing when run non-interactively because the skills CLI scope picker needs a terminal; the scripted flags that work are not documented in the README. And the entire loop is validated only on GPT-6 Astra in Codex, so behavior on Claude-class or other models is inference, not evidence.

Smoke Test Results

Hands-on host test on macOS 26.5.2 aarch64 with Node 24.13.1 and system Python 3, from a fresh clone plus live install probes. The repo's own demo site link was not probed because this review host blocks requests to .dev domains.

Run A - Fresh clone, structural checks

$ git clone --depth 1 https://github.com/achimala/dream-loop
✅ 13MB clone, 12 files, 526 text lines across SKILL.md, README, 5 references, 3 scripts
$ awk frontmatter name
✅ name: dream-loop
$ awk frontmatter description
✅ description present, 204 chars, routes on "dream loop" and graphical-fidelity asks
$ awk frontmatter license
✅ license: MIT declared, matches LICENSE file
$ resolve all relative markdown links
❌ 10 relative links checked, 4 broken: both assets-3d.md files link fal.md at the wrong directory level
$ head -3 LICENSE
✅ MIT license file present at root
$ grep secret patterns (sk-, ghp_, FAL_KEY=) across md/mjs/py
✅ 0 hits
$ env -u FAL_KEY node scripts/fal-batch.mjs --help
✅ usage plus both model recipes printed offline, no key required
$ grep -c "^test(" scripts/fal-batch.test.mjs
✅ 9 test suites declared
$ grep 'Do not read both documents' SKILL.md
✅ workflow split is explicit and exclusive

Pass rate: 9 of 10. The only failure is the fal.md link level, a real defect in the asset ladder.

Full log →

Run B - With deps (Node 24 suite, helper probes, preview server)

$ node --test scripts/fal-batch.test.mjs
✅ 9 tests, 9 pass, 0 fail in 103ms (all fetch mocked, no network)
$ node fal-batch.mjs check valid-jobs.json (documented recipes, real PNG, no key)
✅ exit 0, both jobs state "ready"
$ node fal-batch.mjs check bad-route.json (fal-ai/trellis/image-to-3d)
✅ exit 1: "single-image Trellis uses fal-ai/trellis (no /image-to-3d suffix)."
$ node fal-batch.mjs check bad-opts.json (face_limit on trellis)
✅ exit 1: "face_limit is an H3.1 option, not a Trellis option."
$ node fal-batch.mjs check waiting.json (image not yet generated)
✅ state "waiting-for-image", not an error
$ env -u FAL_KEY node fal-batch.mjs submit valid-jobs.json
✅ exit 1: "Set FAL_KEY or FAL_API_KEY in the environment."
$ curl -X POST real-PNG http://127.0.0.1:4199/__capture
✅ 200, JSON paths returned, .dream-loop/captures/latest.png written
$ curl -X POST notapng http://127.0.0.1:4199/__capture
✅ 400 rejected
$ curl -X POST http://127.0.0.1:4199/__nope
✅ 404 rejected

Pass rate: 9 of 9. The helper layer behaves exactly as documented on positive and negative paths, offline, with no credentials.

Full log →

Run C - Functional verification (install fidelity, registry, schemas)

$ npx skills add achimala/dream-loop </dev/null (README-verbatim, isolated HOME)
❌ exit 0, zero files landed: the scope picker stalls without a TTY
$ npx skills add achimala/dream-loop --agent hermes-agent --skill dream-loop --copy --yes
✅ 12 files landed in ./.hermes/skills/dream-loop/ including references/ and scripts/
$ du -sh installed skill dir
❌ 6.7M installed, 6,976,947 bytes of it assets/vesper-preview.gif the agent never reads
$ find installed dir -name '*.md' -o -name '*.mjs' -o -name '*.py'
✅ 7 markdown files and 3 scripts landed, full progressive structure intact
$ cmp installed SKILL.md vs raw.githubusercontent main
✅ byte-identical
$ cmp all 5 installed references vs upstream main
✅ all 5 byte-identical, no registry staleness
$ curl fal.ai schema endpoints (tripo3d/h3.1, fal-ai/trellis, queue docs)
✅ all HTTP 200
$ skills.sh API search dream-loop
✅ registry entry achimala/dream-loop/dream-loop present, 261 installs

Functional pass rate: 6 of 8. Both failures are packaging and documentation issues (TTY-dependent install docs, GIF weight); install fidelity itself is perfect.

Full log →

What the runs tell you

The executable half of this skill is verified working to a higher standard than most skills ship with: a passing mocked test suite, offline preflight that blocks the documented failure modes, a clean no-key failure, and byte-identical installs. What could not be verified is the loop itself, because it executes inside a live agent with image generation and a vision critic, and the honest reading is that the process docs are well-formed and internally consistent while their real-world effect remains one author's testimony plus one demo GIF.

Setup Walkthrough

1. Install interactively with npx skills add achimala/dream-loop, or script it with npx skills add achimala/dream-loop --agent hermes-agent --skill dream-loop --copy --yes (the scripted form is what GearScope verified; the bare command needs a terminal for the scope picker).
2. Give the agent image generation, either built into the host (the README names Codex and Grok) or via an API key such as Gemini. Without image generation the skill instructs the agent to stop and ask rather than improvise.
3. Optional: set FAL_KEY or FAL_API_KEY to enable image-to-3D asset generation through the bundled helper, at roughly $0.30 per hero asset and $0.02 per small prop using the pinned recipes. Optional: install Blender for custom modeling (Pro workflow only; the Plus workflow forbids Blender as too slow and expensive).
4. Invoke it by asking for something built to high graphical fidelity or by saying "dream loop". The agent picks Plus or Pro based on your stated subscription tier, creates the .dream-loop working directory (auto-gitignored by the shipped .gitignore), and loops.

Alternatives

1. viettranx/3dviz-pro-max - a recipe-catalog approach to creative 3D (223 recipes, Three.js and Blender kits). Prefer it when you want curated starting points rather than an iterate-to-target loop with a judge.
2. pbakaus/impeccable - deterministic design anti-pattern detection for web UIs with no API spend. Prefer it for 2D web polish where a rubric-driven visual loop is overkill.
3. earthtojake/text-to-cad - the CAD vertical built on a real geometry kernel. Prefer it when you need precise engineering CAD rather than visual game art.