@spec-wave/cli 0.10.0 → 0.11.1

package/src/templates/skill/SKILL.md

@@ -67,6 +67,10 @@ Exemplo de `.spec-wave.json`:
 
 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.
 
+**Nunca crie Story ou Task avulsa com `/spec-wave issue`.** Story e Task nascem do `decompose`, já na Etapa **✅ Ready** e vinculadas ao pai. Criadas à mão elas caem em **📥 Backlog**, que é a coluna de descoberta de *produto* — e ali **não aparecem em tela nenhuma** da UI do spec-wave: o inbox do PM lista só Features, a tela do Dev lê a etapa 🚧 Desenvolvimento e a fila do TL lê ✅ Ready. Se o usuário insistir numa Story/Task avulsa, crie-a **com `--parent <n>`** e, logo em seguida, avance-a para ✅ Ready — explicando por que esse passo extra é necessário.
+
+**Nunca use `gh issue create` para criar work items.** Ele não adiciona a issue ao Project, então ela fica **sem Etapa** — e some de todas as telas da UI. Use sempre `npx @spec-wave/cli issue` (ou os atalhos `initiative` / `feature`).
+
 ---
 
 ## Fluxo Kanban
@@ -77,6 +81,20 @@ Exceção: se o usuário pedir explicitamente para revisar ou melhorar um docume
 → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done
 ```
 
+Essa é a sequência completa, mas **cada tipo de artefato percorre só um trecho dela** — e, principalmente, **nasce numa Etapa diferente**. Consulte esta tabela antes de criar ou mover qualquer item.
+
+| Artefato | Nasce em | Percorre | Observações |
+|----------|----------|----------|-------------|
+| **Initiative / Epic** | 📥 Backlog | — | Agrupadores. Não têm fluxo próprio; acompanham os filhos. |
+| **Feature** | 📥 Backlog | 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🚀 Deploy → 🎉 Done | Fica parada em **✅ Ready** esperando um dev assumir — é ali que ela aparece na fila do TL. Só avança para 👀 Code Review quando **TODAS** as suas Stories já estiverem lá. |
+| **Story** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
+| **Task** | **✅ Ready** (criada pelo `decompose`) | 🚧 Desenvolvimento → 🎉 Done | **Não** passa por Code Review, QA nem Homologação — só `task start` e `task done`. |
+| **RFC** | 📥 Backlog | decompõe direto em **Tasks** (que nascem em ✅ Ready) | Não usa spec/plan. |
+| **Bug** | 📥 Backlog | 🚧 Desenvolvimento → 🎉 Done | Ao aprovar, vai direto para Done (não passa por Homologação). |
+| **Spike** | 📥 Backlog | **movido só à mão pelo usuário** | Nunca avance a Etapa de um Spike por conta própria. |
+
+**Regra da Etapa:** a Etapa **só avança, nunca retrocede**. O campo **Status** (Todo / In Progress / Done) mede o progresso *dentro* da Etapa e reinicia a cada avanço. Prefira sempre os comandos da CLI (`task start|done`, `story review`) a mutações manuais no board — eles embutem essas regras.
+
 Labels de gatilho:
 - `spec-wave:spec` → dispara `generate-spec.yml` → gera `spec.md` (especificação funcional, primeiro)
 - `spec-wave:plan` → dispara `generate-plan.yml` → gera `plan.md` (plano técnico, a partir da spec)
@@ -87,6 +105,12 @@ Labels de **estado** (gravadas pelas automações — **não** são gatilhos, n
 - `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves** nos documentos; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
 - `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
 
+Label **modificadora** — `spec-wave:force`: sozinha **não dispara nada**; adicionada **junto** de uma label de gatilho, manda o comando **re-executar a etapa ignorando os guards**. É **consumida** (removida) pelo run que a leu, então vale para uma execução só. Adicione-a **antes ou junto** do gatilho, nunca depois (o evento do gatilho já teria disparado):
+```bash
+gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+Efeito por comando: no **decompose**, ignora o guard e **fecha as sub-issues da decomposição anterior** antes de gerar as novas (veja *Guard de idempotência*); em **spec** e **plan**, não muda nada na prática — eles já regeram e sobrescrevem o arquivo a cada acionamento da label.
+
 A etapa **🚧 Desenvolvimento** é coberta pelo comando **local** `npx @spec-wave/cli@latest implement <número>` (não é uma label/Action): lê uma **Feature** (todas as Stories pendentes, em ordem de dependência), uma Story ou uma Task e aciona o spec-kit para implementar. Veja `/spec-wave implement`.
 
 ---
