[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92664":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":16,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":17,"rankGlobal":9,"rankLanguage":9,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":9,"pushedAt":9,"updatedAt":32,"readmeContent":33,"aiSummary":34,"trendingCount":15,"starSnapshotCount":15,"syncStatus":35,"lastSyncTime":36,"discoverSource":37},92664,"ProductSpec","gokulrajaram\u002FProductSpec","gokulrajaram","ProductSpec is the open standard for software intent before implementation.",null,"TypeScript",108,10,4,1,0,28,45.92,"MIT License",false,"main",true,[23,24,25,26,27,28,29,30,31],"ai-agents","developer-tools","markdown","openspec","prd","product-management","productspec","spec-driven-development","speckit","2026-07-22 04:02:06","# ProductSpec\n\n[![CI](https:\u002F\u002Fgithub.com\u002Fgokulrajaram\u002FProductSpec\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002Fgokulrajaram\u002FProductSpec\u002Factions\u002Fworkflows\u002Fci.yml)\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002F@productspec\u002Fparser.svg)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002F@productspec\u002Fparser)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-blue.svg)](LICENSE)\n\nProductSpec 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```text\nProduct Spec -> Engineering Spec -> Code -> Evaluation -> Learning\nwhat \u002F why      how \u002F plan \u002F 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\nProductSpec can also act as the control file for agent-led work. The repo includes `skills\u002Fproductspec\u002FSKILL.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\u002Fproductspec-authoring\u002FSKILL.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\u002FProductSpec`.\n\nDecision Trace is the optional companion standard for recording how consequential decisions, drift, revisions, and outcomes are handled over time.\n\n```text\nIntent -> Implementation -> Drift -> Decision Trace -> Revised Intent\n```\n\n## Living Specs\n\nProduct Specs are living documents. They should change when evidence, scope, design, acceptance criteria, or success metrics change.\n\n`spec_revision` gives each meaningful revision a portable handle:\n\n```yaml\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` 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.\n\nSee `examples\u002Frevisions\u002F` for a Product Spec that evolves from revision 1 to revision 2.\n\n## Quick Start\n\nIf you want to use ProductSpec with coding agents, start here:\n\n- [Get started with agents](docs\u002Fget-started-with-agents.md): install the skills, convert a PRD, validate in CI, implement from a Product Spec, and record drift.\n\nValidate a Product Spec with the published CLI:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec validate path\u002Fto\u002Ffile.product-spec.md\n```\n\nPrefer an editor?\n\nYou can also draft and validate Product Specs in the free browser editor at [ProductSpec.io](https:\u002F\u002Fproductspec.io). The open standard does not require the hosted editor.\n\nCreate a starter Product Spec:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec init my-feature.product-spec.md\n```\n\nTry an included example:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec validate examples\u002Fminimal.product-spec.md\n```\n\nValidate a Decision Trace:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec validate-trace examples\u002Fdecision-traces\u002Ftranscript-search.decision-trace.json\n```\n\nUse the GitHub Action in a repository:\n\n```yaml\nname: ProductSpec\n\non:\n  pull_request:\n\njobs:\n  validate-product-specs:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\u002Fcheckout@v4\n      - uses: gokulrajaram\u002FProductSpec@main\n        with:\n          files: \"docs\u002Fproduct-specs\u002F**\u002F*.product-spec.md\"\n          decision_traces: \"docs\u002Fdecision-traces\u002F**\u002F*.decision-trace.json\"\n```\n\n## How To Contribute Without Coding\n\nProduct leaders and builders can shape ProductSpec without touching parser code:\n\n- open a `General spec discussion` issue with an example from your product process\n- propose a section vocabulary change when the default sections do not fit consequential work\n- contribute an anonymized Product Spec example\n- contribute a Decision Trace example showing how intent changed during implementation\n- report confusing validator errors or adoption friction\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for exact issue and pull request steps.\n\n## Example\n\nFull Product Spec files include frontmatter such as `title`, optional `spec_revision`, `author`, and timestamps. This shortened example shows the section body.\n\n````markdown\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-acceptance-criteria\n- id: AC-1\n  criterion: New tickets receive urgency, customer tier, suggested owner, confidence score, and model version within 60 seconds.\n- id: AC-2\n  criterion: Reviewers can override any label before it changes downstream workflow state.\n```\n\n```productspec-ai-evals\n- id: EVAL-1\n  type: llm_judge\n  cases:\n    - input: \"Representative input for this eval.\"\n      expected: \"Expected behavior for this eval.\"\n  evaluator: llm\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: SM-1\n  metric: median_time_to_first_human_response\n  target: \"\u003C 15 minutes\"\n  target_status: committed\n  window: business hours\n```\n````\n\nSee [examples\u002Fai-support-triage.product-spec.md](examples\u002Fai-support-triage.product-spec.md) for the complete version.\n\n## Naming\n\n- `ProductSpec` is the open standard, project, repository, and ecosystem for software intent.\n- `Product Spec` is the artifact a person writes.\n\n## When To Use ProductSpec\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\n## Where This Sits\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```text\nProduct Spec (ProductSpec) -> Engineering Spec (OpenSpec \u002F Spec Kit) -> Code (agents)\nwhat \u002F why                       how \u002F plan \u002F 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\n## Where ProductSpec Fits\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```text\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 `user_experience`, but it does not replace the design source of truth.\n- 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\n## Ecosystem\n\nProductSpec is meant to be implemented by many tools.\n\nCurrent repo artifacts:\n\n- `@productspec\u002Fparser`: TypeScript parser, validator, and CLI.\n- `skills\u002Fproductspec` and `skills\u002Fproductspec-authoring`: loadable agent skills for implementing from a Product Spec and for writing one.\n- JSON Schema for parsed Product Spec documents.\n- Valid and invalid conformance fixtures.\n- `starter-kit\u002F`: copyable repo setup with Product Specs, Decision Traces, agent instructions, PR template, and CI.\n- GitHub issue and pull request templates.\n- Examples for AI features, consumer UX, enterprise workflows, internal APIs, and revision history.\n\nDurable 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\u002Fcustom sections remain un-IDed. Tools that need to cite eval children should use positional references like `EVAL-1.case[2]`.\n\nSuccess 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`.\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 `user_experience`.\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\nTraceability uses two shapes:\n\n- Frontmatter for stable document-level relationships such as `linked_github_repo` and `applies_to`.\n- `## Related Artifacts` with a structured `productspec-related-artifacts` block for item-level links from `AC-\u003Cnumber>`, `SM-\u003Cnumber>`, or `EVAL-\u003Cnumber>` to issues, pull requests, eval runs, dashboards, designs, releases, or engineering specs.\n\nEarly ecosystem contributions are welcome: examples, importer\u002Fexporter experiments, editor integrations, CI validation actions, review tools, and mappings into engineering-spec systems.\n\n## What Is Included\n\n- [SPEC.md](SPEC.md): the canonical v0.1 standard.\n- [CHANGELOG.md](CHANGELOG.md): release history for the standard and tooling.\n- [CONTRIBUTING.md](CONTRIBUTING.md): how to propose examples, validator changes, and section vocabulary changes.\n- [docs\u002Fphilosophy.md](docs\u002Fphilosophy.md): the core beliefs behind ProductSpec.\n- [docs\u002Flaunch-post.md](docs\u002Flaunch-post.md): a draft launch post for sharing the project.\n- [docs\u002Fwhy-productspec.md](docs\u002Fwhy-productspec.md): why the intent layer needs its own artifact.\n- [docs\u002Ffaq.md](docs\u002Ffaq.md): answers to common ProductSpec adoption questions.\n- [docs\u002Fget-started-with-agents.md](docs\u002Fget-started-with-agents.md): the shortest path from existing docs to agent-authored and agent-implemented Product Specs.\n- [docs\u002Fuse-in-your-repo.md](docs\u002Fuse-in-your-repo.md): copy-paste setup for using ProductSpec in an existing repository.\n- [docs\u002Fagent-usage.md](docs\u002Fagent-usage.md): how to use ProductSpec as a control file for coding agents.\n- [docs\u002Fadoption.md](docs\u002Fadoption.md): how teams can adopt ProductSpec across Git, Jira, Linear, Figma, CI, engineering specs, and agents.\n- [docs\u002Fadoption-levels.md](docs\u002Fadoption-levels.md): a step-by-step maturity ladder for adopting ProductSpec.\n- [docs\u002Fbefore-after.md](docs\u002Fbefore-after.md): a loose PRD transformed into ProductSpec.\n- [docs\u002Fproductspec-vs.md](docs\u002Fproductspec-vs.md): how ProductSpec differs from PRDs, Jira, Git, Figma, engineering design docs, OpenSpec, Spec Kit, and ADRs.\n- [docs\u002Frepo-starter-kit.md](docs\u002Frepo-starter-kit.md): copy-paste conventions for using ProductSpec in an existing repo.\n- [starter-kit\u002F](starter-kit\u002F): a copyable repo starter kit with ProductSpec, Decision Trace, AGENTS\u002FCLAUDE instructions, and CI.\n- [docs\u002Fhandoff-example.md](docs\u002Fhandoff-example.md): how ProductSpec interacts with Jira, Figma, Git, OpenSpec, Spec Kit, and coding agents.\n- [docs\u002Fend-to-end-handoff.md](docs\u002Fend-to-end-handoff.md): a concrete walkthrough from Product Spec to issue, design, engineering spec, agent loop, pull request, and launch learning.\n- [docs\u002Fvision.md](docs\u002Fvision.md): the public vision for ProductSpec as the intent layer.\n- [docs\u002Fvalidator.md](docs\u002Fvalidator.md): validator error and warning codes.\n- [docs\u002Fvalidate-your-first-product-spec.md](docs\u002Fvalidate-your-first-product-spec.md): the fastest local validation path.\n- [docs\u002Ffield-guide.md](docs\u002Ffield-guide.md): field-level guidance for writing each section.\n- [docs\u002Fversioning.md](docs\u002Fversioning.md): compatibility rules before v1.0.\n- [docs\u002Fdecision-trace.md](docs\u002Fdecision-trace.md): the optional companion standard for decisions, drift, and revisions.\n- [schema\u002Fproduct-spec.schema.json](schema\u002Fproduct-spec.schema.json): JSON Schema for parsed Product Spec documents.\n- [schema\u002Fdecision-trace.schema.json](schema\u002Fdecision-trace.schema.json): JSON Schema for Decision Trace documents.\n- [schema\u002Freview-annotation.schema.json](schema\u002Freview-annotation.schema.json): JSON Schema for portable review annotations.\n- [skills\u002Fproductspec\u002FSKILL.md](skills\u002Fproductspec\u002FSKILL.md): loadable agent guidance for implementing from Product Specs.\n- [skills\u002Fproductspec-authoring\u002FSKILL.md](skills\u002Fproductspec-authoring\u002FSKILL.md): loadable agent guidance for writing, validating, and converting Product Specs.\n- [conformance\u002F](conformance\u002F): valid and invalid fixtures for implementers.\n- [examples\u002FREADME.md](examples\u002FREADME.md): guide to choosing the right example.\n- [examples\u002F](examples\u002F): minimal and expanded examples.\n- [examples\u002Fdecision-traces\u002F](examples\u002Fdecision-traces\u002F): companion Decision Trace examples.\n- [parsers\u002Fts](parsers\u002Fts): TypeScript reference parser, validator, and CLI.\n\nExamples include AI features, consumer UX, enterprise workflows, internal APIs, and agent handoffs:\n\n- [examples\u002Fai-support-triage.product-spec.md](examples\u002Fai-support-triage.product-spec.md)\n- [examples\u002Fagent-coded-feature.product-spec.md](examples\u002Fagent-coded-feature.product-spec.md)\n- [examples\u002Fconsumer-family-calendar.product-spec.md](examples\u002Fconsumer-family-calendar.product-spec.md)\n- [examples\u002Fenterprise-approval-workflow.product-spec.md](examples\u002Fenterprise-approval-workflow.product-spec.md)\n- [examples\u002Finternal-webhook-replay-api.product-spec.md](examples\u002Finternal-webhook-replay-api.product-spec.md)\n- [examples\u002Fplatform-cache-migration.product-spec.md](examples\u002Fplatform-cache-migration.product-spec.md)\n- [examples\u002Ffull-prd.product-spec.md](examples\u002Ffull-prd.product-spec.md)\n\n## Canonical Sections\n\nMandatory sections, in order:\n\n1. `problem`\n2. `hypothesis`\n3. `scope`\n4. `acceptance_criteria`\n5. `success_metrics`\n\nOptional sections:\n\n`user_experience`, `customer_truth`, `solution_alternatives`, `solution`, `strategic_positioning`, `adoption`, `pricing`, `risks`, `ai`, `open_questions`, `rollout`, `related_artifacts`\n\n`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.\n\nCustom sections use `custom-\u003Ckebab-name>`.\n\n## Status\n\nVersion `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\u002Fversioning.md` for compatibility expectations.\n\nProductSpec distinguishes the standard version from the document revision:\n\n- `spec_format_version` tells tools which ProductSpec format the file uses.\n- `spec_revision` is an optional positive integer for this particular product decision. It starts at `1` and increments when intent materially changes.\n\nThe v0.9 milestone includes conformance fixtures, a structured validator, examples, a CLI, optional `spec_revision` frontmatter, traceability fields, a loadable agent skill, a copyable repo starter kit, and first-class Decision Trace validation:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec validate examples\u002Fminimal.product-spec.md\n```\n\nTo validate a Decision Trace:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec validate-trace examples\u002Fdecision-traces\u002Ftranscript-search.decision-trace.json\n```\n\nTo create a starter Product Spec:\n\n```bash\nnpm exec --package @productspec\u002Fparser -- productspec init my-feature.product-spec.md\n```\n\nFor local development from this repository:\n\n```bash\nnpm install\nnpm run build\nnode dist\u002Fcli.js validate examples\u002Fminimal.product-spec.md\n```\n\nOr use the shortcut:\n\n```bash\nnpm run validate -- examples\u002Fminimal.product-spec.md\n```\n\nTo run the local `productspec` CLI without a global install:\n\n```bash\nnpm run cli -- validate examples\u002Fminimal.product-spec.md\n```\n\nTo link the CLI during development:\n\n```bash\nnpm run link:cli\n```\n\nAfter linking, `productspec validate examples\u002Fminimal.product-spec.md` works if your npm\nglobal binary directory is on `PATH`.\n\nSee `docs\u002Fvalidate-your-first-product-spec.md` for the first-run path and current validator checks.\n\nSee `docs\u002Fadoption.md` for a practical team setup across Git, Jira, Linear, Figma, CI, engineering specs, and AI coding agents.\n","ProductSpec 是一个面向软件开发前期的开放规范标准，用于以结构化 Markdown 格式清晰表达产品意图（what\u002Fwhy），作为需求传递、工程规划与 AI 代理执行的统一输入依据。其核心支持可移植的规格版本控制（spec_revision）、决策追溯（Decision Trace）、机器可解析的章节标识与评审注解，并提供可加载的 AI 代理技能（如 spec 解析、PRD 转换、实施校验）。适用于跨职能团队协作、AI 辅助开发、需求变更频繁的中大型产品项目，以及需确保意图在人-人、人-机间无损传递的场景。",2,"2026-07-10 02:30:06","CREATED_QUERY"]