Inspiration

Everyone has a graveyard repository: a Python 2 tool from 2012 that “still works, don’t touch it,” a side project whose CI died with Travis, a library nobody dares upgrade. Migrating that code is real, unglamorous, risky work. Static analyzers produce walls of warnings nobody reads, and “just ask an LLM to rewrite it” produces confident code nobody can trust.

I wanted a tool that makes legacy-code triage memorable and trustworthy at the same time. Tarot gave me the right metaphor. A reading is a small, ordered set of cards, each with a position and a meaning, and orientation (upright or reversed) carries information. That turns out to be a strong information architecture for a code-health report: a few cards that matter, laid out as a story (Past, Present, Future), instead of 400 lint lines.

Then I added the Halloween twist. The oracle doesn’t stop at telling you your code is dead. She raises it.

What it does

The Necro-Oracle is a retro CRT terminal styled as a Game Boy (DMG) cartridge from a haunted 1986: a strict 4-shade phosphor palette, pixel-art Major Arcana, scanlines, and an original chiptune theme synthesized at runtime. Behind the costume is a serious engineering pipeline:

  1. Summon. summon owner/repo pins any public GitHub repository to an exact commit SHA and downloads it as untrusted data (it is parsed, never executed).
  2. Read. read fates, read necropsy, or read celtic runs a 12-card diagnosis deck, one deterministic detector per card (tree-sitter AST, manifests, OSV advisories). Upright means an active problem; reversed means latent risk. Each card shows its evidence (file, line, finding). The reading ends with a 0–100 vitality gauge. The product rule, enforced in code, is “the cards cannot lie”: a deterministic detector decides whether a card is drawn, and the LLM never does.
  3. Explain. explain <position|card> opens the evidence scroll behind any card. Positions 1, 2, and 3 can also be named past, present, or future.
  4. Resurrect. resurrect revives Python 2 files as Python 3. A deterministic Pre_Pass of six idempotent fixers runs first (print statements, except E, e:, <>, long literals, dict iteration methods, unicode/str). The LLM only sees residual diagnostics the fixers could not resolve, chunked so each prompt contains only the relevant part of the file. Every output must pass a validation gate (tree-sitter parse with zero error nodes, plus an AST check that no Python 2 construct survives) or it is rejected. You then see the Necronomicon ritual, a unified diff, the before/after vitality, and a downloadable patch.
  5. The Lovers (Frankenstein binding). lovers <file> js stitches a resurrected Python 3 file to a JavaScript client. A deterministic AST template always emits the Python “heart” (a JSON-lines dispatcher). A routed LLM generates the JS “beloved” (a client that spawns the heart, never a reimplementation), a JSON contract schema, and contract tests on both sides. The result is checked with tree-sitter for both grammars plus a static deny-list scan (no eval, network, or filesystem writes) and delivered as a ZIP.
  6. Tarot (ceremonial draw). tarot [question] draws three distinct cards from the full 22-card Major Arcana with a crypto RNG and gives a staged ceremonial reveal plus a deterministic offline reading. A model-backed /api/tarot route is built and tested in the core, but wiring it live is still on the roadmap — the app does not claim that path is live.
  7. Bring your own key. key set, key status, and key clear let a visitor use their own OpenRouter key for this browser tab only. The key is never persisted.
  8. Delight and access. A guided clickable menu, offline demo replays (demo lich-py2 and others) that cover reading, resurrect, and Lovers under a Mock LLM, runtime-synthesized music (no audio files), and full keyboard, screen-reader, and reduced-motion support.

The app also works with zero AI. With no key configured, readings still render, resurrection still runs the deterministic Pre_Pass, Lovers still runs from Mock fixtures, and tarot still uses its offline reading.

How we built it

This is a solo project, built with Kiro during the Kiroween 2026 submission period. The public repo was created on November 3, 2026, and the write-up records 86 commits from November 3–9, with later UX polish and a README update at 17f6ddb.

The architecture is a TypeScript pnpm monorepo on Next.js / Vercel. Dependency direction is enforced by tests: oracle ← grimoires ← coven ← web. @necro/oracle is pure and browser-safe. The only network-capable LLM module sits behind an injected port, and a static guard test proves the rest of the LLM package cannot reach the network. The terminal’s initial JavaScript stays under a 250,000-byte gzipped budget (201,091 bytes at the last measured gate).

Kiro work was deliberately spec-driven. The committed .kiro/ directory holds 10 specs (168 requirements, 1,011 acceptance criteria, 716/716 task checkboxes ticked, 173 named correctness properties), 9 steering files, 2 agent hooks, and MCP config for GitHub and Context7. Requirements-first specs covered new ground; design-first specs, grounded in facts read from the committed code, covered additive layers. Exploratory spikes stayed conversational — for example a tar-stream characterization test decided the extractor design before the spec committed to it. Anything that touches correctness, security, or the wire protocol went through a spec.

AI usage inside the product follows the same rule as the cards: deterministic first, LLM last, and never trusted without a gate. A pure model router picks FAST for simple units and escalates to STRONG only when a unit is hard. Each unit gets at most two calls, each reading is capped, completions are cached by a content-addressed key that never includes the user’s key, and if the model fails the deterministic result still ships.

A longer, feature-by-feature account of how Kiro was used — including vibe coding versus specs, hooks, steering, MCP, property-based testing, and an honest note about what is not claimed — is in the “How Kiro was used” field and in docs/KIRO_USAGE.md.

Challenges we ran into

