Exolvra-Genesis: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this repository is

Exolvra Genesis is an adversarial orchestration loop for Claude Code — builder subagents iterate against blind, fresh-context critics comparing real output to a concrete quality bar, until the assembled work wins twice in a row. It ships two ways from one source of truth:

• The plugin (commands/, agents/, templates/, hooks/): plain Markdown plus one HTML template. The wording is load-bearing — editing these files is editing behavior.
• The CLI (cli/): a TypeScript package exposing an exolvra-genesis bin that runs the same loop without opening Claude Code. It is transport and ergonomics only; it loads the plugin files at runtime and never restates them. The CLI was built by its own loop (24 judged rounds against cli/cli-spec.md, ending on two consecutive blind critic WINs).

Commands

Plugin (no build tooling — test by installing and running):

/plugin marketplace add <path-to-this-repo>
/plugin install exolvra-genesis@exolvra-genesis
/exolvra-genesis:run <goal or spec path>        # prefix args with `auto` to skip the approval pause
/exolvra-genesis:interview [spec or idea]       # produces a run-ready spec + HTML mockup

CLI (from cli/):

npm install && npm run build      # build also copies the plugin files into dist/plugin
npm run typecheck                 # tsc --noEmit
npm test                          # node --test, 677 tests; the packaging test is slow (~150s)
node --test test/<file>.test.js   # one suite, no rebuild

The full suite is the gate for any CLI change. One known flake: a usage test can time out while the packaging test saturates the machine; it passes in isolation and on rerun.

Architecture

The loop lives entirely in the plugin Markdown:

• commands/run.md — the lead agent. Captures the bar into .exolvra-genesis/bar/ (pinned twice: BAR.md for people, bar.sha256 for the integrity hook; immutable per run), decomposes into Task Specs, fans out builders, re-runs their verification itself, dispatches fresh critics with shuffled labels, maintains the progress page from templates/progress.html, and enforces the win condition.
• commands/interview.md — one-question-at-a-time interview producing a spec plus a single-file interactive mockup. A conversation, not a build; no subagents.
• agents/builder.md (exolvra-genesis-builder) — implements exactly one Task Spec; touches only owned files; reports only FILES CHANGED / COMMANDS RUN / VERIFICATION (verbatim).
• agents/critic.md (exolvra-genesis-critic) — blind judge; sees only the bar and the real output. VERDICT (WIN/LOSS, or BLOCKED only for a missing perception capability — e.g. a visual bar with no browser/screenshot tool) / GAP / EVIDENCE. A tie is a LOSS.