@@ -115,7 +139,9 @@ Esta skill é um **wrapper** da CLI `@spec-wave/cli`, sempre invocada como `npx
 | `--priority <p>` | string | **Opcional.** `P0`, `P1`, `P2` ou `P3`. Omita se o usuário não pediu — a prioridade fica `null` (sem prioridade). Nunca atribua por conta própria. |
 | `--area <area>` | string | `Frontend`, `Backend`, `Mobile`, `Infra`, `DevOps` ou `Data`. |
 
-> Faz tudo: cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa = 📥 Backlog**, **Work Item Type**, **Area** e, **só se informada, Priority**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+> Faz tudo: cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula ao parent como sub-issue, adiciona ao Project e define os campos **Etapa**, **Work Item Type**, **Area** e, **só se informada, Priority**. Grava `Parent: #N` no corpo. Lê o Project do `.spec-wave.json`. **Não use `gh issue create` direto** — ele não adiciona ao board nem vincula o parent.
+>
+> ⚠️ **A Etapa inicial é sempre 📥 Backlog, para qualquer `--type`.** Isso é o correto para **Initiative, Epic, Feature, RFC, Bug e Spike**. Para **Story e Task está errado** — elas pertencem a ✅ Ready (veja a *Regra fundamental*): prefira criá-las via `decompose`; se criar à mão, avance a Etapa logo depois.
 
 ### `@spec-wave/cli initiative` — atalho de `issue --type initiative`
 Cria o nó raiz da hierarquia (agrupa Epics). Mesmas flags do `issue` exceto `--type` (fixo em `initiative`) e `--parent` (Initiative é raiz, não tem pai).
@@ -163,6 +189,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 | Flag | Tipo | Descrição |
 |------|------|-----------|
 | `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
+| `--force` | flag | Re-executa a etapa ignorando os guards. No fluxo por label o equivalente é a label `spec-wave:force` (a linha de comando do workflow é fixa) — prefira a label. |
 
 > ⚠️ Esses quatro comandos são executados pelos **GitHub Actions** (disparados por labels), **não** pela skill diretamente. Veja a *Regra fundamental*: para gerar plan/spec/decompor, adicione a **label** correspondente — não rode o comando à mão (a não ser para debug local).
 >
@@ -180,7 +207,7 @@ Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o flu
 > Diferente dos quatro acima, `implement` roda **localmente** (lê `.spec-wave.json`, como `issue`), não por Action. Detecta o tipo da issue: **Feature** → lista as Stories (sub-issues), **ordena topologicamente pelas dependências** (`Depende de:` + *blocked by*), **pula** as já em 👀 Code Review+ (listadas no contexto como "não tocar") e monta **um único** contexto com todas as pendentes (cada uma com suas Tasks), acionando o spec-kit **uma vez** com `{issue}/{type}/{title}` da Feature — **ciclo de dependências entre Stories pendentes aborta o comando (exit 1)**; **Story** → coleta todas as Tasks (sub-issues) e aciona o spec-kit uma única vez; **Task** → só aquela task. Monta o contexto em `.spec-wave/implement-<n>.md` e chama o comando configurado em `specKit.command` (no `.spec-wave.json`) ou na env `SPEC_WAVE_IMPLEMENT_CMD`. Placeholders disponíveis no template: `{tasksFile} {specFile} {planFile} {issue} {type} {title}`. Se nada estiver configurado, ele apenas monta o contexto e mostra como configurar (não executa). O contexto inclui os **comentários da issue**, um **digest do código recente** e um **aviso de dependências pendentes** quando a issue depende (linha `Depende de: #N` ou relação nativa *blocked by*) de outra que ainda não foi concluída — nesse caso, confirme com o usuário antes de seguir. Inclui também instruções para o agente implementar as Tasks **sequencialmente, uma por vez** (nunca duas com Status "In Progress" ao mesmo tempo): cada Task usa o **Status** (In Progress) *dentro* da Etapa 🚧 Desenvolvimento e, **ao concluir, avança para a Etapa 🎉 Done com Status Done**. **Ao concluir toda a Story**: fazer o commit, abrir o PR e **avançar a Etapa da Story para 👀 Code Review** (Status → Todo) — as Tasks já estão em 🎉 Done. A **Feature só avança** para Code Review quando **TODAS as suas Stories** já estiverem em Code Review — enquanto houver Story pendente, a Feature fica em 🚧 Desenvolvimento. Etapa só avança (nunca volta); Status mede o progresso dentro da etapa.
 
 ### `@spec-wave/cli doctor` — preflight de auth e configuração (comando LOCAL)
-Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models` + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
+Sem flags. Roda um checklist de diagnóstico no repositório atual: token GitHub (e a fonte dele), escopos (`repo`, `project`, `workflow` — com degradação para checks funcionais em fine-grained PATs), conta ativa do `gh` vs. owner, `.spec-wave.json` (campos e sincronia com o Project real), acesso ao repositório, configuração de IA (provider/modelo/`ai.models`/teto de saída + secrets do Actions), **spec-kit** (`specKit.command` / env `SPEC_WAVE_IMPLEMENT_CMD` — se ausente, avisa e sugere exemplos por agente: Claude Code, opencode, Codex, Copilot CLI, Kiro CLI, Qwen Code) e presença dos workflows.
 
 > Saída: `✓` ok, `✗` problema confirmado, `!` não verificável (best-effort — falha de rede nunca derruba o doctor). **Exit 1** se houver algum `✗`. **Quando rodar:** no início de uma sessão de trabalho, ou sempre que aparecer um erro estranho (ex.: **404 ao criar issues** — causa típica: token sem acesso ao repo/org, que o doctor aponta). É o primeiro passo de troubleshooting — prefira-o a depurar `gh api` na mão.
 
@@ -223,7 +250,11 @@ Após o `generate-plan` e **antes** da criação de issues no `decompose`, um se
 
 O evento `labeled` pode redisparar (re-add da label, retry de runner). Para não duplicar Stories/Tasks, o `decompose` **pula** quando a issue já tem a label **`spec-wave:decomposed`** ou já tem sub-issues do tipo-alvo (`[STORY]` para Feature, `[TASK]` para RFC). Ao concluir com sucesso, o Action grava a label. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
 
-**Para forçar um re-decompose:** remova a label (`gh issue edit <n> --remove-label "spec-wave:decomposed"`), **apague/feche as sub-issues antigas** (senão a detecção por sub-issues pula de novo) e re-adicione `spec-wave:decompose`.
+**Para forçar um re-decompose**, adicione a label `spec-wave:force` junto com o gatilho:
+```bash
+gh issue edit <n> --add-label "spec-wave:force" --add-label "spec-wave:decompose"
+```
+O comando então: (1) ignora os dois guards; (2) **fecha** as sub-issues abertas do tipo-alvo da decomposição anterior **e os filhos delas** (as Tasks de cada Story), comentando na issue o que foi fechado; (3) gera a nova decomposição. **É destrutivo** — se alguma Story já tiver saído de ✅ Ready, o comentário destaca quais, para você conferir se descartou trabalho em andamento. Confirme com o usuário antes de acionar em Features com desenvolvimento em curso.
 
 ### Dependências entre Stories (`Depende de: #N`)
 
@@ -253,6 +284,25 @@ Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo
 
 Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo e os overrides de `ai.models` resolvidos.
 
+### Teto de saída (`ai.maxTokens`) e truncamento
+
+O teto de tokens de saída é **32.768** por padrão, ajustável globalmente por `ai.maxTokens` e por ação em `ai.maxTokensByAction` (mesma forma de `model`/`models`; `SPEC_WAVE_MAX_TOKENS` na env tem precedência):
+
+```json
+{
+  "ai": {
+    "maxTokens": 32768,
+    "maxTokensByAction": { "spec": 49152 }
+  }
+}
+```
+
+**Quando a saída não cabe no teto, a geração FALHA — nada é gravado.** Os dois provedores sinalizam o corte (`finish_reason: "length"` no OpenRouter, `stop_reason: "max_tokens"` na Anthropic) e a CLI transforma isso em erro: um documento cortado no meio de uma frase passaria na validação de seções e valeria menos que documento nenhum. O erro é comentado na issue e a label de gatilho é removida, então basta corrigir e re-aplicar a label.
+
+Se acontecer, as saídas são: **aumentar o teto** (`ai.maxTokens`) ou **reduzir o tamanho da issue de origem** — corpo muito grande gera documento muito grande. Modelos com raciocínio (Opus 4.7+, deepseek-r1) gastam parte do teto "pensando" antes de escrever, então o teto precisa cobrir raciocínio + documento.
+
+O `validate` também recusa documento com sinal objetivo de corte (bloco de código não fechado, parêntese aberto na última linha) — rede de segurança para documento editado à mão ou gerado por versão antiga da CLI.
+
 ---
 
 ## Sub-comandos
