FAQ

What is SpecScore? What a spec score means

SpecScore is an open file format for software specifications that a linter checks in CI. A specification (spec) is a written description of what software must do. SDD (spec-driven development) means writing that spec before the code and checking the code against it. CI (continuous integration) is the automated build that runs on every change. Markdown is plain text with light formatting, and YAML is a plain-text format for structured fields.

Published

SpecScore in one paragraph

SpecScore defines how to write features, requirements, acceptance criteria and plans as Markdown files with YAML fields, stored in a spec/ folder of your repository. A requirement (REQ) is one behavior the software must have. An acceptance criterion (AC) is a check, written as Given / When / Then, that shows a requirement is met. A PRD (product requirements document) can be broken into these pieces. The specscore CLI reads the tree, so people and AI coding agents work from the same files. Read spec-driven development for the method, and the homepage overview for the artifact lifecycle.

What "score" means in SpecScore

A score you read. A musical score sets out every part, voice and bar in one structured document. A SpecScore tree does the same for a product: features, their requirements, the acceptance criteria that verify them, and the plans and tasks that cite them, all linked and visible at once.

A score you pass. specscore spec lint is the deterministic check: it fails when required sections are missing, references are broken or a lifecycle status is wrong. The /score skill in SpecStudio Skills is the AI-judged one: it runs the reviewers configured in specscore.yaml and returns an A–F grade with findings for each artifact.

Outside SpecScore, "spec score" can also mean a rating of a device's hardware specifications. This page is about software specifications.

How SpecScore specs are written

A Feature spec is a Markdown file with a short YAML header. Each requirement gets an ID, and each acceptance criterion names the requirement it verifies. Requirements can use EARS (Easy Approach to Requirements Syntax) sentences; see EARS requirements. For a starting point, use the feature spec template and acceptance criteria an agent can verify.

How specs are checked: locally and in CI

Run specscore spec lint on your machine or in a pre-commit hook, then add the same command as a CI step so a pull request with a broken spec fails before it merges. This repository does that in its own dogfood workflow, with a pinned CLI version. The step-by-step guide is how to lint specs in CI, and install the CLI covers macOS, Linux and Windows.

Who SpecScore is for

Teams that write specs for AI coding agents and want those specs to stay correct as the code changes: broken links, missing sections and stale statuses fail the build instead of drifting. It works with any agent, or none, because the specs are ordinary files. To see how it differs from other tools, read how SpecScore compares and the spec-driven development tools roundup.

The format is open source on GitHub (CC BY 4.0), and so is the CLI (Apache-2.0).

Questions about SpecScore and spec scores

What is SpecScore?

SpecScore is an open file format for software specifications, written in Markdown and YAML and kept in your git repository. Its command-line tool lints the specs, locally and in continuous integration (CI), so broken structure fails the build.

What does "spec score" mean?

In SpecScore, "score" has two meanings. Like a musical score, a spec tree lays out the parts of a product so a team or an AI agent can read them at once. It is also a check: the linter passes or fails a spec, and the optional /score skill grades an artifact from A to F.

Is a spec score a number?

Not by default. specscore spec lint reports pass or fail with the problems it found. The /score skill in SpecStudio Skills returns a letter grade from A to F, produced by the reviewers configured in specscore.yaml; Approved means the grade meets a threshold, B by default.

What is a spec score outside SpecScore?

People also use "spec score" for a rating of a product's technical specifications, such as a phone's. That is a different idea: SpecScore checks software specifications that describe what to build.

Is SpecScore free?

Yes. The format and documentation are published under CC BY 4.0 in the specscore/specscore repository, and the CLI is Apache-2.0 in specscore/specscore-cli.

More answers: the SpecScore FAQ.

Have an idea how to improve this page?