Validate before you build

Prove it, then build it.

Have an idea? Once Keel is installed, there's one action to remember: run Keel Guide. Keel guides you through who to interview, what to ask, and whether to pivot, narrow, or proceed. When the evidence is strong enough, it creates a validated brief for Spec Kit — and later checks that what shipped still matches what users told you.

I have an idea — guide me I use Spec Kit — install Keel

Open source · Spec Kit extension · Apache-2.0

Keel won't produce a build brief until your evidence clears the bar.

View the end-to-end showcase →
New here?

How Keel takes an idea to a decision

No terminal experience required to follow this — it's the same process either way, just described without the command names.

Describe your idea.

Keel identifies the risky assumptions your idea depends on, and who you'd need to talk to in order to test them.

You add interview evidence — notes from real conversations, one at a time.

Keel recommends one of five things: pivot, gather more evidence, reduce the risk, narrow the idea, or proceed.

Once the evidence clears the bar, the validated brief moves into the AI build workflow (Spec Kit) to actually get built.

After it ships, Keel checks the finished product against the evidence — and tells you where it drifted.

→

One action to remember: Keel Guide

Run Keel Guide and keep going. It reads what you have completed, determines the current stage, and guides you through the next step. The exact way you invoke it depends on your coding agent.

What you get out of it

Who to interview
Questions to ask
Assumptions requiring proof
Evidence-backed recommendation
Validated product brief
Post-build drift audit

How would you like to continue?

Option 1

Set up Keel myself

Install Keel once. After setup, Keel Guide is the only action you need to remember. It will determine your current stage and guide your next step.

Option 2

Tell us where you're stuck

We're learning where founders need additional guidance. Tell us what you're trying to accomplish and where you are getting stuck. This is not a sales form, and there is no commitment.

Tell us where you're stuck
Worked example

See a real run, start to finish

A real execution of Keel and Spec Kit using a disclosed synthetic interview dataset. The gate, build, live verification and audit are real.

Read the showcase →
Why alongside Spec Kit

Nothing upstream checks whether the idea deserved a spec

Spec Kit is very good at turning a specification into working software. It has no opinion on whether the specification should have existed — that's a different problem, and it's the one Keel solves.

problem 1

Assumptions become spec

Whatever you type into /speckit.specify becomes the plan. There's no step before it that asks whether the belief behind the feature was ever checked against anyone who isn't you.

problem 2

clarify asks you, not evidence

/speckit.clarify resolves ambiguity by asking the person who already believes the idea. Your assumptions become the spec either way. Keel resolves ambiguity against interviews instead.

problem 3

Nothing checks the build against why

/speckit.analyze checks whether your spec, plan, and tasks agree with each other. Nothing checks whether what shipped agrees with the evidence that justified building it. That's what keel.audit is for.

Install

Add it to a Spec Kit project

Requires Python 3.11+. Pick whichever matches where you're starting from — Keel is a Spec Kit extension, so it needs Spec Kit either way.

How Keel fits with Spec Kit

Keel works around Spec Kit, not inside it. It validates the idea before /speckit.specify, hands Spec Kit an evidence-backed brief, and checks the finished product afterward.

Validate Keel Guide
Build Spec Kit
Check what shipped Keel Guide

The invocation format varies by coding agent; the workflow does not.

Which coding agent are you using?

Choose your coding agent to see the correct way to run Keel.

Spec Kit project already initialized (specify init)
Spec Kit CLI ≥ 0.15.0
Python 3.11+ on your PATH
bash, git, awk, sed, grep (already on macOS/Linux)
1

Install the extension

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

Keel is listed in Spec Kit's community catalog, but the entry is still syncing to v0.2.0 — until that update lands, the bare specify extension add keel will resolve the older v0.1.1. The command above installs the pinned v0.2.0 release directly, so you don't need to wait. Spec Kit will ask you to confirm the external source (y) once. Developing locally instead? specify extension add --dev /path/to/spec-kit-keel

2

Start Keel

Advanced: Show individual Keel commands
Technical details: Five phases and enforcement gate

Five internal phases

/speckit.keel.guide reads your project's state and routes through these five phases inline — you don't have to sequence them yourself or track A-00X / E-00X IDs.

keel.init

Captures the hypothesis, derives assumptions, writes a non-leading interview guide and an evidence-gathering plan — who to talk to, and why.

keel.add-evidence

Ingests one interview, extracts claims with provenance, updates assumption confidence.

keel.check

Reports coverage, saturation, and contradictions, then a five-option decision menu: pivot, gather more evidence, reduce risk, narrow the hypothesis, or proceed.

keel.brief

Writes constitution input and an evidence-backed brief for /speckit.specify.

keel.audit

Scores spec quality; with keel/ present, diffs the build against the evidence.

Each one also works as a direct command — /speckit.keel.init, /speckit.keel.check, and so on — if you already know exactly which phase you're in. guide is a router around them, not a replacement.

The gate blocks the brief, by exit code

keel-gate.sh runs at the top of every Keel command. /speckit.keel.brief is blocked while any high-risk assumption is unvalidated, evidence is thin, or all of it comes from a single participant role — not as a suggestion to your agent, as an exit code.

Thresholds live in keel-config.yml. You can lower them; the override gets recorded so keel.audit can surface it later. Keel doesn't write your code either, and it won't pad evidence to make its own gate pass.

This only covers Keel's own commands — it can't stop someone from skipping Keel entirely and running /speckit.specify straight away. The hook that offers to run check before planning is opt-in, not forced, precisely so a project with no keel/ directory is never blocked by a gate it never opted into.

$ bash keel-gate.sh brief evidence files: 2 distinct participant roles: 2 unvalidated high-risk: 1 contradictions: 0 BLOCKED: only 2 evidence files, minimum is 3. -> Run /speckit.keel.add-evidence after more interviews. BLOCKED: 1 high-risk assumption(s) still unvalidated. -> Validate them, downgrade the risk with a reason, or add 'override: A-XXX' to keel/decisions.md.