SpecsGraph documentation

What SpecsGraph is#

SpecsGraph holds one model of the system you are building: its bounded contexts, services, requirements, domain vocabulary and the decisions behind them. Engineers and AI agents work on that same model. Agents connect over MCP and propose changes, people review and approve them, and every approved change is committed to your Git repository next to the code.

It is built for engineering teams that write code with AI agents and want a single source of truth that people and agents can both rely on. It works for one developer too: you review your own agent's proposals.

How a change moves through SpecsGraph#

1. 01

   An agent proposes the change

   Your coding agent reads the graph through the SpecsGraph MCP server and drafts a proposal where the change belongs, for example a new requirement in the Orders context.

2. 02

   Requirements gain structure

   The proposal is typed data, not free text: requirements with IDs such as ORD-12, acceptance scenarios written as Given, When, Then, and words taken from your domain glossary.

3. 03

   The spec lands beside the code

   A person reviews and approves the proposal. SpecsGraph then commits it to the specsgraph/ folder on a proposal branch and opens a pull request. Merging that pull request publishes the change, so the spec and the code share one history.

How the spec workflow works follows a real change through every status, from the first draft to the merged pull request.

How it differs from a wiki or a folder of Markdown#

A wiki stores pages and a docs folder stores files. Both hold prose that people and agents have to interpret, and both drift the moment nobody updates them. SpecsGraph stores a typed, linked model instead:

• Structure you can query. A requirement belongs to a context, has a stable ID and links to the terms and actors it mentions. Agents ask for exactly that over MCP instead of searching text.
• One definition per term. The glossary holds each term once, and every place in the model that uses it links back to it.
• Review before it counts. Changes arrive as proposals with review threads on each node. Nothing becomes part of the spec until a person approves it.
• Git history. Every revision is a Git commit you can diff and review. You roll one back by restoring an earlier version through a proposal; see History and versions.

You still get plain files. SpecsGraph writes Markdown and a machine-readable graph.json into your repository, generated from the model so they stay consistent with each other. See Spec files in your repository.

Self-hosted today, Cloud coming soon#

SpecsGraph is fully open source, and today you run it yourself. The self-hosted edition is the complete product and free, and it makes servers, upgrades, backups and your own GitHub App your job. SpecsGraph Cloud, where we run it for you, is coming soon; the pricing page shows what is planned.

Start here#

• Quickstart: install SpecsGraph on your own server, connect Claude Code and publish your first requirement.
• Start from an existing codebase: build a first model of software that already runs.
• Core concepts: the vocabulary these docs use, from workspace down to scenario.
• Connect an agent: set up Claude Code, Cursor, GitHub Copilot or any other MCP client.
• Self-hosting overview: run the open-source stack on your own infrastructure.