WebAssembly on serverless was the hardest infrastructure problem. Tree-sitter grammars are .wasm files that Next.js output tracing and Vercel’s packaging both fought. A dedicated fix-wasm-tracing spec and a post-build gate landed first; production then failed again when traced paths went through pnpm symlinks, which Vercel rejects. The fix was to copy the grammars as real files, make the gate symlink-aware, and pin the Vercel runtime to Node 22.x.

A strict Content Security Policy with no 'unsafe-inline' also collided with a pixel-art UI. Every dynamic style (card scale, glitch offsets, ritual timing) had to move to CSSOM custom properties.

Encoding hazards hid from unit tests: a BOM-prefixed package.json broke PostCSS, and mojibake em-dashes broke SWC even though Vitest and tsc accepted them. Honest Playwright runs found real bugs I first wanted to dismiss as pre-existing, including an illegal card id used as the Lovers precondition.

Layout in a real browser was the last hard problem. Results had to live inside the 100dvh scroll pane so they no longer sat as a solid block over the card art. Auto-scroll to the very end after resurrect or lovers is still imperfect on some screens (see Known issues in the judges’ testing instructions).

Accomplishments that we're proud of

  • 3,091 unit and property tests passing across 301 test files, plus 52 Playwright e2e tests, with typecheck, lint at 0 warnings, the production build, the bundle budget, and the symlink-aware WASM-trace check all green.
  • 168 requirements and 1,011 acceptance criteria, traceable to code and to 173 named properties; 716/716 spec task checkboxes ticked.
  • Production proof on https://necro-oracle.vercel.app (2026-11-09): a live summon and reading of tomaes/pytarl; a live resurrect of pytarl.py that fully converted with zero residuals and no LLM cost, vitality 0 → 12, Judgement removed, in about 3 seconds (the deterministic Pre_Pass did the work); a later live Lovers binding of lovers pytarl.py javascript that bound 7 functions and returned the Python heart, JS beloved, contract schema, and tests on both sides for 6,418 tokens and 0.0842 USD.
  • A finished-feeling product — boot sequence, Game Boy menu, pixel-art arcana, Necronomicon ritual, original synthesized soundtrack, and offline demo autoplay — inside a 250 KB first-load budget.
  • An AI pipeline whose LLM can only make things better. It can never draw a card, skip a gate, or leak a key. FAST/STRONG routing and residual-only chunking keep spend tiny; BYOK keys stay in tab memory only.

What we learned

Specs pay off when they are written against the real code. Design-first with grounding facts beat requirements-first for every additive layer. Steering is most effective when scoped narrowly with fileMatch, so Kiro received LLM-contract rules only in the coven and LLM packages, and UX rules only in the UI. Hooks turned discipline into a default: commit only when green, but allow planned test-first red. Property tests were the best reviewer for anything generated, whether code from an LLM or code from an agent.

The expensive lesson was prompt scope, not the spec method itself. Early on, broad prompts let Kiro spawn many sub-agents and rerun the full suite after every small change, which burned credits and left scattered results. Short, self-contained prompts — no sub-agents, a minimal diff, and only the touched tests plus lint, typecheck, and build — brought a focused fix down to about 8–33 credits. jsdom unit tests also cannot catch real layout and scroll bugs; those need a real-browser Playwright test that replays the exact user flow, written to fail first.

What's next

  • Wire the already-built model-backed tarot reading (/api/tarot) into the terminal. Today the ceremonial draw ships with deterministic offline text.
  • Sandboxed differential verification: run the original and resurrected code side by side inside a per-ritual micro-VM. An optional E2B py_compile provider already exists behind a port.
  • Open a real pull request against a fork of the target repo, so “REVIVED” means proven and delivered.
  • Chaos mode: the oracle deliberately rots a healthy repo with seeded, reversible mutations and challenges you or an agent to resurrect it under the gates.
  • Bring the oracle everywhere: necro-mcp so Kiro itself can consult it, a necro CLI, and a GitHub Action that reads tarot on every PR. The packages are scaffolded, and the core is already a reusable library.
  • More grimoires, including packaging (setup.py to pyproject) and jQuery to vanilla ES2022.

Category

Frankenstein. The Necro-Oracle stitches together pieces that have no business working together: a 1986 green-phosphor terminal in Game Boy pixel art, 15th-century tarot, tree-sitter WebAssembly static analysis, a deterministic codemod engine, LLM routing across model families, and a Python-to-JavaScript binding that literally stitches two runtimes together through a JSON contract. The result is useful rather than a gimmick: the tarot spread is the information architecture.

It also fits the Resurrection brief — it brings dead technology (Python 2 code, 8-bit handheld aesthetics, CRT terminals) back to life with today’s tooling — and the Costume Contest brief, because the spooky UI enhances function: orientation, position, and the vitality gauge carry the diagnosis. The official submission category is still Frankenstein.

Tarot card art derives from the Rider–Waite–Smith deck illustrated by Pamela Colman Smith (1909), public domain. Pixel-art faces in the app were generated by the author and quantized to the 4-shade palette. All music is synthesized at runtime; there are no audio files. pytarl is © Thomas Gruetzmacher, CC-BY, and is used only as a public demo target, not as part of this project’s source.

Built With

  • axe-core
  • fast-check
  • kiro
  • next.js
  • node.js
  • openrouter
  • playwright
  • pnpm
  • react
  • redis
  • tree-sitter
  • typescript
  • upstash
  • vercel
  • vitest
  • web-audio-api
  • webassembly
  • zod
Share this project:

Updates

Submission history