@spec-wave/cli 0.24.0 → 0.26.0

package/src/plugin/skills/run/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: spec-wave-run
+description: "Use para conduzir o fluxo do spec-wave LOCALMENTE, sem gastar minutos de GitHub Actions: `spec-wave run <issue>` executa nesta máquina o passo que a label dispararia (spec, plan, crítica, validate, decompose, apply) e `spec-wave mode local|actions` alterna entre os dois mundos. Gatilhos: 'rodar o spec-wave local', 'qual o próximo passo da issue 12', 'sem gastar Actions', 'desligar os workflows', 'trocar para execução local'."
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(gh issue view *)
+  - Read
+---
+
+# spec-wave run — o fluxo inteiro na sua máquina
+
+Os workflows do spec-wave nunca fizeram o trabalho: eles instalam a CLI e chamam um comando. O `run` é o mesmo comando, disparado **daqui** — e o `mode` desarma os workflows para o gatilho não acontecer duas vezes.
+
+```bash
+npx @spec-wave/cli@latest mode local      # desarma os workflows (0 minutos de Actions)
+npx @spec-wave/cli@latest run <issue>     # executa o próximo passo pendente
+npx @spec-wave/cli@latest mode actions    # volta tudo para o CI
+```
+
+**Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**. O campo `execution.mode` diz em qual mundo o repositório está.
+
+## Como decidir o que fazer
+
+1. **Sempre comece pelo `--dry-run`.** Ele consulta a issue, olha os documentos e explica o passo sem executar nada nem chamar IA:
+   ```bash
+   npx @spec-wave/cli@latest run <issue> --dry-run
+   ```
+2. Mostre ao usuário o passo, o motivo e o comando que rodaria. **Só então** execute sem a flag.
+3. `--json` devolve a decisão em JSON, quando você precisar ramificar programaticamente. É **um** documento: o desfecho no topo (`action`, `command`, `blocked`) e a sequência inteira em `steps` — útil com `--max-steps`.
+
+## O que o `run` decide sozinho
+
+| Estado da issue | Passo |
+|---|---|
+| Feature sem `spec.md` | `generate-spec` |
+| spec pronta, sem `plan.md` | `generate-plan` (a crítica roda embutida) |
+| spec+plan sem `spec-wave:plan-approved` | `validate` |
+| validada, sem `decomposition.md` | `decompose` (rascunho) |
+| `spec-wave:decompose-ready` | `decompose-apply` — **exige `--apply`** |
+| `spec-wave:decomposed` | nada: sugere a skill **implement** |
+| Bug sem `bug.md` → com `bug.md` → validado | `generate-bug` → `validate` → `triage` (humano) |
+| RFC | `decompose` → `decompose-apply` |
+
+Para PRs: `run --pr <n>` roda `code-review` e, se houver review aprovada, também `qa` — a mesma coisa que os workflows fariam nos eventos do PR.
+
+## Portões (quando ele se recusa a rodar)
+
+O comando **explica e para**, saindo com código 2. Não force sem entender:
+
+- **`trigger-pending`** — há label de gatilho na issue: um Action está em voo (ou falhou deixando-a). Rodar por cima duplicaria documento e comentário. `--force` fura, quando você tem certeza.
+- **`needs-human` / `critique-failed`** — portões humanos da crítica. O caminho é corrigir o documento e remover a label; para o `critique-failed` o passo de retomada é **re-criticar**, nunca regerar.
+- **`stale-checkout`** — o documento existe no repositório e não no seu clone. `git pull` e repita; seguir sobrescreveria o que já foi publicado.
+- **`needs-confirmation`** — o passo cria issues (`decompose-apply`) ou gasta IA repetindo a crítica de um rascunho existente. Revise antes e confirme com `--apply` / `--yes`.
+- **`inconsistent-state`** — as labels afirmam um documento que não existe. Quase sempre o título da issue mudou depois de gerar (o slug vira outro diretório).
+
+## Regras que o `run` respeita — e você também
+
+- **Nunca aplique label de gatilho no modo local.** Ela dispararia o Action e o passo aconteceria duas vezes. O `run` não aplica nenhuma.
+- **Um passo por invocação.** `--max-steps <n>` encadeia, mas cada passo de IA custa dinheiro — encadeie só quando o usuário pedir.
+- A **Regra fundamental** continua valendo: nunca escreva `spec.md`/`plan.md`/`decomposition.md` à mão. Quem gera é a CLI, aqui como no Action.
+
+## `mode` — o interruptor
+
+```bash
+npx @spec-wave/cli@latest mode              # estado atual
+npx @spec-wave/cli@latest mode local        # config + variável SPEC_WAVE_EXECUTION
+npx @spec-wave/cli@latest mode actions      # remove a variável
+```
+
+Ele escreve os **dois** lados: o `.spec-wave.json` (que a CLI e as skills leem) e a variável de repositório que o `if:` de cada job avalia. Com ela setada, o run do workflow aparece como *skipped* — job que não roda não é faturado.
+
+- A variável exige **admin** no repositório. Sem permissão o comando grava o config, avisa e aponta Settings → Secrets and variables → Actions → Variables.
+- **Commite o `.spec-wave.json`**: quem clona o repo (inclusive o dev-agent) lê a versão versionada.
+- Se os workflows instalados forem anteriores à guarda, o comando avisa e o conserto é a skill **update**.
+
+O `doctor` tem um check dedicado: config e variável em desacordo é problema, não detalhe — é o usuário achando que desligou o CI e continuando a pagar por ele.

