feat: add /speckit.qa command — systematic QA testing

[arunt14]

Description

Problem

Spec-Kit's /speckit.implement command follows a TDD approach during development, but there is no dedicated QA testing step after implementation is complete. Unit tests written during TDD verify individual components, but they don't validate the end-to-end user experience against the acceptance criteria defined in spec.md. There's no way to answer: "Does the built application actually do what the spec says it should?"

This gap is especially problematic for web applications, where visual rendering, navigation flows, and form interactions can break even when unit tests pass.

Industry context: GStack's /qa and /browse commands demonstrate that persistent browser automation for visual QA — combined with acceptance criteria validation — catches an entire class of issues that unit tests miss.

Solution

Adds /speckit.qa — a new core command for systematic quality assurance testing that validates acceptance criteria from spec.md against actual application behavior. Supports two modes:

Browser QA Mode (web applications):

• Navigates routes and interacts with UI using Playwright/Puppeteer
• Captures screenshots at key state transitions as evidence
• Validates UI elements, text content, form submissions, navigation behavior
• Records console errors and network failures on test failure

CLI QA Mode (non-web applications):

• Runs existing test suites (npm test, pytest, go test, cargo test, etc.)
• Validates API endpoints with response schema and status code checks
• Verifies command-line output patterns and exit codes
• Checks database state and file system changes

Output: QA report with pass/fail evidence, acceptance criteria coverage matrix, and verdict (QA PASSED / QA PASSED WITH NOTES / QA FAILED).

Business Value

• Bridges the gap between TDD and user acceptance — validates that the product works as specified, not just that the code doesn't throw
• Provides auditable evidence — screenshots, response captures, and test results create a verifiable QA trail
• Catches visual and integration regressions that unit tests miss entirely
• Supports any project type — browser mode for web apps, CLI mode for everything else, with automatic detection
• Completes the quality pipeline: implement → review → qa → ship

Workflow Position

/speckit.implement → /speckit.review → /speckit.qa ⭐ → /speckit.ship → /speckit.retro

Files Added

File	Purpose
templates/commands/qa.md	Command template with dual-mode testing, acceptance criteria mapping, extension hooks (before_qa, after_qa)
templates/qa-template.md	QA report template with test results table, criteria coverage matrix, failure details, and environment info

Testing

• Tested locally with uv run specify --help
• Ran existing tests with uv sync && uv run pytest — 878/972 pass (44 failures are pre-existing, unrelated to this change)
• Verified YAML frontmatter is valid and parseable
• Verified command file is auto-discovered by specify init
• Confirmed no changes to Python source code — template-only addition

AI Disclosure

• AI assistance was used in this PR
• How: GitHub Copilot CLI (Claude) was used to draft the command template and output template content, following the existing patterns established by implement.md and analyze.md. All content was reviewed and validated against the project's template conventions.

---

Note: Happy to discuss the scope and approach with maintainers. This is one of five related-but-independent PRs adding lifecycle commands inspired by GStack's role-based workflow.

[Copilot]

Pull request overview

Adds a new core /speckit.qa command template plus a QA report template to support systematic, evidence-based QA validation of a feature’s acceptance criteria (browser-driven and/or CLI-driven), fitting into the Spec Kit command workflow as a post-implementation quality gate.

Changes:

• Added templates/commands/qa.md to define the /speckit.qa workflow, including before/after extension hook support.
• Added templates/qa-template.md to standardize the generated QA report format.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
templates/commands/qa.md	New command template that outlines QA context loading, scenario extraction, browser/CLI execution, reporting, and extension hooks.
templates/qa-template.md	New markdown template for QA reports (results table, AC coverage matrix, suite summary, failure details, environment, metrics).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Step 9 says to generate the report “using the QA report template” but doesn’t reference the canonical template file path. Other commands explicitly point to templates/*-template.md (e.g., checklist/tasks), which makes outputs consistent and avoids drift. Please reference templates/qa-template.md (or .specify/templates/qa-template.md depending on runtime path conventions) and specify that the report should follow it verbatim.

Suggested change

	Create the QA report at `FEATURE_DIR/qa/qa-{timestamp}.md` using the QA report template. The report must include:
	Create the QA report at `FEATURE_DIR/qa/qa-{timestamp}.md` using the canonical QA report template at `templates/qa-template.md`, following it verbatim (do not add, remove, or reorder sections). The report must include:

[Copilot]

The verdict terminology is inconsistent: the report/template sections use “✅ ALL PASSED / ⚠️ PARTIAL PASS / ❌ FAILURES FOUND”, while Step 10 instructs “QA PASSED / QA PASSED WITH NOTES / QA FAILED”. This is likely to produce mismatched reports and makes automated parsing harder. Please standardize on one set of verdict labels (and ensure the template’s “Verdict” line matches the command’s Step 10 guidance).

[Copilot]

Adding templates/commands/qa.md makes qa a core command name when discovered from the templates directory, but the hard-coded fallback list in src/specify_cli/extensions.py (_FALLBACK_CORE_COMMAND_NAMES) doesn’t include qa. In environments where command discovery isn’t available, extension validation could incorrectly allow an extension namespace/id of qa. Please add qa to the fallback set to keep core/extension conflict checks consistent.

[mnriem]

Please deliver this as an extension. See https://github.com/github/spec-kit/tree/main/extensions

[arunt14]

Thanks for the review! I've addressed all 3 comments in the latest push:

1. Step 9 template reference: Now explicitly references templates/qa-template.md with instruction to follow it verbatim.
2. Verdict terminology: Standardized to ALL PASSED / PARTIAL PASS / FAILURES FOUND across both the command steps and post-QA actions sections, consistent with the template's verdict line.
3. Fallback core command names: Added qa to _FALLBACK_CORE_COMMAND_NAMES in src/specify_cli/extensions.py to prevent extension namespace conflicts.

[mnriem]

Please review https://github.com/github/spec-kit/blob/main/extensions/EXTENSION-PUBLISHING-GUIDE.md for publishing a community hosted extension

[arunt14]

Thanks @mnriem for the guidance! I've reviewed the Extension Publishing Guide and understand the direction - these should be delivered as community extensions rather than core commands. I'll restructure these as proper extensions following the extension.yml manifest pattern and the standard extension directory structure. Will close this PR and resubmit as an extension contribution to catalog.community.json.

[arunt14]

Closing in favor of PR #2049 — restructured as a community extension per maintainer feedback. Extension repo and v1.0.0 release are available.