rogerchappel/specstitch

specstitch

A tiny local-first CLI that stitches PRDs, task lists, docs, tests, and source comments into a traceability quilt. It is deliberately boring: deterministic text parsing, no LLM calls, no telemetry, no archaeology séance. 🪡

Install

specstitch has not been published to the npm registry yet, so install and run it from a source checkout for now:

git clone https://github.com/rogerchappel/specstitch.git
cd specstitch
npm install
npm run build
node dist/src/cli.js scan --root tests/fixtures/tagged-repo

The global npm install -g specstitch command will become available only after the first npm release is published.

Usage

specstitch scan --root .
specstitch check --root . --min-coverage 0.8 --max-stale 0

scan reads docs/PRD.md, docs/TASKS.md, README.md, package.json, src, test, and tests, then writes:

• docs/TRACEABILITY.md
• docs/traceability.json

check runs the same scan and exits non-zero when coverage is below the threshold or stale tags exceed the maximum.

When a generated line or quoted example intentionally contains a requirement tag that should not count as evidence, add specstitch-ignore on that same line:

export const generatedNote = 'REQ-999'; // specstitch-ignore generated example

Configuration

Create specstitch.config.json to set default paths and thresholds:

{
  "prdPath": "docs/PRD.md",
  "tasksPath": "docs/TASKS.md",
  "outMarkdown": "docs/TRACEABILITY.md",
  "outJson": "docs/traceability.json",
  "minCoverage": 0.8,
  "maxStale": 0
}

CLI flags override config values.

Unknown options, unexpected positional arguments, and flags without their required values are usage errors: the CLI prints an actionable diagnostic and exits with status 2.