[Extension]: Add Keel Discovery

[athulrajeev]

Extension ID

keel

Extension Name

Keel Discovery

Version

0.1.1

Description

A Spec Kit extension that puts customer evidence upstream of /speckit.specify, and audits what you shipped against it afterwards.

Author

Keel Discovery

Repository URL

https://github.com/keeldiscovery/spec-kit-keel

Download URL

https://github.com/keeldiscovery/spec-kit-keel/archive/refs/tags/v0.1.1.zip

License

Apache-2.0

Homepage

https://keeldiscovery.com

Documentation URL

https://github.com/keeldiscovery/spec-kit-keel/blob/main/README.md

Changelog URL

https://github.com/keeldiscovery/spec-kit-keel/blob/main/CHANGELOG.md

Required Spec Kit Version

=0.15.0

Required Tools

None beyond what Spec Kit itself already requires (bash, git, awk, sed, grep, Python 3.11+). No additional external dependencies.

Number of Commands

5

Number of Hooks

2

Tags

discovery, evidence, customer-research, validation, traceability

Key Features

• speckit.keel.init — captures the hypothesis, derives 3–7 assumptions, and writes a non-leading interview guide before any spec exists
• speckit.keel.add-evidence — ingests one real interview, extracts attributable claims with provenance, and updates assumption confidence
• speckit.keel.check — reports evidence coverage, saturation, contradictions, and one recommended next action
• speckit.keel.brief — writes an evidence-backed brief and constitution input for /speckit.specify, with keel: traceability markers back to the assumption/evidence behind each requirement
• speckit.keel.audit — round-trip drift check: reads the actual shipped code and diffs it against the original evidence, not just spec-internal consistency (which /speckit.analyze already covers)
• keel-gate.sh — phase-precondition script run at the top of every command; blocks /speckit.keel.brief by exit code (not just a prompt) while any high-risk assumption is unvalidated, evidence is thin, or all evidence comes from a single participant role

Testing Checklist

• Extension installs successfully via download URL
• All commands execute without errors
• Documentation is complete and accurate
• No security vulnerabilities identified
• Tested on at least one real project

Submission Requirements

• Valid extension.yml manifest included
• README.md with installation and usage instructions
• LICENSE file included
• GitHub release created with version tag
• All command files exist and are properly formatted
• Extension ID follows naming conventions (lowercase-with-hyphens)

Testing Details

Tested on macOS 26.5.2 with Spec Kit CLI 0.16.2.dev0 (installed via uvx --from git+https://github.com/github/spec-kit.git).

Five separate end-to-end scenarios were run against real specify init + specify extension add installs (not simulated), each exercising the full command set and the gate script:

1. Full lifecycle (init → add-evidence → check → brief → audit) with a genuine evidence-backed pass, plus a deliberately introduced code drift that the audit correctly caught and explained against the original interview evidence.
2. Gate blocking on thin evidence and on single-source evidence, verified via real keel-gate.sh exit codes and output (not just reading the script).
3. A contradicted assumption with a documented risk downgrade, verifying the audit's "unimplemented mitigation reverts to high severity" rule fires correctly.
4. The override flow for an unresolved high-risk assumption — confirmed the gate blocks before the override, passes after, and excludes only the overridden ID.
5. Edge cases: re-running init preserves existing assumption IDs, audit's spec-quality-only and marker-fallback modes, and a markdown-table parser robustness test that actually found a real bug (a literal | character inside an assumption's Statement text could silently defeat the high-risk gate) — which was then fixed and re-verified against the original repro.

Separately verified: this exact v0.1.1 release archive installs cleanly via specify extension add keel --from <url>, places every file correctly (including LICENSE/CHANGELOG.md), excludes dev-only files (tests/, .claude/) via .extensionignore, and the installed gate script runs successfully post-install.

Example Usage

specify extension add keel --from https://github.com/keeldiscovery/spec-kit-keel/archive/refs/tags/v0.1.1.zip

/speckit.keel.init "Weekly Slack digest for engineering managers, with mandatory human review before send"
/speckit.keel.add-evidence "Participant: engineering_manager. Q: ... A: ..."
/speckit.keel.check
/speckit.keel.brief

Proposed Catalog Entry

{
  "keel": {
    "name": "Keel Discovery",
    "id": "keel",
    "description": "A Spec Kit extension that puts customer evidence upstream of /speckit.specify, and audits what you shipped against it afterwards.",
    "author": "Keel Discovery",
    "version": "0.1.1",
    "download_url": "https://github.com/keeldiscovery/spec-kit-keel/archive/refs/tags/v0.1.1.zip",
    "repository": "https://github.com/keeldiscovery/spec-kit-keel",
    "homepage": "https://keeldiscovery.com",
    "documentation": "https://github.com/keeldiscovery/spec-kit-keel/blob/main/README.md",
    "changelog": "https://github.com/keeldiscovery/spec-kit-keel/blob/main/CHANGELOG.md",
    "license": "Apache-2.0",
    "requires": {
      "speckit_version": ">=0.15.0"
    },
    "provides": {
      "commands": 5,
      "hooks": 2
    },
    "tags": ["discovery", "evidence", "customer-research", "validation", "traceability"],
    "verified": false,
    "downloads": 0,
    "stars": 0,
    "created_at": "2026-08-09T00:00:00Z",
    "updated_at": "2026-08-09T00:00:00Z"
  }
}

Additional Context

A short demo/marketing site (with an interactive, click-through walkthrough of one full discovery cycle) is live at https://keeldiscovery.com if useful for review.

Re: naming overlap — a few extensions already in the catalog have adjacent-sounding names (discovery, harness, intake, red-team). None do what this does: discovery is technical/feasibility discovery, not customer research; harness is generic research/evidence curation; intake normalizes existing PRD/design docs rather than gathering original evidence; red-team is adversarial spec review with no evidence layer. Keel's distinguishing mechanism is the evidence gate (a script that mechanically blocks /speckit.keel.brief on thin/unvalidated evidence) plus the round-trip keel.audit that diffs shipped code against the original interview evidence, not just spec-internal consistency.

[github-actions]

cc @github/spec-kit-maintainers — new catalog submission for review.