SpecGraph

A live spec-driven development framework — specifications as a queryable graph, not static markdown.

SpecGraph provides a spec schema, an authoring funnel, a project constitution (layered ground truth), and a storage + query layer that feeds agentic execution systems. It turns design intent into structured, claimable work units that agents and humans can pick up, execute, and verify.

Why

Existing spec frameworks treat specifications as static documents. This creates gaps:

• No live query layer — you can't ask "what specs are blocked?" without parsing files
• No addressability — specs reference each other by filename, not stable identity
• No execution interface — agents need a task graph, not a folder of markdown
• No ground truth — every authoring session starts from scratch

SpecGraph closes these gaps by modeling specs as nodes in a graph with first-class edges for dependencies, blocks, and compositions.

Architecture

┌─────────────────────────────────────────────────┐
│                  Authoring Funnel                │
│  Spark → Shape → Specify → Decompose → Approve  │
└──────────────────────┬──────────────────────────┘
                       │
              ┌────────▼────────┐
              │   Spec Schema   │
              │  (protobuf v1)  │
              └────────┬────────┘
                       │
          ┌────────────▼────────────┐
          │      Constitution       │
          │  User → Org → Project   │
          │       → Domain          │
          └────────────┬────────────┘
                       │
              ┌────────▼────────┐
              │  ConnectRPC API │
              └────────┬────────┘
                       │
              ┌────────▼────────┐
              │  Graph Storage  │
              │   (Memgraph)    │
              └─────────────────┘

Key concepts

• Specs are graph nodes with edges for dependencies, blocks, and compositions
• Constitution provides layered ground truth — more specific layers override general ones
• Decisions are first-class nodes with bidirectional edges to specs (see ADR-003)
• Authoring funnel guides specs from rough idea to agent-executable work unit

Getting Started

Quick start

Initialize a SpecGraph project in your repo:

specgraph init              # interactive setup (storage backend, deployment mode)
specgraph init --scan       # also scan codebase and draft a constitution

The --scan flag walks your codebase to detect primary language, frameworks (API, CLI, UI, testing), infrastructure (Docker, Kubernetes), and CI provider, then writes a constitution.yaml draft you can refine.

Start the server and begin working with specs:

specgraph serve             # starts the API and manages Memgraph via Docker Compose
specgraph spec create auth-login --title "User login flow"
specgraph constitution show # view project ground truth

In docker mode (the default), serve automatically starts and stops the Memgraph container alongside the ConnectRPC API — no external setup needed.

Beyond quick start

Setup	Mode	Description
Solo / local	docker (default)	specgraph serve manages everything
Team / shared server	remote	Point CLI at a shared SpecGraph instance via config
Production / BYO infra	external	Connect to your own Memgraph or Postgres

See the deployment guide for team and production configurations.

CLI overview

Command	Description
specgraph init	Initialize project config and optionally scan for constitution
specgraph serve	Start the ConnectRPC API server
specgraph spec create/list/show/update	Manage specs
specgraph decision create/list/show	Manage decisions
specgraph constitution show/check/emit	View and validate project constitution
specgraph claim/unclaim	Claim or release specs for work
specgraph edge add/remove/list	Manage graph edges between specs
specgraph deps	Show dependency tree for a spec

Contributing

Prerequisites

• Go 1.25+
• Buf (protobuf code generation)
• Task (task runner)
• Docker (for Memgraph integration tests)

Install development tools

task tools

Build

task build

This runs protobuf code generation (buf generate) then builds the binary.

Run tests

task test          # all tests
task test:short    # skip integration tests
task test:e2e      # end-to-end smoke tests

Run the server locally

task dev                    # development mode with hot reload

Development

Code generation

Protobuf sources live in proto/. Generated code goes to gen/ (gitignored). Regenerate after changing .proto files:

task proto

Formatting and linting

task fmt           # format all files (Go, YAML, Markdown)
task lint          # run all linters

Git hooks

The project uses Lefthook for pre-commit hooks (license headers, golangci-lint, yamlfmt, dprint, conventional commits):

task hooks:install

Roadmap

Phase	Focus	Status
1 — Foundation	Spec schema, constitution, storage, claim protocol, execution bundles, CLI, linter	Complete
2 — Authoring & CLI	Codebase scanner, authoring flow, Claude Code plugin, constitution sync	In progress
3 — Coordination	Multi-agent leasing, MCP server, drift detection, exports, Gastown integration	Planned
4 — Scale	Federation, multi-repo, metrics, governance	Planned

License

MIT — Copyright 2026 Sean Brandt