Eureka/README.md

Eureka

An agent that plans, implements, tests and reports on its own work will hand you green tests and a clean report over a broken machine. Not because it lies, but because its tests pin its own spelling, and its report is written by the party with the most reason to believe it.

Eureka is a Claude Code skill that takes that job apart. One agent maps the change, a second executes exactly one cut of it, and a third — which did not write the code, and is told to attack it — tries to prove the second one wrong. The operator rules on anything that is genuinely a product decision. Nothing grades itself.

In the migration it was extracted from, 29 of 32 independent falsification passes found real defects that the implementing agent's own tests had passed — about 75 in all, among them deadlocks, lost writes, a wire-parity split between two runtimes, and operator rulings with no test behind them. references/postmortem-cultcache.md carries the evidence.

What that actually looks like

Four from a single day, each found by a pass that did not write the code:

• A rule everyone agreed could not be tested. The implementer said so honestly in the entries file rather than faking a kill. A fifteen-line probe reached it in about a millisecond, and the mutant crashed an ordinary optimised build on contact. The suite and the prose agreed with each other, and both were wrong.
• A mutation history that did not exist. Every kill a native bridge had ever reported came from harnesses living in agents' scratchpads. When a later pass went to check two of them, their definitions were gone, and the rules they had defended were defended by nothing anyone could rerun.
• Three passes to pin one line. A rule said a wait must be the timeout the caller asked for. The first suite proved the wait was not one particular constant. The second proved it was not any constant. Then a clamp — cap the wait so shutdown gets noticed, the most ordinary way that line ever gets written — walked through the entire matrix on both platforms.
• A document the system accepted and could never return. Admission took a record 86,751 bytes larger than the transport could carry. Measured against a real client, not inferred.

Each became a rule in references/changelog.md, with the evidence that motivated it. The skill is accumulated scar tissue, not a design.

The pipeline

• Self routes the work, admits the campaign and the operator's rulings, and talks to the operator.
• Imagination specifies each cut: deletes first, an authority map for anything that changes ownership, and verification naming the rule each test pins.
• Hands executes one cut, in small pushed commits, and admits a report.
• Soul runs against the executed commits and tries to falsify every promise, building its own probes rather than trusting the report.
• Life keeps memory honest at phase boundaries.
• The operator rules on real forks, and only on real forks.

It is the Claude Code counterpart of Epiphany, and shares its faculty vocabulary.

Install

git clone https://github.com/GameCult/Eureka.git ~/.claude/skills/eureka

Claude Code discovers the skill from the name and description in SKILL.md.

Layout

• SKILL.md: the pipeline — the faculties, the loop, Self's discipline, and the git and tooling rules, each of which exists because something broke.
• tools/stopgap/ygg-verify.sh: runs a verification job for an exact revision on Yggdrasil in a capped container. It is a stopgap until Idunn's verify transaction lands.
• references/briefs.md: brief templates for each faculty.
• references/campaign-state.md: the typed document set, the selection recipes every faculty reads state through, and the prose map's shape.
• references/postmortem-template.md and references/postmortem-cultcache.md: the template and the worked example.
• references/epiphany-comparison-2026-09-15.md: a dated, source-grounded comparison with Epiphany.
• references/changelog.md: every change to the skill, with its evidence.

Status

Campaign state is typed. Questions, rulings, cut specs, reports, verdicts, findings, follow-ups and resolutions are documents in the instance's mind, held by the Huginn memory organ and reached through the huginn CLI. Epiphany owns the schemas (epiphany-pipeline) and Huginn owns admission. The committed prose keeps only body facts, the model page and rationale.

The skill needs the huginn CLI on PATH, with EUREKA_INSTANCE and HUGINN_ENDPOINT in the environment, and a reachable daemon. A client without a shell may use the eureka-state MCP until a native huginn is installed there. Without one, the pipeline stops rather than keeping state anywhere else.

Maps and postmortems are public artifacts from the first cut, with the scars left in. That is deliberate: a pipeline whose record has been tidied up is a pipeline you cannot check.