A CLI and MCP server for the Product Framework — specify software as a verifiable What/How graph.
The Product Framework is an open standard for
describing a software product as one connected, machine-readable graph: the
What (domain model + event model — entities, commands, events, read models,
UI steps typed against Abstract Interaction Objects, , ,
, ), the (contracts, the screen-composition /
reification model, delivery features), and the typed links between them. The graph
can drive generation, gate verification, and explain itself — so "describe this
system" is a query, not a stale document.
Knowledge graph CLI for managing features, ADRs, and test criteria as MCP-discoverable artifacts.
2026-11-09
ดาว
—
เครื่องมือ
—
อัปไทม์
—
systems
triggers
Deciders
Projectors
How
This repo is the reference tooling: a single Rust binary (product) plus an MCP
server that lets an agent author and verify the graph directly. No database, no
service — the graph lives as YAML/Turtle under .product/.
$ product init --demo # scaffold + seed the bookstore What model
$ product domain new system sys-shop --system-kind application \
--purpose "consumer e-commerce" --target-classes gui
$ product domain validate --strict # per-node shapes + graph-level completeness
$ product decider derive Order # derive an aggregate's executable signature
$ product decider validate Order-decider
$ product mcp --http # MCP server + a live Event-Modeling web view at /
Install
# from source
cargo install --path product-cli
The binary ships with the What→How→Build Claude Code skills baked in.
product init writes them into .claude/skills/ of the new repo (pass
--no-skills to opt out); product skills install (re)installs them, and
product skills install --global puts them in ~/.claude/skills/ for every
project. Start a fresh Claude Code session to pick them up, then /product-session.
Choosing the agent CLI
product session start (and product author domain) host the What→How→Build
session in an agent CLI — Claude Code or GitHub Copilot CLI. The CLI is
resolved in this order:
the --cli claude|copilot flag, else
the repo's [author].cli in .product/config.toml, else
the global user default in $XDG_CONFIG_HOME/product/config.toml
(or ~/.config/product/config.toml), else
claude.
# .product/config.toml — make this repo default to Copilot CLI
[author]
cli = "copilot"
Scaffold it on a new repo with product init --cli copilot, or set a personal
default for every repo by putting the same [author] block in
~/.config/product/config.toml. With a default configured, product session start needs no --cli flag.
60-second tour
product init --demo # a worked What model to explore
product domain list # the captured nodes, by kind
product domain show Order # one node and its links
product domain export # the graph as RDF/Turtle
product domain validate # §3.1/§3.2 per-node conformance shapes
product domain validate --strict # + §3.2.0/§3.2.5/§3.4/§4.5 completeness checks
product decider derive Order # §3.3 — derive decide/evolve signature
product decider simulate Order-decider # run its flow-derived scenarios
product guide # where you are + the next step
The model
What — product domain … captures the domain + event model; product decider … (§3.3) and product projector … (§3.4) make behaviour and read
models executable; product primitive … (§3.5) names irreducible algorithms.
How — product how, product feature, product build, product seam,
product preview cover the How contract, delivery features, the screen seam, and
the §11/§12 design-system / content-store preview profiles.
Everything is validated against the framework's SHACL shapes + SPARQL rules;
the captured What serializes to Turtle (product domain export).
MCP + the web view
product mcp --http starts the MCP server (framework tools: product_domain_*,
product_decider_*, product_projector_*, …) and serves a live web view at /
that renders the active What graph across three connected views — Systems
(the product → systems & journeys map, §3.0), Domain (one bounded context as
an ER graph, §3.1), and Flows (a system's event-model as Event-Modeling
swimlanes — triggers / commands / views over per-aggregate event streams, §3.2).
A node detail panel, the What→How→Build phase stepper, dark/light theme and live
SSE refresh round it out.
ddd — Decision-Driven Design governance
The workspace also ships ddd (crates ddd-core, ddd-lsp, ddd-mcp,
ddd-cli), a separate tool over a separate store: a repo-local .ddd/ graph
of predicates, closure claims, decisions, analyzer/linter manifests, pattern
instances, seam declarations, and interception event rows
(spec, umbrella PRD, formats: migrations).
cargo run -p ddd-cli -- init # scaffold .ddd/
ddd validate # schema + ontology rules (CI gate)
ddd diff --sarif build.sarif # declared vs. detected rules (CI gate)
ddd report escapes # diff + cadence + basis-loss report, each section stating its coverage
ddd why CA2007 # rule -> decision -> principal -> claims (or: detected but unfiled)
ddd render # static self-contained HTML projection of the graph
ddd serve # the ddd_* MCP surface (stdio)
ddd warmup # pre-load the LSP hosts (Roslyn solution load)
ddd what # What-graph boundaries carrying no declaration
Governing the What (the framework graph)
ddd what treats the .product/ What graph as a third governed surface
alongside C# and Bicep. It needs no language server: product-core already
owns the What as typed data, so the adapter reads kinds and containers
straight off DomainGraph and runs them through the same policy-table
mechanism (ddd-core/src/surface.rs, shared with the LSP adapters).
Two kinds of row. Boundary kinds are surface whatever they connect to: a
system (§3.2.5), a context mapping (§3.1), a journey crossing (§3.0.1), a
quality demand (§3.6). Published kinds are surface only when a §3.2.0
Translation carries them — the View a Translation watches, the Command it
issues, and the Events that View projects. Everything else is internal to its
own system and never demands a declaration.
That published/internal split is the What's analogue of C# visibility, and it
is load-bearing: the first table called every event and command a boundary,
which the measurement in DDD-what-02 killed (0 of 39 crossed anything). See
dec/ddd/what-published-qualifier.
A boundary counts as governed when a seam declaration's contract_location
is what:<element-id>. --strict turns it into a CI gate; the default
reports without failing, so the table can be calibrated against a real graph
first.
MCP surface (M3/M4)
ddd serve exposes the ddd_* tool namespace over stdio: LSP-backed
language intelligence for C# (roslyn-language-server --stdio --autoLoadProjects, the official prerelease .NET global tool) and Bicep
(bicep-ls from Azure.Bicep.LangServer) — find_symbol, references,
hover, diagnostics (joined to the manifests by rule id, the same join the
SARIF path uses), signature, rename (computes; application funnels
through the interceptor) — plus the governance tools why, graph_query,
declare_seam, declare_pattern, accept_risk.
The three declare/accept tools take amend: true to revise an entry
already filed. The flag is explicit in both directions — a create never
silently overwrites, an amend never silently creates — and the split is by
field: judgement amends (verdict_knowledge, obligation answers, rationale),
while identity and LSP-derived evidence (contract_location, metadata) are
carried forward untouched, so the interception rows stay machine-authored.
ddd_apply_edit runs every edit through the per-language contract-surface
classifier (policy tables, PRD §9): non-surface edits apply; a surface edit
applies only with a matching same-session declaration; otherwise it is
rejected with a structured demand whose facts (symbol, kind, signature,
visibility, reference count) are pre-filled and whose judgment fields are
blank (dec/ddd/rejection-facts-prefilled). Modes: intercept: enforce | warn | off, per artifact class via intercept_by_class (config format 3);
adapter.csharp.internal_is_surface flips the library-repo posture
(dec/ddd/internal-not-surface). Every classified surface outcome lands as a
row under .ddd/seams/events/ — the correspondence dataset. Hosts are
spawned lazily, health-checked, and respawned on crash; while Roslyn loads
the solution, tools return an explicit {"status": "loading"} rather than
hanging. CI runs against a fixture-grade mock host
(dec/ddd/fixtures-not-sdk); set DDD_LSP_E2E=1 with both tools on PATH to
run the gated real-host suites.
ddd diff compares the manifests under .ddd/manifest/ against two detected
sources per language and reports UNGOVERNED (detected, no manifest entry),
STALE (manifest entry, absent from config and emissions), and
UNCITED_SUPPRESSION (a config or in-source suppression with no
risk-acceptance record):
configured — parsed from .editorconfig (dotnet_diagnostic.<ID>.severity
lines only; section globs are recorded, never evaluated — deliberately not an
editorconfig engine), bicepconfig.json (analyzers.core.rules levels), and
the root Cargo.toml ([workspace.lints.clippy], for this repo's own gates).
Rules enabled by analyzer-package defaults have no config line and surface
via the emitted source only — diff says so when one source covers a rule.
emitted — SARIF 2.1 files from real builds, ingested by one shared
module. Produce them with (verified against current tool docs at M2):
C#: dotnet build -p:ErrorLog=diag.sarif%2Cversion=2.1 — the MSBuild
ErrorLog property; version=2.1 is required (the default is SARIF 1.0),
and %2C escapes the comma on the CLI (or set <ErrorLog> in the project).
Bicep: bicep lint main.bicep --diagnostics-format sarif > bicep.sarif
(also available as az bicep lint).
In-source suppressions differ per toolchain: the C# compiler still logs a
#pragma-suppressed diagnostic into SARIF (marked suppressed), which is how
UNCITED_SUPPRESSION sees it; Bicep's #disable-next-line removes the
diagnostic from the output entirely, so Bicep source suppressions are
invisible to detection — only level: off config suppressions are covered.
Point ddd diff at the files with --sarif or the detect.sarif list in
.ddd/config.yaml. This repo governs itself: .ddd/manifest/clippy.yaml maps
clippy::unwrap_used to its decision, and ddd diff verifies it against the
workspace lints table.
Build & test
cargo build
cargo t # full suite (alias: test --no-fail-fast)
cargo clippy -- -D warnings -D clippy::unwrap_used
