GraphSpec

GraphSpec is a CLI and library for spec-driven development: author software specs as a knowledge graph, then build software by traversing it.

A spec is an Open Knowledge Format v0.1 bundle, a directory of markdown files with YAML frontmatter cross-linked by typed relations. Because the spec is a graph rather than a document, you can pull just the subgraph for the work in front of you, and find out mechanically which requirements nothing implements or tests.

Documentation: graphspec.dev

The npm package is graph-spec-cli. The command it installs is graphspec.

Quickstart

With a coding agent, install the two agent skills:

npx skills add brandonburrus/graphspec

Then ask for what you want: "spec out the checkout flow as a GraphSpec", or "implement the next component from the spec".

Or use the CLI directly, with no install:

npx graph-spec-cli validate spec/ --strict
npx graph-spec-cli coverage spec/
npx graph-spec-cli graph spec/ --from architecture/validator.component --depth 1
npx graph-spec-cli visualize spec/ --open

Requires Node.js 20 or newer.

What a concept looks like

Each file is one concept. Its filename carries its type, and its frontmatter declares typed edges to other concepts.

# specification/checkout.feature.md
---
type: Feature
title: Checkout
relations:
  includes:
    - /specification/payment.requirement.md
    - /specification/tax.requirement.md
---

# Summary

Take payment for a cart and issue a receipt.

The vocabulary is closed: 13 node types and 16 relations. See the profile reference.

Commands

| Command | Question it answers | | --- | --- | | validate | Is this bundle well formed? | | query | Which concepts match these filters? | | index | Regenerate the directory listings and log | | graph | What is connected to this concept? | | coverage | What has the spec not said yet? | | order | What should be built first? | | visualize | What does the whole graph look like? |

Full flags, output shapes, and exit codes: graphspec.dev/cli/overview.

Library

npm install graph-spec-cli

import { loadBundle, Graph, analyzeCoverage } from "graph-spec-cli";

const graph = Graph.fromBundle(await loadBundle("spec"));
console.log(analyzeCoverage(graph).totalGaps);

ESM only. Full surface: graphspec.dev/library/api.

Example bundle

spec/ is GraphSpec specified in GraphSpec, and doubles as the test fixture. It stays clean:

npx graph-spec-cli validate spec/ --strict   # 27 concept(s), 0 error(s), 0 warning(s)
npx graph-spec-cli coverage spec/            # 0 gap(s)

Development

pnpm install
pnpm build       # tsc into dist/
pnpm test        # vitest
pnpm lint        # biome check
pnpm typecheck   # tsc --noEmit

pnpm --filter graphspec-docs dev     # docs site at localhost:4321

See AGENTS.md for architecture and constraints.

License

MIT, see LICENSE.