Articles

Spec management: store, version, and review specifications as code

Spec management is how a team stores a software specification, records each change, reviews that change, and keeps the specification current. Specification management is that same work: a specification is the document that says what the software must do, and managing it is how the document stays findable and trustworthy. Managing specs as code means those documents are files in the version-control system, so a change to a specification is a commit a reviewer can diff. Spec versioning is the history of those commits, together with the status written on each document. Keeping specs in sync with code means a proposed change that breaks the specification’s structure fails the same automatic check the code change goes through. Spec-driven development (SDD) is the practice of writing the specification before the code and treating the specification as the source of truth. Continuous integration (CI) is an automatic check on every proposed change. A product requirements document (PRD) is the prose that states the problem and the scope; the PRD template in Markdown is one SpecScore feature file in that shape. Easy Approach to Requirements Syntax (EARS) is a sentence pattern for a requirement. In SpecScore, a requirement (REQ) is a named rule inside a feature, and an acceptance criterion (AC) is an optional abstract condition that points at one or more of those rules. The check is a command-line interface (CLI) command, specscore spec lint, documented in lint specs in CI. The format lives in the public repository specscore/specscore (CC BY 4.0). The CLI lives in specscore/specscore-cli (Apache-2.0).

Last updated: 9 November 2026

Where the specification is stored

Spec management starts with a place the files can live. In this repository the specification is Markdown under spec/. The spec README lists the directories: features, plans, ideas, decisions, and lessons. A feature is one directory with a README.md. The feature specification is the contract for that file, and the PRD template is a filled example a linter has accepted.

specscore spec lint does not guess which tree to read. internal/cli/spec.go at tag v0.55.1, and the same function at tag v0.39.1, walks upward from the working directory until it finds specscore.yaml. The comment on that function says the command requires the file, returns exit code 3 when it is missing, and tells you to run specscore init. The dogfood workflow on this repository installs CLI v0.39.1 and then runs specscore spec lint, so the checkout it lints has that config file.

An index sits beside the feature files. Rule feature-index-row-sync is an error in the lint catalog at v0.39.1 and at v0.55.1. The catalog line says it requires each feature index row to match its feature file. That is the index staying aligned with the document it points at. It is not a comparison of the requirement’s wording with a source file.

Spec versioning

Spec versioning, for files committed in git, is the commit history of those files. SpecScore does not add a second version number on a feature. The revision a reviewer looks at is the commit on the branch. The status line on the document says where that feature sits in its lifecycle, which is a different fact from the git hash.

The feature specification in the repository is itself **Status:** Stable. It requires a **Status:** line immediately after the title, and the value must be one of Draft, In Review, Approved, Implementing, Stable, Amending, Rejected, or Deprecated. Rule status-mirror, in both catalogs named above, requires a status-bearing artifact’s frontmatter status: to match that body line, and forbids status: on a type that has no status. Matching the two copies is not the same as rejecting a word outside the eight values. Neither catalog line describes a rule that rejects a feature status outside that set, so this page does not claim one.

Plans use a different set. Rule P-006, in both catalogs, requires a single-file plan’s body **Status:** to be one of Draft, In Review, Approved, Executing, Blocked, Implemented, Failed, Rejected, Withdrawn, Superseded, or Deprecated. Rule idea-status-values rejects an idea status outside the set that rule allows. The catalog is the list. This page does not restate the idea words.

The plan specification also describes an optional ## Snapshots table with columns Date, Git Hash, Action, and Comment. It says each snapshot references a git commit hash of the plan’s state at that moment. The two lint catalogs checked for this page do not name a rule that resolves that hash, so this page does not claim the linter checks the commit exists. The hash is a pointer a person can follow in git. The published plan specification is the format page for that document.

Reviewing a specification

Review of a Markdown specification is the pull request that changes it. dogfood.yml runs on pull_request and on a push to main. The job checks out the repository, installs the CLI with SPECSCORE_VERSION set to v0.39.1, and runs specscore spec lint with no extra flags. GitHub Actions fails the step when that process exits non-zero. The permissions on the workflow are contents: read.

