feat: add Portuguese documentation and update language links

2026-03-23 15:38:17 -04:00
parent 5733700d7d
commit 7709059f42
18 changed files with 1477 additions and 5 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,6 +2,8 @@

 Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-prompting, context engineering, and spec-driven development system for AI coding agents.

+Language versions: [English](README.md) · [Português (pt-BR)](pt-BR/README.md) · [日本語](ja-JP/README.md) · [简体中文](zh-CN/README.md)
+
 ## Documentation Index

 | Document | Audience | Description |
--- a/docs/pt-BR/AGENTS.md
+++ b/docs/pt-BR/AGENTS.md
@@ -0,0 +1,64 @@
+# Referência de Agentes do GSD
+
+Este documento descreve os papéis dos agentes especializados no ecossistema GSD.  
+Para a listagem completa com regras detalhadas, consulte [AGENTS.md em inglês](../AGENTS.md).
+
+---
+
+## Visão geral
+
+O GSD usa um **orquestrador leve** para coordenar subagentes especializados por etapa:
+
+- pesquisa
+- planejamento
+- execução
+- validação
+- depuração
+
+Cada agente tem responsabilidade clara, entradas/saídas definidas e contexto de trabalho limitado.
+
+## Famílias de agentes
+
+### Pesquisa
+
+- **Project/Phase researchers**: investigam stack, arquitetura, padrões e riscos
+- **Research synthesizer**: consolida descobertas em artefatos utilizáveis
+
+### Planejamento
+
+- **Planner**: transforma requisitos em planos atômicos
+- **Plan checker**: valida consistência, escopo, verificabilidade e dependências
+
+### Execução
+
+- **Executor**: implementa tarefas do plano com contexto fresco
+- **Integration checker**: verifica se as partes integram corretamente
+
+### Verificação
+
+- **Verifier**: compara entrega contra objetivos da fase
+- **UAT support**: auxilia no processo de validação manual guiada
+
+### Diagnóstico
+
+- **Debugger**: identifica causa-raiz quando há falhas
+- **Forensics**: investiga inconsistências de estado/artefatos/histórico
+
+## Padrões operacionais
+
+- **Contexto isolado por tarefa**: evita poluição acumulada
+- **Commits atômicos**: um commit por unidade de trabalho
+- **Execução em ondas**: paralelo quando possível, sequencial quando necessário
+- **Loop de revisão**: planejamento e validação iteram até critérios mínimos
+
+## Boas práticas
+
+- Prefira tarefas pequenas e verificáveis
+- Trave decisões de implementação no `CONTEXT.md`
+- Use `assumptions mode` quando já houver padrão consolidado no código
+- Ajuste perfil de modelo conforme custo x qualidade
+
+---
+
+> [!NOTE]
+> Esta versão em Português é uma referência operacional. Se você estiver contribuindo com o núcleo do framework ou alterando comportamento de agentes, consulte sempre o documento em inglês para detalhes normativos.
--- a/docs/pt-BR/ARCHITECTURE.md
+++ b/docs/pt-BR/ARCHITECTURE.md
@@ -0,0 +1,77 @@
+# Arquitetura do GSD
+
+Visão arquitetural do Get Shit Done (GSD) em Português.  
+Para detalhes de implementação linha a linha, consulte [ARCHITECTURE.md em inglês](../ARCHITECTURE.md).
+
+---
+
+## Princípios
+
+- **Orquestração leve** no contexto principal
+- **Trabalho pesado em subagentes**
+- **Artefatos persistentes** em `.planning/`
+- **Validação contínua** por fase
+- **Rastreabilidade** por commits atômicos
+
+## Componentes centrais
+
+1. **Camada de comando**  
+   Recebe entrada do usuário (`/gsd:*`) e roteia fluxo.
+
+2. **Camada de orquestração**  
+   Coordena pesquisadores, planejadores, executores e verificadores.
+
+3. **Camada de artefatos**  
+   Mantém `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, planos e sumários.
+
+4. **Camada de execução**  
+   Roda tarefas em ondas, respeitando dependências.
+
+5. **Camada de validação**  
+   Compara entrega contra objetivos, testes e critérios de fase.
+
+## Fluxo arquitetural (alto nível)
+
+```text
+Entrada (/gsd:comando)
+  -> Orquestrador
+  -> Subagentes especializados
+  -> Artefatos em .planning/
+  -> Execução em ondas
+  -> Verificação/UAT
+  -> Atualização de estado + commits
+```
+
+## Estado e persistência
+
+- `STATE.md`: memória operacional da jornada
+- `ROADMAP.md`: visão de progresso por fase
+- `SUMMARY.md`: histórico de decisões e resultados por tarefa
+- `VALIDATION.md` (quando aplicável): contrato de feedback automatizado
+
+## Paralelismo
+
+- Planos independentes: mesma onda (execução paralela)
+- Planos dependentes: ondas posteriores (execução sequencial)
+- Conflitos de arquivo: serialização controlada
+
+## Segurança
+
+- validação de caminhos de arquivo
+- detecção de prompt injection
+- hooks de guarda para escrita/edição sensível
+- scanner CI para padrões de risco
+
+## Extensibilidade
+
+GSD suporta evolução por:
+
+- novos comandos
+- novos tipos de agente
+- novos artefatos por fase
+- novos gates de qualidade/segurança
+
+---
+
+> [!NOTE]
+> Esta versão foi criada para consulta de arquitetura em Português. A especificação canônica e completa continua no documento em inglês.
--- a/docs/pt-BR/CLI-TOOLS.md
+++ b/docs/pt-BR/CLI-TOOLS.md
@@ -0,0 +1,72 @@
+# Referência de Ferramentas CLI
+
+Resumo em Português das ferramentas CLI do GSD.  
+Para API completa (assinaturas, argumentos e comportamento detalhado), consulte [CLI-TOOLS.md em inglês](../CLI-TOOLS.md).
+
+---
+
+## Objetivo
+
+As ferramentas CLI permitem que comandos e agentes do GSD executem ações padronizadas de:
+
+- leitura e escrita de artefatos
+- gerenciamento de fases e roadmap
+- execução e validação de planos
+- integração com git e automação
+
+## Áreas funcionais
+
+### Projeto e estado
+
+- inicialização de artefatos (`PROJECT`, `REQUIREMENTS`, `ROADMAP`, `STATE`)
+- atualização de estado por fase
+- controle de milestones
+
+### Planejamento
+
+- criação de planos atômicos
+- validação pré-execução
+- consolidação de pesquisa
+
+### Execução
+
+- despacho de tarefas por onda
+- persistência de sumários
+- checkpoints de progresso
+
+### Verificação
+
+- comparação de saída com objetivos
+- geração de relatórios de validação
+- apoio ao UAT
+
+### Utilitários
+
+- leitura/escrita segura de arquivos
+- parsing de argumentos
+- normalização de paths
+
+## Boas práticas para autores de agentes
+
+- Use artefatos existentes como fonte de verdade
+- Evite lógica duplicada entre agentes
+- Registre saídas em arquivos canônicos de fase
+- Garanta que toda tarefa tenha critério claro de done/verify
+
+---
+
+## Fluxo típico (programático)
+
+```text
+Ler contexto do projeto
+ -> montar input da etapa
+ -> executar ferramenta CLI
+ -> persistir artefatos
+ -> atualizar estado/roadmap
+ -> retornar resumo para o orquestrador
+```
+
+---
+
+> [!NOTE]
+> Este arquivo é um guia prático em Português para quem integra ou estende workflows. Para contratos estritos e detalhes técnicos completos, use o documento original em inglês.
--- a/docs/pt-BR/COMMANDS.md
+++ b/docs/pt-BR/COMMANDS.md
@@ -0,0 +1,82 @@
+# Referência de Comandos do GSD
+
+Este documento descreve os comandos principais do GSD em Português.  
+Para detalhes completos de flags avançadas e mudanças recentes, consulte também a [versão em inglês](../COMMANDS.md).
+
+---
+
+## Fluxo Principal
+
+| Comando | Finalidade | Quando usar |
+|---------|------------|-------------|
+| `/gsd:new-project` | Inicialização completa: perguntas, pesquisa, requisitos e roadmap | Início de projeto |
+| `/gsd:discuss-phase [N]` | Captura decisões de implementação | Antes do planejamento |
+| `/gsd:ui-phase [N]` | Gera contrato de UI (`UI-SPEC.md`) | Fases com frontend |
+| `/gsd:plan-phase [N]` | Pesquisa + planejamento + verificação | Antes de executar uma fase |
+| `/gsd:execute-phase <N>` | Executa planos em ondas paralelas | Após planejamento aprovado |
+| `/gsd:verify-work [N]` | UAT manual com diagnóstico automático | Após execução |
+| `/gsd:ship [N]` | Cria PR da fase validada | Ao concluir a fase |
+| `/gsd:next` | Detecta e executa o próximo passo lógico | Qualquer momento |
+| `/gsd:fast <texto>` | Tarefa curta sem planejamento completo | Ajustes triviais |
+
+## Navegação e Sessão
+
+| Comando | Finalidade |
+|---------|------------|
+| `/gsd:progress` | Mostra status atual e próximos passos |
+| `/gsd:resume-work` | Retoma contexto da sessão anterior |
+| `/gsd:pause-work` | Salva handoff estruturado |
+| `/gsd:session-report` | Gera resumo da sessão |
+| `/gsd:help` | Lista comandos e uso |
+| `/gsd:update` | Atualiza o GSD |
+
+## Gestão de Fases
+
+| Comando | Finalidade |
+|---------|------------|
+| `/gsd:add-phase` | Adiciona fase no roadmap |
+| `/gsd:insert-phase [N]` | Insere trabalho urgente entre fases |
+| `/gsd:remove-phase [N]` | Remove fase futura e reenumera |
+| `/gsd:list-phase-assumptions [N]` | Mostra abordagem assumida pelo Claude |
+| `/gsd:plan-milestone-gaps` | Cria fases para fechar lacunas de auditoria |
+
+## Brownfield e Utilidades
+
+| Comando | Finalidade |
+|---------|------------|
+| `/gsd:map-codebase` | Mapeia base existente antes de novo projeto |
+| `/gsd:quick` | Tarefas ad-hoc com garantias do GSD |
+| `/gsd:debug [desc]` | Debug sistemático com estado persistente |
+| `/gsd:forensics` | Diagnóstico de falhas no workflow |
+| `/gsd:settings` | Configuração de agentes, perfil e toggles |
+| `/gsd:set-profile <perfil>` | Troca rápida de perfil de modelo |
+
+## Qualidade de Código
+
+| Comando | Finalidade |
+|---------|------------|
+| `/gsd:review` | Peer review com múltiplas IAs |
+| `/gsd:pr-branch` | Cria branch limpa sem commits de planejamento |
+| `/gsd:audit-uat` | Audita dívida de validação/UAT |
+
+## Backlog e Threads
+
+| Comando | Finalidade |
+|---------|------------|
+| `/gsd:add-backlog <desc>` | Adiciona item no backlog (999.x) |
+| `/gsd:review-backlog` | Promove, mantém ou remove itens |
+| `/gsd:plant-seed <ideia>` | Registra ideia com gatilho futuro |
+| `/gsd:thread [nome]` | Gerencia threads persistentes |
+
+---
+
+## Exemplo rápido
+
+```bash
+/gsd:new-project
+/gsd:discuss-phase 1
+/gsd:plan-phase 1
+/gsd:execute-phase 1
+/gsd:verify-work 1
+/gsd:ship 1
+```
--- a/docs/pt-BR/CONFIGURATION.md
+++ b/docs/pt-BR/CONFIGURATION.md
@@ -0,0 +1,84 @@
+# Referência de Configuração do GSD
+
+Configurações do projeto ficam em `.planning/config.json`.  
+Esta versão resume os parâmetros principais em Português. Para schema completo, veja [inglês](../CONFIGURATION.md).
+
+---
+
+## Estrutura base
+
+```json
+{
+  "mode": "interactive",
+  "granularity": "standard",
+  "model_profile": "balanced",
+  "planning": {
+    "commit_docs": true,
+    "search_gitignored": false
+  },
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true,
+    "ui_phase": true,
+    "ui_safety_gate": true,
+    "research_before_questions": false,
+    "discuss_mode": "standard",
+    "skip_discuss": false
+  }
+}
+```
+
+## Configurações principais
+
+| Chave | Opções | Padrão | Descrição |
+|------|--------|--------|-----------|
+| `mode` | `interactive`, `yolo` | `interactive` | `yolo` autoaprova; `interactive` confirma cada etapa |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Granularidade de fases/planos |
+| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` | Perfil de modelos por agente |
+
+## Planning
+
+| Chave | Padrão | Descrição |
+|------|--------|-----------|
+| `planning.commit_docs` | `true` | Comitar `.planning/` no git |
+| `planning.search_gitignored` | `false` | Incluir arquivos ignorados em buscas amplas |
+
+## Workflow toggles
+
+| Chave | Padrão | Descrição |
+|------|--------|-----------|
+| `workflow.research` | `true` | Pesquisa antes de planejar |
+| `workflow.plan_check` | `true` | Loop de verificação de plano |
+| `workflow.verifier` | `true` | Verificação pós-execução |
+| `workflow.nyquist_validation` | `true` | Camada de validação automatizada por requisito |
+| `workflow.ui_phase` | `true` | Contrato de UI para fases frontend |
+| `workflow.ui_safety_gate` | `true` | Gate de segurança para registry UI |
+| `workflow.research_before_questions` | `false` | Pesquisa antes da discussão |
+| `workflow.discuss_mode` | `standard` | Discussão aberta; use `assumptions` para modo baseado em código |
+| `workflow.skip_discuss` | `false` | Pula discuss-phase no modo autônomo |
+
+## Git branching
+
+| Chave | Opções | Padrão | Descrição |
+|------|--------|--------|-----------|
+| `git.branching_strategy` | `none`, `phase`, `milestone` | `none` | Estratégia de criação de branches |
+| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | Nome para branch por fase |
+| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | Nome para branch de milestone |
+| `git.quick_branch_template` | string ou `null` | `null` | Branch opcional para `/gsd:quick` |
+
+## Perfis de modelo
+
+| Perfil | Objetivo |
+|--------|----------|
+| `quality` | Melhor qualidade, maior custo |
+| `balanced` | Equilíbrio (padrão recomendado) |
+| `budget` | Menor custo |
+| `inherit` | Herdar modelo da sessão/runtime |
+
+Troca rápida:
+
+```bash
+/gsd:set-profile budget
+```
--- a/docs/pt-BR/FEATURES.md
+++ b/docs/pt-BR/FEATURES.md
@@ -0,0 +1,56 @@
+# Referência de Recursos do GSD
+
+Visão em Português dos recursos centrais do GSD.  
+Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em inglês](../FEATURES.md).
+
+---
+
+## Recursos principais
+
+- **Desenvolvimento orientado por fases** com artefatos de planejamento versionados
+- **Engenharia de contexto** para reduzir degradação de qualidade em sessões longas
+- **Planejamento em tarefas atômicas** para execução mais previsível
+- **Execução em ondas paralelas** com controle por dependências
+- **Commits atômicos por tarefa** para rastreabilidade e rollback
+- **Verificação pós-execução** com foco em objetivos da fase
+- **UAT guiado** via `/gsd:verify-work`
+- **Suporte brownfield** com `/gsd:map-codebase`
+- **Workstreams** para trilhas paralelas sem colisão de estado
+- **Backlog, seeds e threads** para memória de médio/longo prazo
+
+## Qualidade e segurança
+
+- **Plan-check** antes de executar
+- **Nyquist validation** para mapear requisito -> validação automatizada
+- **Detecção de prompt injection** em entradas do usuário
+- **Prevenção de path traversal** em caminhos fornecidos
+- **Hooks de proteção** para alterações fora de contexto de workflow
+
+## UX de frontend
+
+- **`/gsd:ui-phase`**: contrato visual antes da execução
+- **`/gsd:ui-review`**: auditoria visual em 6 pilares
+- **UI safety gate** para uso de registries de terceiros
+
+## Operação e manutenção
+
+- **Perfis de modelo** (`quality`, `balanced`, `budget`, `inherit`)
+- **Ajuste por toggles** para custo/qualidade/velocidade
+- **Diagnóstico forense** com `/gsd:forensics`
+- **Relatório de sessão** com `/gsd:session-report`
+
+---
+
+## Atalhos recomendados por cenário
+
+| Cenário | Comandos |
+|--------|----------|
+| Projeto novo | `/gsd:new-project` -> `/gsd:discuss-phase` -> `/gsd:plan-phase` -> `/gsd:execute-phase` |
+| Correção rápida | `/gsd:quick` |
+| Código existente | `/gsd:map-codebase` -> `/gsd:new-project` |
+| Fechamento de release | `/gsd:audit-milestone` -> `/gsd:complete-milestone` |
+
+---
+
+> [!NOTE]
+> Este arquivo é uma versão de referência rápida em Português para facilitar uso diário. Para detalhes de baixo nível, requisitos formais e comportamento completo de cada recurso, use o documento original em inglês.
--- a/docs/pt-BR/README.md
+++ b/docs/pt-BR/README.md
@@ -0,0 +1,30 @@
+# Documentação do GSD
+
+Documentação abrangente do framework Get Shit Done (GSD) — um sistema de meta-prompting, engenharia de contexto e desenvolvimento orientado por especificações para agentes de IA.
+
+## Índice da documentação
+
+| Documento | Público | Descrição |
+|----------|----------|-------------|
+| [Guia do Usuário](USER-GUIDE.md) | Todos os usuários | Fluxos de trabalho, troubleshooting e recuperação |
+| [Arquitetura](ARCHITECTURE.md) | Contribuidores, usuários avançados | Arquitetura do sistema, modelo de agentes e design interno |
+| [Referência de comandos](COMMANDS.md) | Todos os usuários | Comandos, sintaxe, flags, opções e exemplos |
+| [Referência de configuração](CONFIGURATION.md) | Todos os usuários | Schema completo de configuração, toggles e perfis |
+| [Referência de recursos](FEATURES.md) | Todos os usuários | Recursos e requisitos detalhados |
+| [Referência de agentes](AGENTS.md) | Contribuidores, usuários avançados | Agentes especializados, papéis e padrões de orquestração |
+| [Ferramentas CLI](CLI-TOOLS.md) | Contribuidores, autores de agentes | API programática `gsd-tools.cjs` |
+| [Monitor de contexto](context-monitor.md) | Todos os usuários | Arquitetura de monitoramento da janela de contexto |
+| [Discuss Mode](workflow-discuss-mode.md) | Todos os usuários | Modo suposições vs entrevista no `discuss-phase` |
+| [Referências](references/) | Todos os usuários | Guias complementares de decisão, verificação e padrões |
+| [Superpowers](superpowers/) | Contribuidores | Planos e specs avançadas do projeto |
+
+## Links rápidos
+
+- **Começar rápido:** [README principal](../../README.pt-BR.md) -> instalação -> `/gsd:new-project`
+- **Fluxo completo:** [Guia do usuário](USER-GUIDE.md)
+- **Comandos:** [Referência de comandos](COMMANDS.md)
+- **Configuração:** [Referência de configuração](CONFIGURATION.md)
+- **Arquitetura interna:** [Arquitetura](ARCHITECTURE.md)
+
+> [!NOTE]
+> Esta pasta `pt-BR` contém a versão em Português dos documentos de uso geral. Documentação técnica avançada ainda referencia os arquivos em inglês para manter precisão e atualização.
--- a/docs/pt-BR/USER-GUIDE.md
+++ b/docs/pt-BR/USER-GUIDE.md
@@ -0,0 +1,335 @@
+# Guia do Usuário do GSD
+
+Referência detalhada de workflows, troubleshooting e configuração. Para setup rápido, veja o [README](../../README.pt-BR.md).
+
+---
+
+## Sumário
+
+- [Fluxo de trabalho](#fluxo-de-trabalho)
+- [Contrato de UI](#contrato-de-ui)
+- [Backlog e Threads](#backlog-e-threads)
+- [Workstreams](#workstreams)
+- [Segurança](#segurança)
+- [Referência de comandos](#referência-de-comandos)
+- [Configuração](#configuração)
+- [Exemplos de uso](#exemplos-de-uso)
+- [Troubleshooting](#troubleshooting)
+- [Recuperação rápida](#recuperação-rápida)
+
+---
+
+## Fluxo de trabalho
+
+Fluxo recomendado por fase:
+
+1. `/gsd:discuss-phase [N]` — trava preferências de implementação
+2. `/gsd:ui-phase [N]` — contrato visual para fases frontend
+3. `/gsd:plan-phase [N]` — pesquisa + plano + validação
+4. `/gsd:execute-phase [N]` — execução em ondas paralelas
+5. `/gsd:verify-work [N]` — UAT manual com diagnóstico
+6. `/gsd:ship [N]` — cria PR (opcional)
+
+Para iniciar projeto novo:
+
+```bash
+/gsd:new-project
+```
+
+Para seguir automaticamente o próximo passo:
+
+```bash
+/gsd:next
+```
+
+### Nyquist Validation
+
+Durante `plan-phase`, o GSD pode mapear requisitos para comandos de teste automáticos antes da implementação. Isso gera `{phase}-VALIDATION.md` e aumenta a confiabilidade de verificação pós-execução.
+
+Desativar:
+
+```json
+{
+  "workflow": {
+    "nyquist_validation": false
+  }
+}
+```
+
+### Modo de discussão por suposições
+
+Com `workflow.discuss_mode: "assumptions"`, o GSD analisa o código antes de perguntar, apresenta suposições estruturadas e pede apenas correções.
+
+---
+
+## Contrato de UI
+
+### Comandos
+
+| Comando | Descrição |
+|---------|-----------|
+| `/gsd:ui-phase [N]` | Gera contrato de design `UI-SPEC.md` para a fase |
+| `/gsd:ui-review [N]` | Auditoria visual retroativa em 6 pilares |
+
+### Quando usar
+
+- Rode `/gsd:ui-phase` depois de `/gsd:discuss-phase` e antes de `/gsd:plan-phase`.
+- Rode `/gsd:ui-review` após execução/validação para avaliar qualidade visual e consistência.
+
+### Configurações relacionadas
+
+| Setting | Padrão | O que controla |
+|---------|--------|----------------|
+| `workflow.ui_phase` | `true` | Gera contratos de UI para fases frontend |
+| `workflow.ui_safety_gate` | `true` | Ativa gate de segurança para componentes de registry |
+
+---
+
+## Backlog e Threads
+
+### Backlog (999.x)
+
+Ideias fora da sequência ativa vão para backlog:
+
+```bash
+/gsd:add-backlog "Camada GraphQL"
+/gsd:add-backlog "Responsividade mobile"
+```
+
+Promover/revisar:
+
+```bash
+/gsd:review-backlog
+```
+
+### Seeds
+
+Seeds guardam ideias futuras com condição de gatilho:
+
+```bash
+/gsd:plant-seed "Adicionar colaboração real-time quando infra de WebSocket estiver pronta"
+```
+
+### Threads persistentes
+
+Threads são contexto leve entre sessões:
+
+```bash
+/gsd:thread
+/gsd:thread fix-deploy-key-auth
+/gsd:thread "Investigar timeout TCP"
+```
+
+---
+
+## Workstreams
+
+Workstreams permitem trabalho paralelo sem colisão de estado de planejamento.
+
+| Comando | Função |
+|---------|--------|
+| `/gsd:workstreams create <name>` | Cria workstream isolado |
+| `/gsd:workstreams switch <name>` | Troca workstream ativo |
+| `/gsd:workstreams list` | Lista workstreams |
+| `/gsd:workstreams complete <name>` | Finaliza e arquiva workstream |
+
+`workstreams` compartilham o mesmo código/git, mas isolam artefatos de `.planning/`.
+
+---
+
+## Segurança
+
+O GSD aplica defesa em profundidade:
+
+- prevenção de path traversal em entradas de arquivo
+- detecção de prompt injection em texto do usuário
+- hooks de proteção para escrita em `.planning/`
+- scanner CI para padrões de injeção em agentes/workflows/comandos
+
+Para arquivos sensíveis, use deny list no Claude Code.
+
+---
+
+## Referência de comandos
+
+### Fluxo principal
+
+| Comando | Quando usar |
+|---------|-------------|
+| `/gsd:new-project` | Início de projeto |
+| `/gsd:discuss-phase [N]` | Definir preferências antes do plano |
+| `/gsd:plan-phase [N]` | Criar e validar planos |
+| `/gsd:execute-phase [N]` | Executar planos em ondas |
+| `/gsd:verify-work [N]` | UAT manual |
+| `/gsd:ship [N]` | Gerar PR da fase |
+| `/gsd:next` | Próximo passo automático |
+
+### Gestão e utilidades
+
+| Comando | Quando usar |
+|---------|-------------|
+| `/gsd:progress` | Ver status atual |
+| `/gsd:resume-work` | Retomar sessão |
+| `/gsd:pause-work` | Pausar com handoff |
+| `/gsd:session-report` | Resumo da sessão |
+| `/gsd:quick` | Tarefa ad-hoc com garantias GSD |
+| `/gsd:debug [desc]` | Debug sistemático |
+| `/gsd:forensics` | Diagnóstico de workflow quebrado |
+| `/gsd:settings` | Ajustar workflow/modelos |
+| `/gsd:set-profile <profile>` | Troca rápida de perfil |
+
+Para lista completa e flags avançadas, consulte [Command Reference](../COMMANDS.md).
+
+---
+
+## Configuração
+
+Arquivo de configuração: `.planning/config.json`
+
+### Núcleo
+
+| Setting | Opções | Padrão |
+|---------|--------|--------|
+| `mode` | `interactive`, `yolo` | `interactive` |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` |
+| `model_profile` | `quality`, `balanced`, `budget`, `inherit` | `balanced` |
+
+### Workflow
+
+| Setting | Padrão |
+|---------|--------|
+| `workflow.research` | `true` |
+| `workflow.plan_check` | `true` |
+| `workflow.verifier` | `true` |
+| `workflow.nyquist_validation` | `true` |
+| `workflow.ui_phase` | `true` |
+| `workflow.ui_safety_gate` | `true` |
+
+### Perfis de modelo
+
+| Perfil | Uso recomendado |
+|--------|------------------|
+| `quality` | trabalho crítico, maior qualidade |
+| `balanced` | padrão recomendado |
+| `budget` | reduzir custo de tokens |
+| `inherit` | seguir modelo da sessão/runtime |
+
+Detalhes completos: [Configuration Reference](../CONFIGURATION.md).
+
+---
+
+## Exemplos de uso
+
+### Projeto novo
+
+```bash
+claude --dangerously-skip-permissions
+/gsd:new-project
+/gsd:discuss-phase 1
+/gsd:ui-phase 1
+/gsd:plan-phase 1
+/gsd:execute-phase 1
+/gsd:verify-work 1
+/gsd:ship 1
+```
+
+### Código já existente
+
+```bash
+/gsd:map-codebase
+/gsd:new-project
+```
+
+### Correção rápida
+
+```bash
+/gsd:quick
+> "Corrigir botão de login no mobile Safari"
+```
+
+### Preparação para release
+
+```bash
+/gsd:audit-milestone
+/gsd:plan-milestone-gaps
+/gsd:complete-milestone
+```
+
+---
+
+## Troubleshooting
+
+### "Project already initialized"
+
+`.planning/PROJECT.md` já existe. Apague `.planning/` se quiser reiniciar do zero.
+
+### Sessão longa degradando contexto
+
+Use `/clear` entre etapas grandes e retome com `/gsd:resume-work` ou `/gsd:progress`.
+
+### Plano desalinhado
+
+Rode `/gsd:discuss-phase [N]` antes do plano e valide suposições com `/gsd:list-phase-assumptions [N]`.
+
+### Execução falhou ou saiu com stubs
+
+Replaneje com escopo menor (tarefas menores por plano).
+
+### Custo alto
+
+Use perfil budget:
+
+```bash
+/gsd:set-profile budget
+```
+
+### Runtime não-Claude (Codex/OpenCode/Gemini)
+
+Use `resolve_model_ids: "omit"` para deixar o runtime resolver modelos padrão.
+
+---
+
+## Recuperação rápida
+
+| Problema | Solução |
+|---------|---------|
+| Perdeu contexto | `/gsd:resume-work` ou `/gsd:progress` |
+| Fase deu errado | `git revert` + replanejar |
+| Precisa alterar escopo | `/gsd:add-phase`, `/gsd:insert-phase`, `/gsd:remove-phase` |
+| Bug em workflow | `/gsd:forensics` |
+| Correção pontual | `/gsd:quick` |
+| Custo alto | `/gsd:set-profile budget` |
+| Não sabe próximo passo | `/gsd:next` |
+
+---
+
+## Estrutura de arquivos do projeto
+
+```text
+.planning/
+  PROJECT.md
+  REQUIREMENTS.md
+  ROADMAP.md
+  STATE.md
+  config.json
+  MILESTONES.md
+  HANDOFF.json
+  research/
+  reports/
+  todos/
+  debug/
+  codebase/
+  phases/
+    XX-phase-name/
+      XX-YY-PLAN.md
+      XX-YY-SUMMARY.md
+      CONTEXT.md
+      RESEARCH.md
+      VERIFICATION.md
+      XX-UI-SPEC.md
+      XX-UI-REVIEW.md
+  ui-reviews/
+```
+
+> [!NOTE]
+> Esta é a versão pt-BR do guia para uso diário. Para detalhes técnicos exatos e cobertura completa de parâmetros avançados, consulte também o [guia original em inglês](../USER-GUIDE.md).
--- a/docs/pt-BR/context-monitor.md
+++ b/docs/pt-BR/context-monitor.md
@@ -0,0 +1,40 @@
+# Monitor de Contexto
+
+O monitor de contexto ajuda a evitar degradação de qualidade em sessões longas, alertando sobre uso excessivo da janela de contexto.
+
+Para detalhes completos de implementação, veja [context-monitor.md em inglês](../context-monitor.md).
+
+---
+
+## Objetivos
+
+- identificar quando a sessão principal está saturando
+- recomendar ações de recuperação (`/clear`, `/gsd:resume-work`, `/gsd:progress`)
+- manter previsibilidade durante ciclos longos de desenvolvimento
+
+## Como funciona
+
+1. coleta sinais de uso da janela de contexto
+2. compara com limiares de alerta
+3. emite avisos progressivos
+4. sugere retomada por artefatos persistentes
+
+## Estratégia recomendada
+
+- Limpe contexto entre fases grandes
+- Execute tarefas pesadas em subagentes
+- Mantenha o estado em `.planning/` como fonte de verdade
+
+## Recuperação quando há degradação
+
+```bash
+/clear
+/gsd:resume-work
+# ou
+/gsd:progress
+```
+
+---
+
+> [!TIP]
+> O monitor não substitui boas práticas de escopo. Planos pequenos e verificáveis continuam sendo o principal fator de qualidade.
--- a/docs/pt-BR/superpowers/README.md
+++ b/docs/pt-BR/superpowers/README.md
@@ -0,0 +1,11 @@
+# Superpowers (pt-BR)
+
+Documentos avançados traduzidos:
+
+## Plans
+
+- [2026-03-18-materialize-new-project-config](plans/2026-03-18-materialize-new-project-config.md)
+
+## Specs
+
+- [2026-03-20-multi-project-workspaces-design](specs/2026-03-20-multi-project-workspaces-design.md)
--- a/docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md
+++ b/docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md
@@ -0,0 +1,60 @@
+# Plano: Materializar Configuração no `new-project` (pt-BR)
+
+Data original: 2026-03-23  
+Fonte canônica: `docs/superpowers/plans/2026-03-18-materialize-new-project-config.md`
+
+---
+
+## Contexto
+
+Este plano formaliza a materialização explícita da configuração do projeto durante `/gsd:new-project`, garantindo que escolhas feitas na inicialização sejam persistidas de forma determinística em `.planning/config.json`.
+
+## Objetivos
+
+- garantir persistência imediata de decisões de setup
+- reduzir divergência entre estado interativo e arquivo de configuração
+- facilitar retomada de sessão e reprodutibilidade
+
+## Escopo
+
+Inclui:
+
+- mapeamento de respostas de setup para chaves de configuração
+- escrita idempotente de `.planning/config.json`
+- validação mínima de schema antes de persistir
+
+Não inclui:
+
+- redesenho completo do schema
+- migração profunda de versões legadas
+
+## Estratégia de implementação
+
+1. Capturar decisões de setup em estrutura intermediária
+2. Normalizar valores (tipos/enum/padrões)
+3. Aplicar merge controlado no config existente
+4. Persistir arquivo final e registrar resumo no estado
+
+## Critérios de aceitação
+
+- após `/gsd:new-project`, `config.json` reflete as escolhas feitas
+- rerun não duplica nem corrompe campos
+- comandos subsequentes observam os valores persistidos
+
+## Riscos e mitigação
+
+- **Risco:** configuração parcial em caso de falha no meio  
+  **Mitigação:** escrita atômica (arquivo temporário + replace)
+- **Risco:** inconsistência com defaults implícitos  
+  **Mitigação:** normalização centralizada com fallback explícito
+
+## Verificação
+
+- teste de inicialização limpa
+- teste de reexecução com config pré-existente
+- teste de compatibilidade com comandos dependentes de config
+
+---
+
+> [!NOTE]
+> Esta versão em Português é uma tradução operacional do plano para consulta rápida. O documento original permanece como referência técnica canônica.
--- a/docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md
+++ b/docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md
@@ -0,0 +1,55 @@
+# Especificação: Design de Multi-Project Workspaces (pt-BR)
+
+Data original: 2026-03-20  
+Fonte canônica: `docs/superpowers/specs/2026-03-20-multi-project-workspaces-design.md`
+
+---
+
+## Problema
+
+Times e desenvolvedores frequentemente precisam trabalhar em múltiplos repositórios/áreas em paralelo, mantendo isolamento de estado de planejamento sem perder fluidez operacional.
+
+## Proposta
+
+Introduzir workspaces multi-projeto com:
+
+- isolamento de `.planning/` por workspace
+- suporte a múltiplos repositórios (worktree/clone)
+- comandos para criação, listagem e remoção
+
+## Objetivos de design
+
+- isolamento forte de estado
+- operação simples via comandos (`new/list/remove workspace`)
+- baixo acoplamento com o workflow padrão
+- fácil observabilidade do que está ativo
+
+## Modelo conceitual
+
+- **Workspace**: unidade isolada de execução GSD
+- **Member repos**: repositórios associados ao workspace
+- **Manifest**: arquivo de metadados com estrutura e status
+
+## Fluxo de uso
+
+1. Criar workspace com nome e repositórios alvo
+2. Inicializar/retomar fluxo GSD dentro do workspace
+3. Operar fases normalmente com estado isolado
+4. Finalizar e remover quando concluído
+
+## Considerações
+
+- comandos devem deixar explícito o contexto atual
+- limpeza precisa remover artefatos derivados com segurança
+- comportamento deve ser previsível em ambientes monorepo
+
+## Critérios de aceitação
+
+- workspaces independentes não colidem estado
+- listagem mostra workspace ativo e metadados essenciais
+- remoção limpa artefatos sem afetar repositórios externos
+
+---
+
+> [!NOTE]
+> Esta versão em Português resume a especificação de design para uso prático. O arquivo original em inglês mantém o detalhamento normativo completo.
--- a/docs/pt-BR/workflow-discuss-mode.md
+++ b/docs/pt-BR/workflow-discuss-mode.md
@@ -0,0 +1,62 @@
+# Discuss Mode (Modo de Discussão)
+
+O GSD oferece dois estilos para `/gsd:discuss-phase`:
+
+- **`standard`**: entrevista aberta para levantar preferências
+- **`assumptions`**: análise do código primeiro, seguida de confirmação/correção de suposições
+
+Para referência completa, veja [workflow-discuss-mode.md em inglês](../workflow-discuss-mode.md).
+
+---
+
+## Quando usar `standard`
+
+Use quando:
+
+- o projeto ainda não tem padrões claros
+- você quer explorar alternativas livremente
+- há decisões de produto/UX em aberto
+
+Vantagem: descoberta ampla.  
+Trade-off: pode consumir mais tempo de perguntas.
+
+## Quando usar `assumptions`
+
+Use quando:
+
+- o código já tem convenções estáveis
+- você quer reduzir fricção no intake
+- o time prefere revisão de propostas em vez de entrevista aberta
+
+Vantagem: velocidade e consistência com o código existente.  
+Trade-off: depende da qualidade do mapeamento de contexto.
+
+## Como habilitar
+
+Via `/gsd:settings`, defina:
+
+```json
+{
+  "workflow": {
+    "discuss_mode": "assumptions"
+  }
+}
+```
+
+## Fluxo no modo `assumptions`
+
+1. GSD lê `PROJECT.md`, mapeamento de código e convenções
+2. Gera lista estruturada de suposições
+3. Você confirma, corrige ou expande
+4. GSD escreve `CONTEXT.md` com decisões consolidadas
+
+## Boas práticas
+
+- Revise suposições antes do `plan-phase`
+- Corrija ambiguidades de nomes/paths cedo
+- Se o plano sair desalinhado, volte ao discuss-phase e refine
+
+---
+
+> [!NOTE]
+> Para ambientes com múltiplos runtimes e perfis de modelo dinâmicos, prefira `assumptions` quando o reuso de padrões de código for prioridade.