feat(extensions): add EARS requirements syntax extension#3324
Open
dhruv-15-03 wants to merge 1 commit into
Open
feat(extensions): add EARS requirements syntax extension#3324dhruv-15-03 wants to merge 1 commit into
dhruv-15-03 wants to merge 1 commit into
Conversation
Add a bundled first-party extension that brings EARS (Easy Approach to
Requirements Syntax) to Spec Kit. EARS constrains each requirement to one
of five sentence patterns built around the mandatory modal "shall",
producing unambiguous, testable requirements.
The extension provides three explicit commands, mirroring the structure of
the bundled bug extension and writing artifacts under .specify/ears/<slug>/:
- speckit.ears.author - draft requirements for a feature directly in EARS
- speckit.ears.lint - read-only audit of existing requirements for EARS
conformance and ambiguity, with suggested rewrites
- speckit.ears.convert - rewrite free-form requirements into EARS and emit
an original-to-EARS traceability matrix
The extension is optional and additive: it changes no core templates and no
default behavior, and is registered as a bundled catalog entry alongside the
existing agent-context, bug, and git extensions.
Adds tests/extensions/ears covering the bundled layout, catalog
registration, bundle resolution, and install via ExtensionManager.
Refs github#1356
Assisted-by: GitHub Copilot (model: Claude Opus 4.8, autonomous)
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new first-party, bundled ears extension to Spec Kit that provides EARS (Easy Approach to Requirements Syntax) workflows for authoring, linting, and converting requirements, along with catalog registration and basic installation/layout tests.
Changes:
- Added a bundled
extensions/ears/extension (manifest, README, and three command prompts: author/lint/convert). - Registered the extension in
extensions/catalog.jsonas a bundled extension. - Added a new
tests/extensions/ears/suite to validate the bundled layout, catalog entry, bundle resolution, and install behavior.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| tests/extensions/ears/test_ears_extension.py | Adds tests for ears bundled layout, catalog registration, locator behavior, and install copying/manifest. |
| tests/extensions/ears/init.py | Marks the new test package for the ears extension. |
| extensions/ears/README.md | Documents the EARS extension purpose, commands, slug conventions, and guardrails. |
| extensions/ears/extension.yml | Declares the ears extension manifest and its provided commands. |
| extensions/ears/commands/speckit.ears.lint.md | Adds the lint command prompt spec (read-only audit + report output). |
| extensions/ears/commands/speckit.ears.convert.md | Adds the convert command prompt spec (rewrite + traceability matrix output). |
| extensions/ears/commands/speckit.ears.author.md | Adds the author command prompt spec (net-new EARS requirements authoring). |
| extensions/catalog.json | Registers ears as a bundled extension in the extensions catalog. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+35
to
+42
| "ears": { | ||
| "name": "EARS Requirements Syntax", | ||
| "id": "ears", | ||
| "version": "1.0.0", | ||
| "description": "Author, lint, and convert requirements using EARS (Easy Approach to Requirements Syntax) - the five industry-standard sentence patterns for unambiguous, testable requirements", | ||
| "author": "spec-kit-core", | ||
| "repository": "https://github.com/github/spec-kit", | ||
| "bundled": true, |
Comment on lines
+78
to
+82
| class TestBundleResolution: | ||
| def test_locate_bundled_extension_finds_ears(self): | ||
| located = _locate_bundled_extension("ears") | ||
| assert located is not None | ||
| assert (located / "extension.yml").is_file() |
Comment on lines
+25
to
+26
| Every EARS requirement uses the mandatory modal **shall** and exactly one pattern keyword: | ||
|
|
Comment on lines
+25
to
+26
| EARS defines five requirement patterns. Every EARS requirement uses the mandatory modal **shall** and exactly one pattern keyword: | ||
|
|
Comment on lines
+25
to
+26
| Every EARS requirement uses the mandatory modal **shall** and exactly one pattern keyword: | ||
|
|
Comment on lines
+60
to
+61
| 4. **Self-check** | ||
| - Verify every converted requirement uses `shall` exactly once and exactly one pattern keyword, names a `<system>`, and is atomic. Fix any that fail before writing. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a bundled first-party extension that brings EARS (Easy Approach to Requirements Syntax) to Spec Kit, addressing #1356 (the most-requested open feature by reactions, with no existing implementation).
EARS constrains every requirement to one of five sentence patterns built around the mandatory modal shall, producing unambiguous, testable requirements. It originated at Rolls-Royce and is widely used in aerospace, automotive, and other safety-critical domains.
What it adds
Three explicit commands, mirroring the structure of the bundled
bugextension and writing artifacts under.specify/ears/<slug>/:speckit.ears.authorrequirements.mdspeckit.ears.lintlint-report.mdspeckit.ears.convertrequirements.mdRegistered as a bundled catalog entry alongside
agent-context,bug, andgit.Design notes
bugextension.lintis strictly read-only - it never edits source; all rewrites are suggestions.Open question for maintainers
#1356 explicitly asks whether EARS should be a core/first-party capability or a community-contributed template. I implemented it as a bundled first-party extension because that is the lowest-friction, non-invasive vehicle, but I am happy to relocate it to the community catalog instead if you prefer - your call. The structure is identical either way.
Testing
tests/extensions/ears/covers bundled layout, catalog registration, bundle resolution, and install viaExtensionManager(8 tests, all passing).tests/extensionssuite passes. The one intermittent failure intest_extension_agent_context.py(bundled-script yaml import) is a pre-existing Windows test-ordering flake unrelated to this change: it passes in isolation and when this PR's tests are excluded.AI disclosure
This change was prepared by GitHub Copilot (model: Claude Opus 4.8) operating autonomously on behalf of @dhruv-15-03, who reviewed and directed the work. Per the repo disclosure conventions, the commit carries an
Assisted-by:trailer.Refs #1356