cucumber-openspec
cucumber-openspec converte arquivos OpenSpec spec.md em arquivos .feature Cucumber / Gherkin determinísticos.
Ele usa scripts TypeScript determinísticos sem IA — um parser de máquina de estados + gerador — para produzir arquivos .feature corretos em qualquer um dos 80 idiomas Gherkin. Nenhuma dependência em tempo de execução além do Node.js.
Início Rápido
# Instale a skill para seu agente de IA
npx skills add neurono-ml/cucumber-openspec
# Converta as especificações de um projeto para Gherkin
npx tsx scripts/index.ts -i ./openspec -o ./features
Funcionalidades
- Parser determinístico — máquina de estados, 0 dependências
- 80 idiomas Gherkin — português, inglês, chinês, árabe, japonês e mais 76
- Tags —
@smoke,@regression,@criticalnos níveis Funcionalidade, Regra e Cenário - Background — etapas compartilhadas via seção
## Background - Scenario Outline + Examples — cenários parametrizados orientados a dados
- DataTables — tabelas pipe como argumentos de etapas
- Doc Strings — sub-itens convertidos em blocos
""" - Delta specs — seções ADICIONADO / MODIFICADO / REMOVIDO para gestão de mudanças
- Validação gramatical Gherkin — toda saída validada via
@cucumber/gherkin - Localização — palavras-chave em 80 idiomas via traduções oficiais do Gherkin
- Skill para Agente — instalável via
skills.sh, compatível com Claude Code, Cursor, OpenCode, Codex
Como Funciona
OpenSpec spec.md → Gherkin .feature
───────────────────── ─────────────────
# [@tag] Domínio [@tag]
## Propósito Funcionalidade: Domínio
## Background Background:
- **DADO** etapa Dado etapa
### [@tag] Requisito: Nome [@tag]
#### [@tag] Cenário: Nome Regra: Nome
- **DADO** texto [@tag]
| col | col | Cenário: Nome
- **QUANDO** texto Dado texto
- **ENTÃO** texto | col | col |
Quando texto
Então texto
Instalação
Como Skill para Agente (recomendado)
Instale via skills.sh para qualquer agente compatível com SKILL.md:
npx skills add neurono-ml/cucumber-openspec
Funciona com:
| Plataforma | Diretório da Skill |
|---|---|
| Claude Code | ~/.claude/skills/ |
| Cursor | ~/.cursor/skills/ |
| OpenCode | ~/.config/opencode/skills/ |
| Codex | ~/.agents/skills/ |
Após a instalação, a skill estará disponível na sua próxima conversa.
Pelo GitHub (clone manual)
git clone https://github.com/neurono-ml/cucumber-openspec.git ~/.agents/skills/cucumber-openspec
Usando npm / npx (uso direto)
Nenhuma instalação global é necessária. O projeto usa npx tsx para executar TypeScript diretamente:
# Clone o repositório
git clone https://github.com/neurono-ml/cucumber-openspec.git
cd cucumber-openspec
# Instale as dependências
npm ci
# Use
npx tsx scripts/index.ts -i ./openspec -o ./features
Pré-requisitos
| Requisito | Versão | Observações |
|---|---|---|
| Node.js | ≥ 18 | Necessário para executar os scripts |
| npm | ≥ 9 | Acompanha o Node.js |
| mdBook | ≥ 0.5 | Necessário apenas para construir a documentação |
Uso
Referência da CLI
npx tsx scripts/index.ts [opções]
Opções
| Flag | Alias | Descrição | Padrão |
|---|---|---|---|
--input | -i | Caminho para o arquivo de especificação ou diretório openspec | (obrigatório) |
--output | -o | Diretório de saída para arquivos .feature | ./features |
--language | -l | Código do idioma Gherkin | en |
Caminhos de Saída
| Entrada | Saída |
|---|---|
openspec/specs/auth/spec.md | features/auth.feature |
openspec/changes/add-auth/specs/auth/spec.md | features/add-auth_auth.feature |
Exemplos
Converter um único arquivo de especificação
npx tsx scripts/index.ts -i openspec/specs/auth/spec.md -o features
Gera features/auth.feature.
Converter um diretório OpenSpec inteiro
npx tsx scripts/index.ts -i ./openspec -o ./features
Percorre openspec/specs/<dominio>/spec.md e todos os arquivos openspec/changes/<mudanca>/specs/<dominio>/spec.md.
Converter para um idioma diferente
# Português
npx tsx scripts/index.ts -i ./openspec -o ./features -l pt
# Chinês Simplificado
npx tsx scripts/index.ts -i ./openspec -o ./features -l zh-CN
# Árabe (direita para esquerda)
npx tsx scripts/index.ts -i ./openspec -o ./features -l ar
Converter uma delta change
npx tsx scripts/index.ts -i openspec/changes/add-auth/specs/auth/spec.md -o features
Isso gera features/add-auth_auth.feature com anotações de ADICIONADO/MODIFICADO/REMOVIDO.
Estrutura do Diretório de Trabalho
projeto/
├── openspec/
│ ├── specs/
│ │ ├── auth/
│ │ │ └── spec.md
│ │ └── billing/
│ │ └── spec.md
│ └── changes/
│ └── add-auth/
│ └── specs/
│ └── auth/
│ └── spec.md
└── features/ # ← gerado
├── auth.feature
├── billing.feature
└── add-auth_auth.feature