@spec-wave/cli 0.29.0 → 0.32.0

package/src/templates/skill/core.md

@@ -0,0 +1,584 @@
+---
+name: spec-wave
+description: "Use when the user wants to set up a spec-driven GitHub workflow, create a Feature issue, generate spec.md or plan.md, decompose a Feature into Stories/Tasks, write RFC documentation, or audit and fix a Pull Request. Implements the RFC-001 workflow with GitHub Projects v2, labels, and AI-powered GitHub Actions."
+argument-hint: "[info|setup|update|doctor|preflight|audit|issue|feature|spec|plan|ready|decompose|order|implement|merge|qa|qa-lead|task|story|move|uninstall|rfc|bug|triage|fix-pr] [target]"
+user-invocable: true
+allowed-tools:
+  - Bash(npx @spec-wave/cli@latest *)
+  - Bash(npx @spec-wave/cli *)
+  - Bash(gh issue *)
+  - Bash(gh project *)
+  - Bash(gh repo view *)
+  - Bash(gh auth status)
+  - Bash(gh pr *)
+  - Bash(gh api *)
+  - Bash(git add *)
+  - Bash(git commit *)
+  - Bash(git push *)
+  - Bash(git checkout *)
+  - Read
+  - Edit
+  - Write
+  - Agent
+---
+
+# spec-wave Skill
+
+Este skill guia o usuário pelo fluxo spec-driven definido no RFC-001.
+
+> **Antes de responder a qualquer sub-comando**, leia o arquivo `rfc/rfc-integrate-spec-kit-into-kanban.md` se ele existir no diretório atual, para embasar suas respostas no processo real da equipe.
+
+> **Verifique se esta skill está atualizada:** logo no topo deste arquivo há um banner `spec-wave skill vX.Y.Z` (inserido na instalação). Compare com `npx @spec-wave/cli@latest --version`. Se a CLI for **mais recente** (ou o banner estiver ausente = instalada por versão antiga), esta skill está desatualizada — avise o usuário e sugira `npx @spec-wave/cli@latest update` (detecta e atualiza só o que mudou: skill, `.spec-wave.json` e workflows/labels do repo) ou, para atualizar só a skill, `npx @spec-wave/cli@latest install-skill --force`. A skill é uma cópia estática e **não** acompanha o `npx` sozinha.
+
+---
+
+## Detecção de configuração (faça isto primeiro, sempre)
+
+Antes de qualquer sub-comando, leia o arquivo `.spec-wave.json` na raiz do repositório atual (use o tool Read). Esse arquivo é gravado pelo `npx @spec-wave/cli@latest init` e é a fonte de estado persistente entre sessões.
+
+- **Se existir**, o spec-wave já foi configurado. Use seus campos para contextualizar as respostas, sem perguntar de novo:
+  - `owner`/`repo` → repositório alvo dos comandos `gh`
+  - `project.url` / `project.title` → o GitHub Project a referenciar
+  - `version` → versão da CLI usada no `init` (compare com `npx @spec-wave/cli@latest --version`; se divergir, sugira `npx @spec-wave/cli@latest refresh --config` para atualizar o arquivo, ou re-rodar o `init` para atualizar workflows/labels)
+  - `initializedAt` → quando foi configurado
+  Não rode `/spec-wave setup` de novo a menos que o usuário peça explicitamente.
+- **Se não existir**, o repositório provavelmente ainda não foi configurado. Sugira começar por `/spec-wave setup`.
+
+Exemplo de `.spec-wave.json`:
+```json
+{
+  "version": "0.1.0",
+  "owner": "acme",
+  "repo": "loja",
+  "project": {
+    "title": "loja — Spec Wave",
+    "url": "https://github.com/users/acme/projects/5",
+    "id": "PVT_..."
+  },
+  "initializedAt": "2026-06-18T13:40:00.000Z"
+}
+```
+
+---
+
+## 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 aprovado OU mergeado)
+```
+
+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.** 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 chegue à main por **Pull Request** e seja 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.
+
+**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
+
+```
+📥 Backlog → 🐞 Triagem → 🎯 Priorizado → 📋 Spec → 📋 Plan → ✅ Ready
+→ 🚧 Desenvolvimento → 👀 Code Review
+→ 🧪 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-apply`) | 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 📋 Homologação → 🎉 Done | **Nunca nasce em 📥 Backlog.** |
+| **Task** | **✅ Ready** (criada pelo `decompose-apply`) | 🚧 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** | **🐞 Triagem** (reportado) ou **✅ Ready** (achado em QA/Homologação/review) | ✅ Ready → 🚧 Desenvolvimento → 👀 Code Review → 🧪 QA → 🚀 Deploy → 🎉 Done | Não passa por 🎯 Priorizado, 📋 Spec, 📋 Plan nem 📋 Homologação. Bug **P0** nasce direto em ✅ Ready — a triagem é confirmada depois. |
+| **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 (`move`, `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)
+- `spec-wave:critique` → dispara `critique.yml` → **re-critica o `plan.md` COMO ESTÁ**, sem regerar. É o gatilho de retomada depois de corrigir o plano à mão — `spec-wave:plan` geraria outro do zero, descartando a correção.
+- `spec-wave:ready` → dispara `validate.yml` → valida ambos os arquivos
+- `spec-wave:decompose` → dispara `decompose.yml` → gera (ou **re-critica**) o **rascunho** em `decomposition.md`. **Não cria issue nenhuma.**
+- `spec-wave:decompose-apply` → dispara o mesmo workflow em modo aplicação → cria as Stories e Tasks **a partir do rascunho revisado**
+- `spec-wave:bug` → dispara `generate-bug.yml` → gera `docs/bugs/<slug>/bug.md` (só para issues `[BUG]`)
+- `spec-wave:qa` → dispara `generate-qa-plan.yml` → gera (ou **re-critica COMO ESTÁ**) o plano de QA em `docs/features/<slug>/qa-plan.md`. **Só em Feature** (o plano é por Feature; numa Story o Action aponta a Feature-pai). A **execução** é sempre local: `npx @spec-wave/cli@latest qa <issue>`.
+
+Labels de **estado** (gravadas pelas automações — **não** são gatilhos, não as adicione por conta própria):
+- `spec-wave:decompose-ready` → o rascunho da decomposição passou pela crítica e espera **revisão humana**; aplique `spec-wave:decompose-apply` para criar as issues
+- `spec-wave:critique-failed` → a crítica adversarial apontou contradições **graves**; **bloqueia** o `spec-wave:ready` até ser removida (veja *Crítica adversarial* abaixo)
+- `spec-wave:needs-human` → a crítica reprovou N vezes seguidas (default 3); **para o fluxo** até uma pessoa revisar e remover a label
+- `spec-wave:decomposed` → a Feature/RFC já foi decomposta; o `decompose` pula silenciosamente enquanto ela existir (veja *Guard de idempotência* abaixo)
+- `spec-wave:bug-approved` → o `bug.md` passou na validação das seis seções obrigatórias
+- `spec-wave:qa-ready` → o `qa-plan.md` passou na validação + crítica e espera **revisão humana** — é o pré-requisito de `qa <issue>` (o veredito verde avança a Etapa sozinho, então o portão humano é a revisão do plano). ⚠️ Não confunda com `spec-wave:ready` (gatilho da validação de spec/plan).
+- `spec-wave:qa-approved` → a execução do QA passou. Aplicada na Story (e na Feature, quando todas as Stories passarem).
+
+Label **modificadora** (esta você pode aplicar):
+- `spec-wave:model:<apelido>` → força um modelo específico **naquela execução**, resolvido por `ai.modelAliases` no `.spec-wave.json`. Serve para reprocessar um caso difícil num modelo mais forte sem editar a configuração do repositório inteiro. Duas dessas labels na mesma issue = ambíguo, nenhuma vale.
+
+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`.
+
+A etapa **🧪 QA** tem artefato e comando próprios: a label `spec-wave:qa` gera o `qa-plan.md` (validado + criticado → `spec-wave:qa-ready`), e a **execução é sempre local** — `npx @spec-wave/cli@latest qa <issue>` roda os cenários contra o checkout. Verde: `qa-approved` + Story → 📋 Homologação (Bug → 🚀 Deploy, sem Homologação). Vermelho: **um Bug por cenário reprovado**, já com `bug.md` commitado. Inconclusivo (`blocked` sem `fail`): nada move, nenhum Bug. Veja `/spec-wave qa`.
+
+---
+
+## Referência da CLI (conheça os parâmetros ANTES de executar)
+
+Esta skill é um **wrapper** da CLI `@spec-wave/cli`, sempre invocada como `npx @spec-wave/cli@latest <comando>`. Regra de ouro: **nunca rode um comando sem os parâmetros que ele aceita** esperando que ele pergunte — colete os valores com o usuário e passe via flags. Em especial, **`init` sem `--repo` abre um wizard interativo (@clack/prompts) que a skill NÃO consegue dirigir** — sempre passe `--repo`.
+
+### `@spec-wave/cli init` — configura o repositório
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório alvo. **Passe SEMPRE** para evitar o wizard interativo. |
+| `--project-title <title>` | string | Nome do GitHub Project. Padrão: `<repo> — Spec Wave`. |
+| `--skip-project` | flag | Pula a criação do Project (use ao re-rodar se já existe). |
+| `--skip-labels` | flag | Pula a criação das labels. |
+| `--skip-files` | flag | Pula a criação dos workflows + issue templates. |
+| `--dry-run` | flag | Simula a configuração sem alterar nada. |
+
+### `@spec-wave/cli issue` — cria um work item tipado, opcionalmente como sub-issue, e adiciona ao board
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--title <title>` | string (obrigatório) | Título, **sem** o prefixo de tipo (a CLI adiciona, ex.: `[STORY]`). |
+| `--type <type>` | string | `initiative`, `epic`, `feature`, `story`, `task`, `bug`, `spike` ou `rfc`. Default: `feature`. |
+| `--parent <n>` | string | Número da issue pai — cria como **sub-issue** dela (relação nativa do GitHub). |
+| `--body <text>` | string | Descrição. |
+| `--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**, **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).
+
+### `@spec-wave/cli feature` — atalho de `issue --type feature`
+Mesmas flags do `issue` (exceto `--type`, fixo em `feature`). Mantido para o fluxo do RFC-001.
+
+### `@spec-wave/cli uninstall` — remove a configuração (mantém o Project)
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--repo <owner/repo>` | string | Repositório (default: lê do `.spec-wave.json`). |
+| `--skip-labels` | flag | Não remove as labels. |
+| `--skip-files` | flag | Não remove os arquivos `.github`. |
+| `--keep-config` | flag | Mantém o `.spec-wave.json` local. |
+| `--dry-run` | flag | Mostra o que seria removido sem alterar nada. |
+| `--yes` | flag | Não pede confirmação. |
+
+> Remove labels + arquivos `.github` + `.spec-wave.json`. **NUNCA apaga o GitHub Project** (preserva o histórico do board) — o usuário deve excluí-lo manualmente se quiser.
+
+### `@spec-wave/cli info` — status de configuração do repo atual
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--json` | flag | Saída JSON (`{"initialized":bool, ..., "skill":{...}}`) para parsing programático. |
+
+> Além do `.spec-wave.json`, valida a **skill instalada**: para cada agente detectado no diretório, compara a cópia instalada com a versão empacotada na CLI (uma cópia **global** atualizada também conta). No JSON, o campo `skill` traz `{agentsDetected, installNeeded, pending:[{agent, reason, path}]}` — `installNeeded: true` significa que o usuário precisa rodar `install-skill` (ou `update`).
+
+### `@spec-wave/cli refresh` — atualiza o `.spec-wave.json` local
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--config` | flag | Re-consulta o GitHub Project e reescreve o `.spec-wave.json` (IDs do campo Etapa, opções, number, versão da CLI). |
+
+> Use quando o `.spec-wave.json` estiver desatualizado: repos inicializados por uma versão antiga (sem `etapaFieldId`/`stageOptions`), Project renomeado, ou versão da CLI divergente. Escreve no arquivo **local** — faça commit depois.
+
+### `@spec-wave/cli update` — atualiza tudo que ficou para trás (só o que mudou)
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--global` | flag | Verifica a skill no escopo do usuário (padrão: projeto). |
+| `--skip-skill` / `--skip-config` / `--skip-repo` | flag | Pula a categoria correspondente. |
+| `--branch [nome]` | flag/string | Envia os arquivos do repo como **Pull Request** numa branch, em **um único commit**, em vez de commitar direto na branch default. Sem valor, usa `spec-wave/update-v<versão>`. |
+| `--config-in-pr` / `--no-config-in-pr` | flag | Força incluir/excluir o `.spec-wave.json` do PR (o default decide sozinho — veja abaixo). |
+| `--skill-in-pr` / `--no-skill-in-pr` | flag | Força incluir/excluir a **skill dos agentes** do PR (o default decide sozinho — veja abaixo). |
+| `--dry-run` | flag | Mostra o que seria atualizado sem alterar nada. |
+| `--yes` | flag | Aplica sem pedir confirmação. |
+
+> Detecta e atualiza **somente o que divergiu** da versão atual da CLI: a **skill** instalada (por agente), o **`.spec-wave.json`** local (se versão/formato divergir) e os **workflows/labels** do repo (compara com os templates empacotados). Interativo por padrão (mostra o plano e confirma). É o atalho recomendado após atualizar a CLI.
+
+> **`--branch` (modo Pull Request).** Sem a flag, os arquivos do repo vão em **commits diretos na branch default** — o que falha no meio da execução em repositório com proteção de branch, deixando parte aplicada, e contorna a revisão. Com a flag, todos os arquivos vão em **um commit atômico** numa branch nova e um PR é aberto: se algo falhar antes da criação da branch, **nada** é alterado no repositório. É **idempotente** — rodar duas vezes não gera um segundo commit nem um segundo PR.
+>
+> As **labels** nunca entram no PR: são metadado do repositório, não há como versioná-las — já valem na base, com ou sem o merge. O corpo do PR diz isso a quem revisa.
+>
+> A **skill** e o **`.spec-wave.json`** seguem a mesma regra, e ela é **verificada, não presumida**: o comando pergunta à base se aquele arquivo já é versionado. Se for (repos que commitam `.claude/skills/spec-wave/SKILL.md`, `.agents/skills/`, `AGENTS.md`, `.cursor/rules/…`), a atualização entra no PR junto com os workflows; se não for, fica só na máquina local. Passar a versionar (ou deixar de versionar) é decisão do projeto — use `--skill-in-pr` / `--no-skill-in-pr` para forçar.
+>
+> ⚠️ O modo PR exige **`pull_requests: write`** além de `contents: write` (ou o escopo `repo` num PAT classic). Sem essa permissão, a branch é criada e o PR falha — a mensagem oferece a URL de `compare` para abrir à mão.
+
+### `@spec-wave/cli generate-plan` · `generate-spec` · `validate` · `decompose`
+| Flag | Tipo | Descrição |
+|------|------|-----------|
+| `--issue-number <n>` | string (obrigatório) | Número da issue no GitHub. |
+| `--apply` | flag (só `decompose`) | Cria as issues a partir do `decomposition.md` revisado. **Sem** a flag, o `decompose` apenas gera/critica o rascunho e não cria nada. |
+
+> ⚠️ 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).
+>
+> **Por tipo de issue:**
+> - `generate-spec` / `generate-plan` → **apenas Features**. Para **Spike, RFC e Bug** a geração é **pulada** (o Action remove a label e comenta) — esses tipos não usam spec/plan.
+> - `decompose` → **Feature** (gera Stories + Tasks) e **RFC** (gera **Tasks** diretamente, sem Stories). Para outros tipos, o Action recusa.
+
+### `@spec-wave/cli implement` — aciona o spec-kit para uma Feature, Story ou Task (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<issue>` | string (obrigatório) | Número da issue (Feature, Story ou Task), ex.: `12` ou `#12`. Argumento posicional. |
+| `--feature-dir <path>` | string | Caminho `docs/features/<slug>` para anexar `spec.md`/`plan.md` como contexto (sobrescreve a resolução automática). |
+| `--dry-run` | flag | Monta o contexto e imprime o comando do spec-kit **sem executar** e **sem escrever nada no GitHub** (não move cards, não adiciona itens ao Project). |
+
+> 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`/escalada da crítica/apelidos de modelo/teto de saída + secrets do Actions), **higiene do board e das labels** (colunas fora do fluxo canônico, labels `spec-wave:*` descontinuadas ou ausentes), **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 os workflows (presença + **versão da CLI fixada**, não `@latest`).
+
+> 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.
+
+### `@spec-wave/cli order <feature>` — ordem de execução das Stories (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<feature>` | string (opcional) | Número da issue da **Feature**, ex.: `12` ou `#12`. Omitido: o mapa de todas as Features com trabalho. |
+| `--milestone <ref>` | string | No mapa sem argumento: só as Features da milestone (número ou título). |
+| `--json` | boolean | Saída JSON **estável** (sem ANSI) — o formato para agentes/scripts consumirem a ordem. |
+| `--remote` | boolean | Une também o blocked_by da API (1 chamada por Story) — pega arestas criadas SÓ pela UI. |
+| `--refresh` | boolean | Ignora o cache local e reconsulta a API. |
+| `--sync` | boolean | Grava as dependências VIVAS (body + blocked_by) de volta no `decomposition.md` e regenera o `dependency-map.json`, com commit local escopado. |
+
+> **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, com a Etapa atual de cada uma no board. As **arestas** vêm de fontes LOCAIS — `dependency-map.json` (escrito pelo `decompose --apply`), `decomposition.md` aplicado e linha `Depende de: #N` do corpo — **zero chamada de API por Story**; `--remote` acrescenta o *blocked by* nativo. A **Etapa** vem de um snapshot único do board, cacheado por `cache.ttlSec` do `.spec-wave.json` (default 600s; env `SPEC_WAVE_CACHE_TTL`; `0` desliga), com a idade impressa quando servido do cache. 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`), sobre **dependências fora de ordem** (Story já em Desenvolvimento+ dependendo de outra que não está Done) e sobre **milestone divergente** (Story sem milestone ou em milestone diferente do da Feature — órfã de toda visão de release; sem milestone na Feature, nada é comparado). Use antes de escolher qual Story implementar, e logo após o `decompose --apply` como detector do pós-apply.
+
+### `@spec-wave/cli preflight --milestone <nome>` — confere tudo ANTES de gerar as specs (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a inventariar. |
+| `--json` | boolean | O relatório em JSON, para ramificar. |
+
+> Um comando reporta: token utilizável, modo de execução (config × variável do repositório), publicação por PR, e as Features da milestone com o **estado do `spec.md` de cada uma** (na base, no disco, em PR aberto, em branch sem PR, a gerar). Existe porque **cada geração paga um modelo**: um erro de configuração descoberto na sétima Feature custa sete gerações — e regenerar um documento que já vive num PR descarta a revisão em curso. Sai com código 1 quando há bloqueio. Rode SEMPRE antes de uma rodada de specs por milestone.
+
+### `@spec-wave/cli audit --milestone <nome>` — cruza as specs da milestone como CONJUNTO (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `--milestone <nome>` | string (obrigatório) | Título da milestone a auditar. |
+| `--critique` | boolean | Roda também a **crítica adversarial de conjunto** — UMA chamada de modelo sobre todas as specs juntas, procurando contradição ENTRE documentos. |
+| `--json` | boolean | O relatório em JSON (com `critica.markdown` pronto para comentar nas issues). |
+
+> A crítica normal audita cada documento contra os insumos da **mesma** Feature; este comando olha o que só existe **no par**: dependência circular entre Features, bloqueante em milestone **posterior** à de quem depende dela, referência a issue inexistente (materiais — exit 1), dependência que nenhuma Feature cria ("recurso sem dono"), sobreposição do slug com código existente e decisão de modelagem com `criada_por: SEM DONO` no `tech_context.yml` (avisos heurísticos — **confira antes de reportar**). Rode depois que as specs existirem (PR aberto também conta), antes de gerar os planos. Achado material é decisão de PO: comente nas issues **dos dois lados**.
+
+### `@spec-wave/cli merge <feature>` — mergeia os PRs empilhados das Stories (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<feature>` | string (obrigatório) | Número da issue da **Feature**, ex.: `12` ou `#12`. |
+| `--yes` | boolean | Executa os merges. **Sem ela, só mostra o plano** (fila na ordem, retargets, avisos). |
+| `--keep-branches` | boolean | Não apaga as branches das Stories após o merge. |
+
+> O `implement` empilha os PRs (cada um baseado no anterior) e o merge da pilha é **ordem-dependente**: `--delete-branch` no primeiro PR fecha o segundo. Este comando encapsula a sequência segura — para cada PR na ordem topológica das Stories: reaponta a base para a default, mergeia com **merge commit**, atualiza o board (**merge move até 🧪 QA**) e **só no fim** apaga as branches. **PR em rascunho bloqueia o plano inteiro** (marcar pronto é a revisão humana — o comando não pula isso). Rodar de novo **retoma**: PR mergeado sai do plano. Use após a revisão, em vez de mergear à mão com `gh`.
+
+### `@spec-wave/cli qa <issue>` — executa o plano de QA localmente (e `qa --pr-number <n>` no Action)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<issue>` | string | Número da **Feature** (todos os cenários das Stories ainda sem `qa-approved`), **Story** (os cenários dela) ou **Bug** (a seção `Teste de Regressão` do `bug.md`). |
+| `--only <n[,m]>` | string | Só o(s) cenário(s) indicado(s) — número **posicional** no plano. O restante herda o veredito do último relatório. |
+| `--severity <p>` | string | Severidade dos Bugs abertos na reprova: `P0`–`P3` (default: `qa.defaultBugPriority` ou `P2`). |
+| `--dry-run` | boolean | Monta o contexto e imprime cenários + comando. **Zero escrita no GitHub.** |
+| `--pr-number <n>` | string | Modo Action (mutuamente exclusivo com `<issue>`): move a Feature/Bug do PR aprovado/mergeado para 🧪 QA. |
+
+> **Pré-requisitos:** Feature dona do plano com `spec-wave:qa-ready` (portão humano — D-QA4), item já em 🧪 QA (o comando **não promove**; Etapa posterior = informa e sai 0), executor em `qa.command` no `.spec-wave.json` (ou `SPEC_WAVE_QA_CMD`) — sem ele, só monta o contexto. **Sempre `--dry-run` primeiro.** Desfechos: verde → `qa-approved` + Story para 📋 Homologação (Bug → 🚀 Deploy; Feature quando TODAS as Stories liberarem; **Bug filho aberto segura a Story mesmo verde**); vermelho → 1 Bug por cenário reprovado (filho da Story, ✅ Ready, `bug.md` determinístico commitado — exceção documentada à regra do `spec-wave:bug`), exit 1; `blocked` sem `fail` → inconclusivo: nada move, nenhum Bug, exit 1. Re-teste após o fix: `qa <story> --only <cenário>` (não duplica Bug — comenta no existente).
+
+### `@spec-wave/cli qa-lead <plan|run|report> <milestone>` — orquestra o QA de uma TRILHA (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<acao>` | string (obrigatório) | `plan` (prepara os planos e PARA no portão humano), `run` (executa o ciclo em containers paralelos) ou `report` (reimprime um ciclo já gravado). |
+| `<milestone>` | string (obrigatório) | Milestone da trilha, por **número ou título** — trilha = milestone (D-QAL1). |
+| `--watch` | boolean | No `plan`: acompanha os planos disparados até resolverem (teto `qa.lead.planWaitTimeoutMin`; estourar relata as pendentes e sai 1). |
+| `--only <features>` | string | No `run`: sub-trilha explícita, ex.: `--only 318,320` (decisão humana declarada, não relaxamento do portão). |
+| `--max-cycles <n>` | string | No `run`: teto de ciclos (default: `qa.lead.maxCycles`, 3). |
+| `--cycle <n>` | string | No `report`: qual ciclo imprimir (default: o último). |
+| `--dry-run` | boolean | Classifica/planeja e imprime — **nenhuma label, zero container, zero escrita**. |
+
+> Duas fases separadas (D-QAL2): o `plan` aplica `spec-wave:qa` nas Features sem plano e **para** — o humano revisa os `qa-plan.md`; o `run` só inicia com a trilha inteira em `qa-ready` (recusa listando as pendentes). O `run` faz preflight global, despacha até `qa.lead.maxParallel` containers (um ambiente isolado por Feature — `qa.lead.container.image` obrigatória), coleta os comentários de veredito e grava `docs/qa/<slug-milestone>/cycle-<n>/{report.md,report.json}` + um **bloco delimitado** na descrição do milestone (substituído a cada ciclo, preservando as Release Notes). Ciclo N+1 só se um Bug fechou ou um bloqueio caiu (D-QAL7); teto de 3 ciclos. O Lead **não** aplica label de estado, **não** move card e **não** abre issue — toda mutação de board é do `qa` dentro dos containers.
+
+### `@spec-wave/cli task <start|done> <n>` — transições de Task no board (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<action>` | string (obrigatório) | `start` (Etapa 🚧 Desenvolvimento + Status In Progress) ou `done` (Etapa 🎉 Done + Status Done). |
+| `<n>` | string (obrigatório) | Número da issue da **Task**, ex.: `12` ou `#12`. |
+
+> **Prefira este comando a mexer no board via GraphQL/`gh` manual** — ele embute as regras do fluxo: a **Etapa nunca retrocede** (se já estiver adiante, só o Status é ajustado) e **uma única Task "In Progress" por vez** dentro da mesma Story (`start` recusa, apontando a Task em andamento, se houver outra irmã em In Progress).
+
+### `@spec-wave/cli story review <n>` — move a Story para Code Review (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<action>` | string (obrigatório) | `review` (única ação hoje). |
+| `<n>` | string (obrigatório) | Número da issue da **Story**, ex.: `12` ou `#12`. |
+
+> Avança a Story para a Etapa **👀 Code Review** com Status **Todo** (o Status reinicia ao trocar de etapa). Mesma regra do `task`: a **Etapa nunca retrocede** — se a Story já estiver em Code Review ou adiante, o comando apenas informa a Etapa atual. Use no fim do `implement` de uma Story, em vez de mutações GraphQL manuais.
+
+### `@spec-wave/cli move <n> <etapa>` — move QUALQUER item do board (comando LOCAL)
+| Flag/Arg | Tipo | Descrição |
+|----------|------|-----------|
+| `<n>` | string (obrigatório) | Número da issue, ex.: `8` ou `#8`. |
+| `<etapa>` | string (obrigatório) | Etapa de destino, com ou sem emoji, sem acento e em qualquer caixa: `"code review"`, `"Homologação"`, `"🎉 Done"`. |
+| `--status <valor>` | string | Valor do campo Status no destino: `Todo`, `In Progress` ou `Done` (default: `Todo`). |
+
+> Serve para **Feature, Story, Task, Bug e RFC** — é o comando a usar quando `story review` e `task start|done` não cobrem o movimento desejado (ex.: mover uma **Feature** para Homologação). Embute as mesmas guardas: a **Etapa nunca retrocede** (se o item já estiver adiante, o comando informa a Etapa atual e não faz nada) e **Spike** é recusado (sua Etapa é movida à mão). Um nome de etapa ambíguo (`"p"` casa com Priorizado e Plan) é recusado listando as candidatas.
+>
+> **Prefira `move` a `gh api graphql` manual.** Não existe escape hatch para retroceder — isso é a regra do fluxo, não uma limitação.
+
+---
+
+## Crítica adversarial, decomposição em duas etapas e dependências
+
+### Crítica adversarial (comentário 🔎)
+
+Depois do `generate-plan` e **antes** de qualquer issue ser criada no `decompose`, um segundo agente de IA audita o artefato procurando contradições com a spec, o plan e o `tech_context`. O resultado vira um comentário **🔎 Crítica adversarial (spec-wave)** na issue, com cabeçalho informando a **tentativa** e o **modelo** usados.
+
+A saída da crítica é **estruturada e validada por schema**: `severity` só aceita `grave` ou `menor`, e um payload fora do contrato **falha alto** em vez de virar um finding menor com JSON cru dentro. Se a crítica não conclui, ela **não** é registrada como aprovada.
+
+**A remediação depende de ONDE a crítica reprovou — são superfícies diferentes:**
+
+| Reprovou depois de | O que corrigir | Como retomar |
+|--------------------|----------------|--------------|
+| `generate-plan` | `plan.md` (ou a `spec.md` que o embasa) | corrija → remova `spec-wave:critique-failed` → reaplique **`spec-wave:critique`** (re-critica o arquivo como está). `spec-wave:ready` apenas valida, **não** re-critica; e `spec-wave:plan` **regera** o plano, descartando a correção. |
+| `decompose` (rascunho) | **`decomposition.md`** — os achados citam **`Story N`** e **`Task N.M`**, que são os títulos desse arquivo | edite o arquivo **no Pull Request** → remova `spec-wave:critique-failed` → reaplique `spec-wave:decompose` (ele **critica o arquivo como está**, sem regerar) |
+
+> ⚠️ No contexto do `decompose`, os achados são sobre as **Stories propostas**, não sobre o `plan.md`. Corrigir o plan não influencia o rascunho já gravado — edite o `decomposition.md` diretamente. Foi exatamente essa confusão que fazia o ciclo não convergir.
+
+- Findings **graves** no `decompose` → **nenhuma Story/Task é criada** e o Action **falha (exit 1)**, com a label `spec-wave:critique-failed`. Um pipeline bloqueado nunca fica verde.
+- Findings **menores** não bloqueiam — trate-os como revisão de qualidade.
+- **Escalada:** na tentativa 2 a crítica roda em `ai.escalationModel` (se configurado). Ao atingir `ai.maxCritiqueAttempts` (default 3), o fluxo aplica **`spec-wave:needs-human`**, comenta e **para** — sem chamar a IA de novo. Para retomar: corrija os documentos e remova **as duas** labels (`spec-wave:needs-human` e `spec-wave:critique-failed`).
+- Uma crítica **limpa** remove a `spec-wave:critique-failed` automaticamente e zera o contador de tentativas.
+
+### Decomposição em duas etapas (`decomposition.md`)
+
+O `decompose` **não cria issues direto**. São dois passos, com um artefato revisável no meio:
+
+```
+spec-wave:decompose
+  ├─ decomposition.md ausente  → gera via IA → abre Pull Request → critica
+  └─ decomposition.md presente → critica o arquivo COMO ESTÁ (preserva suas edições)
+       ├─ grave  → +critique-failed, comentário citando Story N / Task N.M, exit 1
+       └─ limpo  → +decompose-ready, comentário "revise e aplique"
+
+spec-wave:decompose-apply
+  └─ lê decomposition.md → cria Stories/Tasks → board → +decomposed
+     (sem nova crítica: aplicar a label É a aprovação humana)
+```
+
+O arquivo fica em **`docs/features/<slug>/decomposition.md`** (Feature) ou **`docs/rfcs/<slug>/decomposition.md`** (RFC). Formato:
+
+```markdown
+# Decomposição — [FEATURE] Cadastro de Pedidos
+<!-- spec-wave:decomposition v1 issue=360 kind=stories -->
+
+## Story 1 — visualizar meus pedidos
+
+**User story:** Como cliente, quero visualizar meus pedidos, para acompanhar entregas
+**Depende de:** —
+
+Descrição complementar (contexto, critérios de aceite).
+
+### Task 1.1 — criar endpoint GET /pedidos
+
+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:**` 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:** feche o Pull Request e apague a branch `spec-wave/<n>-decompose` (ou apague o arquivo, se já mergeado) e reaplique `spec-wave:decompose`.
+
+### Guard de idempotência do decompose (`spec-wave:decomposed`)
+
+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). O Action grava a label ao **aplicar** a decomposição. Os workflows ainda usam `concurrency` por issue para serializar runs simultâneos.
+
+A `spec-wave:decompose-ready` **não** entra nesse guard: é estado de rascunho pendente, não de decomposição feita.
+
+**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), apague o `decomposition.md` se quiser um rascunho novo, e re-adicione `spec-wave:decompose`.
+
+### Dependências entre Stories (`Depende de: #N`)
+
+O `decompose` grava nas Stories geradas uma linha **`Depende de: #N, #M`** no corpo e cria a relação nativa *blocked by* do GitHub. Essas dependências alimentam:
+- `spec-wave order <feature>` → ordem topológica de execução;
+- `spec-wave implement <feature>` → Stories pendentes implementadas **nessa ordem**; **ciclo de dependências → erro** (corrija as linhas `Depende de:`); dependências **externas** abertas viram aviso no contexto;
+- `spec-wave implement <n>` (Story/Task) → **aviso** no contexto quando uma dependência ainda não está concluída (confirme com o usuário antes de implementar fora de ordem).
+
+Não apague a linha `Depende de:` ao editar o corpo de uma Story; para mudar dependências, edite a linha (e/ou a relação *blocked by*).
+
+### Modelo de IA por ação (`ai.models` no `.spec-wave.json`)
+
+Cada ação de IA (`spec`, `plan`, `decompose`, `critique`) pode usar um modelo próprio, com fallback em `ai.model` e depois no default do provider:
+
+```json
+{
+  "ai": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-6",
+    "models": {
+      "plan": "claude-opus-4-1",
+      "critique": "claude-opus-4-1"
+    },
+    "escalationModel": "claude-opus-5",
+    "maxCritiqueAttempts": 3,
+    "modelAliases": {
+      "opus": "claude-opus-5",
+      "haiku": "claude-haiku-4-5"
+    }
+  }
+}
+```
+
+- `escalationModel` → modelo usado a partir da **segunda** tentativa da crítica.
+- `maxCritiqueAttempts` → quantas reprovas seguidas antes de exigir revisão humana (`spec-wave:needs-human`).
+- `modelAliases` → apelidos para a label **`spec-wave:model:<apelido>`**.
+
+**Precedência do modelo:** `SPEC_WAVE_MODEL` (env) → label `spec-wave:model:<apelido>` → escalada automática da crítica → `ai.models[ação]` → `ai.model` → default do provider.
+
+Edite o bloco `ai` no `.spec-wave.json` (e commite) — o `doctor` mostra o provider, o modelo, os apelidos, a escalada e os overrides resolvidos.
+
+### Override de modelo numa execução (`spec-wave:model:<apelido>`)
+
+Para reprocessar **uma issue difícil** num modelo mais forte sem editar a configuração do repositório inteiro:
+
+```bash
+# 1. Garanta o apelido em ai.modelAliases (uma vez, commitado)
+# 2. Aplique a label na issue e redispare o gatilho
+gh issue edit 360 --add-label "spec-wave:model:opus"
+gh issue edit 360 --add-label "spec-wave:decompose"
+```
+
+A label vale só para as execuções daquela issue e **vence a escalada automática** (é decisão humana explícita). Apelido desconhecido é ignorado com aviso; duas labels dessas na mesma issue = ambíguo, nenhuma vale.
+
+### 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
+
+{{SUBCOMANDOS}}
+
+---
+
+## Tech Context (`.github/config/tech_context.yml`)
+
+Fonte de verdade estática da stack do sistema (RFC-002 §4). O `generate-plan` lê este arquivo para embasar o plano técnico e usar **APENAS** as tecnologias/serviços nele declarados — sem ele, o plano fica genérico e pode inventar APIs inexistentes. O `npx @spec-wave/cli@latest init` gera um **scaffold de exemplo** que **deve ser adaptado** à stack real. Use este fluxo quando o arquivo estiver ausente ou desatualizado.
+
+**Como ajudar a criar (quando não existir):**
+
+1. **Confirme a ausência:** tente `Read .github/config/tech_context.yml`. Se já existir, apenas confirme com o usuário se reflete a stack atual e pule para o fim.
+2. **Detecte a stack** lendo os arquivos do repositório (use Read; não invente):
+   - `package.json` → backend/frontend e libs (ex.: `@nestjs/core`, `next`, `react`, `@prisma/client`, `express`).
+   - `pom.xml` / `build.gradle` (Java), `requirements.txt` / `pyproject.toml` (Python), `go.mod` (Go).
+   - `prisma/schema.prisma` ou pasta `migrations/` → tabelas e colunas para `database_schemas`.
+   - `Dockerfile` / `docker-compose.yml` / charts Helm → `infra`.
+   - Procure papéis/roles (enum de RBAC) no código para `security.rbac_roles`.
+3. **Rascunhe** o YAML seguindo EXATAMENTE este schema (preencha só o que conseguir confirmar; deixe `# TODO` no que faltar — não invente):
+   ```yaml
+   system_info:
+     name: "<nome do sistema>"
+     stack:
+       backend: "<ex.: Node.js (NestJS v11)>"
+       frontend: "<ex.: Next.js 16 (React 19)>"
+       database: "<ex.: PostgreSQL (Prisma 5)>"
+       infra: "<ex.: Docker / Kubernetes>"
+     architecture: "<ex.: Monorepo Nx / Microservices>"
+   security:
+     auth_protocol: "<ex.: JWT>"
+     rbac_roles: ["ADMIN", "..."]
+   database_schemas:
+     - table: "<tabela>"
+       columns: "<col1, col2, ...>"
+   existing_services:
+     - name: "<serviço>"
+       endpoint: "<caminho>"
+       auth: "<ex.: JWT, mTLS>"
+   internal_libraries:
+     - "<lib interna>"
+   ```
+4. **Mostre o rascunho ao usuário e peça confirmação/ajustes** antes de gravar (ele conhece serviços internos e roles que o código pode não revelar).
+5. **Grave** com Write em `.github/config/tech_context.yml`.
+6. **Oriente a commitar e pushar** antes de seguir (o Action lê do repo). Sugira ao usuário rodar, via prefixo `!`:
+   ```bash
+   !git add .github/config/tech_context.yml && git commit -m "chore: tech_context.yml [spec-wave]" && git push
+   ```
+
+**Desvios pontuais:** para uma Feature específica usar algo fora do padrão (ex.: "usar DynamoDB só aqui"), oriente a adicionar uma seção `## Tech Override` no corpo da issue, com um bloco YAML que será mesclado (deep-merge) sobre o `tech_context.yml`:
+
+````markdown
+## Tech Override
+```yaml
+system_info:
+  stack:
+    database: "DynamoDB"
+```
+````
+
+---
+
+## Estrutura de arquivos gerados
+
+```
+docs/
+  features/
+    <slug-da-feature>/
+      spec.md            ← gerado quando spec-wave:spec é adicionado (1º)
+      plan.md            ← gerado quando spec-wave:plan é adicionado (2º, usa a spec)
+      decomposition.md   ← rascunho gerado quando spec-wave:decompose é adicionado (3º).
+                            REVISÁVEL e EDITÁVEL à mão; as issues só nascem com
+                            spec-wave:decompose-apply
+      qa-plan.md         ← plano de QA gerado quando spec-wave:qa é adicionado (4º,
+                            com a Feature já em 🧪 QA). Um cenário por critério de
+                            aceite, seções "## Cenário N — Story #X"; executado
+                            localmente por `spec-wave qa <issue>`
+      dependency-map.json ← grafo de dependências das Stories PRÉ-COMPUTADO,
+                            escrito pelo decompose --apply e atualizado por
+                            `order --sync`. É o que deixa order/implement/merge
+                            consultarem a ordem sem pagar a API por Story
+  rfcs/
+    <slug-do-rfc>/
+      decomposition.md   ← mesmo papel, com "## Task N" (RFC não usa spec/plan)
+  qa/
+    <slug-da-milestone>/
+      cycle-<n>/
+        report.md        ← relatório do ciclo N da trilha de QA (qa-lead run)
+        report.json      ← o mesmo ciclo, no schema protocol/qa-trail-report.v1.json
+```
+
+O slug é gerado a partir do título da issue: `[FEATURE] Cadastro de Pedidos com PIX` → `cadastro-de-pedidos-com-pix`
+
+> ⚠️ O slug vem do **título**. Renomear a Feature entre o rascunho e o apply muda o diretório e o `decomposition.md` antigo fica órfão — o apply reclama que não encontrou o rascunho.