@spec-wave/cli

CLI e skill para implementar um fluxo spec-driven completo no GitHub — do backlog ao deploy — com GitHub Projects v2, labels de gatilho e GitHub Actions com IA.

Conceito

Spec Wave é um sistema de processo de desenvolvimento baseado em especificações. Cada Feature passa por um ciclo documentado antes de ser implementada:

1. Spec funcional gerada por IA a partir do título e descrição da issue
2. Plano técnico gerado por IA a partir da spec e do contexto tecnológico do repositório
3. Validação automática das seções obrigatórias
4. Decomposição em Stories e Tasks gerada por IA
5. Automação do board durante o ciclo de desenvolvimento (Code Review → QA → Done)

O resultado é um board Kanban no GitHub Projects v2 que avança automaticamente conforme o trabalho progride, com toda a documentação versionada no próprio repositório.

Fluxo Kanban

📥 Backlog
  → 🐞 Triagem       ← só Bug reportado (RFC-004)
  → 🎯 Priorizado
  → 📋 Spec          ← label spec-wave:spec → Action gera spec.md
  → 📋 Plan          ← label spec-wave:plan → Action gera plan.md
  → ✅ Ready         ← label spec-wave:ready → Action valida ambos
  → 🚧 Desenvolvimento ← comando local: spec-wave implement <n>
  → 👀 Code Review   ← PR aberto → Action move automaticamente
  → 🧪 QA            ← PR aprovado → Action move automaticamente
  → 📋 Homologação
  → 🚀 Deploy
  → 🎉 Done

Hierarquia de Work Items

Initiative
  └── Epic
        └── Feature
              ├── Story
              │     └── Task
              └── Task

Cada nível é uma GitHub Issue com prefixo no título ([FEATURE], [STORY], etc.) e vínculo de sub-issue nativo do GitHub.

Componentes

CLI (@spec-wave/cli)

Ferramenta Node.js que configura e opera o fluxo via linha de comando.

| Comando | O que faz | |---------|-----------| | init | Cria o GitHub Project, labels, workflows e .spec-wave.json | | info | Mostra o estado de configuração do repositório atual | | refresh | Re-sincroniza o .spec-wave.json com o GitHub Project | | issue | Cria qualquer work item (initiative/epic/feature/story/task/bug/spike/rfc) | | initiative | Atalho para issue --type initiative | | feature | Atalho para issue --type feature | | generate-spec | Gera spec.md (usado pelo GitHub Action) | | generate-plan | Gera plan.md (usado pelo GitHub Action) | | validate | Valida spec.md e plan.md (usado pelo GitHub Action) | | decompose | Gera o rascunho da decomposição em decomposition.md; com --apply, cria as Stories/Tasks a partir do rascunho revisado (usado pelo GitHub Action) | | move <n> <etapa> | Move qualquer item do board (Feature, Story, Task, Bug, RFC) para uma Etapa — a Etapa nunca retrocede | | code-review | Move Feature para Code Review ao abrir PR (usado pelo GitHub Action) | | qa | Move Feature para QA ao aprovar PR (usado pelo GitHub Action) | | implement | Aciona o spec-kit localmente para implementar uma Feature (Stories pendentes em ordem de dependência), Story ou Task | | uninstall | Remove labels, workflows e .spec-wave.json |

GitHub Actions (instalados pelo init)

| Workflow | Gatilho | Ação | |----------|---------|------| | generate-spec.yml | label spec-wave:spec | Gera docs/features/<slug>/spec.md via IA | | generate-plan.yml | label spec-wave:plan | Gera docs/features/<slug>/plan.md via IA | | validate.yml | label spec-wave:ready | Valida seções obrigatórias; adiciona spec-wave:plan-approved | | decompose.yml | labels spec-wave:decompose / spec-wave:decompose-apply | 1º grava e critica o rascunho decomposition.md; 2º cria Stories e Tasks como sub-issues | | code-review.yml | PR aberto/reaberto | Move Feature para 👀 Code Review | | qa.yml | PR aprovado | Move Feature para 🧪 QA |

Skill (src/templates/skill/SKILL.md)

Skill que guia o usuário pelo fluxo via comandos como /spec-wave spec 42, /spec-wave plan 42, /spec-wave decompose 42. A skill lê o .spec-wave.json local, detecta o estado atual e executa os comandos corretos sem abrir wizards interativos. Instale-a no seu agente com install-skill (ver abaixo).

.spec-wave.json

