[Extension]: Add Keel Discovery #4154

Extension ID

keel

Extension Name

Keel Discovery

Version

0.2.0

Description

Evidence-backed discovery upstream of /speckit.specify, plus round-trip drift auditing after implementation.

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.2.0.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

6

Number of Hooks

2

Tags

discovery, evidence, customer-research, validation, traceability

Key Features

• speckit.keel.guide (new in 0.2.0) — state-aware entry point. Reads current keel/ state and does whichever phase (init/add-evidence/check/brief) is next inline, so a user doesn't have to know or sequence the individual commands themselves.
• speckit.keel.init — captures the hypothesis, derives 3–7 assumptions, writes a non-leading interview guide, and now also writes keel/evidence-plan.md (updated in 0.2.0) — a concrete stakeholder/question/priority plan instead of just an interview guide.
• speckit.keel.add-evidence — ingests one real interview, extracts attributable claims with provenance, updates assumption confidence. Now runs conversationally (updated in 0.2.0): after logging one piece of evidence it offers to add another, review what's collected, or edit/remove an item, without requiring the command to be re-invoked per item.
• speckit.keel.check — reports evidence coverage, saturation, and contradictions. Now always ends in a five-option decision menu (updated in 0.2.0): pivot / gather more evidence / reduce or downgrade a risk / narrow the hypothesis / proceed to the brief — with one recommended option and reasoning, instead of a single free-text line.
• 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. New in 0.2.0: a superseded: A-00X mechanism in keel/decisions.md, distinct from override, for a high-risk assumption that evidence actually disproved and replaced with a new one (as opposed to one whose risk is being knowingly accepted unresolved).

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 with Spec Kit CLI 0.16.4.

Automated: the extension's own tests/test-install.sh — 39/39 passing, including gate-parser edge cases (a literal | inside an assumption's Statement text, a supported/validated row with an empty Evidence column) and new 0.2.0-specific coverage for the guide phase (empty state, hypothesis-only, fully-passing, and overridden-high-risk scenarios, each checked against the real gate script's exit code and output).

Real end-to-end dogfood run: built a complete example project (a small GitHub-activity digest app) through the full lifecycle — keel.init → four real interview entries via keel.add-evidence → keel.check → keel-gate.sh brief, which genuinely blocked and then genuinely passed, including a real contradicted-and-superseded high-risk assumption (evidence disproved one belief mid-discovery; the new superseded: mechanism correctly excluded it from the block count while still surfacing it) → keel.brief → Spec Kit's own constitution → specify → plan → tasks → implement → converge pipeline → keel.audit, which correctly traced every keel:-marked requirement back to its originating evidence and caught a real gap in the shipped app (/speckit-converge found two buttons that stayed enabled with nothing to review) before it shipped.

Release-archive install, separately verified just now: specify init on a clean project, then specify extension add keel --from https://github.com/keeldiscovery/spec-kit-keel/archive/refs/tags/v0.2.0.zip — installs cleanly, all 6 commands register correctly, keel-gate.sh guide runs successfully post-install and reports the expected empty-state output.

Example Usage

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

/speckit.keel.guide "ShipLog: a founder enters a GitHub username and gets a draft weekly build-in-public update from their real commits and PRs, reviewed and edited before it's ever shared."

guide will detect this is a fresh project, run init, then prompt for the first interview when you're ready to paste one — no need to know or sequence the individual init/add-evidence/check/brief commands.

Proposed Catalog Entry

{
  "keel": {
    "name": "Keel Discovery",
    "id": "keel",
    "description": "Evidence-backed discovery upstream of /speckit.specify, plus round-trip drift auditing after implementation.",
    "author": "Keel Discovery",
    "version": "0.2.0",
    "download_url": "https://github.com/keeldiscovery/spec-kit-keel/archive/refs/tags/v0.2.0.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": 6,
      "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-15T00:00:00Z"
  }
}

Additional Context

This is an update to an existing catalog entry, not a new submission — keel has been listed since the original v0.1.1 submission (#4026), which was merged via #4035. The catalog's keel entry is currently stale on version (0.1.1 → 0.2.0), download_url (points at the old v0.1.1.zip), and provides.commands (5 → 6, speckit.keel.guide is new). Everything else (description, tags, license, hooks) is unchanged from the existing entry.

A real, working example built with this release is documented at https://keeldiscovery.com/showcase/, with the generated project itself published at https://github.com/keeldiscovery/shiplog for anyone who wants to inspect or run the actual output rather than take the description's word for it.