SpecsGraph documentation
SpecsGraph is a spec of your software system that engineers and AI agents shape together over MCP, reviewed once by people and published to Git with the code.
What SpecsGraph is
SpecsGraph holds the spec of the system you are building as typed artefacts: subdomains, bounded contexts and the glossary, the aggregates, value objects and enums inside the contexts, use cases, event handlers and scheduled jobs, data contracts, read models and integration events, the product side (features with their scenarios, and roles) and the architecture records: decisions and constraints. Engineers edit the spec in the web app; AI agents read it and stage changes over MCP. People accept what agents stage, and a task publishes the agreed changes to Main and to your Git repository. Then the task's work items track the code until it is built, deployed and verified.
It is built for teams that write code with AI agents and want one source of truth that both can rely on. It works for one developer too: you review your own agent's staged changes.
How a change moves through SpecsGraph
Open a workstream
A workstream (
WS-3) is a branch of the spec for one story or change request. Its view is Main plus the changes made in it. Give it the tracker key of the story (KAN-43) and a first task.Edit, or let an agent stage
People edit artefacts directly in the workstream. An agent stages its edits over MCP into the workstream's proposal, grouped into plans for tasks; a person accepts them once, and they become changes of the workstream.
Publish to Main and Git
Publishing a Ready task writes its changes to Main and to your repository, as a commit or a pull request. When the pull request merges, Main advances and the task is Done by itself.
Build and deliver
A Ready task gets work items: implement, deploy, verify. People and agents claim them; a merged pull request that names the item and a deployment reported by CI complete them; a person records the verify result. The Build page shows what is built on Main, and the Roadmap what comes next.
How the spec workflow works follows one change through every state.
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 spec instead:
- Structure you can query. A use case belongs to a bounded context, names its roles and its inputs, and refers to aggregates by id. Agents read exactly that over MCP instead of searching text.
- One definition per term. The glossary holds each term once, per context or project-wide.
- Review once. Agents stage what they change and a person accepts it, unless a project turns on Agent autonomy; either way, nothing reaches Main until a person publishes a task.
- Git history. Every publish is a commit of YAML files you can diff, next to your code; see Spec files in your repository.
- Build status per artefact. Merges and deployments tell SpecsGraph what is coded, deployed and verified, so the spec shows what is built instead of what someone remembered to tick.
A hosted service
SpecsGraph runs as a hosted service, SpecsGraph Cloud. We look after servers, upgrades, backups, security and the GitHub App that publishes your spec, so there is nothing to install or operate. The pricing page shows the plans, and Security and your data explains what we store.
Start here
- Quickstart: create an organisation, connect an agent and publish a first change.
- Start from an existing codebase: build a first spec of software that already runs.
- Core concepts: the words these docs use, from organisation down to scenario.
- Connect an agent: Claude Code, Codex, Cursor or any other MCP client.
For the practices behind the product, read about AI-native software development, spec-driven development, context engineering, AI agent collaboration and requirements traceability.
Browse the docs
Model your system
The spec and its 16 kinds: contexts and the glossary, the domain model, behaviour, interfaces, features, roles, decisions and constraints.
Collaborate
Workstreams, changes, tasks, proposals, questions and decisions, then work items, build status and the roadmap.