@anselmdk/feature-spec-md 0.1.1 → 0.2.1

package/README.md

@@ -1,67 +1,123 @@
 # feature-spec-md
 
-Markdown feature specs with stable rule and scenario IDs, validation, coverage checks, and generated reports.
+Markdown specs for AI-assisted, testable spec driven development.
 
-The goal is simple:
+The concept is deliberately small:
 
 ```txt
-human-readable feature spec
-→ exact executable tests
-→ generated coverage report
+model + features + stack + design
+-> AI-written executable tests that reference stable spec IDs
+-> validation, coverage, screenshots, and reports
 ```
 
-The handwritten spec stays clean. It contains purpose, rules, and scenarios. Test mapping is derived from stable IDs instead of being written manually in the spec.
+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.
 
-## Format
+## What You Write
 
-Feature specs are ordinary Markdown files named `*.feature.md`.
+Use four ordinary Markdown document types:
 
-They use:
+```txt
+*.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.
+
+```md
+### 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
+```
+
+```ts
+test("ACCOUNT-ACCESS-S001 registered person signs in", async ({ page }) => {
+  // Covers ACCOUNT-ACCESS-R001 and ACCOUNT-M001.
+});
+```
+
+See [SPEC_FORMAT.md](SPEC_FORMAT.md) for the exact document format.
 
-- frontmatter for metadata
-- `## Purpose` for intent
-- `## Rules` for general business rules
-- `## Scenarios` for Given / When / Then examples
+## Install
 
-See `SPEC_FORMAT.md` and `examples/account-access.feature.md`.
+```bash
+npm install -D @anselmdk/feature-spec-md
+```
+
+Create starter specs:
+
+```bash
+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](docs/spec-driven-flow.md).
 
 ## CLI
 
 ```bash
-npm install
-npm run dev -- check --specs "examples/**/*.feature.md" --tests "tests/**/*.test.ts" --require-scenario-coverage=false
-npm run dev -- report --specs "examples/**/*.feature.md" --tests "tests/**/*.test.ts"
-npm run dev -- report --specs "examples/**/*.feature.md" --tests "tests/**/*.test.ts" --screenshots "test-results/spec-report/screenshots-*.json"
+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
 ```
 
-Playwright screenshot evidence can be shown in the report by passing one or
-more screenshot manifest JSON files. Each screenshot should point at the spec
-file and line it proves:
-
-```json
-{
-  "screenshots": [
-    {
-      "specPath": "specs/account-access.feature.md",
-      "line": 24,
-      "path": "screenshots/account-s001-line-24.png",
-      "title": "ACCOUNT-S001:24 Given a registered person is on the sign-in page"
-    }
-  ]
-}
+By default the CLI scans:
+
+```txt
+specs/**/*.model.md
+specs/**/*.feature.md
+specs/**/*.stack.md
+specs/**/*.design.md
+tests/**/*.spec.ts
+```
+
+Use explicit patterns when your project uses different paths:
+
+```bash
+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:
+
+```bash
+npx feature-spec-md report \
+  --screenshots "test-results/spec-report/screenshots-*.json"
 ```
 
 ## Library API
 
+Most integrations can use the top-level document API:
+
 ```ts
 import {
-  checkFeatureSpecs,
-  parseFeatureSpec,
+  checkSpecDocuments,
+  parseSpecDocument,
   renderHtmlReport,
-  validateFeatureSpec,
-} from "feature-spec-md";
+  validateSpecDocument,
+} from "@anselmdk/feature-spec-md";
 ```
 
+Feature-only helpers such as `parseFeatureSpec` and `checkFeatureSpecs` remain available for compatibility.
+
 ## Development
 
 ```bash
@@ -73,16 +129,4 @@ npm run build
 
 ## Releases
 
