diff --git a/README.ja-JP.md b/README.ja-JP.md index fcdc9a5e..079b71c2 100644 --- 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) diff --git a/README.md b/README.md index 2880acc6..d2fb6283 100644 --- 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) diff --git a/README.pt-BR.md b/README.pt-BR.md new file mode 100644 index 00000000..eabc07d7 --- /dev/null +++ b/README.pt-BR.md @@ -0,0 +1,442 @@ +
+ +# 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) + +
+ +```bash +npx get-shit-done-cc@latest +``` + +**Funciona em Mac, Windows e Linux.** + +
+ +![GSD Install](assets/terminal.svg) + +
+ +*"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."* + +
+ +**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) + +
+ +--- + +## 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 +``` + +
+Instalação não interativa (Docker, CI, Scripts) + +```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. + +
+ +### 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 + + Create login endpoint + src/app/api/auth/login/route.ts + + Use jose for JWT (not jsonwebtoken - CommonJS issues). + Validate credentials against users table. + Return httpOnly cookie on success. + + curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie + Valid credentials return cookie, invalid return 401 + +``` + +### 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 ` | 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 ` | 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 ` | 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 + + + + + + Star History Chart + + + +--- + +## Licença + +Licença MIT. Veja [LICENSE](LICENSE). + +--- + +
+ +**Claude Code é poderoso. O GSD o torna confiável.** + +
diff --git a/README.zh-CN.md b/README.zh-CN.md index 86dc4a12..6f609bc9 100644 --- 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。** diff --git a/docs/README.md b/docs/README.md index 53303927..81a78c1f 100644 --- 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 | diff --git a/docs/pt-BR/AGENTS.md b/docs/pt-BR/AGENTS.md new file mode 100644 index 00000000..693ebe8d --- /dev/null +++ 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. diff --git a/docs/pt-BR/ARCHITECTURE.md b/docs/pt-BR/ARCHITECTURE.md new file mode 100644 index 00000000..7bc70ad0 --- /dev/null +++ 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. diff --git a/docs/pt-BR/CLI-TOOLS.md b/docs/pt-BR/CLI-TOOLS.md new file mode 100644 index 00000000..764a92e3 --- /dev/null +++ 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. diff --git a/docs/pt-BR/COMMANDS.md b/docs/pt-BR/COMMANDS.md new file mode 100644 index 00000000..87c81db7 --- /dev/null +++ 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 ` | 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 ` | 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 ` | 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 ` | Adiciona item no backlog (999.x) | +| `/gsd:review-backlog` | Promove, mantém ou remove itens | +| `/gsd:plant-seed ` | 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 +``` diff --git a/docs/pt-BR/CONFIGURATION.md b/docs/pt-BR/CONFIGURATION.md new file mode 100644 index 00000000..3e9bee40 --- /dev/null +++ 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 +``` diff --git a/docs/pt-BR/FEATURES.md b/docs/pt-BR/FEATURES.md new file mode 100644 index 00000000..38292401 --- /dev/null +++ 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. diff --git a/docs/pt-BR/README.md b/docs/pt-BR/README.md new file mode 100644 index 00000000..544481ab --- /dev/null +++ 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. diff --git a/docs/pt-BR/USER-GUIDE.md b/docs/pt-BR/USER-GUIDE.md new file mode 100644 index 00000000..9e598ce7 --- /dev/null +++ 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 ` | Cria workstream isolado | +| `/gsd:workstreams switch ` | Troca workstream ativo | +| `/gsd:workstreams list` | Lista workstreams | +| `/gsd:workstreams complete ` | 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 ` | 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). diff --git a/docs/pt-BR/context-monitor.md b/docs/pt-BR/context-monitor.md new file mode 100644 index 00000000..d77516d0 --- /dev/null +++ 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. diff --git a/docs/pt-BR/superpowers/README.md b/docs/pt-BR/superpowers/README.md new file mode 100644 index 00000000..7618b754 --- /dev/null +++ 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) diff --git 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 new file mode 100644 index 00000000..f8758564 --- /dev/null +++ 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. diff --git 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 new file mode 100644 index 00000000..815eeb00 --- /dev/null +++ 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. diff --git a/docs/pt-BR/workflow-discuss-mode.md b/docs/pt-BR/workflow-discuss-mode.md new file mode 100644 index 00000000..549e7304 --- /dev/null +++ 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.