Inspiration

I wanted a first hour with COBOL that did not start with a manual or an emulator. The kind of task you would normally do in Python or a spreadsheet — total a sales file, work out compound interest, run a small payroll — should be enough to see how the old language thinks.

The Halloween brief helped set the tone, but the product is a lesson, not a joke. A “ghost programmer” felt like the right voice: patient, a little dry, and always pointing at a real line of code. The proof matters as much as the atmosphere. If the COBOL and the Python disagree, the séance has failed, and the app says so.

I built the app myself in the Kiro IDE, from written specs and a task list, on a $0 stack: Groq’s free tier, OnlineCompiler.io, Pyodide in the browser, and Vercel Hobby.

What it does

Type a task you'd normally hand to Python, like "total the sales in this CSV." A ghost programmer from 1959 answers in COBOL.

Then Séance proves it.

  1. Summon. A real COBOL-85 program appears, line by line.
  2. Run. It compiles and runs on a real GnuCOBOL 3.2 compiler. Nothing is faked.
  3. Haunt. The ghost walks you through the program. A planchette glides to each line it's explaining, and the matching Python lights up beside it.
  4. Resurrect. The same logic comes back to life as Python, running right in your browser, and the two answers are compared.

When they match, the bar says "Python agrees. Both runs print 5871.50." When they don't, the séance has failed, and Séance tells you so.

No sign-up, no install, no COBOL manual. Your first hour with a 65-year-old language is one sentence and about 20 seconds.

Three chips (sales totals, compound interest, payroll with overtime) replay séances captured from the live system, so the demo works even when the free AI tier is busy. You can also type your own task and attach a small CSV (up to 64 KB, 500 rows).

Three of the four chips replay séances that were captured from the live APIs and saved in the repo, so they still work if the language model is busy:

Chip Result both runs print
Total the sales in a CSV 5871.50 (TOTAL SALES)
Compound interest for 10 years 1628.86 (FINAL AMOUNT)
Payroll with overtime 3612.50 (TOTAL PAYROLL)

The fourth chip, “Sort a list of names,” has no saved fixture. Clicking it starts a live summon, the same path as a task you type yourself. In one live run of the sales task with sales.csv attached, both programs printed 5871.50 and the agreement bar read “Python agrees,” in about 21 seconds.

COBOL is the language that answers today. A language picker labelled “Spirit COBOL” is in the top bar; Fortran (b. 1957) and BASIC (b. 1964) are shown as resting and cannot be selected. The workspace follows a desktop three-column layout, a tablet layout that keeps the COBOL pane in view with Ghost / Python / Output tabs, and a phone layout with Code / Ghost / Python / Output tabs and a docked ghost caption on the Code tab. Motion uses opacity and transform only, and it respects prefers-reduced-motion.

The summon, narrate, and run endpoints each allow 10 requests per minute per IP (in memory, best effort, per serverless instance). Successful summon and narrate responses are cached per instance, at most 200 entries each. API keys stay in server environment variables. A test greps the production client bundle and fails if a secret pattern reaches it. npm test currently runs 419 tests, including property-based tests with fast-check. A Playwright smoke test (npm run smoke) checks the sales chip and the landing CTA; it has been run against a local preview and against the live site.

How we built it

The stack is Vite, React, and TypeScript on Vercel. Server routes live in /api: summon and narrate talk to Groq through an OpenAI-compatible client; run talks to OnlineCompiler.io (gnucobol-3.2). The model ids come from LLM_MODEL and, for narration, optional LLM_NARRATE_MODEL (it falls back to LLM_MODEL). On Groq, the build is aimed at gpt-oss-120b for summon and gpt-oss-20b for narration, so the two steps can use separate token buckets. Zod parses every model and runner response before the UI sees it. Pure logic — ranges, stdin encoding, result comparison, rate limits, caches — lives in src/lib/ with no React and no network, which is what the property tests exercise.

The first drafts of the specs and steering were written with an assistant outside Kiro. I then opened the pack in the Kiro IDE, had Kiro analyse the requirements, and implemented the app task by task from those specs. Kiro wrote the application code. I reviewed the reports, deployed to Vercel, and checked the live site.

How I used Kiro

Spec-driven tasks. There are three specs under .kiro/specs/, each with requirements.md, design.md, and tasks.md:

  • seance-core — the end-to-end product: schemas, APIs, workspace, golden chips, language picker, file attach, responsive layouts, landing page, safety, and the smoke test.
  • proof-runner — stdin protocol, compiler line remapping, the agreement comparator, and the runner chain.
  • ghost-narrator — coverage of PROCEDURE DIVISION lines, step repair, voice, and “Let the ghost fix it.”

I ran the core work one task at a time from seance-core/tasks.md. Tasks 11 through 16 are marked complete there (language picker, file attach, responsive layouts and reduced motion, landing page, safety pass, Playwright smoke test). Every task in seance-core/tasks.md is now ticked, and the earlier MVP work (scaffold, libraries, the three APIs, the workspace, deploy, and golden séances) is also in the git history on main. Each task has an entry in docs/kiro-log.md. The proof-runner and ghost-narrator task lists are still open; parts of that design (stdin, line offsets, agreement, property tests) already live in src/lib/ because the core spec needed them.

Steering, in all four inclusion modes.

  • Always on: product.md, tech.md, structure.md, seance-design.md.
  • File match: cobol-generation.md (prompts, the summon and narrate APIs, and golden fixtures).
  • Auto: cobol-primer.md, a short COBOL and GnuCOBOL reference.
  • Manual: demo-day.md, a pre-recording and submission checklist, invoked with #demo-day.

