NarrativeSpec

Version control for product messaging.

NarrativeSpec is a repo-native source of truth for product messaging. It stores approved claims, qualifiers, and supporting evidence in versioned files, then checks launch assets for drift before they ship.

This MVP focuses on deterministic review for complex product launches:

• approved vs unapproved claims
• stale wording and expired claims
• banned phrases
• missing qualifiers
• cross-surface drift across docs, release notes, and web copy
• CTA drift across site sections
• asset reuse across pages
• date/version drift across launches and docs
• long or filler-heavy phrasing that could be more succinct

Why it exists

Marketing systems move fast. Product narratives drift across websites, docs, launch briefs, release notes, and comms. NarrativeSpec treats messaging as structured project state instead of scattered copy.

Install

npm install
npm run build

CLI

narrativespec check --config examples/demo/narrativespec.config.yaml
narrativespec check --config examples/demo/narrativespec.config.yaml examples/demo/content
narrativespec init ./my-launch

Config

narrativespec.config.yaml

version: 1
registry:
  - ./narratives/claude.yaml
include:
  - ./content/**/*.md
  - ./content/**/*.html
rules:
  fail_on: error
  banned_phrases:
    - guaranteed safe
  unsupported_patterns:
    - pattern: "\\bnever hallucinates\\b"
      explanation: Absolute reliability claim
      severity: error

Claim registry files are YAML documents with a claims array:

product: Claude
claims:
  - id: claude-values
    status: approved
    canonical: Claude is designed to be helpful, honest, and harmless.
    aliases:
      - Claude is helpful, honest, and harmless.
    required_qualifiers:
      - designed to
    evidence:
      - label: Anthropic careers
        url: https://www.anthropic.com/careers

Output

Text output is optimized for CI and pull requests. JSON output is available with --format json.

Issue types:

• unsupported-claim
• banned-phrase
• stale-wording
• stale-claim
• missing-qualifier
• cross-surface-drift
• cta-drift
• asset-reuse
• date-version-drift
• succinctness

GitHub Action

This repo includes a local composite action at the repo root. Example:

name: narrativespec
on:
  pull_request:
  push:
    branches: [main]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ./
        with:
          config: examples/demo/narrativespec.config.yaml

Demo

The repo ships with two example fixtures:

• examples/happy-path is clean and should pass.
• examples/demo includes intentional issues and should fail.
• examples/anthropic-corpus targets a large Firecrawl harvest of Anthropic pages and Claude Code docs.

After building:

npm run example
npm run check:demo
node dist/src/cli.js check --config examples/anthropic-corpus/narrativespec.config.yaml

The latest Anthropic corpus proof and writeup live in proofs/.

Development

npm run typecheck
npm test
npm run build

Scope

This is a deterministic MVP. It does not generate copy, replace review, or claim truth on its own. It checks whether repo-declared messaging rules and evidence are being followed.