package/src/plugin/skills/spec/SKILL.md

@@ -20,7 +20,7 @@ allowed-tools:
 
 O modo é detectado pelo ambiente — fora do Actions, a CLI roda em modo local automaticamente. Os dois geram o arquivo, commitam, dão push, comentam na issue e removem a label de gatilho. **Pergunte ao usuário qual ele quer** se não estiver claro; na dúvida numa sessão interativa, prefira o local (o resultado aparece em segundos, em vez de exigir acompanhar o Action).
 
-> Local exige a chave de IA no seu ambiente (`OPENROUTER_API_KEY` ou `ANTHROPIC_API_KEY`) e um `.spec-wave.json` no repositório. O provider `anthropic` **só** funciona local — no Action ele precisaria do Claude Code como subprocesso, que o runner não tem.
+> Local exige a credencial de IA no seu ambiente (`OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY` ou o login do Claude Code, se o provider for `claude-oauth`) e um `.spec-wave.json` no repositório. Para conduzir o fluxo inteiro sem gastar minutos de Actions, veja a skill **run**.
 
 **Contexto:** leia `.spec-wave.json` (Read). Ausente → skill **setup**.
 

package/src/templates/skill/SKILL.md

@@ -61,9 +61,32 @@ Exemplo de `.spec-wave.json`:
 
 ---
 
+## Modo de execução (Actions × local)
+
+Leia `execution.mode` no `.spec-wave.json` **antes** de acionar qualquer passo do fluxo:
+
+| `execution.mode` | Como acionar um passo | Custo |
+|---|---|---|
+| `actions` (default) | aplicar a label de gatilho (`spec-wave:spec`, `:plan`, …) | minutos de GitHub Actions |
+| `local` | `npx @spec-wave/cli@latest run <issue>` | nenhum — roda nesta máquina |
+
+**No modo `local`, NÃO aplique label de gatilho.** Os workflows estão desarmados por uma variável de repositório, mas a label continua sendo o contrato do outro modo — aplicá-la só polui a issue (e, se alguém religar o CI, dispara tarde).
+
+```bash
+npx @spec-wave/cli@latest mode                 # estado atual dos dois lados do interruptor
+npx @spec-wave/cli@latest mode local           # desarma os workflows
+npx @spec-wave/cli@latest run <issue> --dry-run  # explica o próximo passo sem executar
+npx @spec-wave/cli@latest run <issue>          # executa
+npx @spec-wave/cli@latest run --pr <n>         # code-review (+ qa, se houver aprovação)
+```
+
+O `run` decide o passo pelo estado da issue (documentos existentes + labels), respeita os portões humanos (`needs-human`, `critique-failed`), recusa rodar com uma label de gatilho pendente e **exige `--apply`** para o `decompose-apply`, que cria issues. Sempre mostre o `--dry-run` ao usuário antes de executar.
+
+---
+
 ## Regra fundamental
 