-Stable releases are published to npm by the `Publish to npm` GitHub Actions workflow when a `v*` tag is pushed, or when the workflow is run manually.
-
-Release candidates are published manually from GitHub Actions:
-
-1. Open the `Publish RC to npm` workflow.
-2. Run the workflow from `main`.
-3. The workflow verifies the package, creates a prerelease version using the current package version and GitHub run number, and publishes it with the npm `rc` dist-tag.
-
-Install the latest release candidate with:
-
-```bash
-npm install @anselmdk/feature-spec-md@rc
-```
+Release candidates and stable releases are documented in [docs/releasing.md](docs/releasing.md).

package/SPEC_FORMAT.md

@@ -1,21 +1,32 @@
-# Feature Spec Markdown format
+# Feature Spec Markdown Format
 
-Feature Spec Markdown is a lightweight convention for readable, testable feature specifications.
+Feature Spec Markdown is a lightweight format for testable specs.
 
-It intentionally uses ordinary Markdown and stable IDs instead of a dedicated executable specification language.
+It uses ordinary Markdown plus stable IDs so an AI can write clear product specs, another AI pass can write executable tests from those specs, and tooling can verify that the tests still cover the documented behavior.
 
-## File name
+## Document Set
 
-Use:
+A spec set can contain four document types:
 
 ```txt
+*.model.md
 *.feature.md
+*.stack.md
+*.design.md
 ```
 
-Example:
+- `*.model.md` defines shared domain vocabulary and global domain rules.
+- `*.feature.md` defines user-facing behavior with rules and scenarios.
+- `*.stack.md` defines technical platform choices and their rationale.
+- `*.design.md` defines product, UI, layout, visual, and interaction direction.
+
+The short version:
 
 ```txt
-account-access.feature.md
+model tells tests what things mean
+features tell tests what behavior must work
+stack tells implementation what tools and constraints to use
+design tells implementation what experience to create
 ```
 
 ## Frontmatter
@@ -24,9 +35,10 @@ Every file starts with YAML-like frontmatter:
 
 ```md
 ---
-id: ACCOUNT
-title: Account access
+id: KANBAN-CARD-AUTHORING
+title: Card authoring
 status: draft
+model: KANBAN
 ---
 ```
 
@@ -39,48 +51,81 @@ Optional fields:
 
 - `status`: `draft`, `active`, or `deprecated`
 - `owner`
+- `model`: a single referenced model id, for feature and design files
+- `models`: comma-separated referenced model ids, for feature and design files
+
+IDs use uppercase words separated by hyphens. IDs are the contract between specs, tests, reports, and implementation work.
+
+## Purpose
+
+Every model, feature, stack, and design file MUST include a short `## Purpose` section.
+
+Purpose explains the document boundary and intent. It SHOULD be one or two short paragraphs and SHOULD NOT contain rules, scenarios, implementation details, or roadmap notes.
 
-## Required sections
+## Model Files
+
+Model files use the `.model.md` suffix.
+
+Required sections:
 
 ```md
-# Account access
+# Kanban model
 
 ## Purpose
 
-## Rules
-
-## Scenarios
+## Model
 ```
 
+Optional sections:
+
+```md
 ## Rules
+```
+
+Model items use stable `-M001` IDs:
+
+```md
+### KANBAN-M001: Card
+
+A card represents one work item on the board.
+```
 
-Rules are durable business truths. They use stable IDs and requirement keywords.
+Model rules use stable `-R001` IDs and describe global invariants for the domain vocabulary:
 
 ```md
-- ACCOUNT-R001: A person MUST prove control of a registered email address before accessing an account.
-- ACCOUNT-R002: The system MUST NOT reveal whether an unknown email address belongs to an account.
-- ACCOUNT-R003: A signed-in person SHOULD be returned to the page they originally requested.
+- KANBAN-R001: A card MUST have one current workflow state.
 ```
 
-Use these keywords:
+## Feature Files
+
+Feature files use the `.feature.md` suffix.
+
+Required sections:
+
+```md
+# Card authoring
+
+## Purpose
 
-- `MUST`
-- `MUST NOT`
-- `SHOULD`
-- `SHOULD NOT`
-- `MAY`
-- `OPTIONAL`
+## Rules
 
 ## Scenarios
+```
 
