SysProM — System Provenance Model

/sɪs.prɒm/

A recursive, decision-driven model for recording where every part of a system came from, what decisions shaped it, and how it reached its current form.

Install

# From npm (when published)
npm install -g sysprom

# From GitHub
npm install -g github:ExaDev/SysProM

# Or use without installing
npx sysprom --help

Both sysprom and spm are available as commands — use sysprom for new projects.

CLI

# Convert between formats
sysprom json2md --input .SysProM.json --output ./.SysProM
sysprom md2json --input ./.SysProM --output output.SysProM.json

# Validate and summarise (auto-detects .SysProM.json in current directory)
sysprom validate
sysprom stats

# Query nodes and relationships
sysprom query nodes --type decision
sysprom query node D1
sysprom query rels --from D1
sysprom query trace I1
sysprom query timeline
sysprom query state-at 2026-03-22

# Add nodes (ID auto-generated from type prefix if --id omitted)
sysprom add invariant --name "New Rule" --description "Must hold"
sysprom add decision --name "Choose X" \
  --option "OPT-A:Use framework X" --option "OPT-B:Use framework Y" \
  --selected OPT-A --rationale "Lower migration effort"

# Remove nodes
sysprom remove INV23

# Update nodes, relationships, and metadata
sysprom update node D1 --status deprecated
sysprom update add-rel D1 affects EL5
sysprom update remove-rel D1 affects EL5
sysprom update meta --fields version=2

All commands auto-detect the document — they search the current directory for .SysProM.json, .SysProM.md, or .SysProM/ (in that priority order), then fall back to .spm.json, .spm.md, or .spm/. Use --path to specify an explicit path. Note: spm is an alias for sysprom for backwards compatibility.

MCP Server

SysProM includes an MCP (Model Context Protocol) server exposing 11 tools over stdio transport. Any MCP-compatible agent — Cursor, Windsurf, VS Code Copilot, Cline, or custom clients — can use it.

Configuration

Add the following to your MCP client's configuration (e.g. .cursor/mcp.json, .vscode/mcp.json, cline_mcp_settings.json, or equivalent):

{
  "mcpServers": {
    "sysprom": {
      "command": "npx",
      "args": ["-y", "sysprom", "mcp"]
    }
  }
}

Or via the CLI subcommand (equivalent):

sysprom mcp   # starts the MCP server on stdio

Available Tools

Tool	Description
validate	Validate a SysProM document and return issues
stats	Return document statistics
query-nodes	Query nodes by type, status, or text
query-node	Retrieve a single node by ID
query-relationships	Query relationships by source, target, or type
trace	Trace refinement chains from a node
add-node	Add a new node to the document
remove-node	Remove a node by ID
update-node	Update fields on an existing node
add-relationship	Add a relationship between nodes
remove-relationship	Remove a relationship

All tools accept a path parameter to specify the SysProM document location.

Programmatic API

import {
  // Schema and types
  sysproMDocument,
  node,
  nodeType,
  relationshipType,
  type SysProMDocument,
  type Node,
  type Relationship,

  // Conversion
  jsonToMarkdown,
  jsonToMarkdownSingle,
  jsonToMarkdownMultiDoc,
  markdownToJson,

  // Validation and query
  validate,
  stats,
  queryNodes,
  queryNode,
  queryRelationships,
  traceFromNode,

  // Mutation
  addNode,
  removeNode,
  updateNode,
  addRelationship,
  removeRelationship,
  updateMetadata,

  // File I/O
  loadDocument,
  saveDocument,

  // Utilities
  canonicalise,
  toJSONSchema,
} from "sysprom";

// Validate
const doc = JSON.parse(fs.readFileSync(".SysProM.json", "utf8"));
const result = validate(doc);
console.log(result.valid, result.issues);

// Query
const decisions = queryNodes(doc, { type: "decision" });
const trace = traceFromNode(doc, "I1");

// Mutate
const updated = addNode(doc, { id: "INV23", type: "invariant", name: "New Rule" });
const withRel = addRelationship(updated, { from: "D1", to: "INV23", type: "must_preserve" });