Arquivo de configuração gerado pelo init na raiz do repositório. Armazena owner/repo, dados do GitHub Project (ID, URL, campos) e o provider de IA configurado. Todos os comandos leem este arquivo para operar sem precisar de flags adicionais.

tech_context.yml

Arquivo em .github/config/tech_context.yml que descreve a stack tecnológica do sistema (backend, frontend, banco, infra, roles RBAC, schemas, serviços). O generate-plan usa este arquivo para embasar o plano técnico — sem ele, o plano fica genérico.

Pré-requisitos

• Node.js >= 20
• GitHub CLI (gh) autenticado com escopos project, repo e workflow:

  gh auth refresh --scopes project,repo,workflow

• Secret no repositório, conforme o provider: ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN (assinatura Claude Pro/Max) ou OPENROUTER_API_KEY (Settings → Secrets → Actions)
• Para repositórios em organizações: criar PAT com escopo project e adicionar como secret GH_PROJECT_TOKEN

Modo de execução: GitHub Actions ou local

Todo passo do fluxo roda nos dois lugares — os workflows só instalam a CLI e chamam um comando. Para conduzir tudo sem consumir minutos de Actions:

npx @spec-wave/cli@latest mode local     # desarma os workflows (variável SPEC_WAVE_EXECUTION)
npx @spec-wave/cli@latest run <issue>    # executa aqui o passo que a label dispararia
npx @spec-wave/cli@latest mode actions   # volta ao CI

Com a variável setada, cada job é pulado e o run aparece como skipped — job que não roda não é faturado. run <issue> --dry-run explica o próximo passo (e o porquê) sem executar nada. Detalhes em packages/spec-wave/README.md.

Instalação da CLI

Não é necessário instalar globalmente — use npx:

npx @spec-wave/cli@latest --help

Para instalar globalmente:

npm install -g @spec-wave/cli
spec-wave --help

Modo de execução: GitHub Actions ou local

Todo passo do fluxo roda nos dois lugares — os workflows só instalam a CLI e chamam um comando. Para conduzir tudo sem consumir minutos de Actions:

npx @spec-wave/cli@latest mode local     # desarma os workflows (variável SPEC_WAVE_EXECUTION)
npx @spec-wave/cli@latest run <issue>    # executa aqui o passo que a label dispararia
npx @spec-wave/cli@latest mode actions   # volta ao CI

Com a variável setada, cada job é pulado e o run aparece como skipped — job que não roda não é faturado. run <issue> --dry-run explica o próximo passo (e o porquê) sem executar nada. Detalhes em packages/spec-wave/README.md.

Instalação da Skill

A skill permite usar o fluxo diretamente no seu agente via /spec-wave.

1. Instale a skill com o comando install-skill:

# Autodetecta o agente em uso e instala no local/formato correto
npx @spec-wave/cli@latest install-skill

O comando suporta Claude Code, Cursor, opencode, Cline, Kilo Code, Antigravity e o padrão genérico AGENTS.md. Por padrão instala no escopo do projeto (versionável com o time); use --global para o escopo do usuário. Escolha alvos com --agent <nomes> (ex.: --agent claude,cursor) ou --all para todos os detectados. Use --dry-run para pré-visualizar sem gravar.

2. Adicione ao CLAUDE.md (ou equivalente) do projeto:

# spec-wave skill
Trigger `/spec-wave` to invoke the spec-wave skill.

3. Use no seu agente:

/spec-wave setup
/spec-wave spec 42
/spec-wave plan 42
/spec-wave ready 42
/spec-wave decompose 42
/spec-wave implement 45

Exemplo de uso — do início ao fim

Contexto

Equipe quer implementar uma feature de "Checkout com PIX" em um repositório acme/loja.

1. Configurar o repositório

# Verificar autenticação
gh auth status

# Se faltarem escopos:
gh auth refresh --scopes project,repo,workflow

# Configurar spec-wave (cria Project, labels e workflows)
npx @spec-wave/cli@latest init --repo acme/loja --project-title "Loja — Spec Wave"

O init cria:

• GitHub Project v2 com 12 colunas Kanban e campos personalizados (Work Item Type, Priority, Story Points, Area)
• 20+ labels de tipo, prioridade e gatilho
• 8 GitHub Actions workflows em .github/workflows/
• .spec-wave.json com os IDs do Project

Adicionar o secret de IA no GitHub: Settings → Secrets → Actions — ANTHROPIC_API_KEY, CLAUDE_CODE_OAUTH_TOKEN ou OPENROUTER_API_KEY, conforme o provider escolhido no init.

2. Criar a hierarquia de issues

