SpecFork

Test your spec before agents build three different products.

Comment

Inspiration

Three agents. Three clean diffs. Three green test suites. Three different products.

That's the thing that kept bugging me. Nobody wrote bad code—the code was fine, the tests were fine, everyone was happy—and the team still shipped in three directions. The ticket said what to build, everyone read it differently, and nothing in the toolchain noticed. SpecFork is my attempt to catch that before the team commits to a production implementation.

What it does

You give SpecFork one ambiguous product ticket. It hands that ticket to three independent GPT-5.6 interpretations, turns each interpretation into an observable behavioral contract, and runs the same probes against all three.

On the first full run, everything went green and the conflict panel came back with 10 disagreements. That was the moment. Nothing was broken. The three branches had just quietly built three different things, and every one of them could prove it was correct.

That's what SpecFork calls CODE GREEN / SPEC RED. It pulls the conflicts straight out of execution, asks you one clarification question—the one that actually collapses the ambiguity—and hands back a converged executable spec.

How I built it

Codex, GPT-5.6, React, TypeScript, the OpenAI Responses API, Git worktrees, and Docker.

There are two halves. The public site runs a credential-free Demo Mode, so you can walk through the whole flow right now without an API key. The local Agent Runner is where the real work happens: ask GPT-5.6 for three patch proposals, push each through a shared policy gate, commit whatever survives into its own Git worktree, and run the constrained fixture in a hardened container.

Hardened means no network, a read-only filesystem, dropped Linux capabilities, no-new-privileges, and hard caps on CPU, memory, process count, and wall-clock time. The conflict count is computed from what the containers actually printed—none of it is hard-coded—which brings me to the part I got wrong first.

Challenges I ran into

The evidence layer was wrong. Not intentionally, but an early build would cheerfully report a curated conflict score even after the underlying branch behavior changed. The number just sat there while the thing it was supposed to measure moved. So I tore the whole path out and rebuilt it on shared probes and a diff helper. Now every conflict traces back to real output or it doesn't exist.

A source-code denylist is not a sandbox. I wanted it to be. It's a fine fast pre-filter, and I kept it for that. But the isolation and resource limits are the actual security boundary, and pretending otherwise was just me putting off the container work.

Object shape isn't behavior. Two implementations can give you the same user-visible result and structure it completely differently. If you assert on the structure, you fail branches for no reason. So I added normalization and regression tests around the part a user could actually see.

Accomplishments I'm proud of

  • Ticket goes in, converged spec comes out. The whole loop works.
  • Three genuinely reasonable branches, all passing their own contracts.
  • 10 observable conflicts, every one derived from a real run.
  • GPT-5.6 → policy gate → Git worktree → hardened container, verified end to end.
  • 16 automated tests covering behavior, malformed input, policy bypasses, and response validation.
  • Demo Mode requires no API key.

What I learned

Better coding models make specification testing more important. When implementation gets cheap, ambiguity is what's left. Your tests prove the code matches an interpretation. They say nothing about whether anyone else picked the same one.

Also: Codex was at its best when I stopped asking it to build and started asking it to break. I pointed it at the patch gate, the evidence path, container cleanup, probe integrity, and frontend failure states—and it kept finding things I'd have shipped.

What's next

Safe repository intake: dependency and lockfile policy, secret scanning, artifact retention, and a remote disposable runner protocol. SpecFork has no business touching an arbitrary repository until all of that exists.

Built With

Share this project:

Updates