@spec-wave/cli 0.20.0 → 0.23.0

package/src/templates/skill/SKILL.md

@@ -227,7 +227,7 @@ Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub
 |----------|------|-----------|
 | `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. Argumento posicional. |
 
-> Lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
+> **Sem argumento**, monta o mapa de TODAS as Features abertas fora de 🎉 Done num grafo só (conjunto vindo do board), com a Feature de cada Story ao lado — nesse escopo a dependência entre Features entra na ordenação. Com `<feature>`, lista as Stories da Feature em **ordem topológica** pelas dependências (linha `Depende de: #N` no corpo + relação nativa *blocked by*, mescladas), com a Etapa atual de cada uma no board. Dependências para **fora da Feature** não entram na ordenação (não há como saber onde a Story de outra Feature entra nesta sequência), mas aparecem em **"Bloqueadas por fora desta Feature"**, com o estado de cada bloqueadora. Avisa sobre **ciclos de dependência** (essas Stories ficam fora da ordem — corrija as linhas `Depende de`) e sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done). Use antes de escolher qual Story implementar.
 
 ### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
 | Flag/Arg | Tipo | Descrição |
@@ -316,7 +316,7 @@ Corpo técnico.
 
 **Ao editar à mão:**
 - a **posição** manda, não o número escrito — inserir uma Story no meio sem renumerar funciona;
-- `**Depende de:**` usa referências **1-based** (`Story 1, Story 3`) ou `—`; apontar para si mesma ou para frente é **erro**, não filtro silencioso;
+- `**Depende de:**` aceita **irmãs** (`Story 1, Story 3`, 1-based, só para trás — apontar para si mesma ou para frente é **erro**, não filtro silencioso) e **issues de outras Features** (`#412`, que precisam JÁ existir); as duas formas convivem na mesma linha (`Story 1, #412`), e `—` significa nenhuma;
 - o corpo aceita markdown livre (`## Backend`, cercas de código) — só `## Story N` e `### Task N.M` são estrutura;
 - **para gerar outro rascunho do zero:** apague o arquivo e reaplique `spec-wave:decompose`.
 
@@ -606,7 +606,7 @@ Valida que spec.md e plan.md estão completos e a Feature pode avançar.
    gh issue edit <número> --add-label "spec-wave:ready"
    ```
 2. Informe: "Validação iniciada. O workflow verificará se spec.md e plan.md contêm todas as seções obrigatórias."
-3. Se a validação falhar, o workflow comentará os problemas na issue e adicionará automaticamente `spec-wave:spec`. Informe o usuário para corrigir e tentar novamente.
+3. Se a validação falhar, o workflow comentará os problemas na issue e **não aplicará label de gatilho nenhuma**. Informe o usuário para corrigir e reaplicar `spec-wave:ready`. Falha por título de seção vem com "encontrei X, esperava Y" — renomear resolve. `spec-wave:spec` só se o documento precisar ser REGERADO: ela **sobrescreve** o `spec.md` revisado.
 4. **Se a issue tiver `spec-wave:critique-failed` ou `spec-wave:needs-human`**, a validação falha de imediato — são portões humanos: a crítica apontou contradições graves (comentário 🔎 na issue) ou esgotou as tentativas. Nesses casos a Feature **não** é devolvida para a etapa de spec; siga o fluxo da seção *Crítica adversarial* (corrigir a superfície certa → remover a label → re-aplicar `spec-wave:ready`).
 5. Se passar, oriente: "Feature validada! Mova o card para **✅ Ready** e use `/spec-wave decompose <número>` para gerar o **rascunho** das Stories (nada é criado ainda)."
 
@@ -636,7 +636,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    gh issue edit <número> --add-label "spec-wave:decompose-apply"
    ```
    Aplicar essa label **é** a aprovação humana — não há nova crítica.
-5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução.
+5. Após a aplicação, as issues filhas aparecem como comentário na issue pai. A issue pai e as Stories/Tasks criadas entram no board na Etapa **✅ Ready** (Status Todo; a Etapa nunca retrocede — itens já adiante não são tocados). As Stories trazem a linha `Depende de: #N` (+ relação *blocked by*) — use `npx @spec-wave/cli@latest order <número>` para ver a ordem de execução. Se a issue pai tiver **milestone**, as filhas nascem nele; sem milestone no pai, nascem sem.
 6. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para forçar um re-decompose, siga a seção *Guard de idempotência*.
 
 > **Nunca pule a etapa 1** aplicando `spec-wave:decompose-apply` direto: sem `decomposition.md` o Action falha pedindo o rascunho.

package/src/templates/workflows/code-review.yml