That split mattered. The product and design rules stayed in every chat. The COBOL column and PIC rules appeared when we were actually writing prompts or fixtures. The demo checklist stayed out of the way until it was time to film.

Hooks. Four agent hooks ship in .kiro/hooks/:

  • Guard .kiro and LICENSE (SessionStart) — fails the session if .kiro is gitignored or the MIT license is missing. Kiroween disqualifies a repo that hides .kiro.
  • Block secrets in written files (PreToolUse, on write) — scans the tool input for key-like strings and blocks the write. Keys belong in Vercel environment variables only.
  • Run related tests on save (PostFileSave, on TypeScript under src/, server/, api/, and tests/) — runs the affected Vitest suites, including property tests, and reports failures back to the agent.
  • Log the task and sync docs (PostTaskExecution) — asks the agent to append a short entry to docs/kiro-log.md and to keep the README accurate after each spec task.

Custom agent. cobol-elder is a read-only reviewer. It may read files and run the allowed test commands, and it checks generated COBOL, golden fixtures, narration, and Python translations against the COBOL rules and the design. It does not edit files. Its verdict is meant to be “Fit for the ledger” or “Back to the card punch.”

MCP. .kiro/settings/mcp.json enables a fetch server (mcp-server-fetch via uvx). A git MCP server is defined in the same file but disabled.

Property-based tests. Vitest and fast-check cover the correctness properties in the designs: range intersection and step validation, agreement and number normalisation, input size limits, stdin round-trip, the rate-limit window, and the bounded LRU cache. A separate example test checks that the live sales outputs — COBOL’s edited TOTAL SALES: 5871.50 and Python’s TOTAL SALES: 5871.50 — still agree.

Challenges we ran into

The fourth suggestion chip was supposed to be a fourth golden séance. The repo still has no sort-names fixture. The capture path is real — it calls the deployed APIs — but that program did not come back in a form we could save, so the chip falls back to a live summon. The other three chips do replay from captured fixtures, and a test will not accept a fixture whose COBOL and Python runs disagree.

Talking to a real compiler also took care. GnuCOBOL is strict about fixed format, and the runner compiles with cobc in free-format mode, so the server prepends >>SOURCE FORMAT IS FIXED and then subtracts one from every compiler line number before the UI sees it. Generated programs that used continuation lines, or that tried to DISPLAY money with an EDITED keyword, failed in the sandbox. The summon path now rejects those patterns, and money has to MOVE into an edited PIC before it is printed.

The language model was not always ready with valid JSON, and Groq’s free tier will answer 429 when a bucket is empty. The APIs retry invalid JSON once, wait out short 429s, and cap a long wait so the UI can show a busy state and point the visitor at a cached séance. Narration can use a separate model id so it does not share a tokens-per-minute bucket with summon.

A small hosting surprise: after the landing page moved to / and the workspace to /seance, the /seance/ URL (with the trailing slash) was not being served until a follow-up deploy fixed it. And the landing preview of the ghost had to read its quote and explanation from sales.json itself — “We split the line into region and amount.” — so the picture could not drift from the fixture the chips replay.

Through all of that, the budget stayed at $0. Every service had to have a free tier that did not need a card. That is a constraint, not a slogan, and it shaped the runner and the model choices.

Accomplishments that we're proud of

A visitor can open the live site with no account, click “Total the sales in a CSV,” and watch COBOL, the ghost, and Python arrive at 5871.50 together, even if the model is rate-limited. They can also type their own task, attach a file, and get a live proof. The sales fixture, the landing preview, and the Playwright smoke test all look at the same numbers and the same ghost step, so the demo cannot quietly go stale.

The repo is public, MIT licensed, and includes the .kiro folder. The design system is specific about type, motion, and copy, including a ban on unsourced claims about the COBOL workforce. The safety pass is small and concrete: 10 requests per minute per IP per endpoint, caches capped at 200, and a bundle test for secrets. On 15 November 2026, npm test ran 419 tests and all of them passed.

What we learned

A written spec is only useful if you actually walk the task list and look at each diff. Doing that in Kiro, with steering that loads in different modes, kept the COBOL rules out of chats where they did not belong and in the chats where they did. Hooks are most valuable when they protect a rule you would otherwise forget in a hurry — do not gitignore .kiro, do not write a key into a file, run the tests that this change can break.

I also learned not to trust a generated COBOL program until a real compiler has run it, and not to trust a translation until the two outputs have been compared as numbers, not as strings. COBOL’s edited pictures and Python’s Decimal values look different on the screen and still have to agree. Caching three successful séances made the demo honest: judges should not depend on a free-tier model being free at the moment they click.

The other lesson is editorial. It is tempting to dress a resurrection in big claims about legacy systems. We left those out. The product has to stand on one séance you can watch.

What's next

On the product side, the first gap is the missing sort-names golden fixture, so all four chips can replay from cache. After that, the stretch work already written into the specs: let Fortran and BASIC answer, finish the “Let the ghost fix it” loop, and add “Ask about these lines.” An optional self-hosted GnuCOBOL runner is sketched as a fallback if the free compiler API is busy. None of that is in the live app today, and I would rather show three solid séances than a language picker that pretends they already are.## Inspiration

Built With

Share this project:

Updates

Submission history