Spec Graph
The Spec Graph is a formal specification framework for predictable, automated, agent-driven software development. It extends behavior-only specifications into a multi-dimensional graph that captures everything required to predictably manifest a system: behavior, architecture, design, technology choices, domain concepts, and constraints.
Authoring Model: AI-Agent First
Spec Graph can be edited manually, and that is useful for learning and inspection.
However, the intended operating model is:
- AI agents write and refactor spec graph nodes
- AI agents consume spec graphs to manifest systems
- humans supervise, review, and set direction
In practice, this means using agent tooling (typically via MCP) as the primary interface to the graph, while keeping the JSON structure transparent and auditable.
The Core Idea
A Spec Graph is a directed, typed graph where:
- Nodes are atomic specification entries — each one captures a single decision, behavior, concept, or constraint
- Edges express typed relationships between nodes — dependency, constraint, implementation, containment
- Grouping nodes (
feature,layer) are namespaces for vertical slices and shared horizontal capabilities
The Defining Property
The Spec Graph is the minimal structure that, when processed by a capable implementing agent, will always produce logically equivalent manifestations of the designer's intended system.
Two agents given the same spec graph should produce systems that are indistinguishable across every dimension the designer specified — same behaviors, same architecture, same visual presentation, same domain semantics.
What This Framework Produces
The Spec Graph framework is a design specification, not running code. It produces:
- Formal theory — completeness, minimality, predictable manifestation
- Data model — node types, edge types, and their schemas
- JSON Schemas — for validating spec graph files
- Manifestation process — how agents traverse and implement the graph
- Worked examples — realistic spec graphs demonstrating the framework
These artifacts are sufficient for an engineering team to build a Spec Graph-based agentic development platform without further design decisions about the specification format.
Quick Start
If you want to jump straight in:
- Read Motivation to understand the problem
- Use the MCP Server guide for the recommended agent-driven workflow
- Explore the Graph Structure to understand the data model
- Check Getting Started to learn the manual file mechanics
Background
Behavior-only specs are a strong starting point, but by themselves they usually leave key decisions unspecified (architecture, domain boundaries, non-functional constraints, and technology contracts). Spec Graph closes that gap by modeling those dimensions directly in the graph so manifestations are repeatable across implementing agents.