gherkin-ai

Spec-driven verification and governance for AI-assisted software delivery.

gherkin-ai turns requirements into executable Gherkin specifications and generates verified contracts and code for 20+ stacks. It gates changes on specification quality, drift and delivery risk, and controls what AI coding agents may change.

• Specify. Write or import (GitHub Spec Kit) .feature files, lint them, and build a semantic model of commands, events, endpoints, states and rules.
• Generate. Contracts, a domain kernel, tests bound to the feature, and a runtime for persistence, messaging and tracing. Every stable stack is built and tested in CI.
• Govern. An agent firewall for MCP clients, IDE agents and the CLI's own agent loops. Risk scoring of every change, traceability from requirement to code to tests, and a local audit trail.
• Verify. Spec-to-code convergence, contract drift checks (a feature changed alone, a route the running service no longer serves), and agent repair loops sandboxed in a container by default, with stable exit codes and --json for CI.

Adding it to an existing code base? Start with docs/ADOPTION.md; for the organization-wide rollout, docs/ENTERPRISE.md. Upgrading a generated project? See docs/MIGRATION-3.2.md, which covers every path from 2.x.

Installation

Requires Node.js 22.19 or later.

npm install -g gherkin-ai     # installs the `gherkin-ai` and `ghk` commands
npx -y gherkin-ai@3 --help    # or run without installing

Quick start

ghk init --yes -l typescript -f nestjs          # project configuration (gherkin-ai.config.json)
ghk create                                      # write a feature interactively, or:
ghk speckit import                              # convert Spec Kit specs/NNN-*/spec.md into features
ghk lint --threshold 80                         # specification quality gate (exit 4 below threshold)
ghk generate -f features/orders.feature         # contracts, domain kernel, tests, runtime
ghk implement -f features/orders.feature        # implementation prompt and context for your agent
ghk converge --threshold 80                     # spec-to-code convergence (exit 7 below threshold)
ghk risk --base origin/main --fail-on HIGH      # delivery risk of the change (exit 4 at HIGH or above)
ghk graph --trace OrderPlaced                   # requirement -> code -> tests

On an existing repository, without ghk init

The governance commands work on any repository with .feature files in features/ or specs/. They use the stack ghk detect finds, leave out what they cannot measure without gherkin-ai's own contracts (reported as n/a), and write nothing to the repository:

npx -y gherkin-ai@3 lint --threshold 80                      # exit 4 below the threshold, exit 2 if there is no feature
npx -y gherkin-ai@3 converge --openapi docs/openapi.json     # coverage against your own contract (exit 7 below 80)
npx -y gherkin-ai@3 risk --base origin/main --fail-on HIGH   # risk of the change
npx -y gherkin-ai@3 graph                                    # which commands the code and the tests name
npx -y gherkin-ai@3 firewall check "cat .env"                # DENY: exit 5

tests/golden/brownfield.test.ts runs exactly these on an Express and a Spring service. docs/ADOPTION.md has the CI job.

Connect your coding agent:

ghk mcp install                                 # least-privilege MCP server for Cursor, Claude Desktop and others
ghk firewall check --exec "npm test && git push"  # what an agent may write, run, reach and read

Capabilities

• Stable: covered by tests and by the golden builds, with the CLI contract (exit codes, --json) kept across 3.x.
• Beta: complete and tested; output formats may still change in a minor release. No feature is in beta in 3.2.
• Experimental: use with human review only.

The LLM repair loops write .patch proposals by default. --apply is refused in CI and on protected branches unless explicitly allowed, and every file goes through the agent firewall.

Supported stacks

Every stack below is built and tested in CI. A sample project is generated, built in the stack's official Docker image, and its generated test suite is run. For backends, the runtime integration suite also runs against real PostgreSQL and the stack's broker: RabbitMQ, the Pub/Sub and Service Bus emulators, or Kafka. Then the production image is started, its health probes must answer, and its traces must reach an OpenTelemetry collector.

Other combinations generate contracts and prompts only and are reported as experimental. ghk stacks lists the current matrix.

Maintenance tiers. Every stack above passes the same golden builds on every change. Core stacks (NestJS, Express, Spring Boot and Quarkus in Java and Kotlin, FastAPI, ASP.NET Core, Go; React, Vue, Angular) are kept current by the maintainers and get new runtime features first. Community stacks (Django, Laravel, Rails, Phoenix, Rust, Flutter, React Native, Next.js, Phoenix LiveView) are kept current through contributions. No new stacks are added in 3.x; the effort goes into governance and verification. The evidence behind these claims, and how to reproduce it, is in docs/EVALUATION_REPORT.md.

Industry standards

A project can opt in to the reference standards of its industry with industry.id (ghk init --industry banking, or ghk industry apply banking in an existing project). The standards become lint rules on every specification, constraints in the semantic model and the contracts (x-industry), rules in every agent prompt, and human-approval paths in the agent firewall.

Each profile lists its rules, vocabulary, recommended architecture, compliance reminders and a sample feature in docs/INDUSTRIES.md. The compliance items are engineering guidance, not certification.

Automation contract

With --json, stdout carries exactly one JSON document and diagnostics go to stderr. Details: docs/ENTERPRISE.md#5-automation-contract-exit-codes-and---json.

Known limitations

• Semantic model. It is extracted from Gherkin with deterministic rules. Unusual phrasing can produce generic command names. ghk lint reports specifications that are too vague to model. The @aggregate:Name, @command:Name and @event:Name tags set the names explicitly in any Gherkin dialect, ghk lint --explain-ir shows where every generated name comes from, and ghk lint --assist asks the configured LLM to propose the tags (validated, as a patch; never in the default path).
• Generated runtime. It is a verified starting point, not a framework. The runtime kernel covers one aggregate per feature, on PostgreSQL (and on MySQL 8 for NestJS and Express, with stack.kernelDatabase: "mysql"), with RabbitMQ, Pub/Sub, Service Bus or Kafka. Other databases generate contracts and configuration only; MySQL in the other runtimes, and MongoDB, are planned for 3.3.
• Industry profiles. Their rules check the specification, not the code, and their compliance items are engineering guidance, not certification.
• Traceability graph. It links code by symbol names. Code that does not use the domain names from the specification is not linked.
• Risk scores. They are heuristics with documented weights and evidence. Calibrate the approval threshold (policy.risk) to your organization.
• LLM repair loops. They depend on the model and can fail to converge. They are experimental and always need review.
• Benchmarks. ghk bench measures your agent on your tasks. gherkin-ai does not publish model-quality claims of its own.

Documentation

• Usage guide: the delivery flow, from specification to merge
• Adopting gherkin-ai in an existing project
• Enterprise guide: configuration and policy, providers, network, credentials, firewall, risk, MCP, audit, CI
• Golden builds dashboard: every stable stack's build in the last CI run on main
• Benchmark tasks: the same task in three stacks, to measure your agent with and without gherkin-ai (ghk bench)
• Governance, maintainers and foundation readiness
• Compliance mapping: which gherkin-ai controls give evidence for ISO/IEC 42001, SOC 2 and the EU AI Act, and what they do not cover
• Industry profiles
• Commands
• Runtime kernel
• Deployment: production image, brokers per cloud, Terraform, Helm, CI/CD
• Verification evidence
• MCP guide
• Architecture
• Migration: to 3.2 (every path from 2.x), to 3.1, to 3.0
• Changelog

Support and security

See SUPPORT.md for the support and versioning policy and for how to get help. Report vulnerabilities privately as described in SECURITY.md.

License

MIT. Published on npm by the fenner organization. Documentation: https://fennereduardo.github.io/gherkin-ai-cli/.