cucumber-openspec
cucumber-openspec converts OpenSpec spec.md files into deterministic Cucumber / Gherkin .feature files.
It uses zero-AI, deterministic TypeScript scripts — a state-machine parser + generator — to produce correct .feature files in any of the 80 Gherkin languages. No runtime dependencies beyond Node.js.
Quick Start
# Install the skill for your AI agent
npx skills add neurono-ml/cucumber-openspec
# Convert a project's specs to Gherkin
npx tsx scripts/index.ts -i ./openspec -o ./features
Features
- Deterministic parser — state machine, 0 dependencies
- 80 Gherkin languages — English, Portuguese, Chinese, Arabic, Japanese, and 76 more
- Tags —
@smoke,@regression,@criticalat Feature, Rule, and Scenario level - Background — shared steps via
## Backgroundsection - Scenario Outline + Examples — data-driven parameterized scenarios
- DataTables — pipe tables as step arguments
- Doc Strings — sub-bullets converted to
"""blocks - Delta specs — ADDED / MODIFIED / REMOVED sections for change management
- Gherkin grammar validation — all output validated via
@cucumber/gherkin - Localization — keywords in 80 languages via official Gherkin translations
- Agent Skill — installable via
skills.sh, works with Claude Code, Cursor, OpenCode, Codex
How It Works
OpenSpec spec.md → Gherkin .feature
───────────────────── ─────────────────
# [@tag] Domain [@tag]
## Purpose Feature: Domain
## Background Background:
- **GIVEN** step Given step
### [@tag] Requirement: Name [@tag]
#### [@tag] Scenario: Name Rule: Name
- **GIVEN** text [@tag]
| col | col | Scenario: Name
- **WHEN** text Given text
- **THEN** text | col | col |
When text
Then text
Installation
As an Agent Skill (recommended)
Install via skills.sh for any SKILL.md-compatible agent:
npx skills add neurono-ml/cucumber-openspec
This works with:
| Platform | Skill Directory |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Cursor | ~/.cursor/skills/ |
| OpenCode | ~/.config/opencode/skills/ |
| Codex | ~/.agents/skills/ |
After installation, the skill is available on your next conversation turn.
From GitHub (manual clone)
git clone https://github.com/neurono-ml/cucumber-openspec.git ~/.agents/skills/cucumber-openspec
Using npm / npx (direct usage)
No global install is required. The project uses npx tsx to run TypeScript directly:
# Clone the repo
git clone https://github.com/neurono-ml/cucumber-openspec.git
cd cucumber-openspec
# Install dependencies
npm ci
# Use it
npx tsx scripts/index.ts -i ./openspec -o ./features
Prerequisites
| Requirement | Version | Notes |
|---|---|---|
| Node.js | ≥ 18 | Required for running the scripts |
| npm | ≥ 9 | Ships with Node.js |
| mdBook | ≥ 0.5 | Only needed to build documentation |
Usage
CLI Reference
npx tsx scripts/index.ts [options]
Options
| Flag | Alias | Description | Default |
|---|---|---|---|
--input | -i | Path to spec file or openspec directory | (required) |
--output | -o | Output directory for .feature files | ./features |
--language | -l | Gherkin language code | en |
Output Paths
| Input | Output |
|---|---|
openspec/specs/auth/spec.md | features/auth.feature |
openspec/changes/add-auth/specs/auth/spec.md | features/add-auth_auth.feature |
Examples
Convert a single spec file
npx tsx scripts/index.ts -i openspec/specs/auth/spec.md -o features
Generates features/auth.feature.
Convert an entire OpenSpec directory
npx tsx scripts/index.ts -i ./openspec -o ./features
Walks openspec/specs/<domain>/spec.md and all openspec/changes/<change>/specs/<domain>/spec.md files.
Convert to a different language
# Portuguese
npx tsx scripts/index.ts -i ./openspec -o ./features -l pt
# Simplified Chinese
npx tsx scripts/index.ts -i ./openspec -o ./features -l zh-CN
# Arabic (right-to-left)
npx tsx scripts/index.ts -i ./openspec -o ./features -l ar
Convert a delta change
npx tsx scripts/index.ts -i openspec/changes/add-auth/specs/auth/spec.md -o features
This generates features/add-auth_auth.feature with ADDED/MODIFIED/REMOVED annotations.
Working Directory Structure
project/
├── openspec/
│ ├── specs/
│ │ ├── auth/
│ │ │ └── spec.md
│ │ └── billing/
│ │ └── spec.md
│ └── changes/
│ └── add-auth/
│ └── specs/
│ └── auth/
│ └── spec.md
└── features/ # ← generated
├── auth.feature
├── billing.feature
└── add-auth_auth.feature