{"slug": "productspec-open-standard-for-software-intent-before-implementation", "title": "ProductSpec: Open standard for software intent before implementation", "summary": "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.", "body_md": "ProductSpec is an open standard for software intent before implementation.\n\nIt gives teams a portable Markdown format for the product decision that comes before tickets, engineering plans, and code.\n\nUse 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.\n\n``` php\nProduct Spec -> Engineering Spec -> Code -> Evaluation -> Learning\nwhat / why      how / plan / tasks   implementation   outcome\n```\n\nProductSpec 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.\n\nDesign principle: structure the parts machines must execute or compare. Leave the parts humans must reason about readable.\n\nDecision Trace is the optional companion standard for recording how consequential decisions, drift, revisions, and outcomes are handled over time.\n\nProduct Specs are living documents. They should change when evidence, scope, design, acceptance criteria, or success metrics change.\n\n`spec_revision`\n\ngives each meaningful revision a portable handle:\n\n```\nspec_format_version: \"0.1\" # ProductSpec standard version\nspec_revision: 1           # initial product intent\nspec_revision: 2           # scope changed after design review\nspec_revision: 3           # acceptance criteria updated before implementation\n```\n\nGit keeps the detailed history. `spec_revision`\n\nlets 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.\n\nSee `examples/revisions/`\n\nfor a Product Spec that evolves from revision 1 to revision 2.\n\nValidate a Product Spec with the published CLI:\n\n```\nnpm exec --package @productspec/parser -- productspec validate path/to/file.product-spec.md\n```\n\nCreate a starter Product Spec:\n\n```\nnpm exec --package @productspec/parser -- productspec init my-feature.product-spec.md\n```\n\nTry an included example:\n\n```\nnpm exec --package @productspec/parser -- productspec validate examples/minimal.product-spec.md\n```\n\nFull Product Spec files include frontmatter such as `title`\n\n, optional `spec_revision`\n\n, `author`\n\n, and timestamps. This shortened example shows the section body.\n\n```\n## Problem\n\nSupport leads at B2B SaaS companies lose their morning planning window because urgent, account-risk tickets are buried among routine product questions.\n\n## Hypothesis\n\nIf 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.\n\n## Scope\n\n``` productspec-scope\nin:\n  - ticket ingestion\n  - urgency labels\n  - customer-tier lookup\n  - owner recommendation\n  - confidence score\n  - reviewer override\n  - audit log\nout:\n  - auto-replies\n  - direct ticket reassignment\n  - customer-visible status changes\ncut:\n  - custom routing rules\n```\n\n## Acceptance Criteria\n\n``` productspec-ai-evals\n- id: account_risk_urgency\n  type: rubric\n  input_set: evals/account-risk-golden-set.jsonl\n  evaluator: llm_judge\n  pass_threshold: 0.92\n  checks:\n    - urgency classification identifies account-risk tickets\n```\n\n## Success Metrics\n\n``` productspec-success-metrics\n- id: account_risk_response_time\n  metric: median_time_to_first_human_response\n  target: \"< 15 minutes\"\n  window: business hours\n  segment: account-risk tickets\n  source: helpdesk_analytics\nSee [examples/ai-support-triage.product-spec.md](/gokulrajaram/ProductSpec/blob/main/examples/ai-support-triage.product-spec.md) for the complete version.\n\n`ProductSpec`\n\nis the open standard, project, repository, and ecosystem for software intent.`Product Spec`\n\nis the artifact a person writes.\n\nProductSpec is not for every act of building. It is for consequential software work where intent needs to survive handoff.\n\nFor 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.\n\nFor 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.\n\nProductSpec 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.\n\nOpenSpec 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.\n\n``` php\nProduct Spec (ProductSpec) -> Engineering Spec (OpenSpec / Spec Kit) -> Code (agents)\nwhat / why                       how / plan / tasks                         implementation\nstrategic intent                 technical decomposition                    running system\n```\n\nBoth layers are SDD. Both use the spec as a control system. They serve different roles with different artifacts.\n\nProductSpec does not replace Git, Jira, Linear, Figma, analytics tools, OpenSpec, Spec Kit, or AI coding agents.\n\nIt sits upstream of them.\n\n``` php\nProductSpec -> Engineering Spec -> Tasks -> Code -> Evaluation -> Learning\n```\n\n- 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.\n- 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.\n- Figma stores design artifacts. A Product Spec can link to prototypes, mockups, or screenshots through\n`user_experience`\n\n, but it does not replace the design source of truth. - Analytics tools store outcome data.\n- OpenSpec and Spec Kit turn intent into engineering plans.\n- AI coding agents execute implementation tasks.\n- ProductSpec stores the software intent behind the work: the problem, hypothesis, scope, acceptance criteria, and success metrics that downstream tools should preserve.\n\nProductSpec is meant to be implemented by many tools.\n\nCurrent repo artifacts:\n\n`@productspec/parser`\n\n: TypeScript parser, validator, and CLI.- JSON Schema for parsed Product Spec documents.\n- Valid and invalid conformance fixtures.\n- GitHub issue and pull request templates.\n- Examples for AI features, consumer UX, enterprise workflows, internal APIs, and revision history.\n\nNatural integration points:\n\n- Git and GitHub for versioned Product Specs, pull requests, and review.\n- Jira and Linear for work tracking that links back to Product Spec revisions.\n- Figma and prototypes through\n`user_experience`\n\n. - OpenSpec and Spec Kit for downstream engineering specs.\n- AI coding agents that build until Acceptance Criteria pass.\n- Analytics and experiment tools that measure Success Metrics after launch.\n\nEarly ecosystem contributions are welcome: examples, importer/exporter experiments, editor integrations, CI validation actions, review tools, and mappings into engineering-spec systems.\n\n[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.\n\nExamples include AI features, consumer UX, enterprise workflows, internal APIs, and agent handoffs:\n\n[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)\n\nMandatory sections, in order:\n\n`problem`\n\n`hypothesis`\n\n`scope`\n\n`acceptance_criteria`\n\n`success_metrics`\n\nOptional sections:\n\n`user_experience`\n\n, `customer_truth`\n\n, `solution_alternatives`\n\n, `solution`\n\n, `strategic_positioning`\n\n, `adoption`\n\n, `pricing`\n\n, `risks`\n\n, `ai`\n\n, `open_questions`\n\n, `rollout`\n\n`user_experience`\n\ndescribes 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.\n\nCustom sections use `custom-<kebab-name>`\n\n.\n\nVersion `0.1`\n\nis 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`\n\nfor compatibility expectations.\n\nProductSpec distinguishes the standard version from the document revision:\n\n`spec_format_version`\n\ntells tools which ProductSpec format the file uses.`spec_revision`\n\nis an optional positive integer for this particular product decision. It starts at`1`\n\nand increments when intent materially changes.\n\nThe v0.4 milestone includes conformance fixtures, a structured validator, examples, a CLI, and optional `spec_revision`\n\nfrontmatter:\n\n```\nnpm exec --package @productspec/parser -- productspec validate examples/minimal.product-spec.md\n```\n\nTo create a starter Product Spec:\n\n```\nnpm exec --package @productspec/parser -- productspec init my-feature.product-spec.md\n```\n\nFor local development from this repository:\n\n```\nnpm install\nnpm run build\nnode dist/cli.js validate examples/minimal.product-spec.md\n```\n\nOr use the shortcut:\n\n```\nnpm run validate -- examples/minimal.product-spec.md\n```\n\nTo run the local `productspec`\n\nCLI without a global install:\n\n```\nnpm run cli -- validate examples/minimal.product-spec.md\n```\n\nTo link the CLI during development:\n\n```\nnpm run link:cli\n```\n\nAfter linking, `productspec validate examples/minimal.product-spec.md`\n\nworks if your npm\nglobal binary directory is on `PATH`\n\n.\n\nSee `docs/validate-your-first-product-spec.md`\n\nfor the first-run path and current validator checks.\n\nSee `docs/adoption.md`\n\nfor a practical team setup across Git, Jira, Linear, Figma, CI, engineering specs, and AI coding agents.", "url": "https://wpnews.pro/news/productspec-open-standard-for-software-intent-before-implementation", "canonical_source": "https://github.com/gokulrajaram/ProductSpec", "published_at": "2026-07-08 06:05:51+00:00", "updated_at": "2026-07-08 06:30:11.932932+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools"], "entities": ["ProductSpec", "Jira", "Git"], "alternates": {"html": "https://wpnews.pro/news/productspec-open-standard-for-software-intent-before-implementation", "markdown": "https://wpnews.pro/news/productspec-open-standard-for-software-intent-before-implementation.md", "text": "https://wpnews.pro/news/productspec-open-standard-for-software-intent-before-implementation.txt", "jsonld": "https://wpnews.pro/news/productspec-open-standard-for-software-intent-before-implementation.jsonld"}}