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

Canonical: https://specscore.md/articles/spec-management/

Last updated: 9 November 2026

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](https://specscore.md/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](https://specscore.md/validators/) (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](https://specscore.md/articles/feature-spec-template/) is one SpecScore feature file in that shape. [Easy Approach to Requirements Syntax](https://specscore.md/articles/ears-requirements/) (EARS) is a sentence pattern for a requirement. In [SpecScore](https://specscore.md/), a requirement (REQ) is a named rule inside a feature, and an [acceptance criterion](https://specscore.md/articles/acceptance-criteria/) (AC) is an optional abstract condition that points at one or more of those rules. The check is a [command-line interface](https://specscore.md/cli/) (CLI) command, `specscore spec lint`, documented in [lint specs in CI](https://specscore.md/articles/lint-specs-in-ci/). The format lives in the public repository [specscore/specscore](https://github.com/specscore/specscore) ([CC BY 4.0](https://github.com/specscore/specscore/blob/main/LICENSE)). The CLI lives in [specscore/specscore-cli](https://github.com/specscore/specscore-cli) ([Apache-2.0](https://github.com/specscore/specscore-cli/blob/main/LICENSE)).

## 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](https://github.com/specscore/specscore/blob/main/spec/README.md) lists the directories: features, plans, ideas, decisions, and lessons. A feature is one directory with a `README.md`. The [feature specification](https://specscore.md/feature-specification) is the contract for that file, and the [PRD template](https://specscore.md/articles/feature-spec-template/) is a filled example a linter has accepted.

`specscore spec lint` does not guess which tree to read. [internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go) at tag v0.55.1, and the same function at [tag v0.39.1](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go), 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](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml) 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](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md) and at [v0.55.1](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md). 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](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md) 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](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md) 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](https://specscore.md/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](https://github.com/specscore/specscore/blob/main/.github/workflows/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](https://specscore.md/validators/) 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](https://specscore.md/articles/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](https://github.com/specscore/specscore/blob/main/.github/workflows/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

```yaml
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](https://specscore.md/articles/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](https://specscore.md/validators/). 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](https://specscore.md/spec-driven-development/tools/) is the longer comparison.

The [GitHub Spec Kit agentic SDD reference](https://github.github.io/spec-kit/reference/agentic-sdd.html) 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](https://github.com/Fission-AI/OpenSpec) stores a change as a directory directly under `openspec/changes/`. [openspec validate](https://openspec.dev/docs/cli) 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](https://github.com/specscore/specscore/blob/main/.github/workflows/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.

## Sources

CLI files and lint catalogs read 9 November 2026 at specscore-cli tags v0.39.1 (the version dogfood.yml installs) and v0.55.1. The feature and plan requirements are the files linked below in specscore/specscore. Competitor pages were fetched the same day.

- [specscore/specscore — spec/README.md](https://github.com/specscore/specscore/blob/main/spec/README.md)
- [specscore/specscore — feature status values](https://github.com/specscore/specscore/blob/main/spec/features/feature/README.md)
- [specscore/specscore — plan snapshots](https://github.com/specscore/specscore/blob/main/spec/features/plan/README.md)
- [specscore/specscore](https://github.com/specscore/specscore)
- [specscore/specscore — CC BY 4.0 licence](https://github.com/specscore/specscore/blob/main/LICENSE)
- [specscore/specscore-cli](https://github.com/specscore/specscore-cli)
- [specscore-cli — Apache-2.0 licence](https://github.com/specscore/specscore-cli/blob/main/LICENSE)
- [specscore-cli v0.39.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.39.1/internal/cli/spec.go)
- [specscore-cli v0.55.1 — internal/cli/spec.go](https://github.com/specscore/specscore-cli/blob/v0.55.1/internal/cli/spec.go)
- [specscore-cli v0.39.1 — lint rule catalog](https://github.com/specscore/specscore-cli/blob/v0.39.1/docs/lint-rules.md)
- [specscore-cli v0.55.1 — lint rule catalog](https://github.com/specscore/specscore-cli/blob/v0.55.1/docs/lint-rules.md)
- [specscore/specscore — dogfood.yml (CLI v0.39.1)](https://github.com/specscore/specscore/blob/main/.github/workflows/dogfood.yml)
- [What SpecScore validates](https://specscore.md/validators/)
- [Lint specs in CI with a spec linter](https://specscore.md/articles/lint-specs-in-ci/)
- [EARS requirements syntax explained, with examples](https://specscore.md/articles/ears-requirements/)
- [How to write acceptance criteria AI agents can verify](https://specscore.md/articles/acceptance-criteria/)
- [PRD template in Markdown for AI coding](https://specscore.md/articles/feature-spec-template/)
- [Feature specification](https://specscore.md/feature-specification)
- [Plan specification](https://specscore.md/plan-specification)
- [GitHub Spec Kit — agentic SDD reference (/speckit.analyze)](https://github.github.io/spec-kit/reference/agentic-sdd.html)
- [OpenSpec CLI reference — openspec validate and openspec status](https://openspec.dev/docs/cli)
- [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
- [Spec-driven development tools](https://specscore.md/spec-driven-development/tools/)

## Related

- [Lint specs in CI with a spec linter](https://specscore.md/articles/lint-specs-in-ci/)
- [PRD template in Markdown for AI coding](https://specscore.md/articles/feature-spec-template/)
- [How to write acceptance criteria AI agents can verify](https://specscore.md/articles/acceptance-criteria/)
- [EARS requirements syntax explained, with examples](https://specscore.md/articles/ears-requirements/)
- [Spec-driven development](https://specscore.md/spec-driven-development/)
- [Spec-driven development tools](https://specscore.md/spec-driven-development/tools/)
- [Feature specification](https://specscore.md/feature-specification)
- [Plan specification](https://specscore.md/plan-specification)
- [CLI](https://specscore.md/cli/)
- [What SpecScore validates](https://specscore.md/validators/)