-Scenarios are concrete examples. They use stable IDs and Given / When / Then steps.
+Rules use stable `-R001` IDs:
 
 ```md
-### ACCOUNT-S001: Registered person signs in
+- KANBAN-CARD-AUTHORING-R001: A new card MUST start in the To do column.
+```
+
+Scenarios use stable `-S001` IDs and Given / When / Then steps:
 
-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
+```md
+### KANBAN-CARD-AUTHORING-S001: User creates a card
+
+Given the user is on the board
+When they create a card with the title "Write release notes"
+Then the card "Write release notes" is visible in the To do column
 ```
 
 Allowed step keywords:
@@ -91,20 +136,137 @@ Allowed step keywords:
 - `And`
 - `But`
 
-## Test coverage convention
+Rules state durable product truths. Scenarios show concrete examples that executable tests can implement.
+
+## Stack Files
+
+Stack files use the `.stack.md` suffix.
+
+A stack file defines technical platform choices and the reasoning behind them.
+
+Required sections:
+
+```md
+# Kanban tech stack
+
+## Purpose
+
+## Stack
+```
 
-The spec file does not contain test mappings.
+Optional sections:
 
-Tests reference rule and scenario IDs in test titles, tags, annotations, comments, or metadata.
+```md
+## Context
+
+## Rationale
+
+## Consequences
+```
 
-Generated tooling can then answer:
+Example:
+
+```md
+---
+id: KANBAN-STACK
+title: Kanban tech stack
+status: draft
+---
 
+# Kanban tech stack
+
+## Purpose
+
+Define the initial technical stack for implementing the Kanban board.
+
+## Stack
+
+| Area     | Choice     |
+| -------- | ---------- |
+| Frontend | React      |
+| Language | TypeScript |
+| Testing  | Playwright |
+```
+
+## Design Files
+
+Design files use the `.design.md` suffix.
+
+A design file defines product, UI, layout, visual, and interaction direction.
+
+Required sections:
+
+```md
+# Kanban board design
+
+## Purpose
+
+## Design
+```
+
+Optional sections:
+
+```md
+## Principles
+
+## Layout
+
+## Interaction
+
+## Visual style
+```
+
+Example:
+
+```md
+---
+id: KANBAN-DESIGN
+title: Kanban board design
+status: draft
+model: KANBAN
+---
+
+# Kanban board design
+
+## Purpose
+
+Define the visual and interaction design direction for the Kanban board.
+
+## Design
+
+The board should feel lightweight, immediate, and calm.
+```
+
+## Splitting Guidance
+
+Split model files by coherent domain vocabulary, ownership, or lifecycle.
+
+Split feature files by user capability.
+
+Use stack files for broad technical choices such as framework, language, testing, persistence, deployment, and runtime constraints.
+
+Use design files for product/UI direction such as layout, interaction, visual style, and design principles.
+
+Keep each document small enough for an AI to read, revise, and use as test-writing context without extra explanation.
+
+## Test Coverage Convention
+
+Spec files do not contain test mappings.
+
+Tests reference model item, rule, and scenario IDs in test titles, tags, annotations, comments, or metadata.
+
+Generated tooling can answer:
+
+- Which model items are referenced?
 - Which scenarios have tests?
 - Which rules have executable coverage?
 - Which tests reference deleted or unknown spec IDs?
 - Which visible flows have screenshots, traces, or other evidence?
 
-For Playwright tests, capture one screenshot for each scenario step line in the
-spec. Report manifests associate each screenshot with the exact spec file and
-line number, so the HTML report can display the evidence beside the
-Given / When / Then / And line it proves.
+Example:
+
+```ts
+test("KANBAN-CARD-AUTHORING-S001 user creates a card", async ({ page }) => {
+  // Covers KANBAN-M001 and KANBAN-CARD-AUTHORING-R001.
+});
+```