Authoring ProductSpec Files

ProductSpec is a Markdown format for the product decision that comes before tickets, engineering plans, and code. One file per feature holds the committed intent.

This skill covers producing that file. Reading a finished spec and building against it is a different job, and the productspec skill covers it. This skill ends when the file validates.

Always true

• Files use the extension .product-spec.md: YAML frontmatter between --- markers, then ## Section headings.
• Six sections are mandatory, in order: problem, hypothesis, product_summary, scope, acceptance_criteria, success_metrics.
• Headings match case- and separator-insensitively. ## Acceptance Criteria and ## acceptance_criteria are the same section. Title case is the convention.
• Frontmatter requires spec_format_version: "0.1", title, artifact_type (hypothesis | prd | openspec_proposal), author, created_at, updated_at. Optional: spec_revision, linked_github_repo, applies_to, custom_sections, tool_metadata.
• acceptance_criteria and success_metrics each carry a required fenced block. Prose alone fails validation. Structured scope, AI evals, and related artifacts are optional.
• Structured items carry durable ids: AC-<number>, SM-<number>, EVAL-<number>. Other documents cite them.
• AI evals live inside ## Acceptance Criteria, never in a section of their own. Related artifacts live inside ## Related Artifacts.
• Validate any file with: npm exec --yes --package @productspec/parser -- productspec validate <file> (--yes suppresses npm's interactive install prompt, which hangs CI and non-interactive agents).
• The full normative definition is SPEC.md in the ProductSpec repository: https://github.com/gokulrajaram/ProductSpec/blob/main/SPEC.md. When this skill and SPEC.md disagree, SPEC.md wins.

Pick the task, read one reference