ProductShape

ProductShape, the reference implementation of Product Definition as Code.

Product Definition as Code keeps the agreed product definition in versioned Markdown that delivery work cites instead of restating.

Three specs restate one rule; a change flags every recorded citation. Real output. The end card names the recorded CLI version. Watch on pdac.dev.

See a real product definition, live. This repository's own model is republished on every merge to main.

Explore the public ProductShape site — product guide, onboarding path, arc42 engineering views and the generated self-model.

The methodology belongs to the specification repository: the normative contracts, the conformance tests and the manifesto, which states the founding position. ProductShape is the Product Definition as Code CLI: prodshape lets you author actors, journeys, use cases, business rules, domain terms, product requirements and structured behaviours in Markdown, then keeps that definition validated, evolvable and citable:

• prodshape init: scaffold a product definition (and optional AI, OpenSpec and Spec Kit integrations) in any repository.
• prodshape validate: validate the product definition deterministically: schemas, IDs, relationships and lifecycles, with stable diagnostic codes.
• prodshape graph and prodshape impact <ID>: compile the product graph from the Markdown and answer "what is connected to this?" structurally.
• prodshape change validate and prodshape change apply: evolve the definition through a Product Change. It is validated as an overlay, approved by a human and applied explicitly on a working branch. A human merge accepts the resulting baseline; apply is not acceptance.
• prodshape cite and prodshape citations verify: cite product artifacts from SDD specs and agent prompts by ID and content digest, then verify citations: current, stale, tampered or unresolved. Provider-aware verification enumerates the expected population of an OpenSpec or Spec Kit workspace, so zero discovered citations is a failure, never a vacuous pass.
• prodshape context <ID> [<ID>...]: render a cited context projection of the artifacts a piece of delivery work implements, ready to feed into a Spec Kit specify run or an OpenSpec proposal, so delivery starts from cited canonical text instead of paraphrase.

Deterministic tools check structure and references, never truth; people decide what is true and what should change.

Install

Requires Node.js >= 22. The supported published baseline is @prodshape/cli@0.22.1.

npm install -g @prodshape/cli@0.22.1
# or run it once, without installing
pnpm dlx @prodshape/cli@0.22.1 --help

prodshape is the canonical binary; product-definition is an identical v0.x compatibility alias scheduled for removal before v1.

Packages

The CLI bundles every package below, so installing @prodshape/cli is all you need. Each is also published separately for programmatic use, under the @prodshape scope, versioned independently with Changesets and published from GitHub Actions with provenance (see RELEASING.md).

Package	Version	Description
@prodshape/cli		The prodshape command-line tool (bundles the rest)
@prodshape/core		Deterministic parsing, validation and graph
@prodshape/distribution		Init, provider-asset generation and doctor
@prodshape/integration-claude		Claude Code renderer for canonical assets
@prodshape/integration-codex		Codex renderer for canonical assets
@prodshape/integration-opencode		OpenCode renderer for canonical assets
@prodshape/integration-copilot		GitHub Copilot renderer for canonical assets
@prodshape/integration-openspec		OpenSpec configuration and citation-rule integration
@prodshape/integration-speckit		Spec Kit guidance and feature-spec citation verification

@prodshape/integration-openspec is the current OpenSpec package. The previously published @prodshape/adapter-openspec name belongs to older releases and is not part of the current package set.

Quickstart

This is a disposable sandbox, not the adoption path. It writes into the accepted model directly to show the mechanics in two minutes and is deliberately non-governed. Real adoption changes the definition only through Product Changes: follow the governed citation-first walkthrough in the @prodshape/cli README.

Your model, rendered, in a couple of minutes:

mkdir my-product && cd my-product
npm init -y && npm install --save-dev --save-exact @prodshape/cli@0.22.1
npx --no-install prodshape init

mkdir -p docs/product/model/business-rules
cat > docs/product/model/business-rules/br-refund-001.md <<'EOF'
---
id: BR-REFUND-001
type: business-rule
title: Refund window
status: active
---

## Rule

Refunds are accepted within 30 days of delivery.

## Rationale

Customers need a predictable window; finance needs a bounded liability.

## Examples

A delivery on March 1 may be refunded through March 31.

## Exceptions

None.
EOF

npx --no-install prodshape validate
npx --no-install prodshape graph --format html
open .product/generated/snapshot.html   # xdg-open on Linux

validate reports one warning because the rule has no consumers yet. The model is telling you what to connect next. The snapshot is your product definition rendered as a browsable graph; print a starting point for any kind with prodshape template <kind> and re-run.

Release contract (what CI executes)

One business rule, one citation, one detected drift. CI runs this exact block against the packed release candidate in the release-contract workflow. It substitutes only PRODSHAPE_PACKAGE with the tarball path. What you read here is what is tested.

set -eu
PRODSHAPE_PACKAGE="${PRODSHAPE_PACKAGE:-@prodshape/cli@0.22.1}"

mkdir productshape-quickstart
cd productshape-quickstart
npm init -y >/dev/null
npm install --save-dev --save-exact "$PRODSHAPE_PACKAGE"

npx --no-install prodshape init
npx --no-install prodshape validate

