Skip to content
Docs

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

  1. 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.

  2. 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.

  3. Agree a task

    A task (T-4) scopes the changes that ship together. Open questions are answered in threads on the artefacts; a blocking question holds the task until someone answers it. A person marks the task Ready.

  4. 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.

  5. 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

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

  • Getting started

    What SpecsGraph is, the core ideas and a first spec change in your workspace.

  • 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.

  • Agents and MCP

    Connect Claude, Claude Code, Cursor, GitHub Copilot or any MCP client to the spec.

  • Git and publishing

    How approved changes become commits and files in your repository.

  • SpecsGraph Cloud

    The hosted service: plans, seats, security and what happens to your data.

  • Reference

    Answers to common questions and the methods SpecsGraph builds on.