@@ -27,8 +27,12 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: '24'
+
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - id: resolve
-        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }} --resolve-only
+        run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }} --resolve-only
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}
@@ -56,8 +60,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Move Feature to Code Review
-        run: npx @spec-wave/cli@{{CLI_VERSION}} code-review --pr-number ${{ github.event.pull_request.number }}
+        run: spec-wave code-review --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/critique.yml

@@ -5,7 +5,21 @@ on:
     types: [labeled]
 
 concurrency:
-  group: spec-wave-critique-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:critique'
+    && format('spec-wave-critique-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -29,8 +43,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Critique plan.md as-is
-        run: npx @spec-wave/cli@{{CLI_VERSION}} critique --issue-number ${{ github.event.issue.number }}
+        run: spec-wave critique --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/decompose.yml

@@ -20,7 +20,21 @@ on:
 # o spec.md/plan.md do checkout — que uma geração concorrente estaria trocando
 # debaixo dele.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ (github.event.label.name == 'spec-wave:decompose' || github.event.label.name == 'spec-wave:decompose-apply')
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -50,9 +64,12 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Decompose into Stories and Tasks
         run: >
-          npx @spec-wave/cli@{{CLI_VERSION}} decompose
+          spec-wave decompose
           --issue-number ${{ github.event.issue.number }}
           ${{ github.event.label.name == 'spec-wave:decompose-apply' && '--apply' || '' }}
         env:

package/src/templates/workflows/generate-bug.yml

@@ -12,7 +12,21 @@ on:
 # diferentes a disputa é resolvida no laço de repetição de push do
 # lib/flow-run.mjs — serializar o repositório inteiro mataria a vazão.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:bug'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -34,8 +48,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate bug.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-bug --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-bug --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-plan.yml

@@ -20,7 +20,21 @@ on:
 # mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
 # acontece — no laço de repetição de push do lib/flow-run.mjs.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:plan'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -42,8 +56,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate plan.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-plan --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-plan --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/generate-spec.yml

@@ -20,7 +20,21 @@ on:
 # mataria a vazão, e a disputa entre issues diferentes é resolvida onde ela
 # acontece — no laço de repetição de push do lib/flow-run.mjs.
 concurrency:
-  group: spec-wave-item-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:spec'
+    && format('spec-wave-item-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -42,8 +56,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Generate spec.md
-        run: npx @spec-wave/cli@{{CLI_VERSION}} generate-spec --issue-number ${{ github.event.issue.number }}
+        run: spec-wave generate-spec --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

package/src/templates/workflows/qa.yml

@@ -24,8 +24,12 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
+
       - name: Move Feature to QA
-        run: npx @spec-wave/cli@{{CLI_VERSION}} qa --pr-number ${{ github.event.pull_request.number }}
+        run: spec-wave qa --pr-number ${{ github.event.pull_request.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           PROJECT_TOKEN: ${{ secrets.GH_PROJECT_TOKEN }}

package/src/templates/workflows/validate.yml

@@ -5,7 +5,21 @@ on:
     types: [labeled]
 
 concurrency:
-  group: spec-wave-validate-${{ github.event.issue.number }}
+  # Um run que NÃO vai fazer nada não pode disputar este grupo.
+  #
+  # `issues: [labeled]` dispara para QUALQUER label — prioridade, tipo,
+  # `spec-wave:model:*`. O job é filtrado pelo `if:` e termina skipped, mas o RUN
+  # entra na fila de concurrency do mesmo jeito, e com `cancel-in-progress: false`
+  # o GitHub cancela o run que já estava PENDENTE para pôr o novo no lugar. Foi
+  # assim que um decompose enfileirado atrás de um generate-plan morreu cancelado
+  # em 1 segundo por causa de uma label sem relação nenhuma — a label de gatilho
+  # fica na issue, `labeled` não redispara com ela aplicada, e o fluxo trava sem
+  # nenhum sinal. Rotular o run inútil com um grupo único (`github.run_id`) o tira
+  # da fila sem afrouxar a serialização de quem realmente vai rodar.
+  group: >-
+    ${{ github.event.label.name == 'spec-wave:ready'
+    && format('spec-wave-validate-{0}', github.event.issue.number)
+    || format('spec-wave-noop-{0}', github.run_id) }}
   cancel-in-progress: false
 
 jobs:
@@ -26,8 +40,11 @@ jobs:
         with:
           node-version: '24'
 
+      - name: Instala a CLI
+        run: npm install -g @spec-wave/cli@{{CLI_VERSION}}
+
       - name: Validate spec and plan
-        run: npx @spec-wave/cli@{{CLI_VERSION}} validate --issue-number ${{ github.event.issue.number }}
+        run: spec-wave validate --issue-number ${{ github.event.issue.number }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           GITHUB_REPOSITORY: ${{ github.repository }}