spec-kit-bdd

A spec-kit community extension that adds Behavior-Driven Development and Acceptance Test-Driven Development to the spec-driven workflow — acceptance criteria become executable scenarios before implementation starts.

<div class="flow">
  <div class="flow-step flow-step--purple">
    <span class="flow-num">1. SPEC</span>
    <p>Describe the behaviour with <code>/speckit.specify</code>.</p>
  </div>
  <div class="flow-arrow" aria-hidden="true">→</div>
  <div class="flow-step flow-step--green">
    <span class="flow-num">2. BDD (Gherkin)</span>
    <p>Specify examples with <code>/speckit.bdd.scenarios</code> &mdash; RED.</p>
  </div>
  <div class="flow-arrow" aria-hidden="true">→</div>
  <div class="flow-step flow-step--blue">
    <span class="flow-num">3. ATDD</span>
    <p>Scaffold failing steps with <code>/speckit.bdd.scaffold</code> &mdash; still RED.</p>
  </div>
  <div class="flow-arrow" aria-hidden="true">→</div>
  <div class="flow-step flow-step--muted">
    <span class="flow-num">4. PLAN</span>
    <p>Standard spec-kit: <code>/speckit.plan</code> then <code>/speckit.tasks</code>.</p>
  </div>
  <div class="flow-arrow" aria-hidden="true">→</div>
  <div class="flow-step flow-step--orange">
    <span class="flow-num">5. CODE</span>
    <p>Implement with <code>/speckit.implement</code> until GREEN.</p>
  </div>
  <div class="flow-arrow" aria-hidden="true">→</div>
  <div class="flow-step flow-step--purple">
    <span class="flow-num">6. VERIFY</span>
    <p>Close the loop with <code>/speckit.bdd.verify</code>.</p>
  </div>
</div>
<p class="flow-legend"><span class="dot" aria-hidden="true"></span>Steps 2, 3, and 6 are what spec-kit-bdd adds to your normal spec-kit flow.</p>

<table class="produces-table">
  <thead>
    <tr><th>Command</th><th>What it produces</th></tr>
  </thead>
  <tbody>
    <tr><td><code>/speckit.bdd.scenarios</code></td><td>Gherkin <code>.feature</code> files from your spec-kit specification</td></tr>
    <tr><td><code>/speckit.bdd.scaffold</code></td><td>Step definition stubs (Python, JS, Ruby, Java, C#) ready to implement</td></tr>
    <tr><td><code>/speckit.bdd.verify</code></td><td>A traceability matrix mapping spec requirements ↔ scenarios</td></tr>
  </tbody>
</table>

<div class="install-block">
  <p>Install the extension into an existing spec-kit project:</p>
  <pre><code>specify extension add bdd --from https://github.com/RSginer/spec-kit-bdd/archive/refs/tags/v1.0.3.zip</code></pre>
  <p>That adds six commands to spec-kit's own lifecycle. Here's the full workflow, spec to green tests:</p>
</div>

<div class="steps">
  <div class="step">
    <h3>Write what you want to build</h3>
    <p>Start a spec-kit feature the usual way &mdash; nothing BDD-specific yet.</p>
    <pre><code>/speckit.specify</code></pre>
  </div>
  <div class="step">
    <h3>Convert acceptance criteria to Gherkin</h3>
    <p>Generates <code>features/*.feature</code> files from the spec you just wrote. Tests are written &mdash; <strong>RED</strong>. Review them, they define what the system must do.</p>
    <pre><code>/speckit.bdd.scenarios</code></pre>
  </div>
  <div class="step">
    <h3>Scaffold step definitions</h3>
    <p>Generates step definition stubs that raise <code>NotImplementedError</code> (or the framework equivalent). Tests are now runnable &mdash; still <strong>RED</strong>.</p>
    <pre><code>/speckit.bdd.scaffold</code></pre>
  </div>
  <div class="step">
    <h3>Plan the implementation</h3>
    <p>Back to standard spec-kit: break the spec into an implementation plan and a task list, now informed by the scenarios above.</p>
    <pre><code>/speckit.plan

/speckit.tasks

Implement until every scenario passes

Write code until your step definitions go GREEN.

/speckit.implement

Verify full spec coverage

Produces features/TRACEABILITY.md, mapping every spec requirement to the scenario that covers it, and flags any gaps.

/speckit.bdd.verify

• spec-kit >=0.2.0
• Any AI coding agent supported by spec-kit (Claude, Copilot, Cursor, etc.)