ProductSpec: Open standard for software intent before implementation ProductSpec, an open standard for documenting software intent before implementation, has been released. It provides a portable Markdown format for product decisions that precede tickets, engineering plans, and code, enabling intent to survive handoffs between humans, teams, and AI agents. The standard includes structure for decision traces, revision handling, and validation via a CLI tool. ProductSpec is an open standard for software intent before implementation. It gives teams a portable Markdown format for the product decision that comes before tickets, engineering plans, and code. Use it when the work is consequential enough that intent needs to survive handoff: from humans to humans, from product to engineering, and from teams to AI agents. php Product Spec - Engineering Spec - Code - Evaluation - Learning what / why how / plan / tasks implementation outcome 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. Design principle: structure the parts machines must execute or compare. Leave the parts humans must reason about readable. Decision Trace is the optional companion standard for recording how consequential decisions, drift, revisions, and outcomes are handled over time. Product Specs are living documents. They should change when evidence, scope, design, acceptance criteria, or success metrics change. spec revision gives each meaningful revision a portable handle: spec format version: "0.1" ProductSpec standard version spec revision: 1 initial product intent spec revision: 2 scope changed after design review spec revision: 3 acceptance criteria updated before implementation 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. See examples/revisions/ for a Product Spec that evolves from revision 1 to revision 2. Validate a Product Spec with the published CLI: npm exec --package @productspec/parser -- productspec validate path/to/file.product-spec.md Create a starter Product Spec: npm exec --package @productspec/parser -- productspec init my-feature.product-spec.md Try an included example: npm exec --package @productspec/parser -- productspec validate examples/minimal.product-spec.md Full Product Spec files include frontmatter such as title , optional spec revision , author , and timestamps. This shortened example shows the section body. Problem Support leads at B2B SaaS companies lose their morning planning window because urgent, account-risk tickets are buried among routine product questions. Hypothesis 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. Scope productspec-scope in: - ticket ingestion - urgency labels - customer-tier lookup - owner recommendation - confidence score - reviewer override - audit log out: - auto-replies - direct ticket reassignment - customer-visible status changes cut: - custom routing rules Acceptance Criteria productspec-ai-evals - id: account risk urgency type: rubric input set: evals/account-risk-golden-set.jsonl evaluator: llm judge pass threshold: 0.92 checks: - urgency classification identifies account-risk tickets Success Metrics productspec-success-metrics - id: account risk response time metric: median time to first human response target: "< 15 minutes" window: business hours segment: account-risk tickets source: helpdesk analytics See examples/ai-support-triage.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/ai-support-triage.product-spec.md for the complete version. ProductSpec is the open standard, project, repository, and ecosystem for software intent. Product Spec is the artifact a person writes. ProductSpec is not for every act of building. It is for consequential software work where intent needs to survive handoff. 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. 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. 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, scope, user experience, acceptance criteria, and success metrics. 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. php Product Spec ProductSpec - Engineering Spec OpenSpec / Spec Kit - Code agents what / why how / plan / tasks implementation strategic intent technical decomposition running system Both layers are SDD. Both use the spec as a control system. They serve different roles with different artifacts. ProductSpec does not replace Git, Jira, Linear, Figma, analytics tools, OpenSpec, Spec Kit, or AI coding agents. It sits upstream of them. php ProductSpec - Engineering Spec - Tasks - Code - Evaluation - Learning - 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. - 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. - 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. - Analytics tools store outcome data. - OpenSpec and Spec Kit turn intent into engineering plans. - AI coding agents execute implementation tasks. - ProductSpec stores the software intent behind the work: the problem, hypothesis, scope, acceptance criteria, and success metrics that downstream tools should preserve. ProductSpec is meant to be implemented by many tools. Current repo artifacts: @productspec/parser : TypeScript parser, validator, and CLI.- JSON Schema for parsed Product Spec documents. - Valid and invalid conformance fixtures. - GitHub issue and pull request templates. - Examples for AI features, consumer UX, enterprise workflows, internal APIs, and revision history. Natural integration points: - Git and GitHub for versioned Product Specs, pull requests, and review. - Jira and Linear for work tracking that links back to Product Spec revisions. - Figma and prototypes through user experience . - OpenSpec and Spec Kit for downstream engineering specs. - AI coding agents that build until Acceptance Criteria pass. - Analytics and experiment tools that measure Success Metrics after launch. Early ecosystem contributions are welcome: examples, importer/exporter experiments, editor integrations, CI validation actions, review tools, and mappings into engineering-spec systems. SPEC.md /gokulrajaram/ProductSpec/blob/main/SPEC.md : the canonical v0.1 standard. CHANGELOG.md /gokulrajaram/ProductSpec/blob/main/CHANGELOG.md : release history for the standard and tooling. CONTRIBUTING.md /gokulrajaram/ProductSpec/blob/main/CONTRIBUTING.md : how to propose examples, validator changes, and section vocabulary changes. docs/philosophy.md /gokulrajaram/ProductSpec/blob/main/docs/philosophy.md : the core beliefs behind ProductSpec. docs/launch-post.md /gokulrajaram/ProductSpec/blob/main/docs/launch-post.md : a draft launch post for sharing the project. docs/why-productspec.md /gokulrajaram/ProductSpec/blob/main/docs/why-productspec.md : why the intent layer needs its own artifact. docs/faq.md /gokulrajaram/ProductSpec/blob/main/docs/faq.md : answers to common ProductSpec adoption questions. docs/use-in-your-repo.md /gokulrajaram/ProductSpec/blob/main/docs/use-in-your-repo.md : copy-paste setup for using ProductSpec in an existing repository. docs/adoption.md /gokulrajaram/ProductSpec/blob/main/docs/adoption.md : how teams can adopt ProductSpec across Git, Jira, Linear, Figma, CI, engineering specs, and agents. docs/handoff-example.md /gokulrajaram/ProductSpec/blob/main/docs/handoff-example.md : how ProductSpec interacts with Jira, Figma, Git, OpenSpec, Spec Kit, and coding agents. docs/end-to-end-handoff.md /gokulrajaram/ProductSpec/blob/main/docs/end-to-end-handoff.md : a concrete walkthrough from Product Spec to issue, design, engineering spec, agent loop, pull request, and launch learning. docs/vision.md /gokulrajaram/ProductSpec/blob/main/docs/vision.md : the public vision for ProductSpec as the intent layer. docs/validator.md /gokulrajaram/ProductSpec/blob/main/docs/validator.md : validator error and warning codes. docs/validate-your-first-product-spec.md /gokulrajaram/ProductSpec/blob/main/docs/validate-your-first-product-spec.md : the fastest local validation path. docs/field-guide.md /gokulrajaram/ProductSpec/blob/main/docs/field-guide.md : field-level guidance for writing each section. docs/versioning.md /gokulrajaram/ProductSpec/blob/main/docs/versioning.md : compatibility rules before v1.0. docs/decision-trace.md /gokulrajaram/ProductSpec/blob/main/docs/decision-trace.md : the optional companion standard for decisions, drift, and revisions. schema/product-spec.schema.json /gokulrajaram/ProductSpec/blob/main/schema/product-spec.schema.json : JSON Schema for parsed Product Spec documents. schema/decision-trace.schema.json /gokulrajaram/ProductSpec/blob/main/schema/decision-trace.schema.json : JSON Schema for Decision Trace documents. schema/review-annotation.schema.json /gokulrajaram/ProductSpec/blob/main/schema/review-annotation.schema.json : JSON Schema for portable review annotations. conformance/ /gokulrajaram/ProductSpec/blob/main/conformance : valid and invalid fixtures for implementers. examples/README.md /gokulrajaram/ProductSpec/blob/main/examples/README.md : guide to choosing the right example. examples/ /gokulrajaram/ProductSpec/blob/main/examples : minimal and expanded examples. examples/decision-traces/ /gokulrajaram/ProductSpec/blob/main/examples/decision-traces : companion Decision Trace examples. parsers/ts /gokulrajaram/ProductSpec/blob/main/parsers/ts : TypeScript reference parser, validator, and CLI. Examples include AI features, consumer UX, enterprise workflows, internal APIs, and agent handoffs: examples/ai-support-triage.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/ai-support-triage.product-spec.md examples/consumer-family-calendar.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/consumer-family-calendar.product-spec.md examples/enterprise-approval-workflow.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/enterprise-approval-workflow.product-spec.md examples/internal-webhook-replay-api.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/internal-webhook-replay-api.product-spec.md examples/full-prd.product-spec.md /gokulrajaram/ProductSpec/blob/main/examples/full-prd.product-spec.md Mandatory sections, in order: problem hypothesis scope acceptance criteria success metrics Optional sections: user experience , customer truth , solution alternatives , solution , strategic positioning , adoption , pricing , risks , ai , open questions , rollout 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. Custom sections use custom-