-**Nunca gere `spec.md` ou `plan.md` diretamente.** Sempre acione a label correspondente e deixe o GitHub Action gerar o arquivo. Isso garante que o arquivo seja commitado no repositório e referenciado na issue.
+**Nunca gere `spec.md` ou `plan.md` diretamente.** Acione o passo — a label (modo actions) ou o `run` (modo local) — e deixe o spec-wave gerar o arquivo. Isso garante que o arquivo seja commitado no repositório e referenciado na issue.
 
 Exceção: se o usuário pedir explicitamente para revisar ou melhorar um documento já gerado, use o Write tool para editar o arquivo local.
 

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

@@ -15,6 +15,10 @@ jobs:
   # de concurrency ao job seguinte: `concurrency` de workflow é avaliada no
   # trigger, quando ainda não se sabe qual issue o PR implementa.
   resolve:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
+    if: vars.SPEC_WAVE_EXECUTION != 'local'
     runs-on: ubuntu-latest
     permissions:
       issues: read
@@ -40,7 +44,7 @@ jobs:
   move:
     needs: resolve
     # PR sem vínculo explícito não resolve Feature nenhuma — e não move nada.
-    if: needs.resolve.outputs.feature != ''
+    if: vars.SPEC_WAVE_EXECUTION != 'local' && needs.resolve.outputs.feature != ''
     runs-on: ubuntu-latest
     # MESMO namespace do decompose.yml: um `decompose-apply` em curso na Feature
     # segura este job na fila em vez de disputar a subárvore com ele. Foi essa

package/src/templates/workflows/critique.yml

@@ -24,7 +24,11 @@ concurrency:
 
 jobs:
   critique:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       github.event.label.name == 'spec-wave:critique' &&
       contains(github.event.issue.title, '[FEATURE]')
     runs-on: ubuntu-latest

package/src/templates/workflows/decompose.yml

@@ -44,7 +44,11 @@ jobs:
     #  • spec-wave:decompose-apply → cria as Stories/Tasks a partir do rascunho
     # O `[RFC]` no título também dispara: o caminho RFC → Tasks existe na CLI
     # desde sempre, mas era inalcançável porque o filtro exigia `[FEATURE]`.
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       (github.event.label.name == 'spec-wave:decompose' ||
        github.event.label.name == 'spec-wave:decompose-apply') &&
       (contains(github.event.issue.title, '[FEATURE]') ||

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

@@ -31,7 +31,11 @@ concurrency:
 
 jobs:
   generate-bug:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       github.event.label.name == 'spec-wave:bug' &&
       contains(github.event.issue.title, '[BUG]')
     runs-on: ubuntu-latest

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

@@ -39,7 +39,11 @@ concurrency:
 
 jobs:
   generate-plan:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       github.event.label.name == 'spec-wave:plan' &&
       contains(github.event.issue.title, '[FEATURE]')
     runs-on: ubuntu-latest

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

@@ -39,7 +39,11 @@ concurrency:
 
 jobs:
   generate-spec:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       github.event.label.name == 'spec-wave:spec' &&
       contains(github.event.issue.title, '[FEATURE]')
     runs-on: ubuntu-latest

package/src/templates/workflows/qa.yml

@@ -10,7 +10,12 @@ concurrency:
 
 jobs:
   qa:
-    if: github.event.review.state == 'approved'
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
+    if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
+      github.event.review.state == 'approved'
     runs-on: ubuntu-latest
     permissions:
       issues: write

package/src/templates/workflows/validate.yml

@@ -24,7 +24,11 @@ concurrency:
 
 jobs:
   validate:
+    # Modo de execução: `spec-wave mode local` cria a variável de repositório
+    # SPEC_WAVE_EXECUTION=local e este job passa a ser PULADO — run aparece como
+    # skipped e job que não roda não é faturado. `mode actions` remove a variável.
     if: >
+      vars.SPEC_WAVE_EXECUTION != 'local' &&
       github.event.label.name == 'spec-wave:ready' &&
       (contains(github.event.issue.title, '[FEATURE]') ||
        contains(github.event.issue.title, '[BUG]'))