feature-spec-md

Markdown specs for AI-assisted, testable spec driven development.

The concept is deliberately small:

model + features + stack + design
-> AI-written executable tests that reference stable spec IDs
-> validation, coverage, screenshots, and reports

The specs are meant to be written with an AI before implementation. The tests are meant to be written with an AI from those specs. feature-spec-md checks that the Markdown stays structured and that executable tests still cover the model items, rules, and scenarios the specs define.

What You Write

Use four ordinary Markdown document types:

*.model.md    shared domain vocabulary
*.feature.md  user-facing behavior, rules, and scenarios
*.stack.md    technical platform choices
*.design.md   product, UI, and interaction direction

Each document has frontmatter, a short ## Purpose, and stable IDs. Tests reference those IDs in titles, tags, annotations, comments, or metadata.

### ACCOUNT-ACCESS-S001: Registered person signs in

Given a registered person is on the sign-in page
When they request and open a valid sign-in link
Then they are signed in

test("ACCOUNT-ACCESS-S001 registered person signs in", async ({ page }) => {
  // Covers ACCOUNT-ACCESS-R001 and ACCOUNT-M001.
});

See SPEC_FORMAT.md for the exact document format.

Install

npm install -D @anselmdk/feature-spec-md

Create starter specs:

npx feature-spec-md init --kind model --dir specs
npx feature-spec-md init --kind feature --dir specs
npx feature-spec-md init --kind stack --dir specs
npx feature-spec-md init --kind design --dir specs

Workflow

1. Ask an AI to draft or update *.model.md, *.feature.md, *.stack.md, and *.design.md files.
2. Run npx feature-spec-md check until the spec set is valid.
3. Ask an AI to write executable tests from the specs, preserving the relevant -M001, -R001, and -S001 IDs in the test source.
4. Run npx feature-spec-md coverage to see which scenarios, rules, and model items have tests.
5. Run npx feature-spec-md report to generate an HTML implementation report for review or CI artifacts.

The longer flow, including AI prompts and CI setup, is in docs/spec-driven-flow.md.

CLI

npx feature-spec-md check
npx feature-spec-md coverage --fail-on-missing
npx feature-spec-md report --out test-results/feature-spec-report/index.html

By default the CLI scans:

specs/**/*.model.md
specs/**/*.feature.md
specs/**/*.stack.md
specs/**/*.design.md
tests/**/*.spec.ts

Use explicit patterns when your project uses different paths:

npx feature-spec-md check \
  --specs "product/**/*.model.md,product/**/*.feature.md,product/**/*.stack.md,product/**/*.design.md" \
  --tests "e2e/**/*.spec.ts"

The check command validates spec structure, references between documents, and test coverage. Scenario coverage is required by default when tests are scanned. Use --require-scenario-coverage=false while drafting.

The coverage command prints a terminal implementation report. Use --fail-on-missing when missing scenario tests should fail CI.

The report command writes an HTML report. It can include screenshot evidence from Playwright or another test runner by passing one or more screenshot manifest files:

npx feature-spec-md report \
  --screenshots "test-results/spec-report/screenshots-*.json"

Library API

Most integrations can use the top-level document API:

import {
  checkSpecDocuments,
  parseSpecDocument,
  renderHtmlReport,
  validateSpecDocument,
} from "@anselmdk/feature-spec-md";

Feature-only helpers such as parseFeatureSpec and checkFeatureSpecs remain available for compatibility.

Development

npm install
npm test
npm run typecheck
npm run build

Releases

Release candidates and stable releases are documented in docs/releasing.md.