mkdir -p docs/product/model/business-rules openspec
cat > docs/product/model/business-rules/br-refund-001.md <<'EOF'
---
id: BR-REFUND-001
type: business-rule
title: Refund window
status: active
---

## Rule

Refunds are accepted within 30 days of delivery.

## Rationale

Customers need a predictable window; finance needs a bounded liability.

## Examples

A delivery on March 1 may be refunded through March 31.

## Exceptions

None.
EOF

printf '# Refund delivery specification\n' > openspec/refund.md
npx --no-install prodshape cite \
  --id BR-REFUND-001 \
  --file docs/product/model/business-rules/br-refund-001.md \
  --form sidecar-ledger > openspec/refund.citations.yml
npx --no-install prodshape citations verify

node --input-type=module -e "
  import { readFileSync, writeFileSync } from 'node:fs';
  const path = '.product/config.yaml';
  writeFileSync(path, readFileSync(path, 'utf8').replace('warnings-as-errors: false', 'warnings-as-errors: true'));
"
node --input-type=module -e "
  import { readFileSync, writeFileSync } from 'node:fs';
  const path = 'docs/product/model/business-rules/br-refund-001.md';
  writeFileSync(path, readFileSync(path, 'utf8').replace('30 days', '14 days'));
"

set +e
stale_output="$(npx --no-install prodshape citations verify 2>&1)"
stale_exit=$?
set -e
printf '%s\n' "$stale_output"
test "$stale_exit" -eq 1
printf '%s\n' "$stale_output" | grep -q 'PRODUCT061'

The first prodshape citations verify reports current. The second is expected to fail with PRODUCT061 because the cited rule changed and this quickstart enables warnings-as-errors before the stale check: drift is detected instead of silent. Features on main newer than the pinned baseline are unreleased until a newer CLI version is published.

What to read next:

• The methodology overview: a five-minute read covering the artifact families, the product graph, the operations and the citation contract.
• The specification is normative. Read its manifesto for the authoritative founding position. The frontmatter reference enumerates what you may write in every artifact kind; prodshape schema <kind> prints the same contract without a repository.
• The self-hosted model under docs/product/model: this repository defines itself with its own methodology, so every artifact kind has a real example. schemas/ and templates/ hold the machine contracts the CLI validates against and a conformant starting point for each kind.
• Adoption guides for the entry paths: greenfield, brownfield, existing repository, existing OpenSpec repository and existing Spec Kit repository.

Agent skills

prodshape init --ai claude,codex,copilot,opencode installs generated commands and skills for the chosen providers, so an AI agent works the model through the same operations you do: explore, define, change, audit, impact, recover, bind (backfill citations into existing SDD documents) and refine (interview-driven model improvement). The assets are canonical to the CLI. Run prodshape integration update to refresh them after an upgrade. The methodology overview explains what each operation does.

Install the CLI as above, then pick one provider or several. Every provider gets the same commands and skills, rendered where that tool looks for them:

--ai	Generated	You trigger
claude	.claude/commands/product/*.md and .claude/skills/<name>/	/product:define, /product:change, ...
copilot	.github/prompts/product-*.prompt.md and .github/skills/<name>/	/product-define, /product-change, ...
codex	.agents/commands/product/*.md and .agents/skills/<name>/	the Agent Skills open standard layout; any tool that reads it
opencode	.opencode/commands/product-*.md and .opencode/skills/<name>/	/product-define, /product-change, ...

Running init with no --ai in an interactive terminal reports which of these the repository already uses and offers those, so the flag is for scripts and for overriding what was found. Add a provider later with prodshape integration add <provider>, and --shorthand adds /ps: aliases. OpenCode also reads .agents/skills and .claude/skills, so pairing opencode with codex or claude installs the same skills twice; they differ on commands, which OpenCode reads only from .opencode/commands/.

PDaC conformance

The pinned conformance workflow builds and packs ProductShape, installs that tarball outside the workspace, and runs the spec's conformance tests via the external runner pdac-conformance (1.0.1) against PDaC spec commit b3f44d2179a58bbee0478fae517ab75f3249ca39, the v0.2.0 specification content with RFC 0112 applied: all 45 cases pass and all 12 pinned digests verify, claimed as specification 0.2.0 on serialization v1alpha1. The published tests are not a complete normative set, so the badge claims only this pinned executable profile; ProductShape's own fixtures, self-model and traceability checks run separately as Internal contracts.

Current status

@prodshape/cli@0.22.1 is the supported published baseline. It includes deterministic brownfield recovery sessions, Product Change overlay validation and apply with the affected-citation report, citation emission and verification (including provider-aware OpenSpec population verification), snapshot generation, schema discovery, filename repair, SDD-aware initialization, prodshape change create, prodshape drift, prodshape --version, and generated AI/OpenSpec integrations. The root changelog records every stable CLI release; version 0.10.0 was prepared but never published, and its changes shipped in 0.11.0.

Remaining open decisions are in OPEN-DECISIONS.md. Deliberately out of scope, among others, are graph databases, web UIs, MCP servers, Jira integration, multi-repository graphs, automatic brownfield recovery, roadmaps and OKRs, hosted services and telemetry. The full list, plus known design limitations, is in Limitations.

Contributing

See CONTRIBUTING.md. The specification is normative, docs/product is canonical, and changes to the product definition itself go through its own Change operation.