@@ -314,7 +364,7 @@ Configura o spec-wave no repositório. Você dirige o `init` com flags — **nun
 
 ### `/spec-wave issue <tipo> <descrição>` · `/spec-wave initiative <descrição>` · `/spec-wave feature <descrição>`
 
-Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board em **📥 Backlog**, opcionalmente como sub-issue de um parent.
+Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado ao board, opcionalmente como sub-issue de um parent. A Etapa inicial é **📥 Backlog** — correta para Initiative, Epic, Feature, RFC, Bug e Spike. **Story e Task não devem ser criadas por aqui** (nascem do `decompose`, em ✅ Ready — veja a *Regra fundamental*).
 
 **Hierarquia típica:** Initiative → Epic → Feature → Story → Task. A **Initiative** é o nó raiz e agrupa Epics. Use `--parent <n>` para criar como sub-issue do nível acima (ex.: um Epic filho de uma Initiative, ou uma Story filha de uma Feature). O GitHub mostra o parent na issue filha e vice-versa; a CLI ainda grava `Parent: #N` no corpo.
 
@@ -334,6 +384,7 @@ Crie um work item tipado (Initiative/Epic/Feature/Story/Task/...) já adicionado
    ```
    Para Features, pode usar o atalho `npx @spec-wave/cli@latest feature --title ...` (equivale a `--type feature`).
    A CLI cria a issue (label de tipo — e de prioridade **apenas se `--priority` for informado**), vincula como sub-issue do parent, adiciona ao Project e define Etapa = 📥 Backlog + Work Item Type + Area (+ Priority só se informada). **Não use `gh issue create`** (não adiciona ao board nem vincula o parent).
+   **Se o tipo for `story` ou `task`**, avise o usuário que o caminho normal é o `decompose` e, se ele confirmar mesmo assim, avance a Etapa para ✅ Ready depois de criar — senão o item fica invisível na UI.
 3. Informe o número criado e o vínculo com o pai (se houver).
 4. Para Features: "Quando quiser iniciar, mova para **📋 Spec** e use `/spec-wave spec <número>` para gerar a especificação funcional (o plano técnico vem depois)".
 
@@ -365,7 +416,8 @@ Inicia a geração da **especificação funcional** para uma Feature. É o **pri
    ```
 3. Informe: "Label `spec-wave:spec` adicionada. O GitHub Action `generate-spec.yml` irá gerar o `spec.md` automaticamente."
 4. Após a conclusão, ofereça revisar o spec.md gerado em `docs/features/<slug>/spec.md`.
-5. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
+5. **Para regerar** (a spec já existe e o usuário quer outra versão): basta re-adicionar a label — o Action sobrescreve o arquivo. A label `spec-wave:force` é aceita, mas aqui não muda nada; **avise que o spec.md atual será perdido** (inclusive edições manuais) e confirme antes.
+6. Próximo passo: gerar o plano técnico — mova para **📋 Plan** e use `/spec-wave plan <número>`.
 
 ---
 
@@ -384,7 +436,8 @@ O plano técnico segue o schema do RFC-002 §3.2: **Estratégia Técnica** (com
    ```
 4. Informe: "Label `spec-wave:plan` adicionada. O GitHub Action `generate-plan.yml` irá gerar o `plan.md` automaticamente. Acompanhe em: Actions → Generate Plan."
 5. Após a conclusão (cheque comentários na issue ou aguarde confirmação do usuário), ofereça revisar o plan.md gerado em `docs/features/<slug>/plan.md`.
-6. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
+6. **Para regerar**: re-adicione a label — o Action sobrescreve o `plan.md` (mesma ressalva do spec: edições manuais se perdem, confirme antes).
+7. Próximo passo: validar a Feature — mova para **✅ Ready** e use `/spec-wave ready <número>`.
 
 ---
 
@@ -476,7 +529,7 @@ Para qualquer outro tipo (Spike, Bug, Story, Task, …) o Action **recusa** e co
    ```
 3. Informe: "Decomposição iniciada — Feature gera Stories+Tasks; RFC gera Tasks."
 4. Após a conclusão, as issues filhas aparecerão como comentário na issue pai, junto com o comentário 🔎 da crítica adversarial. 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 geradas 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. 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*.
+5. A issue recebe a label `spec-wave:decomposed` (guard de idempotência): rodar de novo **não** duplica as issues. Para re-decompor, adicione `spec-wave:force` junto com o gatilho — isso **fecha** a decomposição anterior antes de gerar a nova (veja *Guard de idempotência*; confirme com o usuário, é destrutivo).
 
 ---