Skip to content
Back to search

ProductSpec

Open standard for software intent in the AI agent era.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gokulrajaram--productspec/badge.svg)](/listings/gokulrajaram--productspec)

HTML

<a href="/listings/gokulrajaram--productspec"><img src="/api/listings/gokulrajaram--productspec/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

If you want to use ProductSpec as a Product Harness for coding agents, start here:

- [Get started with agents](docs/get-started-with-agents.md): install the skills, convert a PRD, validate in CI, implement from a Product Spec, and record drift. - [Use the MCP server](docs/agent-mcp.md): expose Product Specs to coding agents as structured tools. - [Install MCP in Claude or Cursor](docs/mcp-install.md): generate a copy-pasteable MCP client config. - [Use with Claude Code](docs/use-with-claude-code.md), [Cursor](docs/use-with-cursor.md), or [Codex](docs/use-with-codex.md): tool-specific agent walkthroughs. - [5-minute Product Harness demo](docs/agent-harness-demo.md): see Product Spec, MCP, Agent Run, and Decision Trace working together. - [Product Harness](docs/product-harness.md): the outer-loop frame around coding agents and engineering specs. - [Agent Handoff](docs/agent-handoff.md): generate an implementation brief from a Product Spec without making handoff a canonical spec section. - [60-second demo script](docs/demo-script.md): record the ProductSpec loop closing in a short GIF or Loom. - [Real-world example gallery](examples/real-world/): copy patterns from product, AI, platform, and agent-led specs. - [CI badge demo](docs/ci-badge-demo.md): validate Product Specs in GitHub Actions and show a factual status badge. - [Awesome ProductSpec](awesome-productspec.md): curated docs, examples, workflows, and adjacent tools. - [Status badge spec](docs/status-badge.md): factual badge shapes for valid specs, run receipts, evidence, and revisions. - [Evidence loop](docs/evidence-loop.md): connect Product Specs to implementation, evals, metrics, and Decision Trace. - [Repo maintenance](docs/repo-maintenance.md): garden a repo, reconcile Agent Runs, and serve a local ProductSpec dashboard. - [Agent Run](docs/agent-run.md): record one Claude, Codex, Cursor, or other agent execution against a pinned Product Spec.

1. Try the Product Harness demo:

npm exec --package @productspec/parser -- productspec validate examples/harness-demo/checkout-notifications.product-spec.md

2. Generate an Agent Handoff:

npm exec --package @productspec/parser -- productspec handoff examples/product-harness/video-transcript.product-spec.md

3. Start the MCP server:

npx --yes -p @productspec/parser@latest productspec mcp

Generate a Claude or Cursor MCP config:

npx --yes -p @productspec/parser@latest productspec mcp-config claude

4. Ask Claude, Codex, Cursor, or another MCP-aware agent to implement against the Product Spec:

Use ProductSpec MCP before coding.
Validate examples/harness-demo/checkout-notifications.product-spec.md, call begin_spec_session, load Product Summary, Scope, Acceptance Criteria, AI Evals, Success Metrics, Related Artifacts, and Agent Handoff.
Stay inside scope.in, avoid scope.out and scope.cut, verify every AC- and EVAL- item, call check_spec_session before claiming done, and draft an Agent Run receipt.

5. Draft the run receipt:

npm exec --package @productspec/parser -- productspec init-run examples/harness-demo/checkout-notifications.product-spec.md /tmp/checkout-notifications.agent-run.json

6. Validate the checked-in example receipt and trace:

npm exec --package @productspec/parser -- productspec validate-run examples/harness-demo/checkout-notifications.agent-run.json
npm exec --package @productspec/parser -- productspec validate-trace examples/harness-demo/checkout-notifications.decision-trace.json

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 597 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ProductSpec
  2. [![CI](https://github.com/gokulrajaram/ProductSpec/actions/workflows/ci.yml/badge.svg)](https://github.com/gokulrajaram/ProductSpec/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/@productspec/parser.svg)](https://www.npmjs.com/package/@productspec/parser)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  5. ProductSpec is the open standard for product intent. It acts as a Product Harness for AI-native software work: what to build, what not to build, how to prove completion, and when intent changes.
  6. It gives teams and agents a portable way to define intent up front, attach evidence after work starts, and preserve what changed when reality disagreed.
  7. Use it when consequential software work needs intent to survive handoff: from product to engineering, from humans to agents, and from implementation back to learning.
  8. ```text
  9. Product Spec -> Engineering Spec -> Code -> Evaluation -> Learning
  10. what / why how / plan / tasks implementation outcome
  11. ```
  12. For agent-led work, ProductSpec gives coding agents a product contract:
  13. ```text
  14. Product Spec
  15. -> MCP tools
  16. -> coding agent
  17. -> implementation
  18. -> Agent Run receipt
  19. -> Related Artifacts
  20. -> Decision Trace
  21. -> revised Product Spec
  22. ```
  23. Product Spec is the core artifact. Agent Run and Decision Trace are optional companion artifacts: use them when agents implement against a spec or when evidence changes the decision.
  24. ProductSpec is neutral. It defines structure, section IDs, portable review annotations, calibration-example serialization, and portable decision traces. It does not define what makes a Product Spec good.
  25. Design principle: structure the parts machines must execute or compare. Leave the parts humans must reason about readable.
  26. ProductSpec acts as a Product Harness for agent-led work. The Product Spec tells Claude, Codex, Cursor, and other coding agents what to build, what not to build, how to prove completion, and when to stop and re-plan. For those agents, ProductSpec provides an intent harness: structured context, scope guardrails, acceptance criteria, evals, evidence targets, and revision checks. The repo includes `skills/productspec/SKILL.md`, a loadable agent skill that tells coding agents how to read Product Specs, cite Acceptance Criteria, respect scope, and propose a Decision Trace when implementation diverges from intent. `skills/productspec-authoring/SKILL.md` covers the other direction: writing a Product Spec, validating it, and converting an existing PRD into one. Both are installable with `npx skills add gokulrajaram/ProductSpec`.
  27. Agent Run is the optional companion artifact for recording what happened when an agent used ProductSpec as its product contract: the pinned spec revision, checked criteria and evals, linked evidence, drift status, and completion claim.
  28. Decision Trace is the optional companion standard for recording how consequential decisions, drift, revisions, and outcomes are handled over time.
  29. ```text
  30. Intent -> Implementation -> Drift -> Decision Trace -> Revised Intent
  31. ```
  32. ## What Agents Can Do Today
  33. With the parser, CLI, MCP server, and companion artifacts in this repo, agents can:
  34. - validate Product Specs before planning or coding
  35. - pin `spec_revision` and content hash at the start of a work session
  36. - read Product Summary, Scope, Acceptance Criteria, AI Evals, Success Metrics, and Related Artifacts as structured data
  37. - resolve a folder of specs into buildable, blocked, and ordered work
  38. - garden a repo to find missing evidence, stale revision pins, unscoped specs, and run gaps
  39. - reconcile one Product Spec against one Agent Run before claiming completion
  40. - ask what evidence is expected for each `AC-`, `EVAL-`, and `SM-` item
  41. - check whether the Product Spec changed before claiming completion
  42. - draft an Agent Run receipt
  43. - record drift or learning through Decision Trace
  44. ProductSpec does not tell the agent how to code. It tells the agent what intent it is accountable to.
  45. ## Repo Maintenance Commands
  46. Once Product Specs live in a repo, use these commands to operate the Product Harness across many files:
  47. ```bash
  48. # Scan repo health: specs, runs, traces, graph, evidence, stale revision pins
  49. npm exec --package @productspec/parser -- productspec garden .
  50. # Check whether one Agent Run satisfies one Product Spec revision
  51. npm exec --package @productspec/parser -- productspec reconcile docs/product-specs/my-feature.product-spec.md --against docs/agent-runs/my-feature.agent-run.json
  52. # Open a local read-only dashboard over the same garden report
  53. npm exec --package @productspec/parser -- productspec serve . --port 4317
  54. ```
  55. See [`docs/repo-maintenance.md`](docs/repo-maintenance.md) for the full semantics.
  56. ## Intent And Evidence
  57. ProductSpec defines what should be built and why.
  58. Evidence shows what happened after work started: pull requests, tests, eval runs, dashboards, analytics snapshots, releases, and support signals.
  59. Use `Related Artifacts` to attach evidence to durable ProductSpec IDs:
  60. - `AC-<number>`: implementation evidence
  61. - `EVAL-<number>`: model behavior evidence
  62. - `SM-<number>`: post-launch outcome evidence
  63. Updating evidence links does not automatically require a `spec_revision` bump. Bump `spec_revision` when evidence changes the meaning of the product intent: scope, acceptance criteria, user experience, success metrics, or the underlying bet. Use Decision Trace when evidence changes the product decision.
  64. ProductSpec does not collect traces or run evals. It gives evidence a stable intent target.
  65. ## Living Specs
  66. Product Specs are living documents. They should change when evidence, scope, design, acceptance criteria, or success metrics change.
  67. `spec_revision` gives each meaningful revision a portable handle:
  68. ```yaml
  69. spec_format_version: "0.1" # ProductSpec standard version
  70. spec_revision: 1 # initial product intent
  71. spec_revision: 2 # scope changed after design review
  72. spec_revision: 3 # acceptance criteria updated before implementation
  73. ```
  74. Git keeps the detailed history. `spec_revision` lets people and tools cite the intent revision they are using: a Jira ticket, an engineering spec, an AI agent loop, a pull request, or a Decision Trace.
  75. See `examples/revisions/` for a Product Spec that evolves from revision 1 to revision 2.
  76. ## Quick Start
  77. ![ProductSpec Product Harness loop](docs/assets/product-harness-loop.gif)
  78. If you want to use ProductSpec as a Product Harness for coding agents, start here:
  79. - [Get started with agents](docs/get-started-with-agents.md): install the skills, convert a PRD, validate in CI, implement from a Product Spec, and record drift.
  80. - [Use the MCP server](docs/agent-mcp.md): expose Product Specs to coding agents as structured tools.
  81. - [Install MCP in Claude or Cursor](docs/mcp-install.md): generate a copy-pasteable MCP client config.
  82. - [Use with Claude Code](docs/use-with-claude-code.md), [Cursor](docs/use-with-cursor.md), or [Codex](docs/use-with-codex.md): tool-specific agent walkthroughs.
  83. - [5-minute Product Harness demo](docs/agent-harness-demo.md): see Product Spec, MCP, Agent Run, and Decision Trace working together.
  84. - [Product Harness](docs/product-harness.md): the outer-loop frame around coding agents and engineering specs.
  85. - [Agent Handoff](docs/agent-handoff.md): generate an implementation brief from a Product Spec without making handoff a canonical spec section.
  86. - [60-second demo script](docs/demo-script.md): record the ProductSpec loop closing in a short GIF or Loom.
  87. - [Real-world example gallery](examples/real-world/): copy patterns from product, AI, platform, and agent-led specs.
  88. - [CI badge demo](docs/ci-badge-demo.md): validate Product Specs in GitHub Actions and show a factual status badge.
  89. - [Awesome ProductSpec](awesome-productspec.md): curated docs, examples, workflows, and adjacent tools.
  90. - [Status badge spec](docs/status-badge.md): factual badge shapes for valid specs, run receipts, evidence, and revisions.
  91. - [Evidence loop](docs/evidence-loop.md): connect Product Specs to implementation, evals, metrics, and Decision Trace.
  92. - [Repo maintenance](docs/repo-maintenance.md): garden a repo, reconcile Agent Runs, and serve a local ProductSpec dashboard.
  93. - [Agent Run](docs/agent-run.md): record one Claude, Codex, Cursor, or other agent execution against a pinned Product Spec.
  94. 1. Try the Product Harness demo:
  95. ```bash
  96. npm exec --package @productspec/parser -- productspec validate examples/harness-demo/checkout-notifications.product-spec.md
  97. ```
  98. 2. Generate an Agent Handoff:
  99. ```bash
  100. npm exec --package @productspec/parser -- productspec handoff examples/product-harness/video-transcript.product-spec.md
  101. ```
  102. 3. Start the MCP server:
  103. ```bash
  104. npx --yes -p @productspec/parser@latest productspec mcp
  105. ```
  106. Generate a Claude or Cursor MCP config:
  107. ```bash
  108. npx --yes -p @productspec/parser@latest productspec mcp-config claude
  109. ```
  110. 4. Ask Claude, Codex, Cursor, or another MCP-aware agent to implement against the Product Spec:
  111. ```text
  112. Use ProductSpec MCP before coding.
  113. Validate examples/harness-demo/checkout-notifications.product-spec.md, call begin_spec_session, load Product Summary, Scope, Acceptance Criteria, AI Evals, Success Metrics, Related Artifacts, and Agent Handoff.
  114. Stay inside scope.in, avoid scope.out and scope.cut, verify every AC- and EVAL- item, call check_spec_session before claiming done, and draft an Agent Run receipt.
  115. ```
  116. 5. Draft the run receipt:
  117. ```bash
  118. npm exec --package @productspec/parser -- productspec init-run examples/harness-demo/checkout-notifications.product-spec.md /tmp/checkout-notifications.agent-run.json
  119. ```
  120. 6. Validate the checked-in example receipt and trace:
  121. ```bash
  122. npm exec --package @productspec/parser -- productspec validate-run examples/harness-demo/checkout-notifications.agent-run.json
  123. npm exec --package @productspec/parser -- productspec validate-trace examples/harness-demo/checkout-notifications.decision-trace.json
  124. ```
  125. ## Try This With Your Coding Agent
  126. 1. Pick a real feature you would otherwise describe in a PRD, ticket, or chat thread.
  127. 2. Write a Product Spec for it, or start from `examples/product-harness/video-transcript.product-spec.md`.
  128. 3. Validate it:
  129. ```bash
  130. npm exec --package @productspec/parser -- productspec validate path/to/your.product-spec.md
  131. ```
  132. 4. Generate the Agent Handoff:
  133. ```bash
  134. npm exec --package @productspec/parser -- productspec handoff path/to/your.product-spec.md
  135. ```
  136. 5. Paste the handoff into Claude, Codex, Cursor, or another coding agent.
  137. 6. Require evidence for every `AC-<number>` and `EVAL-<number>` before the agent claims completion.
  138. 7. If implementation pressure changes product intent, update the Product Spec or record a Decision Trace.
  139. Create a starter Product Spec:
  140. ```bash
  141. npm exec --package @productspec/parser -- productspec init my-feature.product-spec.md
  142. ```
  143. Prefer an editor?
  144. You can also draft and validate Product Specs in the free browser editor at [ProductSpec.io](https://productspec.io). The open standard does not require the hosted editor.
  145. Resolve a folder of specs into a build graph:
  146. ```bash
  147. npm exec --package @productspec/parser -- productspec graph conformance/graph
  148. ```
  149. The graph answers the fleet question too: which specs are safe to hand to different agents at the same time. It reports `contention` (the surfaces more than one live spec touches, read from `applies_to`) and `waves` (sets of specs that share no surface and whose dependencies are already met), so two agents never land in the same files and find out at merge.
  150. Read and inspect a spec from the shell:
  151. ```bash
  152. npm exec --package @productspec/parser -- productspec list specs
  153. npm exec --package @productspec/parser -- productspec get path/to/your.product-spec.md acceptance --json
  154. npm exec --package @productspec/parser -- productspec check-claim path/to/your.product-spec.md
  155. ```
  156. The CLI reaches every operation the MCP does: validate, list, show, read a section (`scope`, `acceptance`, `evals`, `metrics`, `related`, `evidence`), graph, generate a handoff, check a completion claim, and pin or check a session for drift. Every read command supports `--json`, so anyone who finds MCP overkill can do the same work from a plain terminal. See the [CLI reference](docs/cli.md) for all commands and flags. The CLI and the MCP call the same functions, so their output cannot drift.
  157. Garden the whole repo for missing evidence, stale revision pins, run gaps, Decision Trace gaps, and graph health:
  158. ```bash
  159. npm exec --package @productspec/parser -- productspec garden .
  160. ```
  161. Reconcile one implementation run against one Product Spec revision:
  162. ```bash
  163. npm exec --package @productspec/parser -- productspec reconcile docs/product-specs/my-feature.product-spec.md --against docs/agent-runs/my-feature.agent-run.json
  164. ```
  165. Serve the same repo-health view locally:
  166. ```bash
  167. npm exec --package @productspec/parser -- productspec serve . --port 4317
  168. ```
  169. See [`docs/repo-maintenance.md`](docs/repo-maintenance.md) for the command semantics.
  170. ## Status Badges
  171. ProductSpec badges should report facts, not subjective quality scores.
  172. ```text
  173. ProductSpec: valid
  174. ProductSpec: rev 3
  175. Agent Run: recorded
  176. Evidence: 4 linked artifacts
  177. ProductSpec graph: buildable
  178. ```
  179. See [`docs/status-badge.md`](docs/status-badge.md) for the recommended badge vocabulary.
  180. Use the GitHub Action in a repository:
  181. ```yaml
  182. name: ProductSpec
  183. on:
  184. pull_request:
  185. jobs:
  186. validate-product-specs:
  187. runs-on: ubuntu-latest
  188. steps:
  189. - uses: actions/checkout@v4
  190. - uses: gokulrajaram/ProductSpec@main
  191. with:
  192. files: "docs/product-specs/**/*.product-spec.md"
  193. decision_traces: "docs/decision-traces/**/*.decision-trace.json"
  194. agent_runs: "docs/agent-runs/**/*.agent-run.json"
  195. ```
  196. ## How To Contribute Without Coding
  197. Product leaders and builders can shape ProductSpec without touching parser code:
  198. - open a `General spec discussion` issue with an example from your product process
  199. - propose a section vocabulary change when the default sections do not fit consequential work
  200. - contribute an anonymized Product Spec example
  201. - contribute a Decision Trace example showing how intent changed during implementation
  202. - report confusing validator errors or adoption friction
  203. See [CONTRIBUTING.md](CONTRIBUTING.md) for exact issue and pull request steps.
  204. ## Example
  205. Full Product Spec files include frontmatter such as `title`, optional `spec_revision`, `author`, and timestamps. This shortened example shows the section body.
  206. ````markdown
  207. ## Problem
  208. Support leads at B2B SaaS companies lose their morning planning window because urgent, account-risk tickets are buried among routine product questions.
  209. ## Hypothesis
  210. If incoming tickets are automatically labeled by urgency, customer tier, and likely owner, support leads will respond to account-risk issues faster because the queue starts each day pre-sorted by consequence.
  211. ## Product Summary
  212. An AI support triage workflow labels incoming tickets by urgency, customer tier, likely owner, and confidence so support leads can start from an ordered queue.
  213. ## Scope
  214. ```productspec-scope
  215. in:
  216. - Include ticket ingestion in this version.
  217. - Include urgency labels in this version.
  218. - Include customer-tier lookup in this version.
  219. - Include owner recommendation in this version.
  220. - Include confidence score in this version.
  221. - Include reviewer override in this version.
  222. - Include audit log in this version.
  223. out:
  224. - Do not build auto-replies in this version.
  225. - Do not build direct ticket reassignment in this version.
  226. - Do not build customer-visible status changes in this version.
  227. cut:
  228. - Cut custom routing rules from the first version if implementation time is tight.
  229. ```
  230. ## Acceptance Criteria
  231. ```productspec-acceptance-criteria
  232. - id: AC-1
  233. criterion: New tickets receive urgency, customer tier, suggested owner, confidence score, and model version within 60 seconds.
  234. - id: AC-2
  235. criterion: Reviewers can override any label before it changes downstream workflow state.
  236. ```
  237. ```productspec-ai-evals
  238. - id: EVAL-1
  239. type: llm_judge
  240. cases:
  241. - input: "Representative input for this eval."
  242. expected: "Expected behavior for this eval."
  243. evaluator: llm
  244. pass_threshold: 0.92
  245. checks:
  246. - urgency classification identifies account-risk tickets
  247. ```
  248. ## Success Metrics
  249. ```productspec-success-metrics
  250. - id: SM-1
  251. metric: median_time_to_first_human_response
  252. target: "< 15 minutes"
  253. target_status: committed
  254. window: business hours
  255. ```
  256. ````
  257. See [examples/ai-support-triage.product-spec.md](examples/ai-support-triage.product-spec.md) for the complete version.
  258. ## Naming
  259. - `ProductSpec` is the open standard, project, repository, and ecosystem for software intent.
  260. - `Product Spec` is the artifact a person writes.
  261. ## When To Use ProductSpec
  262. ProductSpec is not for every act of building. It is for consequential software work where intent needs to survive handoff.
  263. For an individual builder, a Product Spec is useful when the work is complex, risky, long-lived, or being handed to an AI agent loop. For quick experiments, one-off scripts, or throwaway prototypes, it may be faster to brainstorm, build, and iterate directly.
  264. For a team or organization, ProductSpec is most useful when coordination cost appears: multiple people, multiple agents, design and engineering handoffs, customer-facing launches, AI features with evals, or decisions that will need to be revisited later.
  265. ## Where This Sits
  266. ProductSpec operates at the software intent layer: the what and why that come before engineering specs are written. This is where a team commits to the problem, hypothesis, product summary, scope, user experience, acceptance criteria, and success metrics.
  267. OpenSpec and Spec Kit operate at the engineering spec layer. OpenSpec's flow is propose -> apply -> archive. Spec Kit's flow is constitution -> specify -> clarify -> plan -> tasks -> analyze -> implement. Those artifacts live in the repo and are consumed by AI agents to build code.
  268. ```text
  269. Product Spec (ProductSpec) -> Engineering Spec (OpenSpec / Spec Kit) -> Code (agents)
  270. what / why how / plan / tasks implementation
  271. strategic intent technical decomposition running system
  272. ```
  273. Both layers are SDD. Both use the spec as a control system. They serve different roles with different artifacts.
  274. ## Where ProductSpec Fits
  275. ProductSpec does not replace Git, Jira, Linear, Figma, analytics tools, OpenSpec, Spec Kit, or AI coding agents.
  276. It sits upstream of them.
  277. ```text
  278. ProductSpec -> Engineering Spec -> Tasks -> Code -> Evaluation -> Learning
  279. ```
  280. - Git stores implementation history. A Product Spec can live beside code in Git, but code commits should not be the first durable record of why the work exists.
  281. - Jira and Linear store work history. A Product Spec can become epics, tickets, or tasks, but it should remain the durable statement of intent behind those tasks.
  282. - Figma stores design artifacts. A Product Spec can link to prototypes, mockups, or screenshots through `user_experience`, but it does not replace the design source of truth.
  283. - Analytics tools store outcome data.
  284. - OpenSpec and Spec Kit turn intent into engineering plans.
  285. - AI coding agents execute implementation tasks.
  286. - ProductSpec stores the software intent behind the work: the problem, hypothesis, product summary, scope, acceptance criteria, and success metrics that downstream tools should preserve.
  287. ## Ecosystem
  288. ProductSpec is meant to be implemented by many tools.
  289. Current repo artifacts:
  290. - `@productspec/parser`: TypeScript parser, validator, and CLI.
  291. - `skills/productspec` and `skills/productspec-authoring`: loadable agent skills for implementing from a Product Spec and for writing one.
  292. - JSON Schema for parsed Product Spec documents.
  293. - Valid and invalid conformance fixtures.
  294. - `starter-kit/`: copyable repo setup with Product Specs, Agent Runs, Decision Traces, agent instructions, PR template, and CI.
  295. - GitHub issue and pull request templates.
  296. - Examples for AI features, consumer UX, enterprise workflows, internal APIs, and revision history.
  297. Durable IDs are generated for the top-level items that tools execute or compare: `AC-1` for Acceptance Criteria, `SM-1` for Success Metrics, and `EVAL-1` for AI evals. Scope bullets, eval cases, optional eval checks, and prose/custom sections remain un-IDed. Tools that need to cite eval children should use positional references like `EVAL-1.case[2]`.
  298. Success Metrics may be `committed` when the target is known, or `provisional` when the team knows the metric but needs post-launch baseline work before committing the threshold. Provisional targets must name a `target_owner`.
  299. Natural integration points:
  300. - Git and GitHub for versioned Product Specs, pull requests, and review.
  301. - Jira and Linear for work tracking that links back to Product Spec revisions.
  302. - Figma and prototypes through `user_experience`.
  303. - OpenSpec and Spec Kit for downstream engineering specs.
  304. - AI coding agents that build until Acceptance Criteria pass.
  305. - Analytics and experiment tools that measure Success Metrics after launch.
  306. Traceability uses two shapes:
  307. - Frontmatter for stable document-level relationships such as `linked_github_repo` and `applies_to`.
  308. - `## Related Artifacts` with a structured `productspec-related-artifacts` block for item-level links from `AC-<number>`, `SM-<number>`, or `EVAL-<number>` to issues, pull requests, eval runs, dashboards, designs, releases, or engineering specs.
  309. Early ecosystem contributions are welcome: examples, importer/exporter experiments, editor integrations, CI validation actions, review tools, and mappings into engineering-spec systems.
  310. Want a small first contribution? Start with pinned issue [#43: add a real Product Harness example](https://github.com/gokulrajaram/ProductSpec/issues/43).
  311. ## What Is Included
  312. - [SPEC.md](SPEC.md): the canonical v0.1 standard.
  313. - [CHANGELOG.md](CHANGELOG.md): release history for the standard and tooling.
  314. - [CONTRIBUTING.md](CONTRIBUTING.md): how to propose examples, validator changes, and section vocabulary changes.
  315. - [docs/philosophy.md](docs/philosophy.md): the core beliefs behind ProductSpec.
  316. - [docs/launch-post.md](docs/launch-post.md): a draft launch post for sharing the project.
  317. - [docs/why-productspec.md](docs/why-productspec.md): why the intent layer needs its own artifact.
  318. - [docs/faq.md](docs/faq.md): answers to common ProductSpec adoption questions.
  319. - [docs/get-started-with-agents.md](docs/get-started-with-agents.md): the shortest path from existing docs to agent-authored and agent-implemented Product Specs.
  320. - [docs/use-in-your-repo.md](docs/use-in-your-repo.md): copy-paste setup for using ProductSpec in an existing repository.
  321. - [docs/product-harness.md](docs/product-harness.md): how ProductSpec acts as the Product Harness above coding agents and engineering specs.
  322. - [docs/agent-usage.md](docs/agent-usage.md): how to use ProductSpec as an intent harness for coding agents.
  323. - [docs/agent-handoff.md](docs/agent-handoff.md): how to generate an implementation brief from a Product Spec without duplicating canonical intent.
  324. - [docs/agent-run.md](docs/agent-run.md): how to record one agent execution against a pinned Product Spec.
  325. - [docs/graph.md](docs/graph.md): resolving a folder of Product Specs into buildable, blocked, and ordered work, plus the contention and waves a fleet of agents needs to run in parallel safely.
  326. - [docs/repo-maintenance.md](docs/repo-maintenance.md): repo-level garden, reconciliation, and local dashboard commands for ProductSpec libraries.
  327. - [docs/adoption.md](docs/adoption.md): how teams can adopt ProductSpec across Git, Jira, Linear, Figma, CI, engineering specs, and agents.
  328. - [docs/productspec-to-tickets.md](docs/productspec-to-tickets.md): how to project a Product Spec into Jira or Linear tickets without forking intent.
  329. - [docs/adoption-levels.md](docs/adoption-levels.md): a step-by-step maturity ladder for adopting ProductSpec.
  330. - [docs/before-after.md](docs/before-after.md): a loose PRD transformed into ProductSpec.
  331. - [docs/productspec-vs.md](docs/productspec-vs.md): how ProductSpec differs from PRDs, Jira, Git, Figma, engineering design docs, OpenSpec, Spec Kit, and ADRs.
  332. - [docs/repo-starter-kit.md](docs/repo-starter-kit.md): copy-paste conventions for using ProductSpec in an existing repo.
  333. - [starter-kit/](starter-kit/): a copyable repo starter kit with ProductSpec, Agent Run, Decision Trace, AGENTS/CLAUDE instructions, and CI.
  334. - [docs/handoff-example.md](docs/handoff-example.md): how ProductSpec interacts with Jira, Figma, Git, OpenSpec, Spec Kit, and coding agents.
  335. - [docs/end-to-end-handoff.md](docs/end-to-end-handoff.md): a concrete walkthrough from Product Spec to issue, design, engineering spec, agent loop, pull request, and launch learning.
  336. - [docs/vision.md](docs/vision.md): the public vision for ProductSpec as the intent layer.
  337. - [docs/validator.md](docs/validator.md): validator error and warning codes.
  338. - [docs/validate-your-first-product-spec.md](docs/validate-your-first-product-spec.md): the fastest local validation path.
  339. - [docs/field-guide.md](docs/field-guide.md): field-level guidance for writing each section.
  340. - [docs/versioning.md](docs/versioning.md): compatibility rules before v1.0.
  341. - [docs/decision-trace.md](docs/decision-trace.md): the optional companion standard for decisions, drift, and revisions.
  342. - [schema/product-spec.schema.json](schema/product-spec.schema.json): JSON Schema for parsed Product Spec documents.
  343. - [schema/decision-trace.schema.json](schema/decision-trace.schema.json): JSON Schema for Decision Trace documents.
  344. - [schema/agent-run.schema.json](schema/agent-run.schema.json): JSON Schema for Agent Run documents.
  345. - [schema/review-annotation.schema.json](schema/review-annotation.schema.json): JSON Schema for portable review annotations.
  346. - [skills/productspec/SKILL.md](skills/productspec/SKILL.md): loadable agent guidance for implementing from Product Specs.
  347. - [skills/productspec-authoring/SKILL.md](skills/productspec-authoring/SKILL.md): loadable agent guidance for writing, validating, and converting Product Specs.
  348. - [conformance/](conformance/): valid and invalid fixtures for implementers.
  349. - [examples/README.md](examples/README.md): guide to choosing the right example.
  350. - [examples/](examples/): minimal and expanded examples.
  351. - [examples/decision-traces/](examples/decision-traces/): companion Decision Trace examples.
  352. - [examples/product-harness/](examples/product-harness/): Product Spec, generated Agent Handoff, Agent Run, and Decision Trace in one loop.
  353. - [examples/agent-ready-repo/](examples/agent-ready-repo/): ProductSpec as a Product Harness in a small repo layout.
  354. - [parsers/ts](parsers/ts): TypeScript reference parser, validator, and CLI.
  355. Examples include AI features, consumer UX, enterprise workflows, internal APIs, and agent handoffs:
  356. - [examples/ai-support-triage.product-spec.md](examples/ai-support-triage.product-spec.md)
  357. - [examples/agent-coded-feature.product-spec.md](examples/agent-coded-feature.product-spec.md)
  358. - [examples/consumer-family-calendar.product-spec.md](examples/consumer-family-calendar.product-spec.md)
  359. - [examples/enterprise-approval-workflow.product-spec.md](examples/enterprise-approval-workflow.product-spec.md)
  360. - [examples/internal-webhook-replay-api.product-spec.md](examples/internal-webhook-replay-api.product-spec.md)
  361. - [examples/platform-cache-migration.product-spec.md](examples/platform-cache-migration.product-spec.md)
  362. - [examples/full-prd.product-spec.md](examples/full-prd.product-spec.md)
  363. ## Canonical Sections
  364. Mandatory sections, in order:
  365. 1. `problem`
  366. 2. `hypothesis`
  367. 3. `product_summary`
  368. 4. `scope`
  369. 5. `acceptance_criteria`
  370. 6. `success_metrics`
  371. Optional sections:
  372. `user_experience`, `customer_truth`, `solution_alternatives`, `solution`, `strategic_positioning`, `adoption`, `pricing`, `risks`, `ai`, `open_questions`, `rollout`, `related_artifacts`
  373. `user_experience` describes the externally observable experience of the work when there is one: for example, a prototype URL, mockup, design link, public deploy, Loom walkthrough, API documentation page, CLI demo, dashboard, or internal tool screen.
  374. Custom sections use `custom-<kebab-name>`.
  375. ## Status
  376. Version `0.1` is intentionally small. It is stable enough for tooling experiments, but still pre-1.0 while implementers learn what needs to change. See `docs/versioning.md` for compatibility expectations.
  377. ProductSpec distinguishes the standard version from the document revision:
  378. - `spec_format_version` tells tools which ProductSpec format the file uses.
  379. - `spec_revision` is an optional positive integer for this particular product decision. It starts at `1` and increments when intent materially changes.
  380. The current v0.x standard includes conformance fixtures, a structured validator, examples, a CLI, optional `spec_revision` frontmatter, traceability fields, an MCP server, a loadable agent skill, a copyable repo starter kit, generated Agent Handoffs, Decision Trace validation, Agent Run drafting and validation, repo gardening, reconciliation, and a local read-only dashboard:
  381. ```bash
  382. npm exec --package @productspec/parser -- productspec validate examples/minimal.product-spec.md
  383. ```
  384. To validate a Decision Trace:
  385. ```bash
  386. npm exec --package @productspec/parser -- productspec validate-trace examples/decision-traces/transcript-search.decision-trace.json
  387. ```
  388. To validate an Agent Run:
  389. ```bash
  390. npm exec --package @productspec/parser -- productspec validate-run examples/agent-ready-repo/docs/agent-runs/transcript-search.agent-run.json
  391. ```
  392. To draft an Agent Run from a Product Spec:
  393. ```bash
  394. npm exec --package @productspec/parser -- productspec init-run examples/minimal.product-spec.md examples/minimal.agent-run.json
  395. ```
  396. To generate an Agent Handoff from a Product Spec:
  397. ```bash
  398. npm exec --package @productspec/parser -- productspec handoff examples/product-harness/video-transcript.product-spec.md
  399. ```
  400. To create a starter Product Spec:
  401. ```bash
  402. npm exec --package @productspec/parser -- productspec init my-feature.product-spec.md
  403. ```
  404. For local development from this repository:
  405. ```bash
  406. npm install
  407. npm run build
  408. node dist/cli.js validate examples/minimal.product-spec.md
  409. ```
  410. Or use the shortcut:
  411. ```bash
  412. npm run validate -- examples/minimal.product-spec.md
  413. ```
  414. To run the local `productspec` CLI without a global install:
  415. ```bash
  416. npm run cli -- validate examples/minimal.product-spec.md
  417. ```
  418. To link the CLI during development:
  419. ```bash
  420. npm run link:cli
  421. ```
  422. After linking, `productspec validate examples/minimal.product-spec.md` works if your npm
  423. global binary directory is on `PATH`.
  424. See `docs/validate-your-first-product-spec.md` for the first-run path and current validator checks.
  425. See `docs/adoption.md` for a practical team setup across Git, Jira, Linear, Figma, CI, engineering specs, and AI coding agents.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.