.speccy.yaml
This page lists every key of .speccy.yaml, the repo configuration file. The file says which markdown files are spec docs, how docs link by path, who reviews pull requests, and how the review reports on GitHub.
Every key is optional. A missing file is an empty configuration: every folder with a spec doc is a bundle, and Speccy relaxes no check.
bundles: - path: docs/specs/*map: - glob: docs/prd-*.md profile: prd - glob: docs/sdd-*.md profile: sddlink_rules: - "docs/sdd-{name}.md implements docs/prd-{name}.md"link_patterns: jira: https://company.atlassian.net/browse/{key}adoption: relaxed: [links.has-upstream]mode: actionenforcement: advisorypr: inline_limit: 15 levels: [must, should] attribution: none| Key | Type | Default | What it does |
|---|---|---|---|
bundles |
list of path entries |
empty | Limits folder bundles to the folders that match a glob. |
bundles[].path |
glob | none | A folder path, relative to the root. |
map |
list of glob and profile entries |
empty | Makes each markdown file that matches a glob a spec doc with that profile. |
map[].glob |
glob | none; required | A file path, relative to the root. |
map[].profile |
profile key | none; required | The profile of each file that matches. |
map[].size |
feature, app or initiative |
none | The size of each file that matches, when the file names no size itself. |
frontmatter.keys.size |
a frontmatter key | none | The key of your template that holds the size of a doc, such as sdd_level. |
link_rules |
list of text | empty | Links spec docs by path: "<from> <kind> <to>". |
link_patterns |
map of scheme to URL pattern | empty | Turns a short external link target, such as jira:PAY-412, into a URL. |
adoption.relaxed |
list of check slugs | empty | Each check in the list reports at level INFO. |
mode |
action or app |
none | Who reviews pull requests: the GitHub Action, or the GitHub App of a hosted Speccy. With no key, both can run. |
enforcement |
advisory or blocking |
advisory |
Whether a Not Build Ready verdict fails speccy review and speccy action. |
pr.inline_limit |
integer | 15 | The most inline comments that speccy action posts on one bundle. |
pr.levels |
list of must and should |
MUST findings, and SHOULD findings with a fix | The finding levels that go inline as comments. |
pr.attribution |
speccy or none |
speccy |
With none, a pending review does not name Speccy. |
bundles
Section titled “bundles”A folder bundle is a folder that directly holds a markdown file with a type in its frontmatter. With no bundles entry, every such folder is a bundle. With one or more entries, Speccy reads a frontmatter type only in a folder whose path matches a path glob. A file that map selects is a spec doc in any folder.
A map entry makes a markdown file a spec doc without a change to the file. This is how Speccy reads docs that have no frontmatter.
- The glob matches the file path relative to the root.
*matches within one folder, and**matches any number of folders. - The first entry that matches a file gives its profile.
- A
typein the file’s frontmatter wins over the map. - The slug of a mapped file is its path without the extension, such as
docs/prd-payments. - Speccy does not check the profile key when it loads the file. A review of a doc with an unknown key stops, and the message lists the profiles.
On a GitHub source in the app, Write the mapping to the repo opens a pull request. It adds a map entry for each adopted type. Speccy edits the file in place, so its comments and other keys stay.
The size of a doc
Section titled “The size of a doc”A doc names its size with size in its frontmatter. Two keys of .speccy.yaml give the size of a doc that cannot hold that key.
frontmatter: keys: size: sdd_levelmap: - glob: "**/SDD - *.md" profile: sdd size: featurefrontmatter.keys.sizenames the key that your template uses for the size. Speccy reads the size of each doc from that key of its frontmatter. The value must befeature,apporinitiative.map[].sizegives one size to each file that the glob matches. Use it for a doc with no frontmatter.
Speccy takes the first of these that names a size: size in the frontmatter, the key of your template, the map entry. With none, it infers the size from the doc. Profiles and size explains the inferred size.
A value that is not a size does not stop the review. Speccy uses the next of the three, and the run adds a note that names the value and the key.
link_rules
Section titled “link_rules”A link rule links two spec docs by a path convention, so the docs need no links in their frontmatter.
- A rule is three words: the path of the spec doc that links, the link kind, and the path of the target spec doc.
- Both paths are file paths relative to the root.
{name}matches one path segment, or part of one. A variable name has lower-case letters and_.{name*}matches one or more whole folders, so one rule covers docs at every depth:{dir*}/SDD{rest} implements {dir*}/PRD{rest}. It stands between two/, or at an end of the path.- The kind is
implements,refines,referencesorsupersedes. - A rule makes a link only when the target spec doc exists.
- A link in the frontmatter comes first. A rule adds no second link of the same kind to the same target.
A target in an open pull request
Section titled “A target in an open pull request”An SDD and its PRD often go into review at the same time, in two pull requests. Then the tree of the SDD does not hold the PRD. A review that knows its GitHub repo looks for the target in the open pull requests of that repo:
speccy action --pr,speccy review-prs, thereview_urltool andPOST /reviews/url.- A GitHub source.
speccy actionin GitHub Actions.- The GitHub App of a hosted Speccy, in a pull request review.
A local folder review does not look, because the folder names no repo that Speccy can trust.
- Speccy looks only when the tree holds no file at the target path. A doc in the tree always wins.
- A pull request matches when its changed files add or change exactly the target path. A draft pull request counts.
- When several pull requests match, Speccy uses the one with the latest update. A run note names the others.
- Speccy reads the doc at the head commit of that pull request. The coherence, coverage and
reads: [upstream]checks run against it. - Speccy reads the doc again on each review, because a pull request can change.
- The report, the pull request review and the JSON output say
from pull request #N at <commit>. In the JSON output, the link haspullwithnumber,shaandurl. - A Build Ready verdict that depends on such a link gets a run note: the upstream doc is not merged.
- Only a link rule looks. A
linksentry in the frontmatter does not.
One review lists the open pull requests of the repo once. It reads the changed files of each pull request once, and only when a target is missing.
link_patterns
Section titled “link_patterns”A pattern turns a short external link target into a URL. The key is the scheme, and the value is a URL with {key} in it. With the sample above, the target jira:PAY-412 opens https://company.atlassian.net/browse/PAY-412.
- A scheme has lower-case letters, digits,
-,.and+, and it starts with a letter. githubandurlare built in, so a pattern cannot replace them.- The value must be an
httporhttpsURL.
A full URL target needs no pattern. Frontmatter lists the target forms.
adoption.relaxed
Section titled “adoption.relaxed”Each check slug in the list reports at level INFO, whatever its level in the profile. A relaxed check never blocks the verdict. speccy init --github fills the list with the checks that fail on the first lint pass.
A reply of /speccy enforce <slug> in a pull request removes one slug from the list, and the Action or the App commits the change. Reply commands has the details. Speccy does not check the slugs in the list.
mode says who reviews the pull requests of the repo.
mode |
The GitHub Action | The GitHub App of a hosted Speccy |
|---|---|---|
action |
Reviews the bundles in the runner. The HTML report is an artifact of the run. | Skips the repo. |
app |
Exits at once and posts nothing. | Reviews the pull request with the workspace profiles and models. |
| No key | Reviews. | Reviews. |
With mode: app, the Action prints The Speccy App reviews this repo (mode: app in .speccy.yaml), so the Action posts nothing. Keep the verdict in CI compares the two.
standalone is an older name of action, and Speccy still reads it. Connected mode is gone. mode: connected and the server key are errors, and the message names mode: app.
Which branch the App reads
Section titled “Which branch the App reads”A pull request cannot change its own gate. So the App reads some keys from the base branch, and the rest from the head commit.
- From the base branch:
enforcement,adoption.relaxedandmode. - From the head commit:
map,size,link_rulesand the sidecars. - A pull request that adds
.speccy.yamlfor the first time uses its own file.
enforcement
Section titled “enforcement”| Value | Result |
|---|---|
advisory |
A verdict never fails the command or the check run. The check run of a Not Build Ready bundle is neutral. |
blocking |
A Not Build Ready verdict fails the check run. speccy review and speccy action exit with code 1. |
An --enforcement flag wins over the file. The GitHub Action’s enforcement input passes that flag.
pr.inline_limit
Section titled “pr.inline_limit”speccy action posts MUST findings, and findings with a fix for the line, as inline comments on changed lines. It posts at most inline_limit for each bundle, and the rest go into the summary comment. A value of 0 or less is 15.
pr.levels
Section titled “pr.levels”pr.levels names the finding levels that go inline as comments. It applies to speccy action, speccy action --pr and speccy review-prs.
| Value | Inline comments on changed lines |
|---|---|
| No key | Each MUST finding. A SHOULD or INFO finding only with a fix for the line. |
[must] |
The same as no key. |
[must, should] |
Each MUST finding and each SHOULD finding. An INFO finding only with a fix. |
[should] |
Each SHOULD finding. No MUST finding. An INFO finding only with a fix. |
A finding of a named level on a line outside the diff goes into the summary comment, or into the body of a pending review. The --levels flag of speccy action --pr and speccy review-prs wins over the key.
pr.attribution
Section titled “pr.attribution”With pr.attribution: none, a pending review does not name Speccy. Use it when you post the findings in your own name.
- The body does not start with “Speccy reviewed”, and it has no
<!-- speccy:body -->markers. - A comment has no last line with the level, the check and the link to the check catalog.
- A comment has no hidden
<!-- speccy:key:… -->or<!-- speccy:ask:… -->marker.
Speccy keeps the ID of each comment it posts in the local state instead. A later speccy review-prs uses these IDs to update the pending review, and speccy pending list uses them to show which comments Speccy wrote. Thus keep the same local state between the rounds of a review.
The key applies to speccy action --pr --pending, speccy review-prs and speccy ask. The --no-attribution flag of these commands sets it for one run.
The GitHub Action in CI ignores pr.attribution: none and prints a note. The Action posts as its own bot, and it keeps no state between runs. It needs its markers to find its comments on the next push.
Where Speccy looks for the file
Section titled “Where Speccy looks for the file”| Command | The file it reads |
|---|---|
speccy, speccy serve |
.speccy.yaml in the served folder, --dir. |
speccy review, action, tui, mcp, add, export, handoff, report, verify |
The first .speccy.yaml from the current folder up. With none, these commands work on the current folder with no configuration. |
speccy init, speccy init --github |
.speccy.yaml in the current folder. |
| A GitHub source | .speccy.yaml at the root of the repo, on the source’s branch. |
A review of a GitHub URL: review_url, speccy action --pr, speccy review-prs, speccy ask |
.speccy.yaml at the root of the repo, at the commit that the review reads. When the repo has none, the .speccy.yaml of the folder that Speccy serves. The output names the file that the review used. |
The folder that holds the file is the root. Every glob and path in the file is relative to it.
What speccy init writes
Section titled “What speccy init writes”speccy init writes .speccy.yaml in the current folder, when the folder has none. The file sets enforcement: advisory. It holds commented examples of bundles, map, link_rules, adoption and mode. When the file exists, speccy init prints .speccy.yaml exists. Speccy did not change it.
speccy init also adds .speccy/state/ to .gitignore.
speccy init --github asks who reviews pull requests: 1 for the Action, 2 for the App. --reviewer action or --reviewer app gives the answer with no question. With no terminal, it picks the Action and says so. It writes the answer as mode. With app, it writes no workflow. It also writes map entries for the markdown files that read like a spec. It lints the mapped docs once, and it writes each check that fails into adoption.relaxed. It replaces a .speccy.yaml that exists.
Errors
Section titled “Errors”Speccy reads the file strictly. An unknown key, or a value of the wrong type, is an error:
.speccy.yaml does not parse: yaml: unmarshal errors: line 1: field mapp not found in type source.RepoConfigSpeccy checks every entry, and it joins the problems with ; after .speccy.yaml:.
| Problem | Message |
|---|---|
A bad bundles glob |
bundles[0].path "[" is not a valid glob |
A bad or empty map glob |
map[0].glob "docs/[" is not a valid glob |
A map entry with no profile |
map[0] has no profile |
A map size that is not a size |
map[0].size "huge" is not feature, app or initiative |
A key other than size in frontmatter.keys |
frontmatter.keys has "type", and only size has a mapping |
| A rule without three words | link_rules[0]: "…" is not "<from> <kind> <to>" |
| A rule with another kind | link_rules[0]: "…": the kind "implemented-by" is not one of implements, refines, references, supersedes |
| A variable twice in the first path | link_rules[0]: "…": {name} appears twice in the first path |
| A variable only in the second path | link_rules[0]: "…": {name} is in the second path but not the first |
| A folder variable inside a segment | link_rules[0]: "…": {dir*} stands for whole folders, so it must be between two / or at an end of the path |
| A brace that is not a variable | link_rules[0]: "…": "{Dir}/sdd.md" has a brace that is not a variable. A variable is {name} or {name*}, with lower-case letters and _ |
| A scheme with other characters | link_patterns: the scheme "Jira" is not lower-case letters, digits, and - . + |
| A built-in scheme | link_patterns: the scheme "github" is built in, so a pattern cannot replace it |
A pattern with no {key} |
link_patterns: the pattern "https://x/" has no {key} |
| A pattern that is not a web URL | link_patterns: the pattern "ftp://x/{key}" is not an http or https URL |
Another mode |
mode "remote" is not app or action |
mode: connected |
mode connected is gone: a hosted Speccy reviews pull requests with its GitHub App. Set mode: app, and remove server |
A server key |
server is gone with connected mode: a hosted Speccy reviews pull requests with its GitHub App. Remove server, and set mode: app |
Another enforcement |
enforcement "strict" is not advisory or blocking |
Another level in pr.levels |
pr.levels "info" is not must or should |
An empty pr.levels |
pr.levels names no level. Name must, should, or both |
Another pr.attribution |
pr.attribution "anonymous" is not speccy or none |
What each command does with an error:
| Command | Result |
|---|---|
speccy, speccy serve |
The bundles screen lists the problem under Folders that are not bundles, with Speccy ignores the file until you fix it. |
speccy review, action, export, handoff, report, verify |
The command prints .speccy.yaml is not valid with the message, and exits with code 2. |
| A GitHub source | The sync fails with .speccy.yaml in the repo is not valid and the message. |