Make your AI stop guessing.
Forge is a system for writing specifications precise enough that AI agents build what you want without guessing. It works for solo developers, teams, and organizations. It works for code, policy, legal, and anything else where precision matters.
Reduce ambiguity. Reduce probability. Increase deterministic outcomes.
Five minutes (MiniForge): Drop the MiniForge prompt into a session with your project. It reads your code, asks five questions, and tells you honestly whether your project needs more structure.
One file (Machine Reference): Copy forge_rules.md into your project root or CLAUDE.md. Your AI assistant reads it and follows the methodology.
Full methodology (JSON): Drop forge.json into your project. Ask your AI: "Read this methodology, look at my project, and tell me what level of Forge I should use."
methodology/ The full methodology (15 docs + prompts)
reference/ Ambiguous language dictionaries, flagged vocabulary
examples/ Working examples of every artifact type
tooling/ Graph parser, semantic analyzer, Docker stack (optional)
forge.json The entire methodology in one machine-readable file
forge_rules.md Compact machine reference (drop into your project)
Forge has properties (artifacts you produce) and methods (practices that validate them).
| Artifact | What It Does |
|---|---|
| Conventions Doc | Locks your stack choices. Lists forbidden alternatives. Highest immediate ROI. |
| WHY Blocks | Explains why a decision was made AND why alternatives were rejected. Stops agents from "optimizing" away your constraints. |
| TONIC Table | Lists the wrong-but-reasonable choices an agent will make. "Use prost, not tonic. Here's why." |
| Constitution | 3-15 immutable laws your system cannot violate. Derived from your decisions, not written upfront. |
| Decision Tracking | Decided/Open Questions with status annotations. Every decision is explicit. |
| Glossary | Narrows the probability distribution for every project-specific term. |
| Practice | What It Does |
|---|---|
| Cold Validation | Fresh AI session reads your spec and produces a plan. Every question it asks is proof the spec is ambiguous. |
| Cold Code Runs | Fresh session builds from the spec. The code is disposable. The deviations reveal spec defects. |
| Cascading Consistency | After every change, propagate across all cross-references. |
| Multi-Model Validation | Different models find different gaps. Where they converge, the spec is clear. |
| Semantic Review | Scan for probabilistically wide language ("should," "appropriate," "handle gracefully"). |
IDEATE Conversations. Capture verbatim. "Forge it" at breakpoints.
FORMALIZE The AI produces domain docs, conventions, glossary, constitution.
VALIDATE Graph analysis + dictionary lint (optional tooling).
COLD VALIDATE Fresh session reads docs. Questions = doc defects. Fix. Repeat.
COLD CODE RUN Fresh session builds from spec. Code is disposable.
SIGNAL Models converge. No more spec-driven deviations.
IMPLEMENT Code generation is translation, not design.
Not every project needs the full pipeline. Start with what fits your situation.
| Situation | Start With |
|---|---|
| Vibe-coded project getting messy | MiniForge (5 minutes) |
| Small project, low stakes | Conventions doc + WHY blocks |
| Large project, high stakes | Full pipeline |
| Inherited codebase | BackForge protocol |
| Team adoption | Teams guide |
See adoption.md for maturity tiers, order of operations, and the first 48 hours playbook.
Drop the tooling/graph/droppable/ folder into your project for architecture validation. No Neo4j required. Uses networkx (in-memory Python graph) by default.
pip install networkx
cd tools/forge_graph
# Edit forge_graph.toml with your project details
python forge_graph.py validateSee the tooling README for details.
Drop the tooling/semantic/droppable/ folder into your project for semantic consistency checking. No Weaviate required. Uses SQLite + sentence-transformers locally.
pip install sentence-transformers sqlite-vec numpy
cd tools/forge_semantic
# Edit forge_semantic.toml with your project details
python forge_semantic.py load # Embed your docs (~30 seconds first run)
python forge_semantic.py sweep # Concept reachability report
python forge_semantic.py query "error handling" # Ad-hoc search
python forge_semantic.py consistency # Cross-doc contradiction check
python forge_semantic.py orphans # Find isolated contentNo Docker, no API keys, runs on CPU. See the semantic README for details.
Not a substitute for engineering. Forge makes your spec precise. It doesn't make it correct or complete. If you forget to specify something, Forge won't invent it for you.
Not waterfall. The spec is a living artifact that tightens through contact with reality. Code teaches you things the spec can't anticipate. Forge captures the discoveries.
Not just for code. Policy, legal, compliance, thesis writing. Anything where a cold reader needs to act on the spec without guessing.
MIT. See LICENSE.
Larry Diffey / Arenix