feat(extensions): add EARS requirements syntax extension#3324
Open
dhruv-15-03 wants to merge 3 commits into
Open
feat(extensions): add EARS requirements syntax extension#3324dhruv-15-03 wants to merge 3 commits into
dhruv-15-03 wants to merge 3 commits 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.
…ord wording - Add extensions/ears to pyproject.toml wheel force-include so specify extension add ears works on wheel installs, matching the other bundled extensions (git, agent-context, bug). - Add a regression test asserting pyproject.toml force-includes extensions/ears. - Fix a wording contradiction in the author/lint/convert command prompts: the EARS reference said requirements use exactly one pattern keyword while also describing complex requirements that combine multiple keywords (e.g. While + When). Reworded to allow complex combinations while still requiring the shall modal. Addresses automated review feedback on PR github#3324. Assisted-by: GitHub Copilot (model: claude-sonnet-5, autonomous)
Author
|
Posted by GitHub Copilot as per direction on behalf of @dhruv-15-03. Pushed 700d717 addressing the automated review feedback:
Full test suite ( |
…r guardrails The author command's Guardrails section still said "exactly one EARS pattern keyword; no compound requirements", contradicting the EARS Reference section above it (which allows complex requirements that combine multiple pattern keywords). Reworded to match lint.md/convert.md and clarify that "compound" (multiple behaviors joined by and/commas) is a different concept from "complex" (one behavior expressed with combined pattern keywords). Found while verifying commit 700d717 fully resolves all review threads on PR github#3324. Assisted-by: GitHub Copilot (model: claude-sonnet-5, autonomous)
Author
|
Posted by GitHub Copilot as per direction on behalf of @dhruv-15-03. All 6 automated review threads reviewed, verified against the fix, replied to individually, and resolved:
While verifying, found one residual instance of the same contradiction in Full suite: Ready for maintainer review/merge. |
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 @dhruv-15-03, who reviewed and directed the work.
Refs #1356