speckit-bdd-check
Skill3 starsChanged 5 days agoApache-2.0View on GitHub
Check the features, the glossary and the specs; turn each finding into a question to resolve
In this repository16 other files it gives its agents.
- .claude/rules/agents.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- speckit-analyzeSkill
- speckit-bdd-featuresSkill
- speckit-buildSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-designSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-reviewSkill
- speckit-specifySkill
- speckit-tasksSkill
- speckit-taskstoissuesSkill
The file
We split this skill into the rules it gives an agent
3 rules. About 0 are common, 1 is distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Consider the user input before proceeding, if it is not empty.
- Very specific: line 26
Read .specify/extensions/bdd/bdd-config.yml (where it is missing: glossary: GLOSSARY.md, features: features, specs: specs, no specs-from, …
- Very specific: line 35
When the config has specs-from, add --specs-from <specs-from>: the specs before it were written before the project had features, and the …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Check the features, the glossary and the specs
Runs the mechanical checks over every feature, not only the current spec's, and turns what they
find into questions. Before /speckit-clarify, these are its first questions: a contradiction or an
undefined word is exactly the ambiguity clarification exists to remove.
User input
$ARGUMENTSConsider the user input before proceeding, if it is not empty.
Run the checker
Read .specify/extensions/bdd/bdd-config.yml (where it is missing: glossary: GLOSSARY.md,
features: features, specs: specs, no specs-from, and as the checker
uvx --from "git+https://github.com/thinkmorestupidless/speckit-bdd@v0.2.0#subdirectory=checker" speckit-bdd),
then from the project root:
<checker> check --root . --glossary <glossary> --features <features> --specs <specs> --format jsonWhen the config has specs-from, add --specs-from <specs-from>: the specs before it were written
before the project had features, and the checker does not read them. Leave those specs as they are.
It exits 0 with no findings and 1 with some; each finding has file, line, check and
message, and specs says how many specs were checked and how many older ones were skipped.
With specs-from set and checked at 0 while the current spec exists, the setting names a spec
later than the current one: say so and stop, rather than reporting the project clean. An exit of 2,
or a command that cannot be run, is a problem with the setup: say so and stop, rather than reporting
the project clean.
Turn findings into questions
| Finding | What to do |
contradiction | Ask which outcome is right, quoting both scenarios. Never choose one yourself. |
undefined-term | Ask what the word means here, and whether it is the domain's (a term) or ordinary (an everyday word). |
refused-synonym | Reword the step with the glossary's term; no question. |
repeated-scenario | Remove the later copy and update any spec that names it; no question. |
unknown-scenario, removed-scenario-present | Correct the spec's reference, or ask whether the scenario should exist. |
untraced-requirement | Ask for the scenario that shows the requirement holds, or whether it is a requirement at all. |
duplicated-scenario | Move the Given/When/Then into a feature and reference it from the spec; no question. |
parse | Fix the Gherkin. |
Then read the features yourself for two things the checker cannot decide, and report each as a suspicion, not a finding:
- Implementation in a step: a screen, a button, a route, a status code or a component, where the domain's words belong.
- The same situation in other words: two scenarios that differ in wording but describe the same preconditions and action. If their outcomes differ, it is a contradiction.
Also settle every *Proposed.* glossary term: ask whether the word is right, what it does not mean,
and which synonyms to refuse.
Report
The questions, most consequential first (contradictions, then undefined terms, then the rest), each with its file and line, followed by what was fixed without asking. Say how many specs were checked, and how many older ones were not read.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