# Criar Epic
npx @spec-wave/cli@latest issue \
  --type epic \
  --title "Checkout e Pagamentos" \
  --priority P1 \
  --area Backend
# → Issue #5 criada: [EPIC] Checkout e Pagamentos

# Criar Feature como sub-issue do Epic
npx @spec-wave/cli@latest feature \
  --title "Checkout com PIX" \
  --parent 5 \
  --priority P1 \
  --area Backend
# → Issue #12 criada: [FEATURE] Checkout com PIX (sub-issue de #5)
# → Adicionada ao board em 📥 Backlog

3. Gerar a especificação funcional

gh issue edit 12 --add-label "spec-wave:spec"

O GitHub Action generate-spec.yml dispara, chama a IA e faz commit de:

docs/features/checkout-com-pix/spec.md

A issue #12 recebe um comentário com o link para o arquivo.

4. Gerar o plano técnico

Antes de gerar o plano, garanta que .github/config/tech_context.yml existe e reflete a stack real. O init cria um scaffold — edite-o:

system_info:
  name: "Loja ACME"
  stack:
    backend: "Node.js (NestJS v11)"
    frontend: "Next.js 16"
    database: "PostgreSQL (Prisma 5)"
    infra: "Docker / AWS ECS"
security:
  auth_protocol: "JWT"
  rbac_roles: ["ADMIN", "CUSTOMER"]
database_schemas:
  - table: "orders"
    columns: "id, customer_id, status, total, created_at"

git add .github/config/tech_context.yml
git commit -m "chore: tech_context.yml"
git push

# Acionar geração do plano
gh issue edit 12 --add-label "spec-wave:plan"

O Action gera docs/features/checkout-com-pix/plan.md com:

• Estratégia Técnica e Matriz de Rastreabilidade
• Detalhamento da Implementação
• Segurança e Conformidade
• Estratégia de Testes
• Rollback e Monitoramento

5. Validar spec e plan

gh issue edit 12 --add-label "spec-wave:ready"

O Action validate.yml verifica se todas as seções obrigatórias estão presentes em spec.md e plan.md. Se passar:

• Remove a label spec-wave:ready
• Adiciona a label spec-wave:plan-approved
• Comenta "Validação aprovada ✅" na issue

6. Decompor em Stories e Tasks (duas etapas)

A decomposição não cria issues de uma vez. Primeiro nasce um rascunho revisável; as issues só são criadas depois que você aprova.

6a. Gerar o rascunho:

gh issue edit 12 --add-label "spec-wave:decompose"

O Action grava docs/features/<slug>/decomposition.md no repositório e submete o arquivo à crítica adversarial. Nenhuma issue é criada.

# Decomposição — [FEATURE] Pagamento com PIX
<!-- spec-wave:decomposition v1 issue=12 kind=stories -->

## Story 1 — selecionar PIX como forma de pagamento

**User story:** Como cliente, quero selecionar PIX, para pagar mais rápido
**Depende de:** —

### Task 1.1 — criar endpoint POST /orders/:id/payment/pix
### Task 1.2 — integrar API do banco via webhook

Se a crítica encontrar contradições graves, ela comenta na issue citando Story N / Task N.M, aplica spec-wave:critique-failed e o Action falha. Você corrige o decomposition.md — o artefato que os achados referenciam — e reaplica spec-wave:decompose: o arquivo é criticado como está, sem ser regerado.

6b. Aplicar o rascunho aprovado:

gh issue edit 12 --add-label "spec-wave:decompose-apply"

Agora as sub-issues da Feature #12 são criadas a partir do arquivo:

#13 [STORY] selecionar PIX como forma de pagamento
  #14 [TASK] Criar endpoint POST /orders/:id/payment/pix
  #15 [TASK] Integrar API do banco via webhook
  #16 [TASK] Exibir QR Code na tela de checkout
#17 [STORY] receber confirmação do pagamento
  #18 [TASK] Webhook de confirmação do banco
  #19 [TASK] Notificação por e-mail ao confirmar

Todas as Stories e Tasks são adicionadas ao board em ✅ Ready com Status Todo.

7. Implementar

# Via skill no Claude Code:
/spec-wave implement 13

# Ou direto:
npx @spec-wave/cli@latest implement 13 --dry-run   # ver contexto antes
npx @spec-wave/cli@latest implement 13             # executar

O comando monta um arquivo de contexto com spec.md, plan.md e todas as Tasks da Story, e aciona o spec-kit configurado.

8. Code Review automático

Ao abrir um PR que referencia Closes #14 (ou qualquer issue da hierarquia):