// Type guards
if (sysproMDocument.is(data)) { /* data is SysProMDocument */ }
if (node.is(thing)) { /* thing is Node */ }

What is SysProM?

SysProM models systems as directed graphs across abstraction layers — intent, concept, capability, structure, and realisation — with explicit decisions, changes, and invariants. It is domain-agnostic, format-agnostic, and recursively composable.

How SysProM Compares

System	Format		Structure			Decisions		Time		Analysis		Workflow
	Readable	Parseable	State	Nesting	Diagrams	Rationale	Constraints	History	Temporal	Inference	Impact	Scaffolding	Planning	Tracking
MBSE (SysML)	🔶	✅	✅	✅	✅	🔶	✅	🔶			✅
Knowledge Graphs		✅	✅	✅	🔶		🔶			✅
EA (ArchiMate)	✅	🔶	✅	🔶	✅		🔶				✅
Git	🔶	✅	✅					✅	✅					🔶
Event Sourcing		✅	🔶				🔶	✅	✅
DDD	✅		✅	🔶			🔶
C4	✅		✅	🔶	✅
Traceability Matrices	✅		✅				🔶				🔶			🔶
PRD	✅		🔶	🔶	🔶	✅	🔶	🔶			🔶		✅	🔶
ADR	✅					✅		🔶
RFC Processes	✅					✅		🔶					🔶	🔶
BDD (Gherkin)	✅	✅	🔶	🔶			✅					🔶	🔶	✅
Spec Kit	✅		✅	🔶		🔶		🔶				✅	✅	✅
Ralplan	✅		🔶			✅	🔶						✅	🔶
GSD	✅					🔶	🔶
GSD-2	✅	🔶	✅	✅		🔶	🔶	✅			🔶	✅	✅	✅
Taskmaster	✅	✅	✅	✅		🔶		🔶		🔶	🔶	🔶	✅	✅
OpenSpec	✅	🔶	✅	🔶		✅		✅				✅	✅	✅
Kiro	✅	🔶	✅	🔶		🔶	🔶	🔶			🔶	✅	✅	✅
cc-sdd	✅	🔶	✅	🔶		🔶	🔶	🔶			🔶	✅	✅	✅
Ouroboros	✅	🔶	✅			✅	✅	🔶		✅	🔶	🔶	✅	🔶
Spec Kitty	✅	🔶	✅	🔶		🔶	🔶	🔶			🔶	✅	✅	✅
Shotgun	✅	🔶	🔶			🔶		🔶			🔶	🔶	✅	🔶
Superpowers	✅	🔶	🔶	🔶		🔶	✅	🔶		✅	🔶	✅	✅	✅
SysProM	✅	✅	✅	✅	🔶	✅	✅	✅	✅		🔶	✅	✅	✅

✅ = first-class support. 🔶 = partial or implicit.

Key Concepts

Nodes — typed entities (intent, concept, capability, element, realisation, invariant, principle, policy, protocol, stage, role, gate, mode, artefact, decision, change, view)

Relationships — typed directed edges (refines, realises, implements, depends_on, affects, supersedes, must_preserve, and 17 others)

Invariants — rules that must hold across all valid system states

Decisions — choices between alternatives, with context, options, rationale, and must_preserve links to invariants (required when affecting domain nodes)

Changes — modifications to the system, linked to decisions, with scope, operations, and lifecycle tracking

Subsystems — any node can contain a nested SysProM graph, using the same structure recursively

Serialisation

SysProM is format-agnostic. This repository includes:

• JSON — validated against schema.json, supports recursive subsystems
• Markdown — single file (.SysProM.md), multi-document folder, or recursive nested folders with automatic grouping by type

Round-trip conversion between JSON and Markdown is supported with zero information loss.

Development

