v0.23.0: Parser Fidelity And Harness Demo

This release improves parser round-trip fidelity and adds a concrete agent harness demo.

Fixed:

• Unknown frontmatter preservation now covers all key shapes, not only snake_case keys.
• Kebab-case keys, keys with spaces, quoted keys, and non-ASCII keys are preserved under parser_metadata.unknown_frontmatter instead of being silently dropped on serialize.

Added:

• 5-minute agent harness demo.
• Harness demo example with Product Spec, Agent Run, and Decision Trace.
• Contributor guidance for adding example Product Specs.

Note: npm publish for @productspec/parser@0.23.0 still needs to be run separately.

v0.22.0: Agent Run Drafting

ProductSpec now has a first-class Agent Run drafting flow for the intent harness contract.

Highlights:

• Added productspec init-run <spec.product-spec.md> [run.agent-run.json] to draft an Agent Run receipt from a Product Spec.
• Added draft_agent_run to the MCP server so agents can request the same receipt through tools.
• Added status: "draft" to Agent Run, so generated receipts are honest until the agent records checked items, evidence, drift, and completion claim.
• Added Agent Run conformance fixtures.
• Updated README, MCP docs, Agent Run docs, starter kit, validator docs, versioning, and skills around the harness workflow.

The core idea: ProductSpec is the intent harness. Agent Run is the receipt. Agents should not just claim done. They should record which spec revision they used, which AC/EVAL/SM items they checked, what evidence they produced, and whether drift was detected.

Published npm package: @productspec/parser@0.22.0.

ProductSpec v0.10.0

ProductSpec v0.10.0

This release keeps the Product Spec document shape at spec_format_version: "0.1" and updates the reference parser, schema, docs, and conformance suite.

Added

• Fenced-code-aware section parsing. ## headings inside Markdown code samples no longer create duplicate or out-of-order ProductSpec sections.
• target_status: committed | provisional for structured Success Metrics.
• target_owner for provisional Success Metric targets, so teams can record honest post-launch target calibration without turning guesses into committed intent.

Published package

• @productspec/parser@0.10.0

Validation

• Parser test suite passes.
• ProductSpec and Decision Trace conformance fixtures pass.
• npm publish dry-run passed before publishing the parser package.

ProductSpec GitHub Action v0.8.0

ProductSpec GitHub Action v0.8.0

Validate ProductSpec Markdown files in GitHub Actions.

This release adds the reusable ProductSpec validator Action for teams that want Product Specs to live beside code and be checked in pull requests.

Example usage:

name: ProductSpec

on:
  pull_request:

jobs:
  validate-product-specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: gokulrajaram/ProductSpec@v0.8.0
        with:
          files: "docs/product-specs/**/*.product-spec.md"

This version validates the current ProductSpec document shape, including structured Scope, Acceptance Criteria, AI Evals, Success Metrics, traceability frontmatter, and Related Artifacts.

ProductSpec v0.2.0

ProductSpec v0.2.0

ProductSpec v0.2.0 is the first tooling milestone for the ProductSpec standard.

The Product Spec document shape remains spec_format_version: "0.1". This release hardens the tooling around that shape: parser, validator, conformance fixtures, CLI, npm package, and release docs.

Highlights

• Published @productspec/parser@0.2.0 to npm.
• Added the productspec CLI binary.
• Added repo-local and npm-based validation paths.
• Added conformance fixtures for valid and invalid Product Specs.
• Added stable validator error and warning codes.
• Added warnings for empty or very thin required sections.
• Added errors for duplicate sections, required-section order, and invalid custom section IDs.
• Added CI for parser tests, conformance validation, and npm package dry-run.
• Added docs/why-productspec.md.

Quick Start

npm exec --package @productspec/parser -- productspec validate path/to/file.product-spec.md

Links

• npm: https://www.npmjs.com/package/@productspec/parser
• Changelog: https://github.com/gokulrajaram/ProductSpec/blob/main/CHANGELOG.md
• Why ProductSpec: https://github.com/gokulrajaram/ProductSpec/blob/main/docs/why-productspec.md