## Descrição
Implementa endpoint PIX

Closes #14

O Action code-review.yml detecta a referência, sobe a hierarquia Task → Story → Feature, e move a Feature #12 para 👀 Code Review no board.

9. QA automático

Quando um reviewer aprova o PR, o Action qa.yml move a Feature #12 para 🧪 QA.

10. Estado final no board

Feature #12: [FEATURE] Checkout com PIX
  Etapa: 🧪 QA
  Status: Todo
  Work Item Type: Feature
  Priority: P1
  Area: Backend

Após QA passar, mover manualmente para 📋 Homologação → 🚀 Deploy → 🎉 Done.

Atualizar repositórios existentes

Quando uma nova versão da CLI for publicada, rode em cada repositório configurado:

npx @spec-wave/cli@latest init --skip-project --skip-labels

Isso atualiza apenas os arquivos de workflow sem recriar o Project ou as labels.

Providers de IA

| Provider | Secret | Modelo padrão | |----------|--------|---------------| | anthropic | ANTHROPIC_API_KEY | claude-sonnet-4-6 | | claude-oauth | CLAUDE_CODE_OAUTH_TOKEN | claude-sonnet-4-6 | | openrouter | OPENROUTER_API_KEY | anthropic/claude-3.7-sonnet |

Configurar no init:

npx @spec-wave/cli@latest init --repo owner/repo --provider openrouter --model anthropic/claude-3.7-sonnet

claude-oauth — rodar tudo pela assinatura Claude Pro/Max

Mesmo motor do provider anthropic, credencial diferente: em vez de uma chave de API cobrada por token, o token da sua assinatura. Os cinco workflows de IA (spec, plan, bug, decompose, critique) rodam assim, inclusive nos GitHub Actions — o binário do Claude Code vem embarcado na CLI, então o runner não precisa de nada além do setup-node que os workflows já fazem.

claude setup-token          # gere o token (escopo só de inferência)
# cole o valor em Settings → Secrets → Actions → CLAUDE_CODE_OAUTH_TOKEN

npx @spec-wave/cli@latest init --repo owner/repo --provider claude-oauth
# ou, num repo já configurado, troque "provider" no .spec-wave.json e rode `update`

O consumo passa a sair do limite do seu plano — sob rate limit da assinatura o job falha por indisponibilidade, não por erro de configuração.

Modo de execução: Actions ou local

Os workflows nunca fizeram o trabalho — eles instalam a CLI e chamam um comando. Por isso o fluxo inteiro roda igual na sua máquina, e dá para desligar o CI quando o que incomoda é o consumo de minutos.

npx @spec-wave/cli@latest mode                 # estado atual
npx @spec-wave/cli@latest mode local           # desarma os workflows
npx @spec-wave/cli@latest run <issue> --dry-run  # explica o próximo passo
npx @spec-wave/cli@latest run <issue>          # executa aqui
npx @spec-wave/cli@latest mode actions         # volta ao CI

mode escreve os dois lados do interruptor: execution.mode no .spec-wave.json (o que a CLI e as skills leem) e a variável de repositório SPEC_WAVE_EXECUTION (o que o if: de cada job avalia). Com ela setada, o run aparece como skipped — job que não roda não é faturado. A variável exige admin no repositório; sem permissão o comando avisa em vez de fingir que aplicou.

run <issue> executa o passo que a label dispararia, decidido pelo estado da issue: documentos que existem + labels presentes.

| Estado | Passo | |---|---| | Feature sem spec.md | generate-spec | | spec pronta, sem plan.md | generate-plan (crítica embutida) | | sem spec-wave:plan-approved | validate | | validada, sem decomposition.md | decompose (rascunho) | | spec-wave:decompose-ready | decompose-apply — exige --apply | | Bug | generate-bug → validate → triagem (humana) |

run --pr <n> cobre o lado do PR: code-review e, havendo review aprovada, também qa.

Ele se recusa a rodar (saindo com código 2) quando há label de gatilho pendente na issue — Action em voo, e rodar por cima duplicaria o documento —, quando um portão humano da crítica está aplicado (needs-human, critique-failed), quando o documento existe no repositório mas não no seu clone (git pull primeiro) e quando o passo cria issues sem confirmação explícita. --dry-run mostra a decisão sem executar nada; --force, --yes, --apply e --step cobrem os casos em que você sabe o que está fazendo.

O doctor tem um check para o par config × variável: divergir é o estado perigoso — é achar que desligou o CI e continuar pagando por ele.

Licença

MIT