pnpm build            # Typecheck + compile + schema + docs (cached via Turbo)
pnpm typecheck        # Type-check only
pnpm compile          # Compile to dist/
pnpm test             # Typecheck + run all tests
pnpm test:coverage    # Tests with coverage report
pnpm docs             # Generate API + CLI markdown docs
pnpm docs:html        # Generate HTML site for GitHub Pages
pnpm docs:serve       # Live-reload HTML docs during development
pnpm spm <command>    # Run the CLI from source (e.g. pnpm spm validate ...)

Self-Description

.SysProM.json is SysProM describing itself — the specification, its decisions, invariants, changes, and worked examples are all encoded as a SysProM document. The ./.SysProM/ folder contains the same content as human-readable Markdown.

All significant activity — decisions, changes, new capabilities, and invariants — should be recorded in the self-describing document. Updates can be made either by editing the Markdown files in ./.SysProM/ directly or by using the CLI:

# Add a decision via the CLI
sysprom add decision --id D23 --name "My Decision" --context "Why this was needed"

# Or edit ./.SysProM/DECISIONS.md directly, then sync
sysprom md2json --input ./.SysProM --output .SysProM.json

Keep both representations in sync after any change:

# JSON → Markdown
sysprom json2md --input .SysProM.json --output ./.SysProM

# Markdown → JSON
sysprom md2json --input ./.SysProM --output .SysProM.json

Important: Always keep .SysProM.json and ./.SysProM/ up to date with current activity and in sync with each other. Record all decisions, changes, and new capabilities as they happen. After any change to either representation, run the appropriate conversion command above. Validate with sysprom validate before committing.

Claude Code Plugin

SysProM is available as a Claude Code plugin with 28 skills for managing provenance documents. The plugin is defined in .claude-plugin/marketplace.json with skills in .claude/skills/.

Install from Marketplace

# Add the SysProM marketplace
/plugin marketplace add ExaDev/SysProM

# Install the plugin
/plugin install sysprom@sysprom

Skills are namespaced when installed as a plugin (e.g. /sysprom:add-decision, /sysprom:query-nodes).

Local Development

When working on the SysProM repo itself, skills in .claude/skills/ are auto-discovered without plugin installation. Skills use short names (e.g. /add-decision, /query-nodes).

Skills by Category

Node Creation (4 skills)

• add-decision — Create decision nodes with context, options, rationale, and invariant links
• add-change — Create change nodes with scope, operations, and task tracking
• add-invariant — Create invariant nodes representing system rules and constraints
• add-node — Generic node creation for any SysProM type

Node Modification (3 skills)

• update-node — Modify node fields, status, lifecycle, context, or rationale
• remove-node — Delete nodes with safety flags (hard delete, recursive, repair)
• rename-node — Rename node IDs across all references

Relationships (2 skills)

• add-relationship — Create relationships between nodes with specific types
• remove-relationship — Delete relationships

Query & Analysis (5 skills)

• query-nodes — Search nodes by type, status, text, or ID
• query-relationships — Query relationships by source, target, or type
• trace-node — Trace refinement chains through abstraction layers
• check-document — Validate document structure and report issues
• stats — Show document statistics and composition metrics

Visualisation (1 skill)

• graph — Generate Mermaid or DOT graphs with filtering

Format Conversion (4 skills)

• init-document — Create new SysProM documents with metadata
• json-to-markdown — Convert JSON to Markdown format
• markdown-to-json — Convert Markdown to JSON format
• sync-formats — Bidirectional sync between JSON and Markdown

Spec-Kit Integration (4 skills)

• speckit-import — Import Spec-Kit features as SysProM nodes
• speckit-export — Export SysProM nodes to Spec-Kit format
• speckit-sync — Bidirectional sync with Spec-Kit specifications
• speckit-diff — Show differences between SysProM and Spec-Kit

Task Management (3 skills)

• task-list — List tasks in a change node with progress
• task-add — Add tasks to a change
• task-mark-done — Mark tasks as complete

Plan Management (2 skills)

• plan-init — Initialise plans with phases and gates
• plan-status — Show plan progress and phase gates

Fallback to npx

If spm is not globally installed, skills automatically fall back to npx -y sysprom for command execution. All skills work with either global or per-project installation.