feat: add Portuguese documentation and update language links

2026-04-25 17:25:23 +02:00 · 2026-03-23 15:38:17 -04:00
parent 5733700d7d
commit 7709059f42
18 changed files with 1477 additions and 5 deletions
--- a/README.ja-JP.md
+++ b/README.ja-JP.md
@@ -2,13 +2,13 @@

 # GET SHIT DONE

-[English](README.md) · [简体中文](README.zh-CN.md) · **日本語**
+[English](README.md) · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · **日本語**

 **Claude Code、OpenCode、Gemini CLI、Codex、Copilot、Antigravity向けの軽量かつ強力なメタプロンプティング、コンテキストエンジニアリング、仕様駆動開発システム。**

 **コンテキストロット（Claudeがコンテキストウィンドウを消費するにつれ品質が劣化する現象）を解決します。**

-[**English**](README.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md)
+[**English**](README.md) | [**Português**](README.pt-BR.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md)

 [![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
 [![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
--- a/README.md
+++ b/README.md
@@ -2,13 +2,13 @@

 # GET SHIT DONE

-**English** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)
+**English** · [Português](README.pt-BR.md) · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)

 **A light-weight and powerful meta-prompting, context engineering and spec-driven development system for Claude Code, OpenCode, Gemini CLI, Codex, Copilot, and Antigravity.**

 **Solves context rot — the quality degradation that happens as Claude fills its context window.**

-[**English**](README.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md)
+[**English**](README.md) | [**Português**](README.pt-BR.md) | [**简体中文**](docs/zh-CN/README.md) | [**日本語**](docs/ja-JP/README.md)

 [![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
 [![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
--- a/README.pt-BR.md
+++ b/README.pt-BR.md
@@ -0,0 +1,442 @@
+<div align="center">
+
+# GET SHIT DONE
+
+[English](README.md) · **Português** · [简体中文](README.zh-CN.md) · [日本語](README.ja-JP.md)
+
+**Um sistema leve e poderoso de meta-prompting, engenharia de contexto e desenvolvimento orientado a especificação para Claude Code, OpenCode, Gemini CLI, Codex, Copilot, Cursor e Antigravity.**
+
+**Resolve context rot — a degradação de qualidade que acontece conforme o Claude enche a janela de contexto.**
+
+[![npm version](https://img.shields.io/npm/v/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
+[![npm downloads](https://img.shields.io/npm/dm/get-shit-done-cc?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/get-shit-done-cc)
+[![Tests](https://img.shields.io/github/actions/workflow/status/glittercowboy/get-shit-done/test.yml?branch=main&style=for-the-badge&logo=github&label=Tests)](https://github.com/glittercowboy/get-shit-done/actions/workflows/test.yml)
+[![Discord](https://img.shields.io/badge/Discord-Join-5865F2?style=for-the-badge&logo=discord&logoColor=white)](https://discord.gg/gsd)
+[![X (Twitter)](https://img.shields.io/badge/X-@gsd__foundation-000000?style=for-the-badge&logo=x&logoColor=white)](https://x.com/gsd_foundation)
+[![$GSD Token](https://img.shields.io/badge/$GSD-Dexscreener-1C1C1C?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjQiIGhlaWdodD0iMjQiIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj48Y2lyY2xlIGN4PSIxMiIgY3k9IjEyIiByPSIxMCIgZmlsbD0iIzAwRkYwMCIvPjwvc3ZnPg==&logoColor=00FF00)](https://dexscreener.com/solana/dwudwjvan7bzkw9zwlbyv6kspdlvhwzrqy6ebk8xzxkv)
+[![GitHub stars](https://img.shields.io/github/stars/glittercowboy/get-shit-done?style=for-the-badge&logo=github&color=181717)](https://github.com/glittercowboy/get-shit-done)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx get-shit-done-cc@latest
+```
+
+**Funciona em Mac, Windows e Linux.**
+
+<br>
+
+![GSD Install](assets/terminal.svg)
+
+<br>
+
+*"Se você sabe claramente o que quer, isso VAI construir para você. Sem enrolação."*
+
+*"Eu já usei SpecKit, OpenSpec e Taskmaster — este me deu os melhores resultados."*
+
+*"De longe a adição mais poderosa ao meu Claude Code. Nada superengenheirado. Simplesmente faz o trabalho."*
+
+<br>
+
+**Confiado por engenheiros da Amazon, Google, Shopify e Webflow.**
+
+[Por que eu criei isso](#por-que-eu-criei-isso) · [Como funciona](#como-funciona) · [Comandos](#comandos) · [Por que funciona](#por-que-funciona) · [Guia do usuário](docs/pt-BR/USER-GUIDE.md)
+
+</div>
+
+---
+
+## Por que eu criei isso
+
+Sou desenvolvedor solo. Eu não escrevo código — o Claude Code escreve.
+
+Existem outras ferramentas de desenvolvimento orientado por especificação. BMAD, Speckit... Mas quase todas parecem mais complexas do que o necessário (cerimônias de sprint, story points, sync com stakeholders, retrospectivas, fluxos Jira) ou não entendem de verdade o panorama do que você está construindo. Eu não sou uma empresa de software com 50 pessoas. Não quero teatro corporativo. Só quero construir coisas boas que funcionem.
+
+Então eu criei o GSD. A complexidade fica no sistema, não no seu fluxo. Por trás: engenharia de contexto, formatação XML de prompts, orquestração de subagentes, gerenciamento de estado. O que você vê: alguns comandos que simplesmente funcionam.
+
+O sistema dá ao Claude tudo que ele precisa para fazer o trabalho *e* validar o resultado. Eu confio no fluxo. Ele entrega.
+
+— **TÂCHES**
+
+---
+
+Vibe coding ganhou má fama. Você descreve algo, a IA gera código, e sai um resultado inconsistente que quebra em escala.
+
+O GSD corrige isso. É a camada de engenharia de contexto que torna o Claude Code confiável.
+
+---
+
+## Para quem é
+
+Para quem quer descrever o que precisa e receber isso construído do jeito certo — sem fingir que está rodando uma engenharia de 50 pessoas.
+
+---
+
+## Primeiros passos
+
+```bash
+npx get-shit-done-cc@latest
+```
+
+O instalador pede:
+1. **Runtime** — Claude Code, OpenCode, Gemini, Codex, Copilot, Cursor, Antigravity, ou todos
+2. **Local** — Global (todos os projetos) ou local (apenas projeto atual)
+
+Verifique com:
+- Claude Code / Gemini: `/gsd:help`
+- OpenCode: `/gsd-help`
+- Codex: `$gsd-help`
+- Copilot: `/gsd:help`
+- Antigravity: `/gsd:help`
+
+> [!NOTE]
+> A instalação do Codex usa skills (`skills/gsd-*/SKILL.md`) em vez de prompts customizados.
+
+### Mantendo atualizado
+
+```bash
+npx get-shit-done-cc@latest
+```
+
+<details>
+<summary><strong>Instalação não interativa (Docker, CI, Scripts)</strong></summary>
+
+```bash
+# Claude Code
+npx get-shit-done-cc --claude --global
+npx get-shit-done-cc --claude --local
+
+# OpenCode
+npx get-shit-done-cc --opencode --global
+
+# Gemini CLI
+npx get-shit-done-cc --gemini --global
+
+# Codex
+npx get-shit-done-cc --codex --global
+npx get-shit-done-cc --codex --local
+
+# Copilot
+npx get-shit-done-cc --copilot --global
+npx get-shit-done-cc --copilot --local
+
+# Cursor
+npx get-shit-done-cc --cursor --global
+npx get-shit-done-cc --cursor --local
+
+# Antigravity
+npx get-shit-done-cc --antigravity --global
+npx get-shit-done-cc --antigravity --local
+
+# Todos
+npx get-shit-done-cc --all --global
+```
+
+Use `--global` (`-g`) ou `--local` (`-l`) para pular a pergunta de local.
+Use `--claude`, `--opencode`, `--gemini`, `--codex`, `--copilot`, `--cursor`, `--antigravity` ou `--all` para pular a pergunta de runtime.
+
+</details>
+
+### Recomendado: modo sem permissões
+
+```bash
+claude --dangerously-skip-permissions
+```
+
+> [!TIP]
+> Esse é o modo pensado para o GSD: aprovar `date` e `git commit` 50 vezes mata a produtividade.
+
+---
+
+## Como funciona
+
+> **Já tem código?** Rode `/gsd:map-codebase` primeiro para analisar stack, arquitetura, convenções e riscos.
+
+### 1. Inicializar projeto
+
+```
+/gsd:new-project
+```
+
+O sistema:
+1. **Pergunta** até entender seu objetivo
+2. **Pesquisa** o domínio com agentes em paralelo
+3. **Extrai requisitos** (v1, v2 e fora de escopo)
+4. **Monta roadmap** por fases
+
+**Cria:** `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, `.planning/research/`
+
+### 2. Discutir fase
+
+```
+/gsd:discuss-phase 1
+```
+
+Captura suas preferências de implementação antes do planejamento.
+
+**Cria:** `{phase_num}-CONTEXT.md`
+
+### 3. Planejar fase
+
+```
+/gsd:plan-phase 1
+```
+
+1. Pesquisa abordagens
+2. Cria 2-3 planos atômicos em XML
+3. Verifica contra os requisitos
+
+**Cria:** `{phase_num}-RESEARCH.md`, `{phase_num}-{N}-PLAN.md`
+
+### 4. Executar fase
+
+```
+/gsd:execute-phase 1
+```
+
+1. Executa planos em ondas
+2. Contexto novo por plano
+3. Commit atômico por tarefa
+4. Verifica contra objetivos
+
+**Cria:** `{phase_num}-{N}-SUMMARY.md`, `{phase_num}-VERIFICATION.md`
+
+### 5. Verificar trabalho
+
+```
+/gsd:verify-work 1
+```
+
+Validação manual orientada para confirmar que a feature realmente funciona como esperado.
+
+**Cria:** `{phase_num}-UAT.md` e planos de correção se necessário
+
+### 6. Repetir -> Entregar -> Completar
+
+```
+/gsd:discuss-phase 2
+/gsd:plan-phase 2
+/gsd:execute-phase 2
+/gsd:verify-work 2
+/gsd:ship 2
+/gsd:complete-milestone
+/gsd:new-milestone
+```
+
+Ou deixe o GSD decidir:
+
+```
+/gsd:next
+```
+
+### Modo rápido
+
+```
+/gsd:quick
+```
+
+Para tarefas ad-hoc sem ciclo completo de planejamento.
+
+---
+
+## Por que funciona
+
+### Engenharia de contexto
+
+| Arquivo | Papel |
+|---------|-------|
+| `PROJECT.md` | Visão do projeto |
+| `research/` | Conhecimento do ecossistema |
+| `REQUIREMENTS.md` | Escopo v1/v2 |
+| `ROADMAP.md` | Direção e progresso |
+| `STATE.md` | Memória entre sessões |
+| `PLAN.md` | Tarefa atômica com XML |
+| `SUMMARY.md` | O que mudou |
+| `todos/` | Ideias para depois |
+| `threads/` | Contexto persistente |
+| `seeds/` | Ideias para próximos marcos |
+
+### Formato XML de prompt
+
+```xml
+<task type="auto">
+  <name>Create login endpoint</name>
+  <files>src/app/api/auth/login/route.ts</files>
+  <action>
+    Use jose for JWT (not jsonwebtoken - CommonJS issues).
+    Validate credentials against users table.
+    Return httpOnly cookie on success.
+  </action>
+  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
+  <done>Valid credentials return cookie, invalid return 401</done>
+</task>
+```
+
+### Orquestração multiagente
+
+Um orquestrador leve chama agentes especializados para pesquisa, planejamento, execução e verificação.
+
+### Commits atômicos
+
+Cada tarefa gera commit próprio, facilitando `git bisect`, rollback e rastreabilidade.
+
+---
+
+## Comandos
+
+### Fluxo principal
+
+| Comando | O que faz |
+|---------|-----------|
+| `/gsd:new-project [--auto]` | Inicializa projeto completo |
+| `/gsd:discuss-phase [N] [--auto] [--analyze]` | Captura decisões antes do plano |
+| `/gsd:plan-phase [N] [--auto] [--reviews]` | Pesquisa + plano + validação |
+| `/gsd:execute-phase <N>` | Executa planos em ondas paralelas |
+| `/gsd:verify-work [N]` | UAT manual |
+| `/gsd:ship [N] [--draft]` | Cria PR da fase validada |
+| `/gsd:next` | Avança automaticamente para o próximo passo |
+| `/gsd:fast <text>` | Tarefas triviais sem planejamento |
+| `/gsd:complete-milestone` | Fecha o marco e marca release |
+| `/gsd:new-milestone [name]` | Inicia próximo marco |
+
+### Qualidade e utilidades
+
+| Comando | O que faz |
+|---------|-----------|
+| `/gsd:review` | Peer review com múltiplas IAs |
+| `/gsd:pr-branch` | Cria branch limpa para PR |
+| `/gsd:settings` | Configura perfis e agentes |
+| `/gsd:set-profile <profile>` | Troca perfil (quality/balanced/budget/inherit) |
+| `/gsd:quick [--full] [--discuss] [--research]` | Execução rápida com garantias do GSD |
+| `/gsd:health [--repair]` | Verifica e repara `.planning/` |
+
+> Para a lista completa de comandos e opções, use `/gsd:help`.
+
+---
+
+## Configuração
+
+As configurações do projeto ficam em `.planning/config.json`.
+Você pode configurar no `/gsd:new-project` ou ajustar depois com `/gsd:settings`.
+
+### Ajustes principais
+
+| Configuração | Opções | Padrão | Controle |
+|--------------|--------|--------|----------|
+| `mode` | `yolo`, `interactive` | `interactive` | Autoaprovar vs confirmar etapas |
+| `granularity` | `coarse`, `standard`, `fine` | `standard` | Granularidade de fases/planos |
+
+### Perfis de modelo
+
+| Perfil | Planejamento | Execução | Verificação |
+|--------|--------------|----------|-------------|
+| `quality` | Opus | Opus | Sonnet |
+| `balanced` | Opus | Sonnet | Sonnet |
+| `budget` | Sonnet | Sonnet | Haiku |
+| `inherit` | Inherit | Inherit | Inherit |
+
+Troca rápida:
+```
+/gsd:set-profile budget
+```
+
+---
+
+## Segurança
+
+### Endurecimento embutido
+
+O GSD inclui proteções como:
+- prevenção de path traversal
+- detecção de prompt injection
+- validação de argumentos de shell
+- parsing seguro de JSON
+- scanner de injeção para CI
+
+### Protegendo arquivos sensíveis
+
+Adicione padrões sensíveis ao deny list do Claude Code:
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Read(.env)",
+      "Read(.env.*)",
+      "Read(**/secrets/*)",
+      "Read(**/*credential*)",
+      "Read(**/*.pem)",
+      "Read(**/*.key)"
+    ]
+  }
+}
+```
+
+---
+
+## Solução de problemas
+
+**Comandos não apareceram após instalar?**
+- Reinicie o runtime
+- Verifique se os arquivos foram instalados no diretório correto
+
+**Comandos não funcionam como esperado?**
+- Rode `/gsd:help`
+- Reinstale com `npx get-shit-done-cc@latest`
+
+**Em Docker/container?**
+- Defina `CLAUDE_CONFIG_DIR` antes da instalação:
+
+```bash
+CLAUDE_CONFIG_DIR=/home/youruser/.claude npx get-shit-done-cc --global
+```
+
+### Desinstalar
+
+```bash
+npx get-shit-done-cc --claude --global --uninstall
+npx get-shit-done-cc --opencode --global --uninstall
+npx get-shit-done-cc --gemini --global --uninstall
+npx get-shit-done-cc --codex --global --uninstall
+npx get-shit-done-cc --copilot --global --uninstall
+npx get-shit-done-cc --cursor --global --uninstall
+npx get-shit-done-cc --antigravity --global --uninstall
+```
+
+---
+
+## Community Ports
+
+OpenCode, Gemini CLI e Codex agora são suportados nativamente via `npx get-shit-done-cc`.
+
+| Projeto | Plataforma | Descrição |
+|---------|------------|-----------|
+| [gsd-opencode](https://github.com/rokicool/gsd-opencode) | OpenCode | Adaptação original para OpenCode |
+| gsd-gemini (archived) | Gemini CLI | Adaptação original para Gemini por uberfuzzy |
+
+---
+
+## Star History
+
+<a href="https://star-history.com/#glittercowboy/get-shit-done&Date">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date&theme=dark" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=glittercowboy/get-shit-done&type=Date" />
+ </picture>
+</a>
+
+---
+
+## Licença
+
+Licença MIT. Veja [LICENSE](LICENSE).
+
+---
+
+<div align="center">
+
+**Claude Code é poderoso. O GSD o torna confiável.**
+
+</div>
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -2,7 +2,7 @@

 # GET SHIT DONE

-[English](README.md) · **简体中文** · [日本語](README.ja-JP.md)
+[English](README.md) · [Português](README.pt-BR.md) · **简体中文** · [日本語](README.ja-JP.md)

 **一个轻量但强大的元提示、上下文工程与规格驱动开发系统，适用于 Claude Code、OpenCode、Gemini CLI、Codex、Copilot、Cursor 和 Antigravity。**

--- 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.