Specs and tests
spec17 recognises requirement IDs in markdown, test tags in test code, and citations in source comments, then reports where they meet.
Requirement IDs #
An ID is a prefix of 2 to 10 capital letters or digits (the first is a letter), a - and 1 to 5 digits, with optional dotted parts: ABC-12, REQ-0001, FR-001, AC-1.2. An underscore works too, dotted parts included: REQ_001, REQ_001.2. A non-breaking hyphen (U+2011) reads as -.
Well-known tokens that look like IDs are never requirements: UTF-8, ISO-8601, TLS-1.3, SHA-256, RFC-2119, CVE-2024 and similar. Only these shapes are skipped (the list is not_id in core/resources/spec_format.toml), so HTTP-01 and RFC-1 are still IDs.
A requirement also has a level: MUST, SHOULD, MAY or SHALL. Heading and paragraph styles accept the EARS shall in lower case too; bullets and table rows do not, and should and may must always be capitals.
Requirement styles #
spec17 reads several ways of writing a requirement, and one repo can mix them. The styles below are small fixtures in core/test-data that the tests load: bullets, tables, Spec Kit, headings and paragraphs are files of the styles repo; OpenSpec, Kiro, Superpowers and the fallback each have a repo of their own. Spec folders are detected, so there is nothing to configure.
Bullets #
An ID, usually bold, and a level on the first line. A bullet may be -, * or +, or a numbered item. The ID can be bold, in backticks or plain, with an optional :. The requirement runs on to the next blank line.
- **STY-01** MUST — classic bold bullet.
* STY-02: The system SHALL accept a star bullet.
1. `STY-03` SHOULD: numbered, backtick ID.
- **STY-04:** MAY wrap
onto a second line.
Tables #
A table row whose first cell is an ID, with the level in the row. Header rows hold no ID and are ignored.
| ID | Level | Text |
|---|---|---|
| STY-05 | MUST | in a table row |
GitHub Spec Kit #
Functional requirements are plain bullets. A [NEEDS CLARIFICATION: …] stays in the requirement text.
- **FR-001**: System MUST allow users to sign in.
- **FR-002**: System MUST [NEEDS CLARIFICATION: auth method not specified].
- **NFR-001**: Pages SHOULD load within 2 seconds.
Headings #
A heading that starts with an ID opens a requirement that runs to the next heading. The level can be on any line of the block, so EARS sentences work. Lines such as **Covers:** and a cross-reference table of IDs without levels are not read as requirements.
### HDG-1: Input directory from a property
**Covers:** B-1
When the application starts with `importer.input-dir` set, the importer shall use that path.
### RUL-1
**Covers:** project-wide
**MUST NOT** add a batch framework.
Paragraphs #
A paragraph that opens with a bold ID is a block requirement too, with the level anywhere in it. Dotted IDs sort by number: PAR-1.2 comes before PAR-1.10.
**PAR-1.1** Happy path
WHEN the input directory has CSV files
THEN the batch job executes
SHALL read all `*.csv` files
OpenSpec #
Requirements are ### Requirement: ID name headings, usually in openspec/specs/*/spec.md, with scenarios under them.
### Requirement: UIX-01 Serve the page
The system SHALL serve an HTML page at `GET /`.
#### Scenario: Page loads
- **WHEN** a user requests `GET /`
- **THEN** the response status is `200 OK`
A change in progress, openspec/changes/<name>/specs/…, sorts its requirements under ## ADDED, ## MODIFIED, ## REMOVED and ## RENAMED headings. The change’s version of an ID replaces the base one, and a requirement under ## REMOVED Requirements is retired. openspec/changes/archive/ and files such as tasks.md are not specs. A ### Requirement: Title with no ID is reported as a spec issue and not counted: give it an ID.
Kiro and other unnumbered specs #
Kiro’s requirements.md (### Requirement 1, user stories, numbered acceptance criteria) carries no IDs, so spec17 finds no requirements in it and reports the heading as a spec issue. Add IDs in any style above to have it counted.
Superpowers #
Design docs in docs/superpowers/specs/ are scanned like any specs folder; plans in docs/superpowers/plans/ are not.
No specs folder #
When no specs folder holds a requirement line, any markdown file that has one is used. In the fallback fixture that is a design note:
### FBK-1: Startup
The service shall start in under a second.
A repo with no requirement lines at all still opens, with zero requirements.
Reference documents #
A link such as [ADR-0003](decisions/0003-x.md) to a decision record makes that record a reference document. It is listed with state ref and is never due.
Lines that are not requirements #
| Line | Why it is skipped |
|---|---|
- **UTF-8** encoding is used everywhere. | UTF-8 is a well-known token, not an ID |
- ISO-8601 MUST — a date format | same; the level does not make it a requirement |
- **B-1** The system reads the input directory. | B-1 has one letter, so it is not an ID |
| A1 | single file? | All files | | no ID |
Prose mentions STY-01 and HDG-1 but defines nothing. | not a bullet, row, heading or paragraph that opens with an ID |
- **STY-01** is referenced here without a level. | no level, so it does not define STY-01 again; with no definition elsewhere it is a spec issue |
UTF-8 files are read with or without a BOM, and non-ASCII text is kept as written.
Marks #
An ending (manual), (later) or (deferred) marks a bullet; (deferred) means the same as (later). A mark before the end of the line does not count, and the requirement stays due. A struck-out bullet, - ~~**ABC-12**, is retired. A check mark (✅, ✔, ☑ or ✳) says the author considers it done; spec17 then reports whether the tree holds evidence for that (see the verdicts below).
Tests and citations #
- A test tag is the ID in square brackets:
[ABC-12], or[ABC-12, ABC-14]for several. Put it in the test’s title, name or doc attribute, for example a Swift@Test("[REQ_001] underscore tag"), a Rust#[doc = "[API-02]"]above#[test], or a Python docstring. Tags are read in files in test folders or named like tests (test_*.py,*_test.go,*.test.ts). - A source citation is an ID in a line comment (
//,#,///) of a source file.// (ABC-12)is the convention; the parentheses are not required, and block comments are not scanned.
The report also lists tags it distrusts, under invalid tests: an ID no spec defines (unknown) or a struck-out one (retired), an ID tagged only in a comment (comment-only), only on a disabled test (disabled), or only on a test with no direct assertion (no-assert). A citation of an ID no spec defines is a dangling citation when a spec uses the same prefix, which catches typos and retired IDs.
States #
| State | Meaning |
|---|---|
tested | A test is tagged with the ID |
src-only | Code cites the ID, no test is tagged |
none | No test and no code |
manual | Marked (manual): checked by hand, no test expected |
later | Marked (later) or (deferred): not due yet |
ref | A reference document: never due |
A requirement with a check mark also gets a verdict: NO-TEST (no tagged test), NO-LINK (its tests reach no app code in the CodeGraph index), ok (they do), or unchecked (there is no index). Every state and verdict is evidence found in the tree, not a statement that the requirement is met.
Configuration #
Most repos need none. To override a detected field, put spec17.json at the repo root. spec17.example.json shows the common fields (specs, tests, src, ext, profiles, retired_prefixes, codegraph); infra_paths exists too. A field you set replaces its detected value:
{
"specs": "docs/specs",
"tests": ["Tests"],
"src": ["Sources"],
"ext": ["swift"],
"profiles": [{
"name": "swift",
"case": "^\\s*@Test\\b|^\\s*func\\s+test",
"test": "(^|/)[^/]*Tests?(/|\\.swift$)"
}],
"retired_prefixes": [],
"codegraph": ".codegraph/codegraph.db"
}
Each file is read with the profile of its language: comment markers, decl, assert, off, test (which paths are tests) and case (the line that opens a test case). profiles holds entries shaped like a [[profile]] of core/resources/profiles.toml: {"name": "rust", "assert": "assert!|panic!"} changes only that field of the built-in Rust profile, and a new name with ext and comment adds a language. A field a profile does not have is an error, and so are the old top-level comment, decl, assert, off, case and test_files.
The requirement-line patterns (core/resources/spec_format.toml) and the language profiles (core/resources/profiles.toml) are compiled into the binary. To support another language, add a [[profile]] and rebuild, or put the same entry in profiles.
Paths in .aiignore or .spec17ignore (gitignore syntax) are left out of every scan. Symlinks are followed only inside the repo root or a path in the ALLOWED_PATHS environment variable, a :-separated list.