GraphSpec

GraphSpec is a tiny, text-first language for describing process logic as states and events.

It is an implementation-agnostic, non-executable contract: it defines allowed states and the events that trigger transitions between them, not how they run.

It intentionally excludes runtime semantics like timing, concurrency, side effects, and variables.

It can also describe a lightweight agentic operation boundary inside Markdown specs or skills, with enforcement left to tooling.

Quickstart

Install:

• download a prebuilt binary from GitHub Releases (tags v*)
• from a clone: go install ./cmd/graphspec
• or with Go: go install github.com/justinphilpott/graphspec/cmd/graphspec@latest Ensure your Go bin is on PATH:

export PATH="$PATH:$(go env GOPATH)/bin"

Validate a file:

graphspec check path/to/spec.graph

Validate Markdown (only fenced graph blocks are checked):

graphspec check docs/spec.md

Verbose mode (includes counts + timing):

graphspec check -v examples

Errors are printed as file:line:col error <message> and a non-zero exit code is returned.

Top use cases

• Embed GraphSpec in Markdown specs/skills so humans and LLMs share a low-token, validatable process contract.
• Use GraphSpec as a contract between teams or services and validate it in CI to catch invalid event-driven transitions early.
• Treat GraphSpec as the single spec from which diagrams or scaffolding can be generated later.

Example

graph CodeReview
start Draft

state Draft
  on submit -> InReview

state InReview
  on approve -> Approved
  on request_changes -> ChangesRequested

state ChangesRequested
  on resubmit -> InReview

state Approved
  final

Format

GraphSpec definitions live in:

• standalone .graph files
• fenced graph blocks inside Markdown

References:

• syntax: grammar/graphspec.ebnf
• semantics and usage: docs/language.md
• rationale and boundaries: DECISIONS.md
• broader use cases: docs/usage.md

See docs/usage.md for future ideas and extended use cases.