The feature status In Review means the feature is presented for review. Writing that word is an edit to the Markdown file. The pull request is where a person reads the diff. status-mirror checks that the frontmatter and the body name the same status. It does not record that a reviewer agreed with the prose. The validators page separates that structural check from a reading a person still has to do. The rule-by-rule account of what specscore spec lint reports is lint specs in CI.

Keeping specs in sync with code

Keeping specs in sync with code, on this site, means the specification is in the repository with the project, and CI fails the pull request when the specification tree violates the format. A pull request can change a feature file and the code in the same diff. Rule feature-index-row-sync keeps an index row aligned with the feature file it names. It does not read a source file and decide whether the code implements the requirement.

The excerpt below is the install and lint steps from dogfood.yml. The workflow file also sets permissions, a concurrency group, and a comment on why the pin is not latest. Those lines are omitted here. The commands are the ones that file runs.

Install and lint steps from dogfood.yml
name: Dogfood lint

on:
  push:
    branches: [main]
  pull_request:

jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
      - name: Install specscore CLI (pinned)
        env:
          SPECSCORE_VERSION: v0.39.1
        run: |
          curl -fsSL https://specscore.md/install/get-cli | \
            SPECSCORE_INSTALL_DIR="$HOME/.local/bin" sh
          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
          specscore --version
      - name: Lint spec tree
        run: specscore spec lint

The comment in that file says a floating latest pin changes the gate under the repository: a pull request and the main branch it targets can see different rules. The pin is v0.39.1. The job does not pass --fix. A clean run and a failing run, including the file:line [severity] rule: message line, are shown in lint specs in CI.

A sentence in the specification that no longer describes the code is not one of those findings. specscore spec lint validates structure: required files and sections, index rows, heading shape, and the references the rules name. It does not grade whether the implementation matches the requirement. That limit is the point of the validators page. Keeping the prose true is still a review of the diff.

How other spec-driven tools check a specification

The paragraphs below use the pages fetched on 9 November 2026. They describe those tools’ own checks. They do not say how many products exist, and they do not rank a market. The tools roundup is the longer comparison.

The GitHub Spec Kit agentic SDD reference describes /speckit.analyze as a read-only check across spec.md, plan.md, and tasks.md. It reports conflicts, gaps, and ambiguities, it never edits files, and you run it in the agent before implementation. The same page’s command list does not describe a CI job that runs specscore spec lint against a SpecScore tree.

OpenSpec stores a change as a directory directly under openspec/changes/. openspec validate checks changes and specs for structural issues. The reference says exit code 0 means every validated item passed, and exit code 1 means an item failed, the report request is invalid, the config cannot be read, or the run failed. That check is OpenSpec’s shape, including its requirement and scenario blocks, not a SpecScore ### AC: heading. On a different command, openspec status, the same reference says a batch that cannot load one change still exits 1, “so CI doesn’t accept an incomplete report as successful.” That sentence is about openspec status, not about openspec validate.

FAQ

What is spec management?

Spec management is storing a software specification, recording each change, reviewing that change, and keeping the specification current. In SpecScore the files are Markdown in the git repository, and specscore spec lint is the structural check a CI job can fail.

What is specification management?

Specification management is the same practice. The specification is the document that says what the software must do. Managing it means the document has a known place, a history, a review, and a check that its structure still matches the format.

How does managing specs as code work?

The specification is a tree of Markdown files under spec/, plus specscore.yaml at the repository root. A change is a commit. A pull request reviews the diff. dogfood.yml runs specscore spec lint on that pull request.

How does spec versioning work?

Git history is the version history of the files. A feature also carries **Status:** with one of the eight values the feature specification requires. A plan may record a ## Snapshots row whose Git Hash is a commit of the plan’s state. The linter catalogs cited here do not describe a rule that resolves that hash.

How do you keep specs in sync with code?

Put the specification in the repository and fail the pull request when specscore spec lint reports a structural violation, including an index row that does not match its feature file. The command does not decide whether the code implements the requirement. A sentence that has drifted from the code still needs a person to read the diff.

Keep the specification in the repository.

Have an idea how to improve this page?