The spec format

An BSF file is any Markdown document. The parser walks the mdast tree and extracts every fenced code block whose language tag is exactly criterion. The body of each block is YAML conforming to the Criterion schema. All other Markdown is ignored, which means product specs, PRDs, and this document can carry criteria inline next to the prose that motivates them.

Rules:

• A file with zero criterion blocks is a valid spec with zero criteria; verify reports nothing to do and exits 0. lint warns.
• Duplicate id values across blocks in one file are a SPEC_SCHEMA error.
• source.file and source.line are populated by the parser from the mdast position; if present in the YAML they are overwritten.
• Unknown top-level keys in a criterion are a schema error (zod .strict()). This is deliberate; typos in verfiy must not silently become unverifiable criteria.
• Multiple spec files MAY be passed to verify; criteria IDs must be unique across the set.

Example (shown inside a four-backtick fence so this illustration is a single markdown code node and the parser does not extract it; only top-level criterion code nodes count):

The CLI must be safe to run in CI.

```criterion
id: EXM-001
title: Nonzero exit on any FAIL
ears: When any criterion in scope has verdict FAIL, the CLI shall exit with code 1.
pattern: event
priority: must
verify:
  - type: command
    run: pnpm byspec verify fixtures/specs/one-failing.spec.md --repo fixtures/repos/failing-repo --provider mock
    expect_exit: 1
```

The parser lives in packages/core/src/spec/parse.ts and exposes parseSpecFile({ path, root }) and parseSpecString({ content, sourceFile }).

Source: docs/byspec-implementation-spec.md § 6. The Byspec Spec Format (BSF)

EARS (Easy Approach to Requirements Syntax) has five patterns. Byspec uses them because they are testable by construction and because a criterion that cannot be fitted into one of them is usually two criteria or an opinion.

Lint rules#

byspec lint evaluates each criterion against the rules below and produces a per-criterion score and a document score (mean of criterion scores, floored). Each rule has a severity and a deduction.

Score = max(0, 100 minus deductions). lint --min-score N exits 1 when the document score is below N (default from config, 80). Errors always exit 1 regardless of score.

Vague terms#

Default list, overridable in config: fast, quickly, quick, easy, easily, simple, user-friendly, intuitive, appropriate, appropriately, reasonable, reasonably, robust, efficient, efficiently, seamless, seamlessly, as needed, when necessary, etc, and so on, properly, correctly, good, better, best, optimal, adequate, sufficient, minimal, various, some, many, several. Matching is whole-word, case-insensitive. "correctly" is on the list on purpose: "the system shall correctly parse" is not a requirement.

Rewrite (--rewrite)#

When --rewrite is passed, for every criterion with at least one error or warning, the linter asks the provider for a rewrite. The prompt (Section 14.4) contains the original criterion, the rule violations, the EARS table, and instructions to (a) rewrite into exactly one EARS pattern, (b) split compound criteria into multiple criteria with suffixed IDs (ABC-001a, ABC-001b), (c) replace vague terms with measurable ones or mark them [NEEDS NUMBER], and (d) propose at least one deterministic check where obvious. Output is written to a sibling file whose trailing .md is replaced with .rewrite.md (vague.spec.md becomes vague.spec.rewrite.md), containing only criterion blocks and a one-line note per block explaining the change. The original file is never modified. Suffixed IDs like ABC-001a are valid only in rewrite files; the human renumbers before adopting them, and the parser rejects them elsewhere via L01_ID.

Lint output#

--format json prints one document:

{
  "document_score": 74,
  "exit_code": 2,
  "totals": { "errors": 1, "warnings": 3, "info": 0 },
  "criteria": [
    {
      "id": "ABC-001",
      "score": 65,
      "violations": [
        { "rule": "L05_VAGUE", "severity": "warning", "message": "vague term: quickly" }
      ]
    }
  ]
}

Text output prints one line per violation (ABC-001 warning L05_VAGUE vague term: quickly) and a closing score line.

Source: docs/byspec-implementation-spec.md § 7. EARS and the clarity gate