Forge: The Spec-First Operating System for AI Coding

ArenixDev/forge turns instructions into a governed hierarchy, strips ambiguity out of prompts, and makes AI prove it can follow the contract before code is trusted.

10 min read • View on GitHub • More from arenixdev

By Repo Explainer • AI-assisted • Published by Ron Kurti

Published Apr 14, 2026 • Coding Agents

A wide editorial scene shows a white courtroom-like chamber where a bound specification sits on a pedestal under layered documents labeled as governing layers. A machine arm points toward a printout of code, but the code sits lower and farther away, showing that the specification outranks implementation. — Forge treats the spec as the authority and the code as the test. That inversion is the project’s whole argument.

Key Takeaways

Forge argues that the spec is the real artifact, and code is only evidence that the spec can survive execution.
Its governance model separates load-bearing rules from conventions, so AI does not flatten critical decisions into style noise.
TONIC, cold validation, and semantic checks work together to turn vague intent into a tighter contract.
The deepest value is backward as well as forward: Forge can recover intent from legacy systems and harden it into something reusable.

Most AI coding tools optimize for output. Forge optimizes for authority. It treats the prompt as the least reliable part of the system and pushes meaning upward into a governed spec stack: constitution, conventions, domain docs, and validation rules.

That sounds bureaucratic until you notice the real target. Forge is not trying to make the model more creative. It is trying to make the model more accountable.

The Spec Is the Product

The project’s most important move is also the simplest: it promotes the specification from support material to source of truth. Code becomes a byproduct that proves whether the specification is tight enough, not the thing you start from.

That changes the failure mode. In a prompt-first workflow, vague instructions leak directly into vague code. In Forge, vague instructions fail earlier, when the spec is still editable and the cost of correction is low.

A CLI tool for iterative AI-driven development planning. Uses LLM agents to generate comprehensive development plans, review them for quality, and refine based on feedback.

Andrey Moor, Project Creator/Maintainer · andrey-moor/plan-forge README

Constitution, Conventions, and Why AI Needs a Chain of Command

Forge’s hierarchy matters because AI models are good at smoothing distinctions away. If everything is just another instruction, the model will happily average important rules with cosmetic ones. Forge resists that by separating load-bearing constraints from style preferences.

The enforcement loop turns intent into a contract by repeatedly tightening ambiguity until a cold reader can proceed without asking for clarification.

# Authority order

1. Constitution
2. Conventions
3. Domain docs
4. Implementation notes

If a lower-level document conflicts with a higher-level one, the higher-level rule wins.

That is not just a documentation trick. It is a way to stop the model from resolving contradictions on its own terms. When authority is explicit, the AI is forced to negotiate within the system instead of inventing its own hierarchy.

TONIC: Naming the Thing the Model Wanted to Do

TONIC stands for Technically Obvious, Not Intended Choice. It is a small idea with sharp teeth. Instead of only telling the model what to do, Forge records what not to do, which closes off the most tempting wrong turn.

A close-up of a hand filling out a table where a preferred path is written on the left and a rejected alternative is stamped on the right. A rigid guide rail bends a default route away from the page, showing how negative constraints shape the model’s choice. — TONIC captures negative knowledge. It tells the model which technically obvious answer is not the intended one.

Approach	What it optimizes for	Failure mode	How Forge differs
Prompt-first vibe-coding	Speed and momentum	Hidden ambiguity turns into bad code	Moves ambiguity into the spec where it can be tested
Generic planning tools	Task decomposition	Plans can still drift from implementation reality	Makes the spec hierarchically enforced and validation-ready
Descriptive documentation	Human readability	Docs explain without constraining	Docs become a contract with negative and positive rules

This is the repo’s smartest bias correction. Forge does not just prefer one implementation path. It records the rejected path, which is often the only way to keep a model from wandering back to the ecosystem’s default answer.

Cold Validation Treats Missing Spec as a Bug

The cold reader idea is a clean-room test for meaning. A fresh session gets the spec and tries to move forward. If it gets stuck and asks a question, Forge treats that question as a defect in the specification.

Cold reader sees spec -> asks no questions -> proceeds
Cold reader sees spec -> asks question -> log defect -> tighten spec -> rerun

That framing is powerful because it changes the emotional tone. The goal is not to make the model obedient for its own sake. The goal is to make the spec legible enough that obedience becomes almost boring.

The Tooling Layer: Graphs, Semantics, and Orphan Detection

Forge’s Python tooling turns the methodology into enforcement. One layer checks the architecture as a graph. Another checks semantics for contradictions, orphaned sections, and ambiguous language. Together they make the spec machine-auditable instead of merely organized.

Check	What it catches	Why it matters
Graph validation	Illegal dependencies and circular structure	Prevents the spec from contradicting its own architecture
Semantic sweeps	Conceptual mismatches and vague language	Reduces room for AI interpretation drift
Orphan detection	Unreferenced sections and dead branches	Forces the spec to remain connected

This is where Forge stops feeling like documentation and starts feeling like instrumentation. The repository is asking a different question than most toolchains: not "Is this written clearly?" but "Can this survive a machine trying to follow it literally?"

BackForging Legacy Code

The backforging idea is the project’s best argument for relevance beyond greenfield work. It says existing systems are not just codebases to be explained. They are evidence from which durable intent can be reconstructed.

That is a more strategic posture than standard documentation. Traditional docs describe what happened. Backforging asks what this system was for, then turns that answer into an artifact the next AI session can actually use.

In practice, that means the spec is no longer a blank-room fantasy. It can be recovered from real systems, sharpened, and used to govern new work instead of merely memorializing old work.

Where Forge Fits, and What It Replaces

Forge sits earlier than code generation and later than a rough idea. It is not trying to replace editors, agents, or coding assistants. It is trying to replace the slippage that happens when those tools are asked to guess too much.

Tooling style	Best at	Weak spot	Forge’s position
Copilot-style assistance	Filling in code quickly	Can inherit bad assumptions	Downstream of the spec
Planner or agent loops	Breaking work into tasks	Plans may still be soft	One layer earlier, where meaning is hardened
Traditional docs	Sharing context with humans	Not enforceable by default	Turns context into a governed contract

The practical takeaway is simple. If your biggest problem is writing code faster, Forge is probably overkill. If your biggest problem is getting AI to mean the same thing twice, Forge is aiming at the right layer.

That is why the project feels less like a helper and more like a control system. It is built to reduce variance before variance becomes expensive.