golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions 3 Packages Projects Releases Wiki Activity

docs: rebrand to GSD Core and restructure docs with Diataxis (#605)

Browse Source 
* chore: wire docs/agents config into AGENTS.md Agent skills section

Add the `## Agent skills` discovery block pointing the engineering
skills at the existing docs/agents/{issue-tracker,triage-labels,domain}.md
files (issue tracker, triage label mapping, single-context domain docs).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: rebrand to GSD Core and restructure docs with Diataxis

Reorganise the root README and docs/ around the Diataxis framework
(tutorials, how-to guides, reference, explanation), add new how-to
guides and schema references (STATE.md / CONTEXT.md / PLAN.md /
planning artifacts), and cross-link the whole set. Update the lone
legacy gsd-build reference to open-gsd; keep internal get-shit-done/
filesystem paths unchanged (directory rename tracked separately in
open-gsd/gsd-core#604). Regenerate the ja-JP, ko-KR, pt-BR and zh-CN
localised trees to mirror the new structure.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs: backfill changeset PR number (#605)

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-06-02 08:13:09 -04:00
committed by GitHub
parent 8c47dcb1c1
commit 3bb2f8f1c5
200 changed files with 46813 additions and 8415 deletions
Download Patch File Download Diff File Expand all files Collapse all files

809
docs/pt-BR/ARCHITECTURE.md
View File

@@ -1,81 +1,780 @@
# Arquitetura do GSD Core
Visão arquitetural do GSD Core (Git. Ship. Done.) em Português.
Para detalhes de implementação linha a linha, consulte [ARCHITECTURE.md em inglês](../ARCHITECTURE.md).
> Arquitetura do sistema para contribuidores e usuários avançados. Para a documentação voltada ao usuário, consulte a [Referência de Funcionalidades](FEATURES.md) ou o [Guia do Usuário](USER-GUIDE.md).
---
## Princípios
## Índice
- **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
- [Visão Geral do Sistema](#visão-geral-do-sistema)
- [Princípios de Design](#princípios-de-design)
- [Arquitetura de Componentes](#arquitetura-de-componentes)
- [Modelo de Agentes](#modelo-de-agentes)
- [Fluxo de Dados](#fluxo-de-dados)
- [Estrutura do Sistema de Arquivos](#estrutura-do-sistema-de-arquivos)
- [Arquitetura do Instalador](#arquitetura-do-instalador)
- [Sistema de Hooks](#sistema-de-hooks)
- [Camada de Ferramentas CLI](#camada-de-ferramentas-cli)
- [Abstração de Runtime](#abstração-de-runtime)
## Componentes centrais
---
1. **Camada de comando**
Recebe entrada do usuário (`/gsd-*`) e roteia fluxo.
## Visão Geral do Sistema
2. **Camada de orquestração**
Coordena pesquisadores, planejadores, executores e verificadores.
O GSD Core é um **framework de meta-prompting** que fica entre o usuário e os agentes de codificação com IA (Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). Ele fornece:
3. **Camada de artefatos**
Mantém `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md`, planos e sumários.
1. **Engenharia de contexto** — Artefatos estruturados que fornecem à IA tudo o que ela precisa por tarefa (consulte [Engenharia de contexto](explanation/context-engineering.md))
2. **Orquestração multi-agente** — Orquestradores leves que criam agentes especializados com janelas de contexto novas (consulte [Orquestração multi-agente](explanation/multi-agent-orchestration.md))
3. **Desenvolvimento orientado por especificações** — Pipeline de Requisitos → pesquisa → planos → execução → verificação
4. **Gerenciamento de estado** — Memória persistente do projeto entre sessões e reinicializações de contexto
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
```
┌──────────────────────────────────────────────────────┐
│ USUÁRIO │
│ /gsd-command [args] │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ CAMADA DE COMANDOS │
│ commands/gsd/*.md — Arquivos de comandos baseados │
│ em prompts (comandos customizados Claude Code / │
│ skills do Codex) │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ CAMADA DE WORKFLOWS │
│ get-shit-done/workflows/*.md — Lógica de │
│ orquestração │
│ (Lê referências, cria agentes, gerencia estado) │
└──────┬──────────────┬─────────────────┬──────────────┘
│ │ │
┌──────▼──────┐ ┌─────▼─────┐ ┌────────▼───────┐
│ AGENTE │ │ AGENTE │ │ AGENTE │
│ (contexto │ │ (contexto│ │ (contexto │
│ novo) │ │ novo) │ │ novo) │
└──────┬──────┘ └─────┬─────┘ └────────┬───────┘
│ │ │
┌──────▼──────────────▼─────────────────▼──────────────┐
│ CAMADA DE FERRAMENTAS CLI │
│ gsd-tools.cjs command families + domain modules │
│ command-routing-hub + observability seams │
└──────────────────────┬───────────────────────────────┘
│
┌──────────────────────▼───────────────────────────────┐
│ SISTEMA DE ARQUIVOS (.planning/) │
│ PROJECT.md | REQUIREMENTS.md | ROADMAP.md │
│ STATE.md | config.json | phases/ | research/ │
└──────────────────────────────────────────────────────┘
```
## 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
## Princípios de Design
## Paralelismo
### 1. Contexto Novo por Agente
- Planos independentes: mesma onda (execução paralela)
- Planos dependentes: ondas posteriores (execução sequencial)
- Conflitos de arquivo: serialização controlada
Cada agente criado por um orquestrador recebe uma janela de contexto limpa (até 200 mil tokens). Isso elimina o desgaste do contexto — a degradação de qualidade que ocorre à medida que uma IA preenche sua janela de contexto com a conversa acumulada.
## Segurança
### 2. Orquestradores Leves
- 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
Os arquivos de workflow (`get-shit-done/workflows/*.md`) nunca fazem trabalho pesado. Eles:
## Runtimes suportados (v1.32)
- Carregam contexto via `gsd-tools.cjs init <workflow>`
- Criam agentes especializados com prompts focados
- Coletam resultados e encaminham para a próxima etapa
- Atualizam o estado entre as etapas
Claude Code, Gemini CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code.
### 3. Estado Baseado em Arquivos
## Extensibilidade
Todo o estado fica em `.planning/` como Markdown e JSON legíveis por humanos. Sem banco de dados, sem servidor, sem dependências externas. Isso significa:
GSD suporta evolução por:
- O estado sobrevive a reinicializações de contexto (`/clear`)
- O estado é inspecionável tanto por humanos quanto por agentes
- O estado pode ser commitado no git para visibilidade da equipe
- novos comandos
- novos tipos de agente
- novos artefatos por fase
- novos gates de qualidade/segurança
### 4. Ausente = Habilitado
Os feature flags de workflow seguem o padrão **ausente = habilitado**. Se uma chave estiver ausente do `config.json`, o padrão é `true`. Os usuários desabilitam funcionalidades explicitamente; não precisam habilitar os padrões.
### 5. Defesa em Profundidade
Múltiplas camadas previnem modos comuns de falha:
- Os planos são verificados antes da execução (agente plan-checker)
- A execução produz commits atômicos por tarefa
- A verificação pós-execução confronta os objetivos da fase
- O UAT fornece verificação humana como portão final
---
> [!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.
## Arquitetura de Componentes
### Comandos (`commands/gsd/*.md`)
Pontos de entrada voltados ao usuário. Cada arquivo contém frontmatter YAML (name, description, allowed-tools) e um corpo de prompt que inicializa o workflow. Os comandos são instalados como:
- **Claude Code:** Comandos slash customizados (forma com hífen, `/gsd-command-name`)
- **OpenCode / Kilo:** Comandos slash (forma com hífen, `/gsd-command-name`)
- **Codex:** Skills (`$gsd-command-name`)
- **Copilot:** Comandos slash (forma com hífen, `/gsd-command-name`)
- **Gemini CLI:** Comandos slash sob o namespace `gsd:` (forma com dois-pontos, `/gsd:command-name`) — o Gemini agrupa todos os comandos customizados sob o id do plugin, portanto a instalação reescreve cada referência no corpo do texto para a forma com dois-pontos
- **Antigravity:** Skills
**Total de comandos:** consulte [`docs/INVENTORY.md`](INVENTORY.md#commands) para a contagem oficial e o roster completo.
#### Roteamento hierárquico em dois estágios (v1.40, [#2792](https://github.com/open-gsd/gsd-core/issues/2792))
Para manter baixo o custo em tokens da listagem de skills antecipada, a v1.40 introduz seis **meta-skills** de namespace (`gsd-workflow`, `gsd-project`, `gsd-quality`, `gsd-context`, `gsd-manage`, `gsd-ideate` — originados de `commands/gsd/ns-*.md`, mas o `name:` invocável é a forma básica mostrada aqui) dispostos acima das sub-skills concretas. O modelo vê 6 roteadores de namespace (~120 tokens) em vez de uma listagem plana de 86 skills (~2.150 tokens), seleciona um namespace e depois roteia para a sub-skill concreta via tabela de roteamento embutida no corpo do roteador de namespace. As skills de namespace são **aditivas** — cada comando concreto ainda é diretamente invocável.
As descrições dos roteadores usam tags de palavras-chave separadas por pipe (≤ 60 caracteres) conforme a pesquisa Tool Attention, que mostra que tags ricas em palavras-chave superam a prosa no roteamento com ~40% do custo em tokens.
#### Interação com o orçamento de tokens do MCP
A listagem de skills antecipada é um dos dois custos recorrentes de tokens por turno. O outro é o schema de ferramenta MCP injetado por cada servidor MCP habilitado em `.claude/settings.json`. Servidores MCP pesados (browser/playwright, Mac-tools, Windows-tools) podem custar mais de 20 mil tokens por turno cada — muitas vezes eclipsando o que o ajuste do `model_profile` economiza. O controle fica no harness do Claude Code (`enabledMcpjsonServers` / `disabledMcpjsonServers` em `.claude/settings.json`) e **não** é uma preocupação do GSD. Juntos, a camada de roteamento em dois estágios (#2792) e o controle criterioso do MCP são as maiores alavancas de custo por turno. Consulte [`docs/USER-GUIDE.md`](USER-GUIDE.md) e `references/context-budget.md` para o checklist de auditoria.
### Workflows (`get-shit-done/workflows/*.md`)
Lógica de orquestração que os comandos referenciam. Contém o processo passo a passo, incluindo:
- Carregamento de contexto via handlers `gsd-tools.cjs init`
- Instruções de criação de agente com resolução de modelo
- Definições de portões/checkpoints
- Padrões de atualização de estado
- Tratamento de erros e recuperação
**Total de workflows:** consulte [`docs/INVENTORY.md`](INVENTORY.md#workflows) para a contagem oficial e o roster completo.
#### Divulgação progressiva para workflows
Os arquivos de workflow são carregados verbatim no contexto do Claude cada vez que o
comando `/gsd-*` correspondente é invocado. Para manter esse custo limitado, o
orçamento de tamanho de workflow aplicado por `tests/workflow-size-budget.test.cjs`
espelha o orçamento de agentes de #2361:
| Tier | Limite de linhas por arquivo |
|-----------|------------------------------|
| `XL` | 1700 — orquestradores de nível superior (`execute-phase`, `plan-phase`, `new-project`) |
| `LARGE` | 1500 — planejadores com múltiplas etapas e workflows de funcionalidades grandes |
| `DEFAULT` | 1000 — workflows simples e de propósito único (o tier alvo) |
`workflows/discuss-phase.md` é mantido em um teto mais restrito de <500 linhas conforme
a issue #2551. Quando um workflow cresce além de seu tier, extraia os corpos por modo
em `workflows/<workflow>/modes/<mode>.md`, templates em
`workflows/<workflow>/templates/`, e conhecimento compartilhado em
`get-shit-done/references/`. O arquivo pai se torna um despachante leve que
lê apenas os arquivos de modo e template necessários para a invocação atual.
`workflows/discuss-phase/` é o exemplo canônico deste padrão —
o pai despacha, modes/ contém o comportamento por flag (`power.md`, `all.md`,
`auto.md`, `chain.md`, `text.md`, `batch.md`, `analyze.md`, `default.md`,
`advisor.md`), e templates/ contém os schemas CONTEXT.md, DISCUSSION-LOG.md e
checkpoint.json que são lidos apenas quando o arquivo de saída correspondente
está sendo escrito.
### Agentes (`agents/*.md`)
Definições de agentes especializados com frontmatter especificando:
- `name` — Identificador do agente
- `description` — Papel e propósito
- `tools` — Acesso às ferramentas permitidas (Read, Write, Edit, Bash, Grep, Glob, WebSearch, etc.)
- `color` — Cor de saída no terminal para distinção visual
**Total de agentes:** 33
### Referências (`get-shit-done/references/*.md`)
Documentos de conhecimento compartilhado que workflows e agentes `@-referenciam` (consulte [`docs/INVENTORY.md`](INVENTORY.md#references-41-shipped) para a contagem oficial e o roster completo):
**Referências principais:**
- `checkpoints.md` — Definições de tipos de checkpoint e padrões de interação
- `gates.md` — 4 tipos canônicos de portões (Confirm, Quality, Safety, Transition) conectados ao plan-checker e ao verifier
- `model-profiles.md` — Atribuições de tier de modelo por agente
- `model-profile-resolution.md` — Documentação do algoritmo de resolução de modelo
- `verification-patterns.md` — Como verificar diferentes tipos de artefatos
- `verification-overrides.md` — Regras de substituição de verificação por artefato
- `planning-config.md` — Schema completo de configuração e comportamento
- `git-integration.md` — Padrões de commit no git, branching e histórico
- `git-planning-commit.md` — Convenções de commit do diretório de planejamento
- `questioning.md` — Filosofia de extração de visão para inicialização de projetos
- `tdd.md` — Padrões de integração de desenvolvimento orientado por testes
- `ui-brand.md` — Padrões de formatação de saída visual
- `common-bug-patterns.md` — Padrões comuns de bugs para revisão de código e verificação
**Referências de workflow:**
- `agent-contracts.md` — Interface formal entre orquestradores e agentes
- `context-budget.md` — Regras de alocação do orçamento da janela de contexto
- `continuation-format.md` — Formato de continuação/retomada de sessão
- `domain-probes.md` — Perguntas de sondagem específicas de domínio para a discuss-phase
- `gate-prompts.md` — Templates de prompt para portões/checkpoints
- `revision-loop.md` — Padrões de iteração de revisão de plano
- `universal-anti-patterns.md` — Anti-padrões comuns a detectar e evitar
- `artifact-types.md` — Definições de tipos de artefatos de planejamento
- `phase-argument-parsing.md` — Convenções de análise de argumentos de fase
- `decimal-phase-calculation.md` — Regras de numeração decimal de sub-fases
- `workstream-flag.md` — Convenções do ponteiro ativo de workstream
- `user-profiling.md` — Metodologia de perfilamento comportamental do usuário
- `thinking-partner.md` — Ativação condicional de parceiro de raciocínio em pontos de decisão
**Referências para modelos de raciocínio:**
Referências para integrar modelos de classe thinking (o3, o4-mini, Gemini 2.5 Pro) aos workflows do GSD:
- `thinking-models-debug.md` — Padrões de modelos de raciocínio para workflows de depuração
- `thinking-models-execution.md` — Padrões de modelos de raciocínio para agentes de execução
- `thinking-models-planning.md` — Padrões de modelos de raciocínio para agentes de planejamento
- `thinking-models-research.md` — Padrões de modelos de raciocínio para agentes de pesquisa
- `thinking-models-verification.md` — Padrões de modelos de raciocínio para agentes de verificação
**Decomposição modular do planner:**
O agente planner (`agents/gsd-planner.md`) foi decomposto de um único arquivo monolítico em um agente central mais módulos de referência para permanecer abaixo do limite de 50 mil caracteres imposto por alguns runtimes:
- `planner-gap-closure.md` — Comportamento do modo de fechamento de lacunas (lê VERIFICATION.md, replanejamento direcionado)
- `planner-reviews.md` — Integração de revisão entre IAs (lê REVIEWS.md do `/gsd-review`)
- `planner-revision.md` — Padrões de revisão de plano para refinamento iterativo
### Templates (`get-shit-done/templates/`)
Templates Markdown para todos os artefatos de planejamento. Usados por `gsd-tools.cjs template fill` / `phase.scaffold` (e `scaffold` de nível superior) para criar arquivos pré-estruturados:
- `project.md`, `requirements.md`, `roadmap.md`, `state.md` — Arquivos principais do projeto
- `phase-prompt.md` — Template de prompt de execução de fase
- `summary.md` (+ `summary-minimal.md`, `summary-standard.md`, `summary-complex.md`) — Templates de resumo com granularidade ajustável
- `DEBUG.md` — Template de acompanhamento de sessão de depuração
- `UI-SPEC.md`, `UAT.md`, `VALIDATION.md` — Templates de verificação especializados
- `discussion-log.md` — Template de trilha de auditoria de discussão
- `codebase/` — Templates de mapeamento de brownfield (stack, architecture, conventions, concerns, structure, testing, integrations)
- `research-project/` — Templates de saída de pesquisa (SUMMARY, STACK, FEATURES, ARCHITECTURE, PITFALLS)
### Hooks (`hooks/`)
Hooks de runtime que se integram ao agente de IA anfitrião:
| Hook | Evento | Propósito |
|------|--------|-----------|
| `gsd-statusline.js` | `statusLine` | Exibe modelo, tarefa, diretório e barra de uso do contexto |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injeta avisos de contexto voltados ao agente em 35%/25% restante |
| `gsd-check-update.js` | `SessionStart` | Gatilho em primeiro plano para a verificação de atualização em segundo plano |
| `gsd-check-update-worker.js` | (auxiliar) | Worker em segundo plano criado por `gsd-check-update.js`; sem registro de evento direto |
| `gsd-prompt-guard.js` | `PreToolUse` | Escaneia escritas em `.planning/` em busca de padrões de injeção de prompt (consultivo) |
| `gsd-read-injection-scanner.js` | `PostToolUse` | Escaneia saídas da ferramenta Read em busca de instruções injetadas em conteúdo não confiável |
| `gsd-workflow-guard.js` | `PreToolUse` | Detecta edições de arquivos fora do contexto de workflow do GSD (consultivo, ativado via `hooks.workflow_guard`) |
| `gsd-read-guard.js` | `PreToolUse` | Guarda consultivo que impede Edit/Write em arquivos ainda não lidos na sessão |
| `gsd-session-state.sh` | `PostToolUse` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `gsd-validate-commit.sh` | `PostToolUse` | Validação de commit para aplicação de commits convencionais |
| `gsd-phase-boundary.sh` | `PostToolUse` | Detecção de limite de fase para transições de workflow |
Consulte [`docs/INVENTORY.md`](INVENTORY.md#hooks-11-shipped) para o roster oficial de 11 hooks.
### Hub de Roteamento de Comandos (`get-shit-done/bin/lib/command-routing-hub.cjs`)
Os roteadores de família de comandos CJS despacham através do `CommandRoutingHub`. O hub possui o contrato de resultado puro sem lançamento de exceções (`hub.dispatch()` captura exceções internas e retorna `{ ok: false, kind, ...typedPayload }`) e a taxonomia fechada de erros de runtime (`UnknownCommand`, `InvalidArgs`, `HandlerRefusal`, `HandlerFailure`). Os adaptadores de roteador permanecem como tradutores CLI leves — eles constroem o hub, chamam `dispatch` e depois mapeiam o Result para chamadas `output()`/`error()`. O runtime é de caminho único (sem seleção de modo de runtime duplo). Consulte `docs/adr/0174-retire-gsd-sdk-package-boundary.md`.
### Ferramentas CLI (`get-shit-done/bin/`)
Utilitário CLI Node.js (`gsd-tools.cjs`) com módulos de domínio distribuídos em `get-shit-done/bin/lib/` (consulte [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) para o roster oficial):
| Módulo | Responsabilidade |
| ---------------------- | ----------------------------------------------------------------------------------------------------- |
| `core.cjs` | Tratamento de erros, formatação de saída, utilitários compartilhados; re-exportações de compatibilidade para helpers de planejamento |
| `planning-workspace.cjs` | Camada de planejamento (`planningDir`, `planningPaths`, roteamento de workstream ativo, `.planning/.lock`) |
| `state.cjs` | Análise, atualização, progressão e métricas do STATE.md |
| `phase.cjs` | Operações de diretório de fase, numeração decimal, indexação de planos |
| `roadmap.cjs` | Análise do ROADMAP.md, extração de fases, progresso do plano |
| `config.cjs` | Leitura/escrita do config.json, inicialização de seções |
| `verify.cjs` | Estrutura do plano, integridade de fase, referência, validação de commit |
| `template.cjs` | Seleção e preenchimento de template com substituição de variáveis |
| `frontmatter.cjs` | Operações CRUD de frontmatter YAML |
| `init.cjs` | Carregamento composto de contexto para cada tipo de workflow |
| `milestone.cjs` | Arquivamento de milestones, marcação de requisitos |
| `commands.cjs` | Comandos diversos (slug, timestamp, todos, scaffolding, stats) |
| `model-profiles.cjs` | Tabela de resolução de perfis de modelo |
| `security.cjs` | Prevenção de path traversal, detecção de injeção de prompt, análise segura de JSON, validação de argumentos de shell |
| `uat.cjs` | Análise de arquivo UAT, rastreamento de débito de verificação, suporte a audit-uat |
| `docs.cjs` | Inicialização do workflow de atualização de docs, escaneamento de Markdown, detecção de monorepo |
| `workstream.cjs` | CRUD de workstream, migração, ponteiro ativo com escopo de sessão |
| `schema-detect.cjs` | Detecção de desvio de schema para padrões ORM (Prisma, Drizzle, etc.) |
| `profile-pipeline.cjs` | Pipeline de dados de perfilamento comportamental do usuário, escaneamento de arquivos de sessão |
| `profile-output.cjs` | Renderização de perfil, geração de USER-PROFILE.md e dev-preferences.md |
---
## Modelo de Agentes
### Padrão Orquestrador → Agente
```
Orquestrador (workflow .md)
│
├── Carregar contexto: gsd-tools.cjs init <workflow> <phase>
│ Retorna JSON com: informações do projeto, config, estado, detalhes da fase
│
├── Resolver modelo: gsd-tools.cjs resolve-model <agent-name>
│ Retorna: opus | sonnet | haiku | inherit
│
├── Criar Agente (chamada Task/SubAgent)
│ ├── Prompt do agente (agents/*.md)
│ ├── Payload de contexto (JSON do init)
│ ├── Atribuição de modelo
│ └── Permissões de ferramentas
│
├── Coletar resultado
│
└── Atualizar estado: gsd-tools.cjs state update / state patch / state advance-plan
```
### Categorias Principais de Criação de Agentes
Taxonomia conceitual de padrões de criação para os 21 agentes primários. Para o roster oficial de 31 agentes (incluindo os 10 agentes avançados/especializados como `gsd-pattern-mapper`, `gsd-code-reviewer`, `gsd-code-fixer`, `gsd-ai-researcher`, `gsd-domain-researcher`, `gsd-eval-planner`, `gsd-eval-auditor`, `gsd-framework-selector`, `gsd-debug-session-manager`, `gsd-intel-updater`), consulte [`docs/INVENTORY.md`](INVENTORY.md#agents-31-shipped).
| Categoria | Agentes | Paralelismo |
| ---------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Pesquisadores** | gsd-project-researcher, gsd-phase-researcher, gsd-ui-researcher, gsd-advisor-researcher | 4 paralelos (stack, features, architecture, pitfalls); advisor criado durante a discuss-phase |
| **Sintetizadores** | gsd-research-synthesizer | Sequencial (após a conclusão dos pesquisadores) |
| **Planejadores** | gsd-planner, gsd-roadmapper | Sequencial |
| **Verificadores de plano** | gsd-plan-checker, gsd-integration-checker, gsd-ui-checker, gsd-nyquist-auditor | Sequencial (loop de verificação, máximo 3 iterações) |
| **Executores** | gsd-executor | Paralelo dentro de ondas, sequencial entre ondas |
| **Verificadores** | gsd-verifier | Sequencial (após a conclusão de todos os executores) |
| **Mapeadores** | gsd-codebase-mapper | 4 paralelos (tech, arch, quality, concerns) |
| **Depuradores** | gsd-debugger | Sequencial (interativo) |
| **Auditores** | gsd-ui-auditor, gsd-security-auditor | Sequencial |
| **Escritores de doc** | gsd-doc-writer, gsd-doc-verifier | Sequencial (escritor depois verificador) |
| **Perfiladores** | gsd-user-profiler | Sequencial |
| **Analisadores** | gsd-assumptions-analyzer | Sequencial (durante a discuss-phase) |
### Modelo de Execução em Ondas
Durante a `execute-phase`, os planos são agrupados em ondas de dependência:
```
Análise de Ondas:
Plano 01 (sem deps) ─┐
Plano 02 (sem deps) ─┤── Onda 1 (paralelo)
Plano 03 (depende: 01) ─┤── Onda 2 (aguarda a Onda 1)
Plano 04 (depende: 02) ─┘
Plano 05 (depende: 03,04) ── Onda 3 (aguarda a Onda 2)
```
Cada executor recebe:
- Janela de contexto nova de 200 mil tokens (ou até 1 M para modelos que suportam)
- O PLAN.md específico a executar
- Contexto do projeto (PROJECT.md, STATE.md)
- Contexto da fase (CONTEXT.md, RESEARCH.md se disponível)
### Enriquecimento Adaptativo de Contexto (Modelos de 1 M)
Quando a janela de contexto tem 500 mil tokens ou mais (modelos classe 1 M como Opus 4.6, Sonnet 4.6), os prompts de subagentes são automaticamente enriquecidos com contexto adicional que não caberia em janelas de 200 mil tokens padrão:
- **Agentes executores** recebem os arquivos SUMMARY.md de ondas anteriores e o CONTEXT.md/RESEARCH.md da fase, possibilitando consciência entre planos dentro de uma fase
- **Agentes verificadores** recebem todos os arquivos PLAN.md, SUMMARY.md, CONTEXT.md mais REQUIREMENTS.md, possibilitando verificação com consciência do histórico
O orquestrador lê `context_window` da configuração (`gsd-tools.cjs config-get context_window`) e inclui condicionalmente um contexto mais rico quando o valor é >= 500.000. Para janelas de 200 mil tokens padrão, os prompts usam versões truncadas com ordenação favorável ao cache para maximizar a eficiência do contexto.
#### Segurança de Commits Paralelos
Quando múltiplos executores rodam dentro da mesma onda, dois mecanismos previnem conflitos:
1. Commits `--no-verify` — Agentes paralelos pulam hooks de pré-commit (que podem causar contenção de lock de build, por exemplo, disputas de cargo lock em projetos Rust). O orquestrador executa `git hook run pre-commit` uma vez após a conclusão de cada onda.
2. **Bloqueio de arquivo STATE.md** — Todas as chamadas `writeStateMd()` usam exclusão mútua baseada em lockfile (`STATE.md.lock` com criação atômica `O_EXCL`). Isso previne a condição de corrida leitura-modificação-escrita onde dois agentes leem o STATE.md, modificam campos diferentes, e o último a escrever sobrescreve as alterações do outro. Inclui detecção de lock obsoleto (timeout de 10 s) e espera em spin com jitter.
---
## Fluxo de Dados
### Fluxo de Novo Projeto
```
Entrada do usuário (descrição da ideia)
│
▼
Perguntas (filosofia questioning.md)
│
▼
4x Pesquisadores de Projeto (paralelo)
├── Stack → STACK.md
├── Features → FEATURES.md
├── Architecture → ARCHITECTURE.md
└── Pitfalls → PITFALLS.md
│
▼
Sintetizador de Pesquisa → SUMMARY.md
│
▼
Extração de requisitos → REQUIREMENTS.md
│
▼
Roadmapper → ROADMAP.md
│
▼
Aprovação do usuário → STATE.md inicializado
```
### Fluxo de Execução de Fase
```
discuss-phase → CONTEXT.md (preferências do usuário)
│
▼
ui-phase → UI-SPEC.md (contrato de design, opcional)
│
▼
plan-phase
├── Portão de pesquisa (bloqueia se RESEARCH.md tiver perguntas abertas não resolvidas)
├── Pesquisador de Fase → RESEARCH.md
│ └── Portão de Legitimidade de Pacotes: slopcheck em cada pacote; [SLOP] removido,
│ [SUS]/[ASSUMED] sinalizados; tabela de Auditoria escrita no RESEARCH.md
├── Planner (com verificação de alcançabilidade) → arquivos PLAN.md
│ └── checkpoint:human-verify injetado antes de instalações [ASSUMED]/[SUS];
│ linha STRIDE T-{phase}-SC adicionada para planos com instalação
├── Plan Checker → Loop de verificação (máximo 3x)
├── Portão de cobertura de requisitos (REQ-IDs → planos)
└── Portão de cobertura de decisões (CONTEXT.md `<decisions>` → planos, BLOQUEANTE — #2492)
│
▼
state planned-phase → STATE.md (Planned/Ready to execute)
│
▼
execute-phase (redução de contexto: prompts truncados, ordenação favorável ao cache)
├── Análise de ondas (agrupamento por dependência)
├── Executor por plano → código + commits atômicos
├── SUMMARY.md por plano
└── Verifier → VERIFICATION.md
└── Portão de cobertura de decisões (decisões do CONTEXT.md → artefatos entregues, NÃO BLOQUEANTE — #2492)
│
▼
verify-work → UAT.md (testes de aceitação do usuário)
│
▼
ui-review → UI-REVIEW.md (auditoria visual, opcional)
```
### Propagação de Contexto
Cada estágio de workflow produz artefatos que alimentam as etapas subsequentes:
```
PROJECT.md ────────────────────────────────────────────► Todos os agentes
REQUIREMENTS.md ───────────────────────────────────────► Planner, Verifier, Auditor
ROADMAP.md ────────────────────────────────────────────► Orquestradores
STATE.md ──────────────────────────────────────────────► Todos os agentes (decisões, bloqueadores)
CONTEXT.md (por fase) ─────────────────────────────────► Researcher, Planner, Executor
RESEARCH.md (por fase) ────────────────────────────────► Planner, Plan Checker
PLAN.md (por plano) ───────────────────────────────────► Executor, Plan Checker
SUMMARY.md (por plano) ────────────────────────────────► Verifier, rastreamento de estado
UI-SPEC.md (por fase) ─────────────────────────────────► Executor, UI Auditor
```
---
## Estrutura do Sistema de Arquivos
### Arquivos de Instalação
```
~/.claude/ # Claude Code (instalação global)
├── skills/gsd-*/SKILL.md # Skills globais (roster oficial: docs/INVENTORY.md)
├── commands/gsd/*.md # Instalações locais do Claude usam slash commands em vez de skills globais
├── get-shit-done/
│ ├── bin/gsd-tools.cjs # Utilitário CLI
│ ├── bin/lib/*.cjs # Módulos de domínio (roster oficial: docs/INVENTORY.md)
│ ├── workflows/*.md # Definições de workflow (roster oficial: docs/INVENTORY.md)
│ ├── references/*.md # Docs de referência compartilhados (roster oficial: docs/INVENTORY.md)
│ └── templates/ # Templates de artefatos de planejamento
├── agents/*.md # Definições de agentes (roster oficial: docs/INVENTORY.md)
├── hooks/*.js # Hooks Node.js (statusline, guards, monitors, verificação de atualização)
├── hooks/*.sh # Hooks shell (estado de sessão, validação de commit, limite de fase)
├── settings.json # Registros de hooks
└── VERSION # Número da versão instalada
```
Caminhos equivalentes para outros runtimes:
- **OpenCode:** `~/.config/opencode/` global ou `./.opencode/` local
- **Kilo:** `~/.config/kilo/` global ou `./.kilo/` local
- **Gemini CLI:** `~/.gemini/` global ou `./.gemini/` local
- **Codex:** `~/.codex/` global ou `./.codex/` local
- **Copilot:** `~/.copilot/` global ou `./.github/` local
- **Antigravity:** raiz global detectada automaticamente (`~/.gemini/antigravity/`, `~/.gemini/antigravity-ide/`, ou `~/.gemini/antigravity-cli/`) ou `./.agent/` local
- **Cursor:** `~/.cursor/` global ou `./.cursor/` local
- **Windsurf:** `~/.codeium/windsurf/` global ou `./.windsurf/` local
- **Augment Code:** `~/.augment/` global ou `./.augment/` local
- **Trae:** `~/.trae/` global ou `./.trae/` local
- **Qwen Code:** `~/.qwen/` global ou `./.qwen/` local
- **Hermes Agent:** `~/.hermes/` global ou `./.hermes/` local
- **CodeBuddy:** `~/.codebuddy/` global ou `./.codebuddy/` local
- **Cline:** `~/.cline/` global ou `.clinerules` local na raiz do projeto
### Arquivos do Projeto (`.planning/`)
```
.planning/
├── PROJECT.md # Visão do projeto, restrições, decisões, regras de evolução
├── REQUIREMENTS.md # Requisitos com escopo (v1/v2/fora do escopo)
├── ROADMAP.md # Detalhamento de fases com rastreamento de status
├── STATE.md # Memória viva: posição, decisões, bloqueadores, métricas
├── config.json # Configuração de workflow
├── MILESTONES.md # Arquivo de milestones concluídos
├── research/ # Pesquisa de domínio do /gsd-new-project
│ ├── SUMMARY.md
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ └── PITFALLS.md
├── codebase/ # Mapeamento de brownfield (do /gsd-map-codebase)
│ ├── STACK.md # Frontmatter YAML carrega `last_mapped_commit`
│ ├── ARCHITECTURE.md # para o portão de desvio pós-execução (#2003)
│ ├── CONVENTIONS.md
│ ├── CONCERNS.md
│ ├── STRUCTURE.md
│ ├── TESTING.md
│ └── INTEGRATIONS.md
├── phases/
│ └── XX-phase-name/
│ ├── XX-CONTEXT.md # Preferências do usuário (da discuss-phase)
│ ├── XX-RESEARCH.md # Pesquisa de ecossistema (da plan-phase)
│ ├── XX-YY-PLAN.md # Planos de execução
│ ├── XX-YY-SUMMARY.md # Resultados de execução
│ ├── XX-VERIFICATION.md # Verificação pós-execução
│ ├── XX-VALIDATION.md # Mapeamento de cobertura de testes Nyquist
│ ├── XX-UI-SPEC.md # Contrato de design de UI (da ui-phase)
│ ├── XX-UI-REVIEW.md # Pontuações de auditoria visual (da ui-review)
│ └── XX-UAT.md # Resultados de testes de aceitação do usuário
├── quick/ # Rastreamento de tarefas rápidas
│ └── YYMMDD-xxx-slug/
│ ├── PLAN.md
│ └── SUMMARY.md
├── todos/
│ ├── pending/ # Ideias capturadas
│ └── done/ # Todos concluídos
├── threads/ # Threads de contexto persistentes (do /gsd-thread)
├── seeds/ # Ideias prospectivas (do /gsd-capture --seed)
├── debug/ # Sessões de depuração ativas
│ ├── *.md # Sessões ativas
│ ├── resolved/ # Sessões arquivadas
│ └── knowledge-base.md # Aprendizados persistentes de depuração
├── ui-reviews/ # Screenshots do /gsd-ui-review (ignoradas pelo git)
└── continue-here.md # Handoff de contexto (do pause-work)
```
### Portão de Desvio de Código Base Pós-Execução (#2003)
Após a última onda de commits do `/gsd-execute-phase`, o workflow executa uma
etapa `codebase_drift_gate` não bloqueante (entre `schema_drift_gate` e
`verify_phase_goal`). Ele compara o diff `last_mapped_commit..HEAD`
contra `.planning/codebase/STRUCTURE.md` e conta quatro tipos de
elementos estruturais:
1. Novos diretórios fora dos caminhos mapeados
2. Novas exportações barrel em `(packages|apps)/<name>/src/index.*`
3. Novos arquivos de migração
4. Novos módulos de rota em `routes/` ou `api/`
Se a contagem atingir `workflow.drift_threshold` (padrão 3), o portão
**avisa** (padrão) com o comando `/gsd-map-codebase --paths …` sugerido,
ou **remapeia automaticamente** (`workflow.drift_action = auto-remap`) criando
`gsd-codebase-mapper` com escopo para os caminhos afetados. Qualquer erro na detecção
ou remapeamento é registrado e a fase continua — a detecção de desvio não pode falhar
a verificação.
`last_mapped_commit` fica no frontmatter YAML no topo de cada
arquivo `.planning/codebase/*.md`; `bin/lib/drift.cjs` fornece
os helpers de ida e volta `readMappedCommit` e `writeMappedCommit`.
---
## Arquitetura do Instalador
O instalador (`bin/install.js`, ~10.700 linhas) trata de:
1. **Detecção de runtime** — Prompt interativo ou flags CLI (`--claude`, `--opencode`, `--gemini`, `--kilo`, `--codex`, `--copilot`, `--antigravity`, `--cursor`, `--windsurf`, `--augment`, `--trae`, `--qwen`, `--hermes`, `--codebuddy`, `--cline`, `--all`)
2. **Seleção de local** — Global (`--global`) ou local (`--local`)
3. **Implantação de arquivos** — Copia comandos, skills, workflows, referências, templates, agentes e hooks
4. **Adaptação de runtime** — Transforma o conteúdo de arquivos por runtime:
- Claude Code: Usa como está
- OpenCode: Converte comandos/agentes para o formato de comando plano + subagente compatível com OpenCode
- Kilo: Reutiliza o pipeline de conversão do OpenCode com os caminhos de configuração do Kilo
- Codex: Gera config TOML + skills a partir de comandos
- Copilot: Mapeia nomes de ferramentas (Read→read, Bash→execute, etc.)
- Gemini: Ajusta nomes de eventos de hook (`AfterTool` em vez de `PostToolUse`)
- Antigravity: Skills em primeiro lugar com equivalentes de modelo do Google
- Cursor: Skills em primeiro lugar com referências de regras do Cursor
- Windsurf: Skills em primeiro lugar com referências de regras do Windsurf
- Trae: Instalação skills-first em `~/.trae` / `./.trae` sem `settings.json` ou integração de hooks
- Qwen Code: Skills em primeiro lugar com reescritas de caminho e prompt com marca Qwen
- Hermes Agent: Skills por categoria em `skills/gsd/`
- CodeBuddy: Skills em primeiro lugar com reescritas de caminho e prompt do CodeBuddy
- Cline: Escreve `.clinerules` para integração baseada em regras
- Augment Code: Skills em primeiro lugar com conversão completa de skills e gerenciamento de configuração
5. **Normalização de caminhos** — Substitui caminhos `~/.claude/` por caminhos específicos do runtime
6. **Integração de configurações** — Registra hooks no `settings.json` do runtime
7. **Backup de patches** — Desde a v1.17, faz backup de arquivos modificados localmente em `gsd-local-patches/` para `/gsd-update --reapply`
8. **Rastreamento de manifesto** — Escreve `gsd-file-manifest.json` para desinstalação limpa
9. **Modo de desinstalação** — `--uninstall` remove todos os arquivos, hooks e configurações do GSD
Movimentações de arquivos no momento da instalação, limpeza de artefatos obsoletos, reescritas de configuração e
preservação de dados do usuário são governadas pelo Módulo de Migração do Instalador. Consulte
[Migrações do Instalador](../installer-migrations.md) e
[ADR 0008](../adr/0008-installer-migration-module.md).
O módulo de migração também controla o escaneamento de linha de base inicial condicionado para
instalações legadas, classificando as superfícies de instalação de runtime conhecidas antes que migrações posteriores
removam ou reescrevam qualquer coisa.
O guarda de desvio de plano (`plan_review.source_grounding`) — que verifica referências de símbolos em planos gerados contra o código-fonte ativo antes da execução — é especificado no [ADR 22](../adr/22-plan-drift-guard.md).
### Tratamento de Plataforma
- **Windows:** `windowsHide` em processos filho, proteção EPERM/EACCES em diretórios protegidos, normalização de separador de caminho
- **WSL:** Detecta o Node.js do Windows rodando no WSL e avisa sobre incompatibilidades de caminho
- **Docker/CI:** Suporta a variável de ambiente `CLAUDE_CONFIG_DIR` para locais de diretório de configuração personalizados
---
## Sistema de Hooks
### Arquitetura
```
Motor de Runtime (Claude Code / Gemini CLI)
│
├── evento statusLine ──► gsd-statusline.js
│ Lê: stdin (JSON de sessão)
│ Escreve: stdout (status formatado), /tmp/claude-ctx-{session}.json (bridge)
│
├── evento PostToolUse/AfterTool ──► gsd-context-monitor.js
│ Lê: stdin (JSON de evento de ferramenta), /tmp/claude-ctx-{session}.json (bridge)
│ Escreve: stdout (hookSpecificOutput com aviso additionalContext)
│
└── evento SessionStart ──► gsd-check-update.js
Lê: arquivo VERSION
Escreve: ~/.claude/cache/gsd-update-check.json (cria processo em segundo plano)
```
### Limites do Monitor de Contexto
| Contexto Restante | Nível | Comportamento do Agente |
| ----------------- | -------- | ------------------------------------------------ |
| > 35% | Normal | Nenhum aviso injetado |
| ≤ 35% | AVISO | "Evite iniciar trabalho complexo novo" |
| ≤ 25% | CRÍTICO | "Contexto quase esgotado, informe o usuário" |
Debounce: 5 usos de ferramenta entre avisos repetidos. A escalada de severidade (AVISO→CRÍTICO) contorna o debounce.
### Propriedades de Segurança
- Todos os hooks encapsulam em try/catch, saem silenciosamente em caso de erro
- Guarda de timeout de stdin (3 s) evita travamento em problemas de pipe
- Métricas obsoletas (> 60 s) são ignoradas
- Arquivos bridge ausentes são tratados graciosamente (subagentes, sessões novas)
- O monitor de contexto é consultivo — nunca emite comandos imperativos que substituam as preferências do usuário
### Portão de Legitimidade de Pacotes (v1.42.1)
O pipeline pesquisador → planner → executor inclui um portão de cadeia de suprimentos contra slopsquatting (nomes de pacotes alucinados por IA pré-registrados com scripts pós-instalação maliciosos).
**Modelo de ameaça:** O GSD automatiza o caminho completo de "pesquisador nomeia um pacote" a "executor executa `npm install`". Um nome alucinado que passa pelo `npm view` (provando apenas o registro, não a legitimidade) anteriormente fluía sem ser detectado. ~20% das referências de pacotes geradas por IA são alucinadas; ~43% desses nomes recorrem consistentemente entre prompts, tornando o pré-registro economicamente viável para atacantes.
**Camadas do portão:**
| Camada | Componente | Ação |
|--------|------------|------|
| Pesquisa | `gsd-phase-researcher` | Executa `slopcheck install <pkgs> --json`; escreve tabela `## Package Legitimacy Audit` no RESEARCH.md; remove pacotes `[SLOP]` antes de o RESEARCH.md ser escrito |
| Planejamento | `gsd-planner` | Lê a tabela de Auditoria; insere `checkpoint:human-verify` antes de qualquer tarefa de instalação `[ASSUMED]` ou `[SUS]`; adiciona linha STRIDE `T-{phase}-SC` supply-chain ao `<threat_model>` |
| Execução | `gsd-executor` | REGRA 3 exclui a instalação de pacotes do escopo de correção automática; instalações com falha surgem como checkpoints, nunca substituições silenciosas |
**Integração de proveniência de afirmações:** Nomes de pacotes descobertos via WebSearch são marcados como `[ASSUMED]` (não `[VERIFIED]`) independentemente do resultado do `npm view`. Isso estende o sistema de proveniência `[ASSUMED]` / `[VERIFIED]` / `[CITED]` existente, aplicando a tag de proveniência como um portão rígido no limite de instalação — `[ASSUMED]` sempre gera um `checkpoint:human-verify` no PLAN.md.
**Cobertura de ecossistemas:** O pesquisador usa comandos de verificação específicos de registro — `npm view` (Node), `pip index versions` (Python), `cargo search` (Rust) — em vez de uma única verificação genérica. Isso captura alucinações entre ecossistemas (taxa de ~9% documentada em pesquisa USENIX de 2025).
**Degradação graceful:** Se o `slopcheck` não estiver disponível, cada pacote recomendado é marcado como `[ASSUMED]` e condicionado com um checkpoint. Pesquisa e planejamento prosseguem; o sistema nunca falha definitivamente por dependência de ferramenta ausente.
**Dependência externa:** `slopcheck` (MIT, instalável via pip). Se abandonado, o fallback do portão `[ASSUMED]` mantém a cobertura de checkpoint humano.
---
### Hooks de Segurança (v1.27)
Para uma visão geral conceitual de como as camadas de hook e guarda se encaixam na abordagem de segurança mais ampla, consulte [Modelo de segurança](explanation/security-model.md).
**Prompt Guard** (`gsd-prompt-guard.js`):
- Acionado em Write/Edit para arquivos `.planning/`
- Escaneia o conteúdo em busca de padrões de injeção de prompt (substituição de papel, bypass de instrução, injeção de tag de sistema)
- Apenas consultivo — registra a detecção, não bloqueia
- Padrões são embutidos (subconjunto de `security.cjs`) para independência do hook
**Workflow Guard** (`gsd-workflow-guard.js`):
- Acionado em Write/Edit para arquivos fora de `.planning/`
- Detecta edições fora do contexto de workflow do GSD (sem comando `/gsd-` ativo ou subagente Task)
- Aconselha o uso de `/gsd-quick` ou `/gsd-fast` para alterações rastreadas por estado
- Ativado via `hooks.workflow_guard: true` (padrão: false)
---
## Abstração de Runtime
O GSD suporta múltiplos runtimes de codificação com IA por meio de uma arquitetura unificada de comandos/workflows:
### Matriz de Contrato de Instalação por Runtime
Esta matriz descreve as superfícies de runtime que o instalador materializa hoje.
A propriedade específica de migração e os snapshots de fonte vivem em
[Migrações do Instalador](../installer-migrations.md#runtime-configuration-contract-registry).
| Runtime | Raiz global | Raiz local | Superfície de invocação | Superfície de agente | Configuração e hooks |
| --- | --- | --- | --- | --- | --- |
| Claude Code | `~/.claude` | `./.claude` | `skills/gsd-*/SKILL.md` global; `commands/gsd/*.md` local | `agents/gsd-*.md` | Entradas de hook e statusLine em `settings.json` |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/gsd-*.md` | `agents/gsd-*.md` | `opencode.json` ou `opencode.jsonc`; sem hooks do GSD |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/gsd-*.md` | `agents/gsd-*.md` | `kilo.json` ou `kilo.jsonc`; sem hooks do GSD |
| Gemini CLI | `~/.gemini` | `./.gemini` | `commands/gsd/*.toml` | `agents/gsd-*.md` | flag de funcionalidade, hooks e statusline em `settings.json` |
| Codex | `~/.codex` | `./.codex` | `skills/gsd-*/SKILL.md` | markdown de origem de agentes mais TOML por agente | `config.toml` `[agents.gsd-*]`, `[features].hooks` (canônico; alias legado `codex_hooks` é reconhecido e migrado no reinstall, #3566) e tabelas de hooks |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/gsd-*/SKILL.md` e `copilot-instructions.md` | arquivos `.agent.md` | Sem hooks ou statusline do GSD |
| Antigravity | detectado automaticamente: `~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, ou `~/.gemini/antigravity-cli` | `./.agent` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Entradas de hook `settings.json` no estilo Gemini quando instalado pelo GSD |
| Cursor | `~/.cursor` | `./.cursor` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Referências de regras em `rules/`; sem hooks do GSD |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Referências de regras em `rules/`; sem hooks do GSD |
| Augment Code | `~/.augment` | `./.augment` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Sem hooks ou statusline do GSD |
| Trae | `~/.trae` | `./.trae` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Referências de regras em `rules/`; sem hooks do GSD |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Configurações comuns do GSD e entradas de hook onde suportado |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/gsd/DESCRIPTION.md` mais `skills/gsd/gsd-*/SKILL.md` | `agents/gsd-*.md` | Configurações comuns do GSD e entradas de hook onde suportado |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/gsd-*/SKILL.md` | `agents/gsd-*.md` | Configurações comuns do GSD e entradas de hook onde suportado |
| Cline | `~/.cline` | raiz do projeto | `.clinerules` | Somente regras | Sem hooks ou statusline do GSD |
### Fontes do Contrato Upstream
As expectativas de instalação por runtime são verificadas contra documentação primária quando
disponível. O snapshot de fonte atual é 2026-05-11:
- Claude Code: Documentação de comandos slash, configurações, hooks e subagentes da Anthropic.
- OpenCode e Kilo: Documentação de configuração do OpenCode e documentação de subagente customizado do Kilo.
- Gemini CLI e Qwen Code: Documentação de comandos/configuração; a documentação de comandos do Qwen foi atualizada pela última vez em 2026-05-06.
- Codex: Documentação do OpenAI Codex e `config-schema.json`; o instalador também carrega compatibilidade com o Codex 0.124.0 para o formato de tabela de agentes.
- Copilot, Cursor, Cline, Augment, Hermes e CodeBuddy: Documentação do fornecedor para instruções customizadas, regras, skills ou configuração.
- Antigravity, Windsurf e Trae: Linhas com fontes limitadas. O instalador documenta os shims de compatibilidade atuais, e as migrações devem atualizar essas fontes antes de reescrever sua configuração.
### Pontos de Abstração
1. **Mapeamento de nomes de ferramentas** — Cada runtime tem seus próprios nomes de ferramentas (ex.: `Bash` do Claude → `execute` do Copilot)
2. **Nomes de eventos de hook** — Claude usa `PostToolUse`, Gemini usa `AfterTool`
3. **Frontmatter de agente** — Cada runtime tem seu próprio formato de definição de agente
4. **Convenções de caminho** — Cada runtime armazena a configuração em diretórios diferentes
5. **Referências de modelo** — O perfil `inherit` permite que o GSD adie para a seleção de modelo do runtime
O instalador trata de toda a tradução no momento da instalação. Workflows e agentes são escritos no formato nativo do Claude Code e transformados durante a implantação.
---
## Relacionados
- [Orquestração multi-agente](explanation/multi-agent-orchestration.md)
- [Modelo de segurança](explanation/security-model.md)
- [Ferramentas CLI](CLI-TOOLS.md)
- [Índice de documentação](README.md)

530
docs/pt-BR/CLI-TOOLS.md
View File

@@ -1,72 +1,502 @@
# Referência de Ferramentas CLI
# Referência de Ferramentas CLI do GSD
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) — inclui a secção de uso de `gsd-tools.cjs query`.
> Referência para o CLI `gsd-tools` (`get-shit-done/bin/gsd-tools.cjs`). Para comandos slash e fluxos de usuário, consulte a [Referência de Comandos](COMMANDS.md). Voltar ao [índice de documentação](README.md).
---
## Objetivo
## Visão Geral
As ferramentas CLI permitem que comandos e agentes do GSD executem ações padronizadas de:
`gsd-tools.cjs` centraliza a análise de configuração, resolução de modelos, busca de fases, commits git, verificação de resumos, gerenciamento de estado e operações de templates em comandos, fluxos de trabalho e agentes do GSD.
- 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
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Caminho instalado** | `get-shit-done/bin/gsd-tools.cjs` |
| **Implementação** | 20 módulos de domínio em `get-shit-done/bin/lib/` (o diretório é autoritativo) |
| **Status** | Principal superfície de comandos em tempo de execução para orquestração, fluxos de trabalho e automação. |
### Projeto e estado
- inicialização de artefatos (`PROJECT`, `REQUIREMENTS`, `ROADMAP`, `STATE`)
- atualização de estado por fase
- controle de milestones
**Uso (CJS):**
### Planejamento
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
- criação de planos atômicos
- validação pré-execução
- consolidação de pesquisa
**Flags globais (CJS):**
### Execução
- despacho de tarefas por onda
- persistência de sumários
- checkpoints de progresso
| Flag | Descrição |
| -------------- | ---------------------------------------------------------------------------- |
| `--raw` | Saída legível por máquina (JSON ou texto simples, sem formatação) |
| `--cwd <path>` | Substitui o diretório de trabalho (para subagentes em sandbox) |
| `--ws <name>` | Contexto de fluxo de trabalho para caminhos `.planning/workstreams/<name>` |
### 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)
## Comandos de Estado
```text
Ler contexto do projeto
-> montar input da etapa
-> executar ferramenta CLI
-> persistir artefatos
-> atualizar estado/roadmap
-> retornar resumo para o orquestrador
Gerencia `.planning/STATE.md` — a memória viva do projeto.
```bash
# Carrega configuração completa do projeto + estado como JSON
node gsd-tools.cjs state load
# Exibe o frontmatter do STATE.md como JSON
node gsd-tools.cjs state json
# Atualiza um único campo
node gsd-tools.cjs state update <field> <value>
# Obtém o conteúdo do STATE.md ou uma seção específica
node gsd-tools.cjs state get [section]
# Atualiza múltiplos campos em lote
node gsd-tools.cjs state patch --field1 val1 --field2 val2
# Incrementa o contador de planos
node gsd-tools.cjs state advance-plan
# Registra métricas de execução
node gsd-tools.cjs state record-metric --phase N --plan M --duration Xmin [--tasks N] [--files N]
# Recalcula a barra de progresso
node gsd-tools.cjs state update-progress
# Adiciona uma decisão
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
# Ou a partir de arquivos:
node gsd-tools.cjs state add-decision --summary-file path [--rationale-file path]
# Adiciona/resolve bloqueadores
node gsd-tools.cjs state add-blocker --text "..."
node gsd-tools.cjs state resolve-blocker --text "..."
# Registra continuidade da sessão
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
# Início de fase — atualiza Status/Última atividade do STATE.md para uma nova fase
node gsd-tools.cjs state begin-phase --phase N --name SLUG --plans COUNT
# Sinalização de bloqueador detectável por agentes (usado por discuss-phase / fluxos de UI)
node gsd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node gsd-tools.cjs state signal-resume
```
### Snapshot de Estado
Análise estruturada do STATE.md completo:
```bash
node gsd-tools.cjs state-snapshot
```
Retorna JSON com: posição atual, fase, plano, status, decisões, bloqueadores, métricas, última atividade.
---
## Comandos de Fase
Gerencia fases — diretórios, numeração e sincronização com o roadmap.
```bash
# Localiza diretório de fase pelo número
node gsd-tools.cjs find-phase <phase>
# Calcula o próximo número de fase decimal para inserções
node gsd-tools.cjs phase next-decimal <phase>
# Adiciona nova fase ao roadmap + cria diretório
node gsd-tools.cjs phase add <description>
# Insere fase decimal após a existente
node gsd-tools.cjs phase insert <after> <description>
# Remove fase, renumera as subsequentes
node gsd-tools.cjs phase remove <phase> [--force]
# Marca a fase como concluída, atualiza estado + roadmap
node gsd-tools.cjs phase complete <phase>
# Indexa planos com ondas e status
node gsd-tools.cjs phase-plan-index <phase>
# Lista fases com filtragem
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
> [!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.
## Comandos de Roadmap
Analisa e atualiza o `ROADMAP.md`.
```bash
# Extrai a seção de fase do ROADMAP.md
node gsd-tools.cjs roadmap get-phase <phase>
# Análise completa do roadmap com status em disco
node gsd-tools.cjs roadmap analyze
# Atualiza linha da tabela de progresso a partir do disco
node gsd-tools.cjs roadmap update-plan-progress <N>
```
---
## Comandos de Configuração
Lê e grava em `.planning/config.json`.
```bash
# Inicializa config.json com valores padrão
node gsd-tools.cjs config-ensure-section
# Define um valor de configuração (notação de ponto)
node gsd-tools.cjs config-set <key> <value>
# Obtém um valor de configuração
node gsd-tools.cjs config-get <key>
# Define o perfil de modelo
node gsd-tools.cjs config-set-model-profile <profile>
```
---
## Resolução de Modelos
```bash
# Obtém o modelo para um agente com base no perfil atual
node gsd-tools.cjs resolve-model <agent-name>
# A saída bruta retorna o ID/tier do modelo selecionado.
# A saída JSON também inclui o perfil e, quando o runtime ativo suporta,
# reasoning_effort.
```
Nomes de agentes: `gsd-planner`, `gsd-executor`, `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-roadmapper`, `gsd-debugger`, `gsd-codebase-mapper`, `gsd-nyquist-auditor`
---
## Comandos de Verificação
Valida planos, fases, referências e commits.
```bash
# Verifica arquivo SUMMARY.md
node gsd-tools.cjs verify-summary <path> [--check-count N]
# Verifica estrutura + tarefas do PLAN.md
node gsd-tools.cjs verify plan-structure <file>
# Verifica se todos os planos têm resumos
node gsd-tools.cjs verify phase-completeness <phase>
# Verifica se @-refs + caminhos resolvem
node gsd-tools.cjs verify references <file>
# Verifica hashes de commit em lote
node gsd-tools.cjs verify commits <hash1> [hash2] ...
# Verifica must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>
# Verifica must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>
```
---
## Comandos de Validação
Verifica a integridade do projeto.
```bash
# Verifica numeração de fases, sincronização disco/roadmap
node gsd-tools.cjs validate consistency
# Verifica integridade de .planning/, com opção de reparo
node gsd-tools.cjs validate health [--repair]
# Verifica utilização da janela de contexto para linha de status / chamadores de hook (v1.40.0)
node gsd-tools.cjs validate context
# Utilização de contexto como superfície JSON tipada (#455)
node gsd-tools.cjs validate context --json
```
`validate context` emite um envelope estruturado com `utilization`, `status`
(`ok` / `warn` / `critical` nos limites de 60% / 70%), e uma
string `suggestion`. Os mesmos dados sustentam `/gsd-health --context`.
Passe `--json` para receber o IR tipado diretamente (útil em scripts e asserções de teste).
---
## Comandos de Template
Seleção e preenchimento de templates.
```bash
# Seleciona o template de resumo com base na granularidade
node gsd-tools.cjs template select <type>
# Preenche o template com variáveis
node gsd-tools.cjs template fill <type> --phase N [--plan M] [--name "..."] [--type execute|tdd] [--wave N] [--fields '{json}']
```
Tipos de template para `fill`: `summary`, `plan`, `verification`
---
## Comandos de Frontmatter
Operações CRUD de frontmatter YAML em qualquer arquivo Markdown.
```bash
# Extrai frontmatter como JSON
node gsd-tools.cjs frontmatter get <file> [--field key]
# Atualiza único campo
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
# Mescla JSON no frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
# Valida campos obrigatórios
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```
---
## Comandos de Scaffold
Cria arquivos e diretórios pré-estruturados.
```bash
# Cria template CONTEXT.md
node gsd-tools.cjs scaffold context --phase N
# Cria template UAT.md
node gsd-tools.cjs scaffold uat --phase N
# Cria template VERIFICATION.md
node gsd-tools.cjs scaffold verification --phase N
# Cria diretório de fase
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
```
---
## Comandos Init (Carregamento de Contexto Composto)
Carrega todo o contexto necessário para um fluxo de trabalho específico em uma única chamada. Retorna JSON com informações do projeto, configuração, estado e dados específicos do fluxo de trabalho.
```bash
node gsd-tools.cjs init execute-phase <phase>
node gsd-tools.cjs init plan-phase <phase>
node gsd-tools.cjs init new-project
node gsd-tools.cjs init new-milestone
node gsd-tools.cjs init quick <description>
node gsd-tools.cjs init resume
node gsd-tools.cjs init verify-work <phase>
node gsd-tools.cjs init phase-op <phase>
node gsd-tools.cjs init todos [area]
node gsd-tools.cjs init milestone-op
node gsd-tools.cjs init map-codebase
node gsd-tools.cjs init progress
# Init com escopo de fluxo de trabalho (flag `--ws`)
node gsd-tools.cjs init execute-phase <phase> --ws <name>
node gsd-tools.cjs init plan-phase <phase> --ws <name>
```
**Tratamento de payloads grandes:** Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna `@file:/tmp/gsd-init-XXXXX.json`. Os fluxos de trabalho verificam o prefixo `@file:` e leem do disco:
```bash
INIT=$(node gsd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
---
## Comandos de Milestone
```bash
# Arquiva milestone
node gsd-tools.cjs milestone complete <version> [--name <name>] [--archive-phases]
# Marca requisitos como concluídos
node gsd-tools.cjs requirements mark-complete <ids>
# Aceita: REQ-01,REQ-02 ou REQ-01 REQ-02 ou [REQ-01, REQ-02]
```
---
## Habilidades de Agente
Emite o bloco de habilidades para um tipo de agente específico.
```bash
# Emite bloco XML bruto de habilidades (padrão — seguro para expansão de shell)
node gsd-tools.cjs agent-skills <agent-type>
# Emite superfície JSON tipada (#455) — { agent_type, block, skills_count }
node gsd-tools.cjs agent-skills <agent-type> --json
```
A flag `--json` retorna um objeto IR tipado adequado para consumo estruturado e asserções de teste, enquanto o padrão (sem flag) preserva a saída XML bruta que as expansões de shell de fluxo de trabalho necessitam.
---
## Manifesto de Habilidades
Pré-computa e armazena em cache a descoberta de habilidades para carregamento mais rápido de comandos.
```bash
# Gera manifesto de habilidades (grava em .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest
# Gera com caminho de saída personalizado
node gsd-tools.cjs skill-manifest --output <path>
```
Retorna mapeamento JSON de todas as habilidades GSD disponíveis com seus metadados (nome, descrição, caminho de arquivo, dicas de argumentos). Usado pelo instalador e hooks de início de sessão para evitar varreduras repetidas do sistema de arquivos.
---
## Comandos Utilitários
```bash
# Converte texto em slug seguro para URL
node gsd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# Obtém timestamp
node gsd-tools.cjs current-timestamp [full|date|filename]
# Conta e lista tarefas pendentes
node gsd-tools.cjs list-todos [area]
# Verifica existência de arquivo/diretório
node gsd-tools.cjs verify-path-exists <path>
# Agrega todos os dados de SUMMARY.md
node gsd-tools.cjs history-digest
# Extrai dados estruturados de SUMMARY.md
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
# Estatísticas do projeto
node gsd-tools.cjs stats [json|table]
# Renderização de progresso (legível por humanos)
node gsd-tools.cjs progress [json|table|bar]
# Progresso como superfície JSON tipada (#455)
node gsd-tools.cjs progress --json
# Conclui uma tarefa
node gsd-tools.cjs todo complete <filename>
# Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
node gsd-tools.cjs audit-uat
# Fila de auditoria entre artefatos — verifica `.planning/` em busca de itens de auditoria não resolvidos
node gsd-tools.cjs audit-open [--json]
# Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/gsd-import --from-gsd2`)
node gsd-tools.cjs from-gsd2 [--path <dir>] [--force] [--dry-run]
# Commit git com verificações de configuração
node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--respect-staged]
```
> `--no-verify`: Ignora hooks de pré-commit. Usado por agentes executores paralelos durante a execução baseada em ondas para evitar contenção de bloqueio de build (ex.: conflitos de cargo lock em projetos Rust). O orquestrador executa os hooks uma vez após cada onda ser concluída. Não use `--no-verify` durante a execução sequencial — deixe os hooks rodarem normalmente.
> `--files <paths>` **comportamento de staging**: por padrão, `--files` executa `git add -- <path>` para cada arquivo nomeado antes de commitar. Isso sobrescreve qualquer staging por hunk configurado via `git add -p`. Passe `--respect-staged` para ignorar o passo `git add` e commitar apenas o que já está no índice dentro do pathspec solicitado. Se nada estiver staged nesse escopo, o comando retorna `{ committed: false, reason: 'nothing staged' }` sem erro. O `-- <paths>` pathspec final no commit é aplicado em ambos os modos, portanto arquivos staged fora do escopo `--files` nunca são incluídos (invariante #3061).
```bash
# Busca na web (requer chave de API do Brave)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
## Graphify
Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. Requer `graphify.enabled: true` em `config.json` (consulte a [Referência de Configuração](CONFIGURATION.md#graphify-settings)).
```bash
# Constrói ou reconstrói o grafo de conhecimento
node gsd-tools.cjs graphify build
# Pesquisa um termo no grafo
node gsd-tools.cjs graphify query <term>
# Exibe atualidade e estatísticas do grafo
node gsd-tools.cjs graphify status
# Exibe alterações desde a última construção
node gsd-tools.cjs graphify diff
# Grava um snapshot nomeado do grafo atual
node gsd-tools.cjs graphify snapshot [name]
```
Ponto de entrada para o usuário: `/gsd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#gsd-graphify)).
---
## Arquitetura de Módulos
| Módulo | Arquivo | Exportações |
|--------|------|---------|
| Core | `lib/core.cjs` | `error()`, `output()`, `parseArgs()`, utilitários compartilhados, re-exportações de compatibilidade |
| State | `lib/state.cjs` | Todos os subcomandos `state`, `state-snapshot` |
| Phase | `lib/phase.cjs` | CRUD de fase, `find-phase`, `phase-plan-index`, `phases list` |
| Planning Workspace | `lib/planning-workspace.cjs` | Costura de planejamento: `planningDir`, `planningPaths`, roteamento de fluxo de trabalho ativo, `.planning/.lock` |
| Roadmap | `lib/roadmap.cjs` | Análise de roadmap, extração de fase, atualizações de progresso |
| Config | `lib/config.cjs` | Leitura/gravação de configuração, inicialização de seção |
| Verify | `lib/verify.cjs` | Todos os comandos de verificação e validação |
| Template | `lib/template.cjs` | Seleção de template e preenchimento de variáveis |
| Frontmatter | `lib/frontmatter.cjs` | CRUD de frontmatter YAML |
| Init | `lib/init.cjs` | Carregamento de contexto composto para todos os fluxos de trabalho |
| Milestone | `lib/milestone.cjs` | Arquivamento de milestone, marcação de requisitos |
| Commands | `lib/commands.cjs` | Diversos: slug, timestamp, todos, scaffold, stats, websearch |
| Model Profiles | `lib/model-profiles.cjs` | Tabela de resolução de perfis |
| UAT | `lib/uat.cjs` | Auditoria UAT/verificação entre fases |
| Profile Output | `lib/profile-output.cjs` | Formatação de perfil do desenvolvedor |
| Profile Pipeline | `lib/profile-pipeline.cjs` | Pipeline de análise de sessão |
| Graphify | `lib/graphify.cjs` | Construção/consulta/status/diff/snapshot do grafo de conhecimento (suporta `/gsd-graphify`) |
| Learnings | `lib/learnings.cjs` | Extrai aprendizados de artefatos de fases/SUMMARY (suporta `/gsd-extract-learnings`) |
| Audit | `lib/audit.cjs` | Manipuladores de fila de auditoria de fase/milestone; helper `audit-open` |
| GSD2 Import | `lib/gsd2-import.cjs` | Importador de migração reversa de projetos GSD-2 (suporta `/gsd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | Índice de inteligência de código consultável (suporta `/gsd-map-codebase --query`) |
---
## Roteamento CLI do Revisor
`review.models.<cli>` mapeia um sabor de revisor para um comando shell invocado pelo fluxo de trabalho de revisão de código. Defina via [`/gsd-config --integrations`](COMMANDS.md#gsd-config) ou diretamente:
```bash
node gsd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node gsd-tools.cjs config-set review.models.gemini "gemini -m gemini-2.5-pro"
node gsd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node gsd-tools.cjs config-set review.models.claude "" # limpa — retorna ao modelo da sessão
```
Os slugs são validados contra `[a-zA-Z0-9_-]+`; slugs vazios ou contendo caminhos são rejeitados. Consulte [`docs/CONFIGURATION.md`](CONFIGURATION.md#code-review-cli-routing) para a referência completa do campo.
## Tratamento de Segredos
As chaves de API configuradas via `/gsd-settings` (`brave_search`, `firecrawl`, `exa_search`) são gravadas em texto simples em `.planning/config.json`, mas são mascaradas (`****<last-4>`) em toda saída de `config-set` / `config-get`, tabela de confirmação e prompt interativo. Consulte `get-shit-done/bin/lib/secrets.cjs` para a implementação do mascaramento. O próprio arquivo `config.json` é o limite de segurança — proteja-o com permissões do sistema de arquivos e mantenha-o fora do git (`.planning/` está no gitignore por padrão).
---
## Relacionados
- [Comandos](COMMANDS.md)
- [Configuração](CONFIGURATION.md)
- [Arquitetura](ARCHITECTURE.md)
- [índice de documentação](README.md)

1572
docs/pt-BR/COMMANDS.md
View File

File diff suppressed because it is too large Load Diff

1377
docs/pt-BR/CONFIGURATION.md
View File

File diff suppressed because it is too large Load Diff

493
docs/pt-BR/INVENTORY.md Normal file
View File

@@ -0,0 +1,493 @@
# Inventário de Superfícies Entregues do GSD
> Registro autoritativo de toda superfície GSD entregue: comandos, agentes, workflows, referências, módulos de CLI e hooks. Quando a documentação ampla (AGENTS.md, COMMANDS.md, ARCHITECTURE.md, CLI-TOOLS.md) divergir do sistema de arquivos, este arquivo e a árvore do repositório são a fonte de verdade.
## Como Usar Este Arquivo
- As contagens aqui são derivadas do sistema de arquivos no pino v1.36.0 e podem divergir entre versões. Para contagens ao vivo, execute `ls commands/gsd/*.md | wc -l`, `ls agents/gsd-*.md | wc -l`, etc. na cópia local do repositório.
- Este arquivo enumera toda superfície entregue em todas as seis famílias (agentes, comandos, workflows, referências, módulos de CLI, hooks). Documentações amplas podem apresentar narrativas ou subconjuntos curados; quando discordarem do sistema de arquivos, este arquivo e as listagens de diretório são autoritativos.
- Novas superfícies adicionadas após v1.36.0 devem aparecer aqui primeiro, depois propagar para as documentações amplas. Os testes de controle de drift em `tests/inventory-counts.test.cjs`, `tests/commands-doc-parity.test.cjs`, `tests/agents-doc-parity.test.cjs`, `tests/cli-modules-doc-parity.test.cjs`, `tests/hooks-doc-parity.test.cjs`, `tests/architecture-counts.test.cjs` e `tests/command-count-sync.test.cjs` ancoram as contagens e o conteúdo do registro ao sistema de arquivos.
Este é o registro autoritativo de toda superfície do GSD Core entregue. Veja o [índice de documentação](README.md) para navegar por tópico.
---
## Agentes (33 entregues)
Registro completo em `agents/gsd-*.md`. A coluna "Documento primário" indica se [`docs/AGENTS.md`](AGENTS.md) apresenta um cartão de função completo (*primary*), um stub resumido na seção "Agentes Avançados e Especializados" (*advanced stub*), ou nenhuma cobertura (*inventory only*).
| Agente | Função (uma linha) | Invocado por | Documento primário |
|--------|--------------------|--------------|--------------------|
| gsd-project-researcher | Pesquisa o ecossistema do domínio antes da criação do roadmap (stack, funcionalidades, arquitetura, armadilhas). | `/gsd-new-project`, `/gsd-new-milestone` | primary |
| gsd-phase-researcher | Pesquisa a abordagem de implementação para uma fase específica antes do planejamento. | `/gsd-plan-phase` | primary |
| gsd-ui-researcher | Produz contratos de design de UI para fases de frontend. | `/gsd-ui-phase` | primary |
| gsd-assumptions-analyzer | Produz premissas embasadas em evidências para a discuss-phase (modo de premissas). | workflow `discuss-phase-assumptions` | primary |
| gsd-advisor-researcher | Pesquisa uma única decisão em zona cinzenta durante o modo advisordiscuss-phase. | workflow `discuss-phase` (modo advisor) | primary |
| gsd-research-synthesizer | Combina saídas de pesquisadores paralelos em um SUMMARY.md unificado. | `/gsd-new-project` | primary |
| gsd-planner | Cria planos de fase executáveis com detalhamento de tarefas e verificação retroativa a partir dos objetivos. | `/gsd-plan-phase`, `/gsd-quick` | primary |
| gsd-roadmapper | Cria roadmaps de projeto com detalhamento de fases e mapeamento de requisitos. | `/gsd-new-project` | primary |
| gsd-executor | Executa planos GSD com commits atômicos e tratamento de desvios. | `/gsd-execute-phase`, `/gsd-quick` | primary |
| gsd-plan-checker | Verifica se os planos vão atingir os objetivos da fase (8 dimensões de verificação). | `/gsd-plan-phase` (loop de verificação) | primary |
| gsd-integration-checker | Verifica a integração entre fases e fluxos de ponta a ponta. | `/gsd-audit-milestone` | primary |
| gsd-ui-checker | Valida contratos de design UI-SPEC.md contra dimensões de qualidade. | `/gsd-ui-phase` (loop de validação) | primary |
| gsd-verifier | Verifica o alcance dos objetivos da fase por meio de análise retroativa a partir dos objetivos. | `/gsd-execute-phase` | primary |
| gsd-nyquist-auditor | Preenche lacunas de validação Nyquist gerando testes. | `/gsd-validate-phase` | primary |
| gsd-ui-auditor | Auditoria visual retroativa de 6 pilares do código frontend implementado. | `/gsd-ui-review` | primary |
| gsd-codebase-mapper | Explora a base de código e escreve documentos de análise estruturados. | `/gsd-map-codebase` | primary |
| gsd-debugger | Investiga bugs usando o método científico com estado persistente. | `/gsd-debug`, `/gsd-verify-work` | primary |
| gsd-user-profiler | Avalia o comportamento do desenvolvedor em 8 dimensões. | `/gsd-profile-user` | primary |
| gsd-doc-writer | Escreve e atualiza a documentação do projeto. | `/gsd-docs-update` | primary |
| gsd-doc-verifier | Verifica afirmações factuais na documentação gerada. | `/gsd-docs-update` | primary |
| gsd-security-auditor | Verifica mitigações de ameaças do modelo de ameaças do PLAN.md. | `/gsd-secure-phase` | primary |
| gsd-pattern-mapper | Mapeia novos arquivos para os análogos existentes mais próximos; escreve PATTERNS.md para o planejador. | `/gsd-plan-phase` (entre pesquisa e planejamento) | advanced stub |
| gsd-debug-session-manager | Executa o loop completo de checkpoint e continuação do `/gsd-debug` em contexto isolado para manter o contexto principal enxuto. | `/gsd-debug` | advanced stub |
| gsd-code-reviewer | Revisa arquivos-fonte em busca de bugs, problemas de segurança e qualidade de código; produz REVIEW.md. | `/gsd-code-review` | advanced stub |
| gsd-code-fixer | Aplica correções às descobertas do REVIEW.md com commits atômicos por correção; produz REVIEW-FIX.md. | `/gsd-code-review --fix` | advanced stub |
| gsd-ai-researcher | Pesquisa a documentação oficial de um framework de IA escolhido em orientações prontas para implementação (AI-SPEC.md §3–§4b). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-domain-researcher | Levanta critérios de avaliação de especialistas de domínio e modos de falha para um sistema de IA (AI-SPEC.md §1b). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-planner | Projeta uma estratégia de avaliação estruturada para uma fase de IA (AI-SPEC.md §5–§7). | `/gsd-ai-integration-phase` | advanced stub |
| gsd-eval-auditor | Auditoria retroativa da cobertura de avaliação de uma fase de IA; produz EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | `/gsd-eval-review` | advanced stub |
| gsd-framework-selector | Matriz de decisão interativa com ≤6 perguntas que pontua e recomenda um framework de IA/LLM. | `/gsd-ai-integration-phase` | advanced stub |
| gsd-intel-updater | Escreve arquivos de intel estruturados (`.planning/intel/*.json`) usados como base de conhecimento consultável da base de código. | `/gsd-map-codebase --query` | advanced stub |
| gsd-doc-classifier | Classifica um único documento de planejamento como ADR, PRD, SPEC, DOC ou UNKNOWN; invocado em paralelo para processar o corpus de documentos. | `/gsd-ingest-docs` | advanced stub |
| gsd-doc-synthesizer | Sintetiza documentos de planejamento classificados em um único contexto consolidado com regras de precedência, detecção de ciclos e relatório de conflitos em três categorias. | `/gsd-ingest-docs` | advanced stub |
**Nota de cobertura.** `docs/AGENTS.md` fornece cartões de função completos para 21 agentes primários, além de stubs concisos para os 12 agentes avançados. O Resumo de Permissões de Ferramenta de Agente nesse arquivo cobre apenas os 21 agentes primários; as listas de ferramentas dos agentes avançados estão capturadas no frontmatter de cada agente em `agents/gsd-*.md`.
---
## Comandos (67 entregues)
Registro completo em `commands/gsd/*.md`. Os agrupamentos abaixo espelham a ordem das seções de `docs/COMMANDS.md`; cada linha traz o nome do comando, uma função em uma linha derivada do `description:` do frontmatter do comando e um link para o arquivo-fonte. `tests/command-count-sync.test.cjs` trava a contagem contra o sistema de arquivos.
### Meta-Skills de Namespace
Esses seis roteadores são entradas apenas descritivas que o modelo seleciona primeiro; o corpo de cada um contém uma tabela de roteamento que aponta para a sub-habilidade concreta correta. Eles existem para manter baixo o custo de tokens da listagem ansiosa de habilidades enquanto toda a superfície permanece acessível. Veja [#2792](https://github.com/open-gsd/gsd-core/issues/2792) para a justificativa; as tabelas de roteamento apontam para a superfície consolidada pós-[#2790](https://github.com/open-gsd/gsd-core/issues/2790).
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-workflow` | Roteador de pipeline de fase — discuss / plan / execute / verify / phase / progress. | [commands/gsd/ns-workflow.md](../../commands/gsd/ns-workflow.md) |
| `/gsd-project` | Roteador de ciclo de vida do projeto — milestones, auditorias, resumo. | [commands/gsd/ns-project.md](../../commands/gsd/ns-project.md) |
| `/gsd-quality` | Roteador de portão de qualidade — revisão de código, debug, auditoria, segurança, avaliação, ui. | [commands/gsd/ns-review.md](../../commands/gsd/ns-review.md) |
| `/gsd-context` | Roteador de inteligência da base de código — map, graphify, docs, learnings. | [commands/gsd/ns-context.md](../../commands/gsd/ns-context.md) |
| `/gsd-manage` | Roteador de gerenciamento — config, workspace, workstreams, thread, update, ship, inbox. | [commands/gsd/ns-manage.md](../../commands/gsd/ns-manage.md) |
| `/gsd-ideate` | Roteador de exploração e captura — explore, sketch, spike, spec, capture. | [commands/gsd/ns-ideate.md](../../commands/gsd/ns-ideate.md) |
### Workflow Principal
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-new-project` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md. | [commands/gsd/new-project.md](../../commands/gsd/new-project.md) |
| `/gsd-workspace` | Gerencia workspaces GSD — criar (`--new`), listar (`--list`) ou remover (`--remove`) ambientes de workspace isolados. | [commands/gsd/workspace.md](../../commands/gsd/workspace.md) |
| `/gsd-discuss-phase` | Coleta contexto da fase por meio de perguntas adaptativas antes do planejamento. | [commands/gsd/discuss-phase.md](../../commands/gsd/discuss-phase.md) |
| `/gsd-mvp-phase` | Planeja uma fase como uma fatia vertical de MVP — história de usuário, divisão SPIDR, depois plan-phase. | [commands/gsd/mvp-phase.md](../../commands/gsd/mvp-phase.md) |
| `/gsd-spec-phase` | Refinamento socrático de especificação produzindo um SPEC.md com requisitos falsificáveis. | [commands/gsd/spec-phase.md](../../commands/gsd/spec-phase.md) |
| `/gsd-ui-phase` | Gera contrato de design de UI (UI-SPEC.md) para fases de frontend. | [commands/gsd/ui-phase.md](../../commands/gsd/ui-phase.md) |
| `/gsd-ai-integration-phase` | Gera contrato de design de IA (AI-SPEC.md) via seleção de framework, pesquisa e planejamento de avaliação. | [commands/gsd/ai-integration-phase.md](../../commands/gsd/ai-integration-phase.md) |
| `/gsd-plan-phase` | Cria plano de fase detalhado (PLAN.md) com loop de verificação. | [commands/gsd/plan-phase.md](../../commands/gsd/plan-phase.md) |
| `/gsd-plan-review-convergence` | Loop de convergência de plano entre IAs — replanejar com feedback de revisão até que não restem preocupações HIGH (máx. 3 ciclos). | [commands/gsd/plan-review-convergence.md](../../commands/gsd/plan-review-convergence.md) |
| `/gsd-ultraplan-phase` | [BETA] Delega a fase de planejamento ao ultraplan cloud do Claude Code — rascunhos remotamente, revisar no navegador, importar de volta via `/gsd-import`. Apenas Claude Code. | [commands/gsd/ultraplan-phase.md](../../commands/gsd/ultraplan-phase.md) |
| `/gsd-spike` | Realiza um spike rápido de uma ideia com experimentos descartáveis; use `--wrap-up` para empacotar as descobertas como uma habilidade persistente. | [commands/gsd/spike.md](../../commands/gsd/spike.md) |
| `/gsd-sketch` | Esboça rapidamente ideias de UI/design usando mockups HTML descartáveis; use `--wrap-up` para empacotar as descobertas. | [commands/gsd/sketch.md](../../commands/gsd/sketch.md) |
| `/gsd-execute-phase` | Executa todos os planos de uma fase com paralelização baseada em ondas. | [commands/gsd/execute-phase.md](../../commands/gsd/execute-phase.md) |
| `/gsd-verify-work` | Valida funcionalidades construídas por meio de UAT conversacional com autodiagnóstico. | [commands/gsd/verify-work.md](../../commands/gsd/verify-work.md) |
| `/gsd-ship` | Cria PR, executa revisão e prepara para merge após verificação. | [commands/gsd/ship.md](../../commands/gsd/ship.md) |
| `/gsd-fast` | Executa uma tarefa trivial inline — sem subagentes, sem overhead de planejamento. | [commands/gsd/fast.md](../../commands/gsd/fast.md) |
| `/gsd-quick` | Executa uma tarefa rápida com garantias GSD (commits atômicos, rastreamento de estado) mas pula agentes opcionais. | [commands/gsd/quick.md](../../commands/gsd/quick.md) |
| `/gsd-ui-review` | Auditoria visual retroativa de 6 pilares do código frontend implementado. | [commands/gsd/ui-review.md](../../commands/gsd/ui-review.md) |
| `/gsd-code-review` | Revisa arquivos-fonte alterados durante uma fase em busca de bugs, segurança e problemas de qualidade de código; use `--fix` para aplicar as descobertas automaticamente. | [commands/gsd/code-review.md](../../commands/gsd/code-review.md) |
| `/gsd-eval-review` | Audita retroativamente a cobertura de avaliação de uma fase de IA executada; produz EVAL-REVIEW.md. | [commands/gsd/eval-review.md](../../commands/gsd/eval-review.md) |
### Gerenciamento de Fases e Milestones
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-phase` | CRUD de fases — adicionar (padrão), inserir (`--insert`), remover (`--remove`) ou editar (`--edit`) fases no ROADMAP.md. | [commands/gsd/phase.md](../../commands/gsd/phase.md) |
| `/gsd-add-tests` | Gera testes para uma fase concluída com base nos critérios de UAT e na implementação. | [commands/gsd/add-tests.md](../../commands/gsd/add-tests.md) |
| `/gsd-validate-phase` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída. | [commands/gsd/validate-phase.md](../../commands/gsd/validate-phase.md) |
| `/gsd-secure-phase` | Verifica retroativamente as mitigações de ameaças para uma fase concluída. | [commands/gsd/secure-phase.md](../../commands/gsd/secure-phase.md) |
| `/gsd-audit-milestone` | Audita a conclusão do milestone contra a intenção original antes do arquivamento. | [commands/gsd/audit-milestone.md](../../commands/gsd/audit-milestone.md) |
| `/gsd-audit-uat` | Auditoria entre fases de todos os itens de UAT e verificação pendentes. | [commands/gsd/audit-uat.md](../../commands/gsd/audit-uat.md) |
| `/gsd-audit-fix` | Pipeline autônomo de auditoria para correção — encontrar problemas, classificar, corrigir, testar, commitar. | [commands/gsd/audit-fix.md](../../commands/gsd/audit-fix.md) |
| `/gsd-complete-milestone` | Arquiva o milestone concluído e prepara para a próxima versão. | [commands/gsd/complete-milestone.md](../../commands/gsd/complete-milestone.md) |
| `/gsd-new-milestone` | Inicia um novo ciclo de milestone — atualizar PROJECT.md e rotear para os requisitos. | [commands/gsd/new-milestone.md](../../commands/gsd/new-milestone.md) |
| `/gsd-milestone-summary` | Gera um resumo abrangente do projeto a partir dos artefatos do milestone. | [commands/gsd/milestone-summary.md](../../commands/gsd/milestone-summary.md) |
| `/gsd-cleanup` | Arquiva diretórios de fases acumulados de milestones concluídos. | [commands/gsd/cleanup.md](../../commands/gsd/cleanup.md) |
| `/gsd-manager` | Central de comando interativa para gerenciar múltiplas fases de um terminal. | [commands/gsd/manager.md](../../commands/gsd/manager.md) |
| `/gsd-workstreams` | Gerencia workstreams paralelos — listar, criar, alternar, status, progresso, concluir, retomar. | [commands/gsd/workstreams.md](../../commands/gsd/workstreams.md) |
| `/gsd-autonomous` | Executa todas as fases restantes de forma autônoma — discuss → plan → execute por fase. | [commands/gsd/autonomous.md](../../commands/gsd/autonomous.md) |
| `/gsd-undo` | Reversão git segura — reverter commits de fase ou plano usando o manifesto da fase. | [commands/gsd/undo.md](../../commands/gsd/undo.md) |
### Sessão e Navegação
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-progress` | Verifica o progresso do projeto, exibe contexto e roteia para a próxima ação; use `--next` para avançar automaticamente ou `--do` para executar uma tarefa de forma livre. | [commands/gsd/progress.md](../../commands/gsd/progress.md) |
| `/gsd-capture` | Captura ideias, tarefas, notas e seeds — todo (padrão), `--note`, `--backlog`, `--seed` ou `--list` de todos pendentes. | [commands/gsd/capture.md](../../commands/gsd/capture.md) |
| `/gsd-stats` | Exibe estatísticas do projeto — fases, planos, requisitos, métricas git, linha do tempo. | [commands/gsd/stats.md](../../commands/gsd/stats.md) |
| `/gsd-pause-work` | Cria handoff de contexto ao pausar o trabalho no meio de uma fase. | [commands/gsd/pause-work.md](../../commands/gsd/pause-work.md) |
| `/gsd-resume-work` | Retoma o trabalho da sessão anterior com restauração completa do contexto. | [commands/gsd/resume-work.md](../../commands/gsd/resume-work.md) |
| `/gsd-explore` | Ideação socrática e roteamento de ideias — pensar nas ideias antes de se comprometer. | [commands/gsd/explore.md](../../commands/gsd/explore.md) |
| `/gsd-review-backlog` | Revisa e promove itens do backlog para o milestone ativo. | [commands/gsd/review-backlog.md](../../commands/gsd/review-backlog.md) |
| `/gsd-thread` | Gerencia threads de contexto persistentes para trabalho entre sessões. | [commands/gsd/thread.md](../../commands/gsd/thread.md) |
### Inteligência da Base de Código
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-map-codebase` | Analisa a base de código com agentes mapeadores paralelos; use `--fast` para varredura leve ou `--query` para consultas de intel. | [commands/gsd/map-codebase.md](../../commands/gsd/map-codebase.md) |
| `/gsd-graphify` | Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. | [commands/gsd/graphify.md](../../commands/gsd/graphify.md) |
| `/gsd-extract-learnings` | Extrai decisões, lições, padrões e surpresas de artefatos de fases concluídas. | [commands/gsd/extract-learnings.md](../../commands/gsd/extract-learnings.md) |
### Revisão, Debug e Recuperação
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-review` | Solicita revisão de pares entre IAs de planos de fase a partir de CLIs de IA externos. | [commands/gsd/review.md](../../commands/gsd/review.md) |
| `/gsd-debug` | Depuração sistemática com estado persistente entre resets de contexto. | [commands/gsd/debug.md](../../commands/gsd/debug.md) |
| `/gsd-forensics` | Investigação post-mortem de workflows GSD com falha — analisa git, artefatos, estado. | [commands/gsd/forensics.md](../../commands/gsd/forensics.md) |
| `/gsd-health` | Diagnostica a integridade do diretório de planejamento e opcionalmente repara problemas. | [commands/gsd/health.md](../../commands/gsd/health.md) |
| `/gsd-import` | Ingere planos externos com detecção de conflitos contra decisões do projeto. | [commands/gsd/import.md](../../commands/gsd/import.md) |
| `/gsd-inbox` | Faz triagem e revisão de todas as issues e PRs abertas do GitHub contra os templates do projeto. | [commands/gsd/inbox.md](../../commands/gsd/inbox.md) |
### Documentação, Perfil e Utilitários
| Comando | Função | Fonte |
|---------|--------|-------|
| `/gsd-docs-update` | Gera ou atualiza a documentação do projeto verificada contra a base de código. | [commands/gsd/docs-update.md](../../commands/gsd/docs-update.md) |
| `/gsd-ingest-docs` | Varre um repositório em busca de ADRs/PRDs/SPECs/DOCs mistos e inicializa ou mescla a configuração completa de `.planning/` com classificação, síntese e relatório de conflitos. | [commands/gsd/ingest-docs.md](../../commands/gsd/ingest-docs.md) |
| `/gsd-profile-user` | Gera perfil comportamental do desenvolvedor e artefatos descobríveis pelo Claude. | [commands/gsd/profile-user.md](../../commands/gsd/profile-user.md) |
| `/gsd-settings` | Configura alternâncias de workflow GSD e perfil de modelo. | [commands/gsd/settings.md](../../commands/gsd/settings.md) |
| `/gsd-config` | Configura as definições GSD — alternâncias de workflow (padrão), parâmetros avançados (`--advanced`), integrações (`--integrations`) ou perfil de modelo (`--profile`). | [commands/gsd/config.md](../../commands/gsd/config.md) |
| `/gsd-pr-branch` | Cria um branch limpo de PR filtrando commits de `.planning/`. | [commands/gsd/pr-branch.md](../../commands/gsd/pr-branch.md) |
| `/gsd-surface` | Alterna quais habilidades são expostas — aplica um perfil, lista ou desativa um cluster sem reinstalar. | [commands/gsd/surface.md](../../commands/gsd/surface.md) |
| `/gsd-update` | Atualiza o GSD para a versão mais recente; use `--sync` para sincronizar habilidades entre runtimes ou `--reapply` para reaplicar patches locais. | [commands/gsd/update.md](../../commands/gsd/update.md) |
| `/gsd-help` | Exibe os comandos GSD disponíveis e o guia de uso. | [commands/gsd/help.md](../../commands/gsd/help.md) |
---
## Workflows (88 entregues)
Registro completo em `get-shit-done/workflows/*.md`. Workflows são orquestradores enxutos que os comandos referenciam internamente; a maioria não é lida diretamente pelos usuários finais. As linhas abaixo mapeiam cada arquivo de workflow para sua função (derivada do bloco `<purpose>`) e, quando aplicável, para o comando que o invoca.
| Workflow | Função | Invocado por |
|----------|--------|--------------|
| `add-backlog.md` | Adiciona um item de backlog ao ROADMAP.md usando numeração 999.x. | `/gsd-capture --backlog` |
| `add-phase.md` | Adiciona uma nova fase inteira ao final do milestone atual no roadmap. | `/gsd-phase` (padrão) |
| `add-tests.md` | Gera testes unitários e E2E para uma fase concluída com base em seus artefatos. | `/gsd-add-tests` |
| `add-todo.md` | Captura uma ideia ou tarefa que surge durante uma sessão como um todo estruturado. | `/gsd-capture` (padrão) |
| `ai-integration-phase.md` | Orquestra seleção de framework → pesquisa de IA → pesquisa de domínio → planejamento de avaliação no AI-SPEC.md. | `/gsd-ai-integration-phase` |
| `analyze-dependencies.md` | Analisa as fases do ROADMAP.md para sobreposição de arquivos e dependências semânticas; sugere arestas `Depends on`. | `/gsd-manager --analyze-deps` |
| `audit-fix.md` | Pipeline autônomo de auditoria para correção — executar auditoria, analisar, classificar, corrigir, testar, commitar. | `/gsd-audit-fix` |
| `audit-milestone.md` | Verifica se o milestone atendeu sua definição de pronto ao agregar verificações de fase. | `/gsd-audit-milestone` |
| `audit-uat.md` | Auditoria entre fases de arquivos de UAT e verificação; produz lista priorizada de itens pendentes. | `/gsd-audit-uat` |
| `autonomous.md` | Conduz as fases do milestone de forma autônoma — todas restantes, um intervalo ou uma única fase. | `/gsd-autonomous` |
| `check-todos.md` | Lista todos pendentes, permite seleção, carrega contexto e roteia para a ação apropriada. | `/gsd-capture --list` |
| `cleanup.md` | Arquiva diretórios de fases acumulados de milestones concluídos. | `/gsd-cleanup` |
| `code-review-fix.md` | Autocorrige problemas do REVIEW.md via gsd-code-fixer com commits atômicos por correção. | `/gsd-code-review --fix` |
| `code-review.md` | Revisa alterações de código-fonte da fase via gsd-code-reviewer; produz REVIEW.md. | `/gsd-code-review` |
| `complete-milestone.md` | Marca uma versão entregue como concluída — entrada no MILESTONES.md, evolução do PROJECT.md, tag. | `/gsd-complete-milestone` |
| `diagnose-issues.md` | Orquestra agentes de debug paralelos para investigar lacunas de UAT e encontrar causas raiz. | `/gsd-verify-work` (autodiagnóstico) |
| `discovery-phase.md` | Executa a descoberta no nível de profundidade apropriado. | `/gsd-new-project` (caminho de descoberta) |
| `discuss-phase-assumptions.md` | Discuss no modo de premissas — extrai decisões de implementação via análise com base no código primeiro. | `/gsd-discuss-phase` (quando `discuss_mode=assumptions`) |
| `discuss-phase-power.md` | Discuss para usuário avançado — pré-gera todas as perguntas em um arquivo de estado JSON + UI HTML. | `/gsd-discuss-phase --power` |
| `discuss-phase.md` | Extrai decisões de implementação por meio de discussão iterativa de zonas cinzentas. | `/gsd-discuss-phase` |
| `mvp-phase.md` | Planeja uma fase como uma fatia vertical de MVP — história de usuário, divisão SPIDR, depois plan-phase. | `/gsd-mvp-phase` |
| `do.md` | Roteia texto livre do usuário para o comando GSD mais adequado. | `/gsd-progress --do` |
| `docs-update.md` | Gera, atualiza e verifica documentação canônica e escrita à mão do projeto. | `/gsd-docs-update` |
| `edit-phase.md` | Edita qualquer campo de uma fase existente no ROADMAP.md no lugar, preservando número e posição. | `/gsd-phase --edit` |
| `eval-review.md` | Auditoria retroativa da cobertura de avaliação de uma fase de IA implementada. | `/gsd-eval-review` |
| `execute-phase.md` | Executa todos os planos de uma fase usando execução paralela baseada em ondas. | `/gsd-execute-phase` |
| `execute-plan.md` | Executa um prompt de fase (PLAN.md) e cria o resumo do resultado (SUMMARY.md). | `execute-phase.md` (subagente por plano) |
| `explore.md` | Ideação socrática — guia o desenvolvedor por perguntas investigativas. | `/gsd-explore` |
| `debug.md` | Depuração sistemática — roteamento de subcomandos, criação de sessão, delegação para gsd-debug-session-manager. | `/gsd-debug` |
| `extract-learnings.md` | Extrai decisões, lições, padrões e surpresas de artefatos de fases concluídas. | `/gsd-extract-learnings` |
| `fast.md` | Executa uma tarefa trivial inline sem overhead de subagente. | `/gsd-fast` |
| `forensics.md` | Investigação forense de workflows com falha — análise de git, artefatos e estado. | `/gsd-forensics` |
| `graduation.md` | Agrupa itens recorrentes do LEARNINGS.md entre fases e levanta candidatos de promoção HITL. | `transition.md` (etapa graduation_scan) |
| `health.md` | Valida a integridade do diretório `.planning/` e reporta problemas acionáveis. | `/gsd-health` |
| `help.md` | Exibe a referência completa de comandos do GSD Core. | `/gsd-help` |
| `import.md` | Ingere planos externos com detecção de conflitos contra decisões existentes do projeto. | `/gsd-import` |
| `inbox.md` | Faz triagem de issues e PRs abertas do GitHub contra templates de contribuição do projeto. | `/gsd-inbox` |
| `ingest-docs.md` | Varre um repositório em busca de documentos de planejamento mistos; classifica, sintetiza e inicializa ou mescla no `.planning/` com um relatório de conflitos. | `/gsd-ingest-docs` |
| `insert-phase.md` | Insere uma fase decimal para trabalho urgente descoberto no meio de um milestone. | `/gsd-phase --insert` |
| `list-phase-assumptions.md` | Levanta as premissas do Claude sobre uma fase antes do planejamento. | `/gsd-discuss-phase --assumptions` |
| `list-workspaces.md` | Lista todos os workspaces GSD encontrados em `~/gsd-workspaces/` com seu status. | `/gsd-workspace --list` |
| `manager.md` | Central de comando interativa de milestone — dashboard, discuss inline, plan/execute em segundo plano. | `/gsd-manager` |
| `map-codebase.md` | Orquestra agentes mapeadores paralelos da base de código para produzir documentos em `.planning/codebase/`. | `/gsd-map-codebase` |
| `milestone-summary.md` | Síntese do resumo do milestone — artefato de onboarding e revisão a partir dos artefatos do milestone. | `/gsd-milestone-summary` |
| `new-milestone.md` | Inicia um novo ciclo de milestone — carregar contexto do projeto, coletar objetivos, atualizar PROJECT.md/STATE.md. | `/gsd-new-milestone` |
| `new-project.md` | Fluxo unificado de novo projeto — questionamento, pesquisa (opcional), requisitos, roadmap. | `/gsd-new-project` |
| `new-workspace.md` | Cria um workspace isolado com worktrees/clones do repositório e um `.planning/` independente. | `/gsd-workspace --new` |
| `next.md` | Detecta o estado atual do projeto e avança automaticamente para o próximo passo lógico. | `/gsd-progress --next` |
| `node-repair.md` | Operador de reparo autônomo para verificação de tarefa com falha; invocado por `execute-plan`. | `execute-plan.md` (recuperação) |
| `note.md` | Captura de ideia sem atrito — uma chamada Write, uma linha de confirmação. | `/gsd-capture --note` |
| `pause-work.md` | Cria os arquivos de handoff estruturados `.planning/HANDOFF.json` e `.continue-here.md`. | `/gsd-pause-work` |
| `plan-phase.md` | Cria arquivos PLAN.md executáveis com pesquisa integrada e loop de verificação. | `/gsd-plan-phase`, `/gsd-quick` |
| `plan-review-convergence.md` | Loop de convergência de plano entre IAs — replanejar com feedback de revisão até que não restem preocupações HIGH. | `/gsd-plan-review-convergence` |
| `plant-seed.md` | Captura uma ideia prospectiva como um arquivo de seed estruturado com condições de acionamento. | `/gsd-capture --seed` |
| `pr-branch.md` | Cria um branch limpo para pull requests filtrando commits de `.planning/`. | `/gsd-pr-branch` |
| `profile-user.md` | Orquestra o fluxo completo de perfil do desenvolvedor — consentimento, varredura de sessão, geração de perfil. | `/gsd-profile-user` |
| `progress.md` | Renderização de progresso — contexto do projeto, posição e roteamento para próxima ação. | `/gsd-progress` |
| `quick.md` | Execução de tarefa rápida com garantias GSD (commits atômicos, rastreamento de estado). | `/gsd-quick` |
| `reapply-patches.md` | Reaaplica modificações locais após uma atualização do GSD. | `/gsd-update --reapply` |
| `remove-phase.md` | Remove uma fase futura do roadmap e renumera as fases subsequentes. | `/gsd-phase --remove` |
| `remove-workspace.md` | Remove um workspace GSD e limpa worktrees. | `/gsd-workspace --remove` |
| `resume-project.md` | Retoma o trabalho — restaura o contexto completo do STATE.md, HANDOFF.json e artefatos. | `/gsd-resume-work` |
| `review.md` | Revisão de plano entre IAs via CLIs externos; produz REVIEWS.md. | `/gsd-review` |
| `scan.md` | Varredura rápida e focada da base de código — alternativa leve ao map-codebase. | `/gsd-map-codebase --fast` |
| `secure-phase.md` | Auditoria retroativa de mitigação de ameaças para uma fase concluída. | `/gsd-secure-phase` |
| `session-report.md` | Relatório de sessão — uso de tokens, resumo do trabalho, resultados. | `/gsd-pause-work --report` |
| `settings.md` | Configura alternâncias de workflow GSD e perfil de modelo. | `/gsd-settings`, `/gsd-config --profile` |
| `settings-advanced.md` | Configura parâmetros avançados do GSD — bouncing de plano, timeouts, templates de branch, execução entre IAs, parâmetros de runtime. | `/gsd-config --advanced` |
| `settings-integrations.md` | Configura chaves de API de terceiros (Brave/Firecrawl/Exa), roteamento de CLI `review.models.<cli>` e injeção de `agent_skills.<agent-type>` com exibição mascarada (`****<last-4>`). | `/gsd-config --integrations` |
| `ship.md` | Cria PR, executa revisão e prepara para merge após verificação. | `/gsd-ship` |
| `sketch.md` | Explora direções de design por meio de mockups HTML descartáveis com 2–3 variantes por sketch. | `/gsd-sketch` |
| `sketch-wrap-up.md` | Curadoria das descobertas do sketch e empacotamento como uma habilidade persistente `sketch-findings-[project]`. | `/gsd-sketch --wrap-up` |
| `spec-phase.md` | Refinamento socrático de especificação com pontuação de ambiguidade; produz SPEC.md. | `/gsd-spec-phase` |
| `spike.md` | Validação rápida de viabilidade por meio de experimentos focados e descartáveis. | `/gsd-spike` |
| `spike-wrap-up.md` | Curadoria das descobertas do spike e empacotamento como uma habilidade persistente `spike-findings-[project]`. | `/gsd-spike --wrap-up` |
| `stats.md` | Renderização de estatísticas do projeto — fases, planos, requisitos, métricas git. | `/gsd-stats` |
| `sync-skills.md` | Sincronização de habilidades GSD entre runtimes — diff e aplicação de diretórios de habilidades `gsd-*` entre raízes de runtime. | `/gsd-update --sync` |
| `transition.md` | Workflow de transição de limite de fase — verificações de workstream, avanço de estado. | `execute-phase.md`, `/gsd-progress --next` |
| `ui-phase.md` | Gera contrato de design UI-SPEC.md via gsd-ui-researcher. | `/gsd-ui-phase` |
| `ui-review.md` | Auditoria visual retroativa de 6 pilares via gsd-ui-auditor. | `/gsd-ui-review` |
| `ultraplan-phase.md` | [BETA] Delega o planejamento ao ultraplan cloud do Claude Code; rascunhos remotamente e importa de volta via `/gsd-import`. | `/gsd-ultraplan-phase` |
| `undo.md` | Reversão git segura — commits de fase ou plano usando o manifesto da fase. | `/gsd-undo` |
| `thread.md` | Cria, lista, fecha ou retoma threads de contexto persistentes para trabalho entre sessões. | `/gsd-thread` |
| `update.md` | Atualiza o GSD para a versão mais recente com exibição do changelog. | `/gsd-update` |
| `validate-phase.md` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída. | `/gsd-validate-phase` |
| `verify-phase.md` | Verifica o alcance dos objetivos da fase por meio de análise retroativa a partir dos objetivos. | `execute-phase.md` (pós-execução) |
| `verify-work.md` | UAT conversacional com autodiagnóstico — produz UAT.md e planos de correção. | `/gsd-verify-work` |
> **Nota:** Alguns workflows não têm comando direto voltado ao usuário (p. ex. `execute-plan.md`, `verify-phase.md`, `transition.md`, `node-repair.md`, `diagnose-issues.md`) — eles são invocados internamente por workflows orquestradores. `discovery-phase.md` é uma entrada alternativa para `/gsd-new-project`.
---
## Referências (62 entregues)
Registro completo em `get-shit-done/references/*.md`. Referências são documentos de conhecimento compartilhado que workflows e agentes `@-reference`. Os agrupamentos abaixo correspondem a [`docs/ARCHITECTURE.md`](ARCHITECTURE.md#references-get-shit-donereferencesmd) — clusters principais, de workflow, de modelo de raciocínio e a decomposição modular do planejador.
### Referências Principais
| Referência | Função |
|------------|--------|
| `checkpoints.md` | Definições de tipos de checkpoint e padrões de interação. |
| `gates.md` | 4 tipos canônicos de portão (Confirm, Quality, Safety, Transition) conectados ao plan-checker e verifier. |
| `model-profiles.md` | Atribuições de nível de modelo por agente. |
| `model-profile-resolution.md` | Documentação do algoritmo de resolução de modelo. |
| `verification-patterns.md` | Como verificar diferentes tipos de artefato. |
| `verification-overrides.md` | Regras de substituição de verificação por artefato. |
| `planning-config.md` | Esquema completo de configuração e comportamento. |
| `git-integration.md` | Padrões de commit git, ramificação e histórico. |
| `git-planning-commit.md` | Convenções de commit do diretório de planejamento. |
| `questioning.md` | Filosofia de extração de sonhos para a inicialização do projeto. |
| `tdd.md` | Padrões de integração de desenvolvimento orientado a testes. |
| `ui-brand.md` | Padrões de formatação de saída visual. |
| `common-bug-patterns.md` | Padrões comuns de bugs para revisão de código e verificação. |
| `debugger-philosophy.md` | Disciplinas de depuração perenes carregadas pelo `gsd-debugger`. |
| `mandatory-initial-read.md` | Boilerplate de leitura obrigatória compartilhado injetado nos prompts de agentes. |
| `project-skills-discovery.md` | Boilerplate de descoberta de habilidades do projeto injetado nos prompts de agentes. |
### Referências de Workflow
| Referência | Função |
|------------|--------|
| `agent-contracts.md` | Interface formal entre orquestradores e agentes. |
| `context-budget.md` | Regras de alocação do orçamento da janela de contexto. |
| `continuation-format.md` | Formato de continuação/retomada de sessão. |
| `domain-probes.md` | Perguntas de sondagem específicas de domínio para a discuss-phase. |
| `gate-prompts.md` | Templates de prompt de portão/checkpoint. |
| `scout-codebase.md` | Tabela de seleção de tipo de fase → mapa de base de código para a etapa de scout da discuss-phase (extraída via #2551). |
| `revision-loop.md` | Padrões de iteração de revisão de plano. |
| `universal-anti-patterns.md` | Antipadrões universais a detectar e evitar. |
| `worktree-path-safety.md` | Suite de guarda do worktree: asserção de HEAD, sentinela de drift de cwd (etapa 0a, #3097) e guarda de caminho absoluto (etapa 0b, #3099) — carregados nos prompts de spawn do executor via `<execution_context>`. |
| `artifact-types.md` | Definições de tipos de artefato de planejamento. |
| `phase-argument-parsing.md` | Convenções de análise de argumentos de fase. |
| `decimal-phase-calculation.md` | Regras de numeração de subfases decimais. |
| `workstream-flag.md` | Convenções de ponteiro ativo de workstream (`--ws`). |
| `user-profiling.md` | Heurísticas de detecção de perfil comportamental do usuário. |
| `thinking-partner.md` | Ativação condicional do parceiro de raciocínio em pontos de decisão. |
| `autonomous-smart-discuss.md` | Lógica de smart-discuss para o modo autônomo. |
| `ios-scaffold.md` | Padrões de scaffolding de aplicativo iOS. |
| `ai-evals.md` | Referência de design de avaliação de IA para `/gsd-ai-integration-phase`. |
| `ai-frameworks.md` | Referência da matriz de decisão de frameworks de IA para `gsd-framework-selector`. |
| `executor-examples.md` | Exemplos resolvidos para o agente gsd-executor. |
| `doc-conflict-engine.md` | Contrato compartilhado de detecção de conflitos para workflows de ingest/import. |
| `execute-mvp-tdd.md` | Semântica de portão de runtime para execute-phase em MVP+TDD — verificação de teste com falha pré-tarefa, revisão bloqueante no final da fase. |
| `mvp-concepts.md` | Índice de referência cruzada dos seis arquivos de referência relacionados a MVP; mapeia cada arquivo para sua finalidade e qual workflow o carrega. |
| `verify-mvp-mode.md` | Regras de enquadramento de UAT para fases em modo MVP — ordenação com fluxo de usuário primeiro, verificações técnicas adiadas, guarda de formato de história de usuário. |
### Referências de Sketch
Referências consumidas pelo workflow `/gsd-sketch` e seu companion de wrap-up.
| Referência | Função |
|------------|--------|
| `sketch-interactivity.md` | Regras para tornar os sketches HTML interativos e vivos. |
| `sketch-theme-system.md` | Sistema de variáveis de tema CSS compartilhado para consistência entre sketches. |
| `sketch-tooling.md` | Utilitários de barra de ferramentas flutuante incluídos em todo sketch. |
| `sketch-variant-patterns.md` | Padrões HTML de múltiplas variantes (abas, lado a lado, sobreposições). |
### Referências de Modelo de Raciocínio
Referências para integrar modelos de classe de raciocínio (o3, o4-mini, Gemini 2.5 Pro) em workflows GSD.
| Referência | Função |
|------------|--------|
| `thinking-models-debug.md` | Padrões de modelo de raciocínio para workflows de debug. |
| `thinking-models-execution.md` | Padrões de modelo de raciocínio para agentes de execução. |
| `thinking-models-planning.md` | Padrões de modelo de raciocínio para agentes de planejamento. |
| `thinking-models-research.md` | Padrões de modelo de raciocínio para agentes de pesquisa. |
| `thinking-models-verification.md` | Padrões de modelo de raciocínio para agentes de verificação. |
### Decomposição Modular do Planejador
O agente `gsd-planner` é decomposto em um agente principal mais módulos de referência para caber nos limites de caracteres do runtime.
| Referência | Função |
|------------|--------|
| `planner-antipatterns.md` | Antipadrões do planejador e exemplos de especificidade. |
| `planner-chunked.md` | Formatos de retorno do modo chunked (`## OUTLINE COMPLETE`, `## PLAN COMPLETE`) para mitigação do travamento de stdio no Windows. |
| `planner-gap-closure.md` | Comportamento do modo de fechamento de lacuna (lê VERIFICATION.md, replanejamento direcionado). |
| `planner-reviews.md` | Integração de revisão entre IAs (lê REVIEWS.md do `/gsd-review`). |
| `planner-revision.md` | Padrões de revisão de plano para refinamento iterativo. |
| `planner-source-audit.md` | Regras de auditoria de fonte e limite de autoridade do planejador. |
| `planner-mvp-mode.md` | Regras de planejamento em fatia vertical para o modo MVP. |
| `planner-human-verify-mode.md` | Regras para `workflow.human_verify_mode = end-of-phase`: suprime a emissão de tarefas `checkpoint:human-verify` e roteia itens adiados via `<verify><human-check>`. |
| `planner-graphify-auto-update.md` | Como `load_graph_context` levanta o estado de atualização automática de `.last-build-status.json` (running / failed / stale head) junto com a anotação de desatualização existente. Opt-in via `graphify.auto_update` (#3347). |
| `planner-interface-context.md` | Regras de contexto de interface para executores — como extrair interfaces/tipos/exportações chave do código existente e documentar novas interfaces que planos subsequentes consumirão. |
| `skeleton-template.md` | Template do SKELETON.md emitido para o Walking Skeleton de novo projeto (Fase 1 + `--mvp`). |
| `user-story-template.md` | Formato de história de usuário para planejamento MVP — campos estruturados "Como / Quero / Para que". |
| `spidr-splitting.md` | Regras de decomposição de divisão SPIDR para lidar com histórias de usuário grandes no modo MVP. |
> **Subdiretório:** `get-shit-done/references/few-shot-examples/` contém exemplos adicionais de few-shot (`plan-checker.md`, `verifier.md`) que são referenciados por agentes específicos. Estes não são contados nas 62 referências de nível superior.
---
## Módulos de CLI (81 entregues)
Listagem completa: `get-shit-done/bin/lib/*.cjs`.
| Módulo | Responsabilidade |
|--------|-----------------|
| `active-workstream-store.cjs` | Precedência de fonte e seleção de workstream (CLI `--ws` > env `GSD_WORKSTREAM` > ponteiro armazenado); validação de nome e propagação de ambiente |
| `adr-parser.cjs` | Analisador de decisão ADR para o caminho expresso de ingestão da plan-phase; normaliza sinônimos de seção, analisa cercas de status/decisão/escopo e aplica portões de rejeição de status |
| `agent-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools agent` |
| `artifacts.cjs` | Registro canônico de artefatos — nomes de arquivos raiz conhecidos de `.planning/`; usado pelo lint W019 do `gsd-health` |
| `audit.cjs` | Despacho de auditoria, sessões abertas de auditoria, auxiliares de armazenamento de auditoria |
| `check-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools check` |
| `cjs-command-router-adapter.cjs` | Adaptador de compatibilidade compartilhado para roteadores de família de comandos CJS com suporte de manifesto |
| `clock.cjs` | Costura de relógio injetável (now/sleep) para teste determinístico de bloqueio |
| `clusters.cjs` | Definições de cluster de habilidades para o módulo de superfície de runtime (ADR-0011 Fase 2) |
| `code-review-flags.cjs` | Analisador de flags tipado para `/gsd:code-review`; exporta `parseCodeReviewFlags(argv)` (→ `{ fix, all, auto, depth, files }`) e `resolveCodeReviewWorkflow(flags)` (→ `'code-review.md' \| 'code-review-fix.md'`); costura de despacho canônica para roteamento de `--fix`/`--all`/`--auto` |
| `command-aliases.cjs` | Metadados de alias/subcomando para roteadores de família com suporte de manifesto |
| `command-arg-projection.cjs` | Auxiliares de projeção de flag tipada e argumento posicional compartilhados entre roteadores de família de comandos |
| `command-routing-hub.cjs` | Hub de despacho de resultado puro que centraliza a decisão de modo (SDK vs CJS), taxonomia de erros e contrato sem lançamento para todos os roteadores de família de comandos (#3788) |
| `commands.cjs` | Comandos CLI diversos (slug, timestamp, todos, scaffolding, stats) |
| `config-schema.cjs` | Fonte única de verdade para `VALID_CONFIG_KEYS` e padrões de chave dinâmica; importado tanto pelo validador quanto pelo teste de paridade config-schema-docs |
| `config.cjs` | Leitura/escrita de `config.json`, inicialização de seção; importa validador de `config-schema.cjs` |
| `config-types.cjs` | Definições de tipo TypeScript para o bloco de configuração `model_policy` — `ModelPolicyConfig`, `TierEntry`, `RuntimeTiers`; compilado de `src/config-types.cts` no momento da publicação (ADR-457) |
| `configuration.cjs` | Módulo de Configuração — carregamento canônico de configuração, normalização de chave legada, merge de padrões e migração explícita em disco; fonte de verdade para consumidores SDK e CJS |
| `context-utilization.cjs` | Classificador puro para `gsd-health --context` — converte (tokensUsed, contextWindow) em um resultado de triagem `{ percent, state }` contra os limiares de ponto de fratura de 60%/70% (#2792) |
| `core.cjs` | Tratamento de erros, formatação de saída, utilitários compartilhados, fallbacks de runtime; re-exportações de compatibilidade para auxiliares de planning-workspace |
| `decisions.cjs` | Analisa blocos `<decisions>` do CONTEXT.md; aceita IDs numéricos (D-42) e alfanuméricos (D-INFRA-01); retorna `{id, text, category, tags, trackable}` |
| `docs.cjs` | Inicialização do workflow docs-update, varredura de Markdown, detecção de monorepo |
| `drift.cjs` | Detector de drift estrutural pós-execução da base de código (#2003): classifica alterações de arquivo em categorias new-dir/barrel/migration/route e faz round-trip do frontmatter `last_mapped_commit` |
| `fallow-runner.cjs` | Adaptador de auditoria fallow para `/gsd-code-review`: resolução binária (`PATH` depois `node_modules/.bin`), erros acionáveis de binário ausente e normalização de descobertas estruturais |
| `frontmatter.cjs` | Operações CRUD de frontmatter YAML |
| `gap-checker.cjs` | Análise de lacunas pós-planejamento (#2493): relatório unificado de cobertura de decisões do REQUIREMENTS.md + CONTEXT.md vs PLAN.md (`gsd-tools gap-analysis`) |
| `graphify.cjs` | Build/consulta/status/diff do grafo de conhecimento para `/gsd-graphify` |
| `gsd2-import.cjs` | Ingestão de plano externo para `/gsd-import --from-gsd2` |
| `init-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools init` |
| `init.cjs` | Carregamento de contexto composto para cada tipo de workflow |
| `install-profiles.cjs` | Lista de permissões de perfil de instalação + staging de habilidades para instalação `--minimal` (#2762); fonte única de verdade para quais habilidades/agentes `gsd-*` ficam nos diretórios de configuração de runtime |
| `installer-migration-authoring.cjs` | Barreiras de autoria de migração do instalador para metadados de registro, escopos explícitos, evidência de propriedade e citações de contrato de runtime |
| `installer-migration-report.cjs` | Projeção de relatório de migração do instalador e guarda de ação bloqueada para integração de instalação/atualização |
| `installer-migrations.cjs` | Planejamento de migração do instalador, classificação de artefatos, persistência do estado de instalação, aplicação com journal e auxiliares de rollback |
| `intel.cjs` | Armazenamento de intel da base de código suportando `/gsd-map-codebase --query` e `gsd-intel-updater` |
| `learnings.cjs` | Extração de aprendizados entre fases para `/gsd-extract-learnings` |
| `milestone.cjs` | Arquivamento de milestone, marcação de requisitos |
| `model-catalog.cjs` | Adaptador CJS sobre o JSON do catálogo de modelos compartilhado; exporta padrões canônicos de nível de runtime, mapas de perfil de agente, mapas de alias e metadados de roteamento para todos os consumidores de CLI |
| `model-profiles.cjs` | Auxiliares de perfil compatíveis com versões anteriores derivados de `model-catalog.cjs`; não possui mais sua própria tabela de modelos |
| `package-identity.cjs` | Fonte única gerada para as coordenadas do pacote publicado do GSD (nome npm, nome bin, slug do repositório, URL do changelog, comando de instalação manual), derivado do package.json; lido pelo worker de atualização, `check-latest-version` e instalador (#498) |
| `phase-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools phase` |
| `phase-lifecycle.cjs` | Auxiliares de ciclo de vida de fase de computação pura extraídos do handler SDK de ciclo de vida de fase |
| `phase.cjs` | Operações de diretório de fase, numeração decimal, indexação de planos |
| `phases-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools phases` |
| `plan-scan.cjs` | Scanner canônico de plano de fase para detectar arquivos de plano e resumo em layouts planos e aninhados (k014) |
| `planning-workspace.cjs` | Costura de caminho/workstream de planejamento (`planningDir`, `planningPaths`, roteamento de workstream ativo, orquestração de `.planning/.lock`) |
| `project-root.cjs` | Resolve uma raiz de projeto a partir de um diretório inicial usando quatro heurísticas (guarda de `.planning/` próprio, config `sub_repos`, flag `multiRepo`, heurística `.git`) |
| `profile-output.cjs` | Renderização de perfil, geração de USER-PROFILE.md e dev-preferences.md |
| `profile-pipeline.cjs` | Pipeline de dados de perfil comportamental do usuário, varredura de arquivos de sessão |
| `prompt-budget.cjs` | Contabilidade pura de orçamento de tokens para prompts de revisão — estima tokens, aplica prioridade de corte determinística (redução de cabeça PROJECT.md, truncamento proporcional de plano, descarte de contexto/pesquisa/requisitos, guarda de falha rígida), retorna metadados estruturados para `review.max_prompt_tokens` (#3081) |
| `review-reviewer-selection.cjs` | Auxiliares de seleção/normalização de revisor para política de revisor padrão e precedência do `/gsd-review` |
| `roadmap-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools roadmap` |
| `roadmap-upgrade.cjs` | Ferramenta de migração para converter entradas legadas `Phase N` para a convenção prefixada de milestone `Phase M-NN`; `computeMigrationPlan` + `applyMigration` com padrão dry-run e rollback atômico |
| `roadmap.cjs` | Análise de ROADMAP.md, extração de fases, progresso de plano |
| `runtime-artifact-layout.cjs` | Módulo de layout de artefatos de runtime — resolve as formas do diretório de artefatos (comandos, agentes, habilidades) para cada runtime suportado; fonte única de verdade para posicionamento de artefatos por runtime (#3663) |
| `runtime-name-policy.cjs` | Política de normalização de nome de runtime — sanitização canônica de token para identificadores de runtime usados na construção de caminhos e exibição |
| `runtime-homes.cjs` | Mapeamento canônico de runtime → diretório de configuração/habilidades global; suporte de primeira classe para todos os 15 runtimes incluindo layout aninhado Hermes e exclusão baseada em regras Cline (#3126) |
| `runtime-slash.cjs` | Formatador de comando slash com reconhecimento de runtime — fonte única de verdade para emitir `/gsd-<cmd>` (runtimes baseados em habilidades) e `$gsd-<cmd>` (codex) em saída voltada ao usuário e artefatos persistidos (#3584) |
| `schema-detect.cjs` | Detecção de drift de esquema para padrões ORM (Prisma, Drizzle, Supabase, TypeORM, Payload); exporta `detectSchemaFiles`, `detectSchemaOrm`, `checkSchemaDrift`, `SCHEMA_PATTERNS`, `ORM_INFO` |
| `secrets.cjs` | Convenção de mascaramento de configuração de segredo (`****<last-4>`) para chaves de integração; exporta `SECRET_CONFIG_KEYS`, `isSecretKey`, `maskSecret`, `maskIfSecret` |
| `semver-compare.cjs` | Auxiliares de política de comparação semver compartilhados (`compareSemverCore`, validação de tripla estável, análise de tupla normalizada) consumidos por hooks de verificação de atualização, detecção de instalação dev da linha de status e lógica de intervalo de extração de changeset (#10) |
| `security.cjs` | Prevenção de path traversal, detecção de injeção de prompt, auxiliares JSON/shell seguros |
| `shell-command-projection.cjs` | Projeção de comando shell com reconhecimento de runtime para serialização de hook gerenciado: decide o uso do operador de chamada PowerShell por runtime/plataforma e normaliza tokens de caminho de script Windows |
| `state-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools state` |
| `state.cjs` | Análise, atualização, progressão e métricas do STATE.md |
| `state-document.cjs` | Extração de campo, substituição, normalização de status e transformações de cálculo de progresso puras do STATE.md |
| `surface.cjs` | Módulo de superfície de runtime — gerencia o estado de superfície de habilitação/desabilitação do runtime independentemente do marcador de perfil no momento da instalação (ADR-0011 Fase 2) |
| `task-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools task` |
| `template.cjs` | Seleção e preenchimento de template com substituição de variáveis |
| `uat.cjs` | Análise de arquivo UAT, rastreamento de dívida de verificação, suporte audit-uat |
| `ui-safety-gate.cjs` | Detector de token de UI de limite de palavra sem shell (#3706, #3718); lê texto de seção de fase do stdin, sai com 0 (UI encontrada) ou 1 (sem UI); também implantado em `get-shit-done/bin/lib/` para que o instalador GSD o entregue em `$RUNTIME_DIR` (#448) |
| `update-context.cjs` | Resolvedor de contexto de instalação puro para `/gsd:update` — detecção de runtime/escopo/config-dir/versão (LOCAL/GLOBAL/UNKNOWN) portada do bash de update.md; sustenta `gsd-tools update-context` (#498) |
| `validate-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools validate` |
| `validate.cjs` | Auxiliares de normalização de variante de fase puros (`phaseVariants`, `buildRoadmapPhaseVariants`, `buildNotStartedPhaseVariants`) usados por `verify.cjs` para verificações W006/W007; sem I/O, sem async |
| `verify-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `gsd-tools verify` |
| `verify.cjs` | Estrutura de plano, completude de fase, referência, validação de commit |
| `workstream-inventory-builder.cjs` | Construtor de projeção de inventário de workstream puro |
| `workstream-inventory.cjs` | Projeção de inventário de workstream compartilhada: campos de estado, contagens de fase/plano/resumo, contagem de fase do roadmap e marcador ativo — orquestrador fino que delega projeção pura para `workstream-inventory-builder.cjs` |
| `workstream-name-policy.cjs` | Validação canônica de nome de workstream (`isValidActiveWorkstreamName`, `hasInvalidPathSegment`, `validateWorkstreamName`) e normalização de slug (`toWorkstreamSlug`) |
| `workstream.cjs` | CRUD de workstream, migração, ponteiro ativo com escopo de sessão |
| `worktree-safety.cjs` | Resolução de raiz de worktree e decisões de política de poda não destrutiva; possui a lógica de verificação de integridade W017 |
[`docs/CLI-TOOLS.md`](CLI-TOOLS.md) pode descrever um subconjunto desses módulos; quando discordar do sistema de arquivos, esta tabela e a listagem de diretório são autoritativas.
---
## Hooks (14 entregues)
Listagem completa: `hooks/`.
| Hook | Evento | Finalidade |
|------|--------|-----------|
| `gsd-statusline.js` | `statusLine` | Exibe modelo, tarefa, diretório, uso de contexto |
| `gsd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injeta avisos de contexto voltados ao agente a 35%/25% de contexto restante |
| `gsd-check-update.js` | `SessionStart` | Verificação em segundo plano de novas versões do GSD |
| `gsd-check-update-worker.js` | (worker) | Auxiliar de worker em segundo plano para check-update |
| `gsd-update-banner.js` | `SessionStart` | Banner opt-in que levanta a disponibilidade de atualização quando a statusline GSD não é usada (PR #2795) |
| `gsd-prompt-guard.js` | `PreToolUse` | Varre escritas em `.planning/` em busca de padrões de injeção de prompt (consultivo) |
| `gsd-workflow-guard.js` | `PreToolUse` | Detecta edições de arquivo fora do contexto de workflow GSD (consultivo, opt-in) |
| `gsd-read-guard.js` | `PreToolUse` | Guarda consultiva que impede Edit/Write em arquivos não lidos |
| `gsd-read-injection-scanner.js` | `PostToolUse` | Varre resultados de Read de ferramenta em busca de padrões de injeção de prompt (v1.36+, PR #2201) |
| `gsd-worktree-path-guard.js` | `PreToolUse` | Bloqueia rigorosamente Edit/Write/MultiEdit com caminhos absolutos fora da raiz do worktree (PR #579, #260) |
| `gsd-session-state.sh` | `PostToolUse` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `gsd-validate-commit.sh` | `PostToolUse` | Validação de commit para aplicação de conventional-commit |
| `gsd-phase-boundary.sh` | `PostToolUse` | Detecção de limite de fase para transições de workflow |
| `gsd-graphify-update.sh` | `PostToolUse` | Reconstrução automática do grafo de conhecimento após o avanço do HEAD principal (opt-in, padrão desativado — #3347) |
---
## Manutenção
- Quando um novo comando, agente, workflow, referência, módulo de CLI ou hook for entregue, atualize a seção correspondente aqui antes que a versão seja liberada.
- Os testes de guarda de drift em `tests/` (veja "Como Usar Este Arquivo" acima) asseguram que todo arquivo entregue está enumerado neste inventário. Um novo arquivo sem uma linha correspondente aqui falhará no CI.
- Quando o sistema de arquivos divergir das contagens de `docs/ARCHITECTURE.md` ou de documentações de subconjunto curado (p. ex. o registro primário do `docs/AGENTS.md`), este arquivo é a fonte de verdade.
## Relacionados
- [Comandos](COMMANDS.md) — referência de comandos voltados ao usuário
- [Arquitetura](ARCHITECTURE.md) — como as superfícies se encaixam
- [índice de documentação](README.md)

85
docs/pt-BR/README.md
View File

@@ -1,34 +1,69 @@
# Documentação do GSD Core
Documentação abrangente do GSD Core (Git. Ship. Done.) — um sistema de meta-prompting, engenharia de contexto e desenvolvimento orientado por especificações para agentes de IA.
A documentação está organizada em quatro quadrantes: **tutoriais** ajudam você a aprender na prática, **guias de instruções** resolvem tarefas específicas, **referência** apresenta fatos autorizados, e **explicação** explora conceitos e decisões de design.
## Índice da documentação
Versões por idioma: [English](../README.md) · [Português (pt-BR)](README.md) · [日本語](../ja-JP/README.md) · [简体中文](../zh-CN/README.md)
| 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 | Superfície CJS `gsd-tools.cjs` + guia guia de `gsd-tools.cjs query` |
| [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 |
---
## Novidades v1.39
## Tutorials
Perfil de instalação `--minimal` (≥94% de redução no cold-start), `/gsd-phase --edit`, build & test gate pós-merge, `review.models.<cli>` para escolha de modelo de review por runtime, herança de configuração de workstream, workflow manual de canary release, consolidação de skills (86 → 59).
- [Seu primeiro projeto](tutorials/your-first-project.md) — da instalação à primeira fase entregue, um caminho garantido
- [Integrando uma base de código existente](tutorials/onboarding-an-existing-codebase.md) — leve o GSD Core a um repositório já existente
## 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)
## How-to guides
> [!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.
- [Instalar no seu ambiente de execução](how-to/install-on-your-runtime.md) — passos de instalação específicos para cada um dos 15 ambientes de execução suportados
- [Discutir uma fase](how-to/discuss-a-phase.md) — registrar decisões de implementação antes do início do planejamento
- [Planejar uma fase](how-to/plan-a-phase.md) — executar pesquisa, decompor o trabalho e verificar a qualidade do plano
- [Executar uma fase](how-to/execute-a-phase.md) — rodar planos em ondas paralelas com subagentes com contexto renovado
- [Verificar e entregar](how-to/verify-and-ship.md) — revisar o trabalho concluído, diagnosticar falhas e criar o PR
- [Rodar fases de forma autônoma](how-to/run-phases-autonomously.md) — usar o modo autônomo para execução de fases sem supervisão
- [Lidar com tarefas rápidas e ágeis](how-to/handle-quick-and-fast-tasks.md) — usar `/gsd-quick` e `/gsd-fast` para trabalho avulso fora do ciclo de fases
- [Configurar perfis de modelo](how-to/configure-model-profiles.md) — alternar entre níveis de modelo: qualidade, equilibrado e econômico
- [Configurar revisão entre IAs](how-to/set-up-cross-ai-review.md) — configurar uma segunda IA para revisar o código produzido pelo agente principal
- [Trabalhar em paralelo com workstreams](how-to/work-in-parallel-with-workstreams.md) — executar linhas de trabalho independentes simultaneamente usando workstreams
- [Isolar trabalho com workspaces](how-to/isolate-work-with-workspaces.md) — usar workspaces para isolar mudanças experimentais ou arriscadas
- [Depurar uma execução com falha](how-to/debug-a-failed-execution.md) — diagnosticar e recuperar de execuções de fase quebradas ou incompletas
- [Explorar e esboçar](how-to/spike-and-sketch.md) — usar `/gsd-spike` e `/gsd-sketch` para trabalho exploratório antes de comprometer com um plano
- [Projetar uma fase de UI](how-to/design-a-ui-phase.md) — usar o ciclo de fase de UI para trabalho de frontend e visual
- [Conduzir o GSD a partir de uma issue do rastreador](how-to/drive-gsd-from-a-tracker-issue.md) — iniciar uma fase a partir de uma issue do GitHub, Linear ou Jira
- [Migrar do GSD 2](how-to/migrate-from-gsd-2.md) — atualizar um projeto GSD 2 existente para o GSD Core
- [Atualizar o GSD](how-to/update-gsd.md) — executar novamente o instalador para obter a versão mais recente
- [Recuperar e solucionar problemas](how-to/recover-and-troubleshoot.md) — corrigir problemas comuns, reconstruir contexto e desinstalar
---
## Referência
- [Comandos](COMMANDS.md) — todos os comandos com flags e exemplos
- [Configuração](CONFIGURATION.md) — schema completo de configuração, perfis de modelo, estratégias de branching git
- [Ferramentas CLI](CLI-TOOLS.md) — API programática `gsd-tools.cjs` para workflows e agentes
- [Funcionalidades](FEATURES.md) — índice completo de funcionalidades
- [Inventário](INVENTORY.md) — skills instaladas e mapa de superfície
- [Schema do STATE.md](reference/state-md.md) — referência campo a campo para `.planning/STATE.md`
- [Schema do CONTEXT.md](reference/context-md.md) — referência campo a campo para `.planning/phases/<N>/CONTEXT.md`
- [Schema do PLAN.md](reference/plan-md.md) — referência campo a campo para `.planning/phases/<N>/PLAN.md`
- [Artefatos de planejamento](reference/planning-artifacts.md) — todos os arquivos `.planning/` e seus papéis
---
## Explicação
- [Engenharia de contexto](explanation/context-engineering.md) — como a degradação de contexto se forma e como o GSD Core a previne
- [O ciclo de fase](explanation/the-phase-loop.md) — racional de design para o ciclo Discuss → Plan → Execute → Verify → Ship
- [Orquestração multi-agente](explanation/multi-agent-orchestration.md) — como os subagentes são criados, delimitados e coordenados
- [Modelo de segurança](explanation/security-model.md) — limites de confiança, permissões e automação segura
- [Arquitetura](ARCHITECTURE.md) — arquitetura do sistema, modelo de agentes e fluxo de dados
- [Modos de discussão](workflow-discuss-mode.md) — modo de suposições vs. modo de entrevista para `/gsd-discuss-phase`
- [Monitoramento de contexto](context-monitor.md) — arquitetura do hook de monitoramento da janela de contexto
- [Orquestração orientada por issues](issue-driven-orchestration.md) — receita para conduzir o GSD a partir de uma issue do rastreador usando primitivos existentes
---
## Relacionados
- [README raiz](../README.md) — página inicial, início rápido e visão geral da documentação
- [Changelog](../../CHANGELOG.md) — histórico de versões

941
docs/pt-BR/USER-GUIDE.md
View File

File diff suppressed because it is too large Load Diff

90
docs/pt-BR/context-monitor.md
View File

@@ -1,40 +1,80 @@
# Monitor de Contexto
# Monitor de Janela 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.
Um hook pós-ferramenta (`PostToolUse` para o Claude Code, `AfterTool` para o Gemini CLI) que avisa o agente quando o uso da janela de contexto está elevado.
Para detalhes completos de implementação, veja [context-monitor.md em inglês](../context-monitor.md).
## Problema
---
A barra de status exibe o uso de contexto para o **usuário**, mas o **agente** não tem consciência dos limites de contexto. Quando o contexto está se esgotando, o agente continua trabalhando até atingir o limite — potencialmente no meio de uma tarefa, sem nenhum estado salvo.
## Objetivos
## Como Funciona
- 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
1. O hook da barra de status grava métricas de contexto em `/tmp/claude-ctx-{session_id}.json`
2. Após cada uso de ferramenta, o monitor de contexto lê essas métricas
3. Quando o contexto restante cai abaixo dos limiares, ele injeta um aviso como `additionalContext`
4. O agente recebe o aviso em sua conversa e pode agir de acordo
## Como funciona
## Limiares
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
| Nível | Restante | Comportamento do Agente |
|-------|----------|-------------------------|
| Normal | > 35% | Sem aviso |
| ALERTA | <= 35% | Encerrar a tarefa atual, evitar iniciar trabalhos complexos novos |
| CRÍTICO | <= 25% | Parar imediatamente, salvar estado (`/gsd-pause-work`) |
## Estratégia recomendada
## Debounce
- Limpe contexto entre fases grandes
- Execute tarefas pesadas em subagentes
- Mantenha o estado em `.planning/` como fonte de verdade
Para evitar sobrecarregar o agente com avisos repetidos:
- O primeiro aviso sempre é disparado imediatamente
- Avisos subsequentes exigem 5 usos de ferramenta entre eles
- A escalada de severidade (ALERTA -> CRÍTICO) ignora o debounce
## Recuperação quando há degradação
## Arquitetura
```bash
/clear
/gsd-resume-work
# ou
/gsd-progress
```
Hook da Barra de Status (gsd-statusline.js)
| escreve
v
/tmp/claude-ctx-{session_id}.json
^ lê
|
Monitor de Contexto (gsd-context-monitor.js, PostToolUse/AfterTool)
| injeta
v
additionalContext -> Agente recebe o aviso
```
O arquivo de ponte é um objeto JSON simples:
```json
{
"session_id": "abc123",
"remaining_percentage": 28.5,
"used_pct": 71,
"timestamp": 1708200000
}
```
## Integração com o GSD
O comando `/gsd-pause-work` do GSD salva o estado de execução. A mensagem de ALERTA sugere utilizá-lo. A mensagem CRÍTICA instrui o salvamento imediato do estado.
## Configuração
Ambos os hooks são registrados automaticamente durante a instalação do `npx @opengsd/gsd-core` — nenhuma etapa manual é necessária em circunstâncias normais. Para detalhes de configuração de hooks, substituições de limiares e exemplos de registro manual, consulte [Configuração](CONFIGURATION.md).
Como referência rápida: o hook da barra de status se registra como `statusLine` em `settings.json`; o monitor de contexto (`gsd-context-monitor.js`) se registra como um hook `PostToolUse` (ou `AfterTool` para o Gemini CLI). Ambas as entradas utilizam o caminho absoluto do executável Node que executou o instalador. No Windows PowerShell, prefixe caminhos de executáveis entre aspas com `&`.
## Segurança
- O hook envolve tudo em try/catch e encerra silenciosamente em caso de erro
- Ele nunca bloqueia a execução de ferramentas — um monitor com falha não deve interromper o fluxo de trabalho do agente
- Métricas obsoletas (com mais de 60s) são ignoradas
- Arquivos de ponte ausentes são tratados de forma elegante (subagentes, sessões novas)
---
> [!TIP]
> O monitor não substitui boas práticas de escopo. Planos pequenos e verificáveis continuam sendo o principal fator de qualidade.
## Relacionados
- [Arquitetura](ARCHITECTURE.md)
- [Configuração](CONFIGURATION.md)
- [Índice da documentação](README.md)

90
docs/pt-BR/explanation/context-engineering.md Normal file
View File

@@ -0,0 +1,90 @@
# Engenharia de contexto
> Por que o GSD Core existe e qual problema ele foi projetado para resolver.
---
## O problema: degradação de contexto
Toda sessão de programação com IA começa do zero. O modelo lê sua pergunta, raciocina sobre ela e responde. Mas raramente uma sessão é composta de uma única troca. Você faz perguntas de acompanhamento, cola mensagens de erro, itera sobre o código, redireciona o modelo quando ele se desvia. Cada turno adiciona tokens à janela de contexto — o buffer finito de texto que o modelo consegue "enxergar" de uma só vez.
À medida que essa janela vai se preenchendo, algo sutil acontece. O modelo não falha de forma escancarada. Ele continua respondendo. Mas a qualidade das suas respostas vai se degradando silenciosamente. As instruções iniciais são empurradas para as bordas do que ele consegue atentar. A nuance das primeiras trocas — as restrições que você estabeleceu, a arquitetura que você acordou, os casos extremos que você sinalizou — compete por atenção com tudo o que veio depois. Pesquisadores chamam isso de **degradação de contexto** (*context rot*).
A degradação de contexto se manifesta de várias formas:
- O modelo começa a contradizer decisões anteriores que havia reconhecido.
- O estilo do código se distancia das convenções estabelecidas no início da sessão.
- Os planos passam a ignorar requisitos que foram claramente declarados, mas que agora estão soterrados no histórico.
- O modelo alucina nomes de arquivos ou assinaturas de funções que tinha corretos vinte mensagens atrás.
Nada disso é um bug do modelo. É uma propriedade fundamental de como a atenção de transformers funciona sobre sequências longas. O modelo não está esquecendo — ele nunca "lembrou" no sentido humano. Ele está ponderando a relevância ao longo de uma janela finita e, à medida que essa janela se preenche com ruído acumulado, a relação sinal-ruído se degrada.
A resposta ingênua é usar `/clear` e recomeçar. Mas isso perde a continuidade. Você precisa reexplicar o contexto, recolar os arquivos relevantes, reafirmar as restrições. A sessão essencialmente volta à estaca zero.
---
## A resposta do GSD Core: subagentes com contexto limpo
O insight central do GSD Core é que *a maior parte* do trabalho em uma sessão de programação não precisa acontecer no contexto principal. Pesquisa, planejamento, escrita de código e verificação são tarefas discretas e delimitadas. Cada uma pode ser entregue a um subagente especializado que começa com uma janela de contexto limpa e cuidadosamente delimitada — e reporta seu resultado de volta a um orquestrador enxuto que permanece leve.
Isso não é um contorno para a degradação de contexto. É uma solução estrutural.
O orquestrador — sua sessão principal — nunca toca os arquivos-fonte. Ele spawna agentes, coleta seus resultados, atualiza o estado compartilhado e encaminha para o próximo passo. Como ele faz muito pouco por conta própria, sua janela de contexto cresce de forma lenta e previsível. O trabalho pesado acontece em agentes que cada um começa do zero, recebe exatamente o contexto necessário para sua tarefa e termina quando concluído.
Considere o que isso significa na prática. Quando você executa `/gsd-plan-phase`, o orquestrador:
1. Carrega um payload de contexto JSON compacto (resumo do projeto, objetivo da fase, configuração relevante).
2. Spawna um agente pesquisador com uma janela limpa de 200k tokens.
3. Spawna um agente planejador com a saída da pesquisa e os requisitos da fase.
4. Spawna um agente verificador de plano para validar o plano antes da execução.
Cada agente opera com capacidade total, sem o peso do histórico acumulado da sua sessão. Quando o planejador escreve seus arquivos `PLAN.md` em `.planning/phases/`, essa saída se torna um artefato durável — não uma memória frágil em uma janela de contexto compartilhada.
---
## Desenvolvimento orientado a especificações e meta-prompting
A engenharia de contexto por si só não é suficiente. Se um agente começa do zero mas recebe instruções vagas, ele vai produzir saídas vagas. O GSD Core combina subagentes com contexto limpo com duas disciplinas complementares:
**Desenvolvimento orientado a especificações** significa que toda fase produz artefatos estruturados antes de a execução começar. Um `CONTEXT.md` captura as decisões de implementação da etapa Discuss. Um `RESEARCH.md` registra o que o pesquisador encontrou. Um `PLAN.md` divide o trabalho em tarefas discretas, ordenadas por dependência, com critérios de aceite explícitos. Quando um agente executor toca um arquivo, ele tem uma especificação precisa para seguir — não uma reinterpretação de uma conversa longa.
**Meta-prompting** significa que as próprias definições de agentes são prompts cuidadosamente engenheirados, não instruções ad-hoc. Os arquivos em `get-shit-done/workflows/` e `agents/` codificam conhecimento conquistado a duras penas sobre como delimitar tarefas, o que verificar e quando escalar para um checkpoint humano. O usuário não precisa reexplicar esse conhecimento a cada sessão; ele está integrado aos próprios prompts do sistema.
A combinação é deliberada. O contexto limpo garante que cada agente raciocine com clareza. Os artefatos orientados a especificações garantem que cada agente raciocine sobre a *coisa certa*. O meta-prompting garante que cada agente saiba *como* raciocinar bem sobre ela.
---
## O papel do `.planning/`
A engenharia de contexto exige que o conhecimento sobreviva a reinicializações de contexto. O GSD Core usa o sistema de arquivos para isso. Toda saída significativa é escrita em `.planning/` como Markdown ou JSON legível por humanos. Isso significa que:
- Reiniciar sua sessão (ou uma falha do modelo) não faz você perder trabalho.
- Qualquer agente subsequente pode ler artefatos anteriores diretamente, sem depender de um histórico de conversa compartilhado.
- Você pode inspecionar, editar ou commitar artefatos de planejamento no git — são texto simples, não estado opaco em um banco de dados.
`STATE.md` é a espinha dorsal desse sistema. Ele registra a posição atual do projeto (qual milestone, qual fase, quais planos estão completos), decisões ativas e bloqueadores, e métricas de progresso. Quando qualquer workflow começa, ele lê o `STATE.md` para se orientar. Quando qualquer workflow conclui uma etapa significativa, ele escreve de volta no `STATE.md`. Os agentes não dependem de memória; dependem do arquivo.
---
## Concessões e limitações
É importante ser honesto sobre as concessões envolvidas.
**Sobrecarga.** O ciclo de fases introduz atrito real. Executar `/gsd-discuss-phase`, `/gsd-plan-phase` e `/gsd-execute-phase` como etapas separadas leva mais tempo que digitar "escreva esse recurso" em uma sessão simples. Para uma mudança pequena e bem compreendida, essa sobrecarga não se justifica.
**Latência.** Spawnar múltiplos subagentes com contexto limpo é mais lento do que uma única edição no contexto. Pesquisa, planejamento e execução incorrem cada um em custos de ida e volta.
**Cerimônia para tarefas simples.** Se você precisa renomear uma variável, corrigir um erro de digitação ou adicionar um import ausente, o ciclo de fases é exagero. O GSD Core fornece `/gsd-quick` e `/gsd-fast` para trabalho ad-hoc que não justifica uma fase completa. Veja [Lidar com tarefas rápidas](../how-to/handle-quick-and-fast-tasks.md).
O ciclo de fases se paga quando o trabalho é suficientemente complexo para que a degradação de contexto seja um risco real — recursos com múltiplos arquivos, refatorações transversais, trabalho que se estende por horas ou sessões. Para todo o resto, recorra ao primitivo mais leve.
Uma regra de bolso útil: se a tarefa pudesse ser totalmente especificada em um prompt único e curto e concluída em um turno de agente sem mais esclarecimentos, pule o ciclo de fases. Se a tarefa requer pesquisa, envolve arquivos que você não leu recentemente, ou depende de decisões que ainda não estão definidas, o ciclo de fases te protege.
---
## Relacionados
- [O ciclo de fases](the-phase-loop.md) — como o ciclo Discuss → Plan → Execute → Verify → Ship coloca a engenharia de contexto em prática
- [Orquestração multi-agente](multi-agent-orchestration.md) — como subagentes são spawnados, delimitados e coordenados
- [Arquitetura](../ARCHITECTURE.md) — arquitetura do sistema, modelo de agentes e fluxo de dados
- [Índice de documentação](../README.md)

234
docs/pt-BR/explanation/multi-agent-orchestration.md Normal file
View File

@@ -0,0 +1,234 @@
# Orquestração multi-agente no GSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core foi projetado em torno da
> orquestração multi-agente e *como as partes se encaixam*. Não é um guia
> passo a passo. Para configuração, consulte
> [Configurar perfis de modelo](../how-to/configure-model-profiles.md) e a
> [Referência de configuração](../CONFIGURATION.md). Para o catálogo completo de agentes,
> consulte [Inventário](../INVENTORY.md).
---
## O problema que este design resolve
Agentes de codificação com IA degradam. Não porque o modelo piora, mas porque a
*janela de contexto fica cheia*. À medida que uma conversa cresce, decisões e código
anteriores são expulsos ou diluídos pelo ruído das etapas intermediárias. Quando um
agente escreve o quinto arquivo em uma tarefa complexa, pode já ter esquecido
a restrição declarada na primeira mensagem. Isso é às vezes chamado de *podridão
de contexto* (*context rot*).
O design multi-agente do GSD Core é uma resposta direta a esse problema. Em vez de
um único agente de longa duração carregando toda a sessão, um orquestrador enxuto gera
agentes especializados de curta duração, cada um com uma **janela de contexto fresca de 200 K tokens**
e *somente os artefatos de que precisa* para realizar seu trabalho específico. O orquestrador
nunca faz o trabalho pesado por conta própria; ele carrega o contexto, gera o agente
adequado, coleta o resultado e atualiza o estado compartilhado em `.planning/`.
---
## O padrão orquestrador → agente
Todos os workflows em `get-shit-done/workflows/` seguem a mesma estrutura:
```text
Orquestrador (arquivo .md de workflow)
│
├── Carregar contexto
│ gsd-tools.cjs init <workflow> <phase>
│ → JSON: informações do projeto, config, estado, detalhes da fase
│
├── Resolver modelo
│ gsd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── Gerar agente especializado (chamada Task/SubAgent)
│ ├── Definição do agente (agents/*.md)
│ ├── Payload de contexto (JSON de init)
│ ├── Atribuição de modelo
│ └── Permissões de ferramentas
│
├── Coletar resultado
│
└── Atualizar estado
gsd-tools.cjs state update / state patch / state advance-plan
```
O orquestrador é deliberadamente enxuto. Ele não raciocina sobre o domínio,
não escreve código e não interpreta resultados além de roteá-los para a
próxima etapa. Esse limite mantém a responsabilidade de cada camada clara e impede
que o contexto do orquestrador acumule ruído de domínio.
### O catálogo de agentes
Os agentes do GSD Core se enquadram em categorias funcionais que mapeiam o
pipeline pesquisa → planejamento → execução → verificação:
| Categoria | Agentes | Paralelismo típico |
|---|---|---|
| Pesquisadores | `gsd-project-researcher`, `gsd-phase-researcher`, `gsd-ui-researcher`, `gsd-advisor-researcher` | 4 em paralelo (stack, funcionalidades, arquitetura, armadilhas) |
| Sintetizadores | `gsd-research-synthesizer` | Sequencial, após a conclusão dos pesquisadores |
| Planejadores | `gsd-planner`, `gsd-roadmapper` | Sequencial |
| Verificadores | `gsd-plan-checker`, `gsd-integration-checker`, `gsd-ui-checker`, `gsd-nyquist-auditor` | Sequencial, até 3 iterações de revisão |
| Executores | `gsd-executor` | Paralelo dentro de uma onda, sequencial entre ondas |
| Validadores | `gsd-verifier` | Sequencial, após a conclusão de todos os executores |
| Mapeadores | `gsd-codebase-mapper` | 4 sub-sondas em paralelo |
| Auditores | `gsd-ui-auditor`, `gsd-security-auditor` | Sequencial |
Cada definição de agente (em `agents/*.md`) declara o acesso às ferramentas permitido,
a finalidade e a cor para saída no terminal. Um agente que só precisa ler arquivos
e escrever um único documento de saída recebe exatamente essas permissões — sem
execução de Bash, sem acesso a um estado mais amplo. Essa restrição é intencional: ela
mantém o raio de impacto pequeno caso um agente se comporte de forma inesperada.
Para o catálogo completo de 31 agentes, consulte [Inventário](../INVENTORY.md#agents-31-shipped).
---
## Execução paralela baseada em ondas
A expressão mais visível do design multi-agente é como o `/gsd-execute-phase`
lida com um conjunto de planos que podem depender uns dos outros.
Antes de gerar qualquer executor, o orquestrador realiza uma **análise de ondas**:
ele lê as declarações de dependência em cada arquivo `PLAN.md` e agrupa os planos
em ondas. Planos sem dependências declaradas formam a Onda 1 e executam em
paralelo. Planos que dependem da Onda 1 formam a Onda 2, e assim por diante.
```text
Plano 01 (sem deps) ─┐
Plano 02 (sem deps) ─┤─── Onda 1 (paralelo)
Plano 03 (depende de: 01) ─┤─── Onda 2 (aguarda Onda 1)
Plano 04 (depende de: 02) ─┘
Plano 05 (depende de: 03, 04) ─── Onda 3 (aguarda Onda 2)
```
Cada executor dentro de uma onda:
- recebe uma janela de contexto fresca (200 K tokens, ou até 1 M em modelos capazes)
- recebe o `PLAN.md` específico pelo qual é responsável
- recebe o contexto do projeto (`PROJECT.md`, `STATE.md`)
- recebe o contexto da fase (`CONTEXT.md`, `RESEARCH.md` se disponível)
- produz commits git atômicos ao concluir
- escreve um `SUMMARY.md` descrevendo o que foi construído
Após a conclusão de todos os executores em uma onda, o orquestrador executa o hook
de pré-commit uma vez para a onda como um todo. Os executores fazem commit com `--no-verify` para
evitar contenção de bloqueio de build (por exemplo, conflitos de lock do Cargo em projetos
Rust) quando múltiplos agentes fazem commit em paralelo. O hook, portanto, é executado
uma vez por onda em vez de uma vez por commit.
### Segurança de commits paralelos
Dois mecanismos previnem conflitos de escrita quando múltiplos executores executam
simultaneamente:
1. **Lock atômico em `STATE.md`** — Toda escrita em `STATE.md` usa um
arquivo de lock (`STATE.md.lock`) com criação atômica `O_EXCL`. Isso previne
a corrida de leitura-modificação-escrita onde dois agentes leem o arquivo, modificam
campos diferentes, e o escritor posterior sobrescreve as alterações do anterior.
Locks obsoletos (com mais de 10 segundos) são automaticamente removidos.
2. **Execução de hook por onda** — Em vez de cada executor executar hooks de pré-commit
de forma independente (o que pode causar contenção em nível de arquivo em artefatos
de build compartilhados), o orquestrador executa `git hook run pre-commit` uma vez após
a conclusão de cada onda.
---
## Enriquecimento adaptativo de contexto para modelos de janela grande
Janelas de contexto padrão de 200 K são suficientes para um executor implementar um
plano único e focado. Quando o `context_window` configurado é de 500 K tokens ou
maior (por exemplo, ao usar o Opus 4.6 ou Sonnet 4.6 no modo de 1 M), o orquestrador
automaticamente enriquece os prompts de subagentes com contexto adicional que não
caberia em uma janela padrão:
- **Agentes executores** recebem arquivos `SUMMARY.md` de ondas anteriores e o
`CONTEXT.md`/`RESEARCH.md` da fase, fornecendo a eles consciência entre planos
dentro da fase
- **Agentes validadores** recebem todos os arquivos `PLAN.md`, `SUMMARY.md` e `CONTEXT.md`
mais `REQUIREMENTS.md`, habilitando verificação com consciência histórica
Esse enriquecimento é condicional ao valor de `context_window` em
`config.json`. Em configurações de janela padrão, os prompts usam versões truncadas
com ordenação favorável ao cache para maximizar a eficiência de tokens.
---
## Por que este design — a conexão com a engenharia de contexto
O padrão orquestrador → agente só faz sentido como parte de uma abordagem mais ampla
de *engenharia de contexto*: a ideia de que o que um agente de IA recebe em sua
janela de contexto importa tanto quanto o nível do modelo ou a qualidade do prompt. Consulte
[Engenharia de contexto](context-engineering.md) para o tratamento completo.
A orquestração multi-agente operacionaliza a engenharia de contexto de duas formas:
**Isolamento de contexto.** Cada agente recebe apenas o que precisa. Um pesquisador
recebe a descrição do projeto e as questões de domínio; ele não recebe o histórico
completo de planejamento. Um validador recebe todos os planos e resumos; ele não recebe
a pesquisa bruta. O isolamento mantém o contexto de cada agente denso em sinal em vez
de diluído pelo ruído de outros estágios do pipeline.
**Higiene de contexto entre sessões.** Como todo o estado vive em
`.planning/` como Markdown e JSON legíveis por humanos (não na janela de contexto
de nenhum agente), os workflows do GSD sobrevivem a resets de contexto (`/clear`), trocas de
abas e intervalos de vários dias. O próximo agente sempre começa a partir de artefatos
persistidos e verificados, em vez de uma memória reconstruída de uma longa conversa.
---
## Compensações
A orquestração multi-agente não é gratuita.
**Sobrecarga de coordenação.** Cada geração de agente é uma ida e volta: o orquestrador
deve formatar um prompt, repassar o contexto, aguardar a conclusão do subagente
(tipicamente 1–5 minutos) e então analisar o resultado. Um único agente capaz
trabalhando em um contexto terminaria mais rápido para tarefas simples. O GSD mitiga
isso tornando o paralelismo o padrão sempre que as dependências permitirem — os
quatro pesquisadores em um `plan-phase` executam simultaneamente, não sequencialmente.
**Opacidade durante a execução.** Enquanto um subagente está em execução, seu trabalho é
invisível para a sessão pai. Não há fluxo de progresso ao vivo. Esta é uma
consequência deliberada do design de contexto fresco: o subagente está operando
em sua própria janela de contexto. O orquestrador exibe uma nota de atividade na
linha de geração ("executado em um subagente — sem saída até retornar") para definir
expectativas.
**Custo de costura de contexto.** Empacotar os artefatos certos para cada agente
requer que o orquestrador gaste tokens montando e transmitindo payloads de contexto.
Este é o custo do isolamento. O handler `gsd-tools.cjs init`
produz um payload JSON que equilibra completude com orçamento de tokens, aplicando
ordenação favorável ao cache para que as partes estáveis do payload (definição do projeto,
config) acertem o cache em invocações repetidas.
**Amplificação do custo do modelo.** Executar cinco agentes em paralelo no nível Opus
custa mais do que executar um. O sistema de perfis de modelo (`model_profiles.md`,
resolvido por agente pelo `model-profiles.cjs`) permite atribuir níveis mais baratos a
agentes menos críticos. O recurso `dynamic_routing` reduz ainda mais o custo ao
iniciar cada agente em um nível mais barato e escalar apenas em caso de falha suave.
Consulte [Configuração](../CONFIGURATION.md) para as opções completas.
Em troca desses custos, o design compra *qualidade consistente em fases grandes*.
Um executor escrevendo o décimo arquivo em um plano de 400 linhas não degrada porque
seu contexto está fresco. Um validador verificando vinte requisitos não esquece os
primeiros dez porque os recebeu todos como entrada estruturada em vez de histórico
de conversa.
---
## Relacionados
- [Engenharia de contexto](context-engineering.md) — o princípio upstream que
motiva este design
- [Configurar perfis de modelo](../how-to/configure-model-profiles.md) — como
atribuir níveis de modelo por agente
- [Referência de configuração](../CONFIGURATION.md) — schema completo de `config.json`
incluindo `models`, `model_overrides`, `dynamic_routing` e
`context_window`
- [Inventário](../INVENTORY.md) — catálogo autoritativo de agentes e lista de workflows
- [Arquitetura](../ARCHITECTURE.md#agent-model) — detalhes em nível de implementação
sobre o padrão orquestrador → agente e o modelo de execução por ondas
- [Índice de documentação](../README.md)

270
docs/pt-BR/explanation/security-model.md Normal file
View File

@@ -0,0 +1,270 @@
# Modelo de segurança do GSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core possui a
> postura de segurança que possui e *como as camadas se articulam*. Não é uma
> referência para todos os parâmetros de hook. Para o comando `/gsd-secure-phase`
> e suas opções, consulte [Comandos](../COMMANDS.md). Para a arquitetura de
> hooks em nível de implementação, consulte
> [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system).
> Para a linha de base de segurança organizacional (controles de scanner,
> checklists de incidentes, modelo de responsabilidade), consulte
> [SECURITY.md](../../../SECURITY.md).
---
## Por que o desenvolvimento orientado por IA precisa de uma postura de segurança dedicada
Um editor de código convencional não executa pacotes arbitrários em seu nome.
O GSD Core sim. O pipeline pesquisa → plano → execução automatiza o caminho
completo de "nomear um pacote" até "executar `npm install <package>`", de
"escrever um artefato de planejamento" até "usar esse artefato como prompt de
sistema de um LLM". Cada etapa de automação remove um humano do ciclo — e cada
remoção é uma superfície de ataque potencial.
O modelo de segurança do GSD Core é construído em torno de um princípio
organizador: **defesa em profundidade**. Nenhum controle isolado é assumido
como perfeito. Várias camadas sobrepostas reduzem, cada uma, uma classe distinta
de risco e, juntas, tornam a superfície de ataque substancialmente mais difícil
de explorar sem eliminá-la completamente. O resumo honesto ao final deste
documento explica o que o sistema não consegue proteger.
---
## Camada 1 — Proteção da cadeia de suprimentos: o Package Legitimacy Gate
### A ameaça
Modelos de IA alucinam nomes de pacotes. Este não é um modo de falha marginal:
pesquisas de 2025 documentam aproximadamente 20% das referências de pacotes
geradas por IA como nomes alucinados que não correspondem a pacotes legítimos.
Um subconjunto desses nomes alucinados — aproximadamente 43% na mesma pesquisa —
recorre consistentemente entre prompts, o que significa que um atacante pode
observar quais nomes as ferramentas de IA costumam produzir e pré-registrar
esses nomes no npm, PyPI ou crates.io com scripts de pós-instalação maliciosos.
A técnica é chamada de *slopsquatting*.
A qualidade insidiosa do slopsquatting é que um nome alucinado que passa no
`npm view` *parece legítimo*. A entrada no registro prova apenas que alguém
registrou o nome — não que o pacote faz o que a IA disse que faz, não que
possui usuários legítimos e não que seus scripts de instalação são seguros.
Sem uma barreira, um nome alucinado fluiria sem ser detectado pelo pipeline
pesquisador → planejador → executor do GSD e eventualmente seria executado como
`npm install <attacker-package>` na sua máquina.
### Como a barreira funciona
A barreira opera em três estágios do pipeline:
**Estágio de pesquisa.** Quando `gsd-phase-researcher` recomenda pacotes
externos, executa `slopcheck install <pkgs> --json` para cada um. Os resultados
são gravados em uma tabela `## Package Legitimacy Audit` no `RESEARCH.md`.
Pacotes marcados com `[SLOP]` (alucinação de alta confiança ou registrado por
atacante) são **removidos inteiramente do `RESEARCH.md`** antes de o arquivo
ser salvo. Eles nunca chegam ao planejador.
**Estágio de planejamento.** `gsd-planner` lê a tabela de auditoria. Para
qualquer pacote marcado com `[SUS]` (suspeito: recém-registrado, baixa contagem
de downloads, sem repositório de código-fonte ou padrão de nomenclatura próximo
a um pacote popular) ou `[ASSUMED]` (originado de WebSearch em vez de
verificação direta no registro), o planejador **insere uma tarefa
`checkpoint:human-verify`** antes da etapa de instalação. O checkpoint inclui
um link direto para a página do registro e aspectos específicos a verificar:
histórico do mantenedor, atividade no rastreador de problemas, ausência de
scripts de instalação suspeitos.
**Estágio de execução.** Se uma instalação falhar, `gsd-executor` **exibe um
checkpoint e para**. Ele não tenta silenciosamente um nome de pacote alternativo
— que poderia ser malicioso. Esta é uma regra explícita no comportamento do
executor (RULE 3 na definição do agente executor).
### Por que pacotes do WebSearch são sempre `[ASSUMED]`
Nomes de pacotes descobertos via WebSearch são marcados como `[ASSUMED]`
independentemente de o `npm view` ser bem-sucedido. Um pacote que existe no
registro não é o mesmo que um pacote seguro de instalar. `npm view` prova o
registro, não a legitimidade. A marcação `[ASSUMED]` aciona o mesmo checkpoint
de verificação humana que `[SUS]`, garantindo que qualquer recomendação
descoberta na web e não verificada sempre receba revisão humana antes da
instalação.
### Cobertura por ecossistema
O pesquisador usa comandos de verificação específicos de cada registro, em vez
de uma única verificação genérica:
- Node.js: `npm view`
- Python: `pip index versions`
- Rust: `cargo search`
Isso cobre alucinações entre ecossistemas, que ocorrem em aproximadamente 9%
dos casos de acordo com a pesquisa USENIX de 2025 — situações em que uma IA
recomenda um pacote que existe em um ecossistema, mas não no que está realmente
em uso.
### Degradação graciosa
Se `slopcheck` não estiver disponível (não instalado, ou se a instalação via
pip falhar no momento da pesquisa), o GSD aplica o fallback mais restrito
possível: **todo pacote recomendado é marcado como `[ASSUMED]`**, e o planejador
bloqueia cada instalação com uma tarefa `checkpoint:human-verify`. Pesquisa e
planejamento prosseguem normalmente — o sistema nunca falha irrecuperavelmente
por dependência de ferramenta ausente. Isso é intencionalmente mais restritivo
do que o fluxo normal: a indisponibilidade do slopcheck significa que toda
instalação de pacote recebe um checkpoint humano.
A ferramenta `slopcheck` é licenciada sob MIT e instalável via pip. Se for
descontinuada, o fallback de barreira `[ASSUMED]` garante que a cobertura por
checkpoint humano seja mantida independentemente.
---
## Camada 2 — Defesas contra injeção de prompt
### A ameaça
O GSD Core gera arquivos Markdown que se tornam prompts de sistema de LLMs. O
pipeline de pesquisa lê conteúdo externo da web; o pipeline de planejamento
incorpora texto fornecido pelo usuário (`--text-file`, `--prd`); o pipeline de
execução grava artefatos de planejamento que são relidos posteriormente como
contexto de agente. Qualquer texto controlado pelo usuário que flua para esses
artefatos é um vetor potencial de **injeção indireta de prompt** — uma string
controlada por um atacante que, uma vez dentro de um prompt de sistema, tenta
substituir as instruções do agente ou exfiltrar informações.
### Como as defesas funcionam
O GSD Core trata a injeção de prompt em três níveis.
**Validação de entrada (`security.cjs`).** O módulo
`get-shit-done/bin/lib/security.cjs` é o utilitário central de segurança.
Ele fornece:
- Prevenção de path traversal: caminhos de arquivo fornecidos pelo usuário
(`--text-file`, `--prd`) são validados para resolver dentro do diretório do
projeto, com resolução explícita do symlink `/var` → `/private/var` no macOS
- Detecção de injeção de prompt: padrões de injeção conhecidos (sobrescritas de
papel, desvios de instrução, injeções de tag de sistema) são escaneados em
texto fornecido pelo usuário antes de entrar em qualquer artefato de
planejamento
- Parsing seguro de JSON: um wrapper que previne ataques de poluição de
protótipo via payloads JSON manipulados
- Validação de argumentos de shell: argumentos passados a comandos de subshell
são validados antes do uso
**Hook de runtime: `gsd-prompt-guard.js`.** Este hook é acionado a cada
chamada de Write ou Edit que tem como alvo arquivos `.planning/`. Ele escaneia
o conteúdo sendo gravado em busca dos mesmos padrões de injeção que o
`security.cjs` (um subconjunto inlinado diretamente no hook para independência
— o hook não usa `require()` para carregar o módulo, portanto é executado mesmo
que o caminho do módulo mude). A detecção é **apenas consultiva**: o hook
registra a descoberta, mas não bloqueia a gravação. A justificativa é que um
bloqueio falso-positivo em uma gravação de planejamento legítima seria mais
disruptivo do que uma injeção não detectada em uma camada de varredura
secundária.
**Hook de runtime: `gsd-read-injection-scanner.js`.** Este hook é acionado na
saída de cada chamada da ferramenta Read. Ele escaneia o *conteúdo que acabou
de ser lido* em busca de instruções injetadas em conteúdo não confiável —
capturando casos em que um atacante incorporou instruções em um arquivo que o
GSD está prestes a incorporar ao contexto de um agente.
**Scanner de CI.** `prompt-injection-scan.test.cjs` escaneia todos os arquivos
de agente, workflow e comando em busca de vetores de injeção embutidos como
parte do conjunto de testes. Isso detecta tentativas de injeção no próprio
código-fonte do GSD — por exemplo, um ataque de cadeia de suprimentos que
modificou um arquivo de workflow para adicionar uma instrução de sobrescrita de
papel.
### Read Injection Scanner vs Prompt Guard
Os dois hooks cobrem superfícies complementares. `gsd-prompt-guard.js` monitora
*gravações em artefatos de planejamento* — ele detecta injeções sendo plantadas.
`gsd-read-injection-scanner.js` monitora *leituras de qualquer arquivo* — ele
detecta injeções sendo ingeridas a partir de conteúdo externo (o README de uma
dependência, um arquivo de configuração de terceiros, um documento fornecido
pelo usuário). Juntos, eles delimitam o ciclo de vida ingestão → armazenamento
→ releitura.
---
## Camada 3 — Integridade do repositório e das dependências
Acima do comportamento de runtime do GSD, a organização `open-gsd` aplica
controles nos níveis de repositório e pacote. Eles estão documentados
integralmente em [`docs/security/baseline.md`](../../security/baseline.md) e são
resumidos aqui para completude.
**Integridade das dependências.** Todas as dependências de terceiros são
fixadas via `package-lock.json` e verificadas em relação aos checksums
publicados antes da instalação. Uma barreira `scripts/check-npm-integrity.cjs`
detecta versões inválidas, pacotes ausentes e pacotes estranhos no momento do
CI. Isso mitiga ataques de confusão de dependências e typosquatting contra as
próprias dependências do GSD.
**Varredura de segredos.** Cada commit e PR é escaneado em busca de segredos
codificados no código. Fixtures de teste intencionais devem ser anotadas com a
gramática de exclusão padrão do projeto (consulte `SECURITY.md` para o formato
de anotação). Supressões não anotadas falham no CI.
**Varredura de texto com segurança de localidade.** Strings de saída e voltadas
ao usuário são escaneadas em busca de homóglifos Unicode, caracteres de
substituição bidirecional e Unicode invisível — a classe de ataques documentada
na CVE-2021-42574 ("Trojan Source") que pode ocultar conteúdo malicioso em
diffs.
---
## Concessões e limitações
O modelo de segurança descrito aqui reduz significativamente a superfície de
ataque para o desenvolvimento orientado por IA. Ele não elimina o risco da
cadeia de suprimentos.
**O que o Package Legitimacy Gate reduz:** A probabilidade de que um pacote
alucinado ou registrado por um atacante chegue ao `npm install` sem um
checkpoint humano. A barreira `[SLOP]` remove completamente pacotes ruins de
alta confiança; as barreiras `[SUS]` / `[ASSUMED]` exigem revisão humana antes
da execução. Isso eleva substancialmente o custo de um ataque de slopsquatting
bem-sucedido.
**O que o Package Legitimacy Gate não elimina:** Um pacote legítimo que é
comprometido posteriormente (tomada de conta, confusão de dependências em sua
própria árvore) não é detectado pelo slopcheck, que verifica sinais de registro
no momento da pesquisa. Lock files e `npm audit` na camada de integridade de
dependências são os controles para essa classe de ataque.
**O que as defesas contra injeção de prompt reduzem:** A probabilidade de que
texto controlado pelo usuário em artefatos de planejamento substitua com sucesso
as instruções do agente. A correspondência de padrões com formas de injeção
conhecidas detecta os casos comuns; jailbreaks novos ou injeções de baixo sinal
podem passar sem ser detectados. A postura apenas consultiva significa que a
detecção é registrada, mas não bloqueada — uma escolha deliberada que preserva
a continuidade do fluxo de trabalho ao custo de não interromper definitivamente
em uma detecção.
**O que as defesas contra injeção de prompt não eliminam:** Uma injeção
suficientemente criativa que não corresponde a padrões conhecidos, ou uma
injeção que chega por um canal que os hooks não cobrem (por exemplo, conteúdo
injetado no README publicado de uma dependência que é lido por um subagente
navegando em documentação). Defesa em profundidade significa que cada camada
torna o ataque mais difícil, não que qualquer camada isolada o torna impossível.
**Reportando vulnerabilidades.** Relate por meio de advisory de segurança
privado do GitHub em
`https://github.com/open-gsd/gsd-core/security/advisories/new`. Não abra
issues públicas. Consulte [SECURITY.md](../../../SECURITY.md) para o cronograma
de resposta e a política de divulgação.
---
## Relacionados
- [Comandos](../COMMANDS.md) — inclui `/gsd-secure-phase` e
`/gsd-code-review` com flags relevantes para segurança
- [Arquitetura § Sistema de Hooks](../ARCHITECTURE.md#hook-system) —
detalhes de implementação de cada hook, seu gatilho de evento e propriedades
de segurança
- [SECURITY.md](../../../SECURITY.md) — reporte de vulnerabilidades, linha de
base de segurança organizacional, governança de exclusão de varredura de
segredos e verificação de integridade de dependências
- [Índice de documentação](../README.md)

129
docs/pt-BR/explanation/the-phase-loop.md Normal file
View File

@@ -0,0 +1,129 @@
# O loop de fases
> O modelo mental central de como o GSD Core organiza o trabalho.
---
## O que é o loop
O GSD Core estrutura todo o trabalho de desenvolvimento como um ciclo que se repete:
```text
Discuss → (UI design) → Plan → Execute → Verify → Ship
```
Cada unidade de trabalho — chamada de **fase** — percorre essas etapas em ordem. O loop não é uma formalidade. Cada etapa existe porque protege contra uma classe específica de falha que a etapa anterior, por si só, não consegue evitar.
Este documento explica *por que* o loop tem a forma que tem. Para instruções sobre como executar cada etapa, veja os guias práticos linkados ao final.
---
## Por que cada etapa existe
### Discuss
O planejamento não pode começar até que você saiba *como* construir a coisa, não apenas *o que* construir. O objetivo da fase em `ROADMAP.md` descreve o resultado. A etapa Discuss captura as decisões de implementação que moldam o caminho até esse resultado: quais bibliotecas, qual estratégia de tratamento de erros, se uma funcionalidade é por rota ou global, como os casos extremos devem se comportar.
Sem uma etapa Discuss, o planejador precisa tomar essas decisões por conta própria. Às vezes acerta. Muitas vezes acerta de forma plausível, mas errada — produzindo um plano coerente, porém desalinhado com suas preferências reais. Quando a execução termina e você percebe o erro, já está desfazendo um trabalho significativo.
A etapa Discuss é deliberadamente leve. É uma conversa, não um exercício de especificação. O resultado é um `CONTEXT.md` no diretório da fase: um registro estruturado de decisões que o planejador, executor e verificador podem ler. A conversa leva alguns minutos; pode economizar horas de retrabalho.
### UI design (opcional)
Para fases com componente visual, existe uma etapa opcional `/gsd-ui-phase` entre Discuss e Plan. Ela produz um `UI-SPEC.md` — um contrato de design que descreve layout, interação e comportamento visual antes de qualquer código ser escrito. Vale a pena executar essa etapa quando a interface é complexa o suficiente para que ambiguidades no design produzam escolhas de implementação divergentes. Um contrato de design claro é muito mais barato de escrever do que de reimplementar.
### Plan
A etapa Plan realiza a pesquisa, a decomposição e o raciocínio estrutural que a execução exige. Ela roda como uma sequência de subagentes com contexto zerado: um pesquisador que investiga o ecossistema e registra os achados em `RESEARCH.md`, um planejador que lê tanto a pesquisa quanto o `CONTEXT.md` para produzir os arquivos `PLAN.md`, e um verificador de planos que confere se os planos estão completos, consistentes e dentro do escopo.
O que um plano contém? Cada `PLAN.md` descreve uma unidade delimitada de trabalho: os arquivos a serem tocados, as mudanças específicas a serem feitas, os critérios de aceite que definem o que é "concluído". Os planos são ordenados em ondas de dependência para que a execução paralela seja segura — executores na mesma onda tocam preocupações que não se sobrepõem.
A etapa Plan é o momento em que a ambiguidade é mais cara. Um plano ambíguo produz um executor que faz suposições. Múltiplos executores paralelos fazendo suposições diferentes sobre a mesma preocupação produzem conflitos. O trabalho do verificador de planos é capturar isso antes de a execução começar, não depois.
### Execute
A execução roda os planos. Cada executor recebe uma janela de contexto zerada de 200k tokens carregada com exatamente o que precisa: o resumo do projeto, o contexto da fase, a pesquisa e o `PLAN.md` específico para sua tarefa. Nada mais.
Os executores escrevem código e fazem commits de forma atômica. Cada commit corresponde a uma tarefa concluída em um plano. Quando uma onda de executores paralelos termina, o orquestrador mescla o estado deles e inicia a próxima onda.
O contexto zerado do executor não é uma conveniência — é o mecanismo pelo qual a degradação de contexto é evitada. Um executor rodando com 180k tokens de histórico de sessão acumulado é um executor degradado. Um executor que começa do zero e lê apenas o que seu plano exige é um executor operando em plena capacidade.
### Verify
Após todos os executores terem concluído, um agente verificador lê o objetivo da fase, as decisões do `CONTEXT.md`, os planos e os resumos de execução — e verifica se o que foi construído corresponde ao que foi pretendido. Ele produz um `VERIFICATION.md` e, se houver discrepâncias, gera planos de correção direcionados.
A verificação não é apenas testes. Ela confere a cobertura de requisitos (todos os REQ-IDs foram endereçados?), a cobertura de decisões (as decisões capturadas no `CONTEXT.md` foram realmente implementadas?) e o alinhamento geral com o objetivo da fase. Uma fase não está concluída porque a execução terminou sem erros. Está concluída porque o que foi construído é o que foi planejado, e o que foi planejado é o que foi decidido.
### Ship
A etapa Ship cria o pull request e arquiva os artefatos da fase. O `STATE.md` é atualizado para marcar a fase como concluída. O loop então recomeça para a próxima fase.
---
## Marcos e fases
Um **marco** é um ciclo de versão — um incremento significativo e entregável do projeto. Tem um nome, um número de versão e um conjunto de requisitos que definem o que deve entregar. Um marco está completo quando todas as suas fases foram entregues e seus requisitos estão cobertos.
Uma **fase** é uma unidade de trabalho dentro de um marco. Uma fase tem um objetivo, um conjunto de requisitos que endereça e um conjunto de planos que a implementam.
A relação importa porque marcos e fases têm escopos de preocupação diferentes. Um marco pergunta: "O que esta versão do produto faz e o que ela não faz?" Uma fase pergunta: "Qual é a próxima coisa delimitada que podemos pesquisar, planejar, executar e verificar?"
Os limites dos marcos são traçados em fronteiras naturais do produto — uma API implantável, um fluxo de interface funcional, um modelo de dados completo. Os limites das fases são traçados nos limites do que pode ser executado com segurança em um loop sem que ele se torne incontrolável.
---
## O que define um bom escopo de fase
Vale a pena refletir sobre isso, pois é a fonte mais comum de atrito com o loop.
Uma fase muito grande torna-se um projeto de pesquisa em si mesma. O planejador tem dificuldade para decompô-la em planos independentes. Executores em ondas posteriores ficam bloqueados aguardando ondas anteriores. A verificação torna-se uma auditoria completa em vez de uma revisão direcionada. O ciclo de feedback se estende de horas para dias, e o risco de descobrir um erro de design fundamental tarde — após muito código ter sido escrito — aumenta drasticamente.
Uma fase muito pequena fragmenta trabalho que naturalmente pertence junto. Você acaba com arquivos de plano de meia dúzia de linhas, fases que completam em minutos e um custo de planejamento que supera em muito o custo de execução. O loop parece burocrático em vez de útil.
Um bom escopo de fase é aquele em que:
- O objetivo pode ser enunciado em uma única frase que não seja obviamente trivial nem suspeito de ser ampla demais.
- A pesquisa necessária para planejá-la é delimitada — as questões sobre o ecossistema têm respostas que não dependem de outras fases sendo concluídas primeiro.
- A execução pode ser paralelizada em um punhado de planos que não se sobrepõem, não dezenas.
- Existe uma definição clara e testável de "concluído" que um verificador pode checar sem ler todo o código-base.
Concretamente: "Adicionar middleware de validação de assinatura HMAC-SHA256" é um bom escopo de fase. "Construir o sistema de autenticação" geralmente não é — quase sempre contém múltiplas preocupações independentes que seriam melhor tratadas como fases separadas. "Corrigir o erro de digitação no README" está abaixo do limite onde o loop agrega valor; use `/gsd-quick` nesse caso.
Na dúvida, divida. Uma fase menor completa mais rápido, verifica com mais confiança e facilita a correção de curso se uma decisão de design se mostrar errada.
---
## Como `.planning/` transporta estado ao longo do loop
O loop não é uma sessão única. Pesquisa, planejamento e execução podem acontecer em múltiplas sessões, com reinicializações de contexto no meio. O diretório `.planning/` é o que torna isso possível.
Cada etapa do loop lê artefatos produzidos por etapas anteriores e escreve artefatos para etapas posteriores. O CONTEXT.md que a etapa Discuss produz ainda está disponível quando o Planejador roda — mesmo que isso ocorra em uma sessão diferente, horas depois. Os arquivos PLAN.md que o Planejador produz ainda estão disponíveis quando o Executor roda — mesmo após uma reinicialização. O VERIFICATION.md que o Verificador escreve ainda está disponível quando você revisa a fase.
`STATE.md` é a camada de navegação acima de tudo isso. Ele registra exatamente onde no loop o projeto está atualmente: qual marco está ativo, qual fase está em andamento, quais planos estão completos e quais estão pendentes. Qualquer agente ou fluxo de trabalho que precise se orientar lê o `STATE.md` primeiro.
Para a estrutura precisa desses arquivos, consulte [Artefatos de planejamento](../reference/planning-artifacts.md) e o [esquema do STATE.md](../reference/state-md.md).
---
## O loop é um ritmo, não uma restrição
É tentador ver o loop como burocracia — um conjunto de etapas obrigatórias que você tem que executar antes de ter permissão para escrever código. Essa visão está errada.
O loop existe porque cada etapa previne falhas que são genuinamente caras de corrigir depois. O Discuss previne o planejamento com base em suposições erradas. O Plan previne a execução de um design fundamentalmente quebrado. O Verify previne a entrega de trabalho que perdeu o escopo. Esses não são problemas inventados. São os modos de falha reais do desenvolvimento assistido por IA na escala de funcionalidades reais.
Quando o loop funciona bem, ele parece um ritmo: uma cadência de trabalho focado e delimitado em que cada etapa é clara porque a etapa anterior fez seu trabalho. O custo adicional é real, mas está concentrado no início — pago em minutos de planejamento em vez de horas de retrabalho.
Para trabalhos que ficam abaixo do limite em que o loop é justificado, o GSD Core oferece primitivas mais leves. O loop de fases é uma ferramenta, não a única ferramenta.
---
## Relacionados
- [Engenharia de contexto](context-engineering.md) — por que subagentes com contexto zerado evitam a degradação de qualidade que torna o loop necessário
- [Discutir uma fase](../how-to/discuss-a-phase.md)
- [Planejar uma fase](../how-to/plan-a-phase.md)
- [Executar uma fase](../how-to/execute-a-phase.md)
- [Verificar e entregar](../how-to/verify-and-ship.md)
- [Artefatos de planejamento](../reference/planning-artifacts.md)
- [Esquema do STATE.md](../reference/state-md.md)
- [índice de documentação](../README.md)

218
docs/pt-BR/how-to/configure-model-profiles.md Normal file
View File

@@ -0,0 +1,218 @@
# Como configurar perfis de modelo
Escolha a estratégia de nível de modelo adequada para o seu projeto e ajuste agentes individuais ou tipos de fase inteiros sem precisar escrever um bloco de substituição extenso. Este guia começa pelo controle mais simples e avança até o roteamento dinâmico.
---
## Os quatro perfis (mais `adaptive` e `inherit`)
Defina `model_profile` em `.planning/config.json` ou via `/gsd-config --profile <name>`:
| Perfil | Planejador | Executor | Pesquisadores | Verificador | Usar quando |
|--------|-----------|----------|---------------|-------------|-------------|
| `quality` | Opus | Opus | Opus | Sonnet | Trabalho de qualidade para produção onde o custo é secundário |
| `balanced` | Opus | Sonnet | Sonnet | Sonnet | Desenvolvimento normal — o padrão |
| `budget` | Sonnet | Sonnet | Haiku | Haiku | Prototipagem rápida, contextos com restrições de custo |
| `adaptive` | Opus | Sonnet | Sonnet | Sonnet | Resolve da mesma forma que os outros níveis em perfis cientes de runtime; use ao alternar entre runtimes com frequência |
| `inherit` | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | (modelo da sessão) | Provedores não-Anthropic (OpenRouter, modelos locais) — todos os agentes seguem o modelo atual da sessão |
A tabela acima mostra um subconjunto representativo. Todos os 33 agentes incluídos possuem atribuições de nível explícitas por perfil em `sdk/shared/model-catalog.json`. Para a tabela completa, consulte [Perfis de Modelo](../CONFIGURATION.md#model-profiles) na referência de configuração.
**Troca rápida via comando:**
```bash
/gsd-config --profile balanced # Desenvolvimento normal
/gsd-config --profile budget # Prototipagem ou fases de alto custo
/gsd-config --profile quality # Lançamento em produção
/gsd-config --profile inherit # OpenRouter, modelos locais
```
**Ou edite `.planning/config.json` diretamente:**
```json
{
"model_profile": "balanced"
}
```
---
## Substituições por agente (`model_overrides`)
Se um único agente precisa de um nível diferente sem alterar o perfil inteiro, use `model_overrides`:
```json
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-codebase-mapper": "haiku"
}
}
```
Valores válidos: `opus`, `sonnet`, `haiku`, `inherit` ou qualquer ID de modelo totalmente qualificado (ex.: `"openai/o3"`, `"google/gemini-2.5-pro"`).
`model_overrides` pode ser definido por projeto em `.planning/config.json` ou globalmente em `~/.gsd/defaults.json`. Entradas por projeto têm precedência em conflitos; entradas globais sem conflito são preservadas.
**Importante para Codex e OpenCode:** Esses runtimes incorporam o modelo resolvido na configuração estática de cada agente no momento da instalação. Após editar `model_overrides`, execute novamente o instalador para que a alteração entre em vigor:
```bash
npx @opengsd/gsd-core@latest --codex --global # ou --opencode, --kilo, etc.
```
---
## Modelos por tipo de fase (`models`)
Se você quer dizer "Opus para planejamento, Sonnet para todo o resto" sem precisar aprender todos os 33 nomes de agentes, use o bloco `models`. Ele mapeia seis tipos de fase para aliases de nível:
```json
{
"model_profile": "balanced",
"models": {
"planning": "opus",
"discuss": "opus",
"research": "sonnet",
"execution": "opus",
"verification": "sonnet",
"completion": "sonnet"
}
}
```
Tipos de fase e seus agentes:
| Tipo de fase | Agentes cobertos |
|---|---|
| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
| `research` | `gsd-phase-researcher`, `gsd-project-researcher`, `gsd-research-synthesizer`, `gsd-codebase-mapper`, `gsd-ui-researcher` |
| `execution` | `gsd-executor`, `gsd-debugger`, `gsd-doc-writer` |
| `verification` | `gsd-verifier`, `gsd-plan-checker`, `gsd-integration-checker`, `gsd-nyquist-auditor`, `gsd-ui-checker`, `gsd-ui-auditor`, `gsd-doc-verifier` |
| `discuss`, `completion` | Reservado — nenhum subagente hoje; aceito pelo esquema para compatibilidade futura |
O bloco `models` aceita apenas aliases de nível (`opus`, `sonnet`, `haiku`, `inherit`). Para um ID de modelo totalmente qualificado, use `model_overrides` por agente.
**Combinando `models` com uma exceção por agente:**
```json
{
"model_profile": "balanced",
"models": {
"research": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
}
}
```
Todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `gsd-codebase-mapper`, que está fixado em `haiku`.
---
## Roteamento dinâmico — comece barato, escale em caso de falha
Se você quiser pagar pelos níveis mais baratos por padrão e só escalar quando um agente falhar em um controle de qualidade, habilite `dynamic_routing`:
```json
{
"dynamic_routing": {
"enabled": true,
"tier_models": {
"light": "haiku",
"standard": "sonnet",
"heavy": "opus"
},
"escalate_on_failure": true,
"max_escalations": 1
}
}
```
Cada agente possui um nível padrão (`light`, `standard` ou `heavy`). Na primeira tentativa, o GSD escolhe `tier_models[default_tier]`. Se o orquestrador detectar uma falha suave (verificação inconclusiva, verificação de plano sinalizada, etc.), ele reinicia o agente um nível acima. `max_escalations` limita o total de novas tentativas.
Agentes que já estão em `heavy` não podem escalar mais.
**Desativar a escalada mantendo a resolução dinâmica:**
```json
{
"dynamic_routing": {
"enabled": true,
"escalate_on_failure": false
}
}
```
Cada tentativa usa `tier_models[default_tier]` independentemente do resultado — útil quando você quer mapeamento explícito de nível para modelo sem o comportamento de escalada.
`dynamic_routing` está **desabilitado por padrão**. Omitir o bloco ou definir `enabled: false` preserva a resolução estática.
---
## Usando o GSD em runtimes não-Anthropic
Se você instalou o GSD para Codex, OpenCode, Gemini CLI ou Kilo, o instalador já definiu `resolve_model_ids: "omit"` na sua configuração. Isso instrui o GSD a pular a resolução de IDs de modelo Anthropic e deixar o runtime escolher seu próprio modelo padrão. Nenhuma configuração manual é necessária para o caso básico.
**Se você quiser modelos por nível no Codex:**
```json
{
"runtime": "codex",
"model_profile": "balanced"
}
```
O GSD resolve cada alias de nível para o modelo nativo do Codex e o esforço de raciocínio definido no mapa de nível do runtime.
**Se você quiser IDs de modelo por agente em qualquer runtime não-Claude:**
```json
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
}
}
```
Para a referência completa de perfis cientes de runtime e a superfície `model_policy` (predefinições neutras em relação ao provedor adicionadas na v1.42), consulte [Referência de configuração — Perfis de Modelo](../CONFIGURATION.md#model-profiles).
---
## Precedência de resolução (maior para menor)
Quando múltiplas camadas se aplicam, o resolvedor escolhe a entrada de maior prioridade:
```text
1. model_overrides[<agent>] — por agente; IDs completos; exceção direcionada
2. dynamic_routing.tier_models[<tier>] — quando habilitado; escala em falha suave
3. models[<phase_type>] — nível de fase grosseiro
4. model_profile (coluna por agente) — estratégia global de nível
5. Padrão do runtime — quando nada mais se aplica
```
---
## Escolhendo o controle certo
| O que você quer | Use |
|---|---|
| Uma estratégia de nível para todos os agentes | `model_profile` |
| Ajuste grosseiro por fase ("Opus para planejamento") | `models.<phase_type>` |
| Precisão por agente ("forçar Haiku no mapeador de base de código") | `model_overrides[<agent>]` |
| Um ID de modelo totalmente qualificado para um agente específico | `model_overrides[<agent>]: "openai/gpt-5"` |
| Começar barato, escalar apenas em falha | `dynamic_routing` |
| Todos os agentes seguem o modelo da sessão (provedor não-Anthropic) | `model_profile: "inherit"` |
---
## Relacionados
- [Referência de configuração](../CONFIGURATION.md)
- [Orquestração multi-agente](../explanation/multi-agent-orchestration.md)
- [Referência de comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)

178
docs/pt-BR/how-to/debug-a-failed-execution.md Normal file
View File

@@ -0,0 +1,178 @@
# Como depurar uma execução com falha
**Objetivo:** Recuperar quando uma execução de fase falha, trava ou produz trabalho incompleto — e retomar de forma limpa sem perder o progresso ou repetir o trabalho que já foi concluído com sucesso.
**Pré-requisitos:** Você executou `/gsd-execute-phase N` e a execução parou antes de gravar `VERIFICATION.md`, ou você vê saída inesperada, arquivos ausentes ou um indicador de progresso travado.
---
## Detectar se a execução travou ou falhou
Antes de tomar qualquer ação de recuperação, determine o que realmente aconteceu.
### Se você ver "Spawning…" sem saída após 1–5 minutos
Isso é normal, não é um travamento. Os subagentes GSD são executados em uma janela de contexto isolada. A nota de atividade na linha de spawn confirma isso. Não interrompa a sessão.
Se já se passaram mais de 10 minutos sem resultado, verifique a barra lateral do Claude Code. Se a tarefa do agente aparecer como concluída mas nenhuma saída tiver aparecido, o resultado pode ter sido perdido em uma troca de contexto — execute novamente o mesmo comando:
```bash
/gsd-execute-phase 1
```
O GSD verifica a existência de arquivos `SUMMARY.md` antes de despachar os executores. Planos que já possuem um são ignorados automaticamente.
### Se a execução parou no meio de uma onda com uma mensagem de erro
Verifique o histórico do git para ver quais planos foram commitados com sucesso:
```bash
git log --oneline -20
```
Planos que commitaram seu trabalho terão uma entrada como `feat(01-02): …`. Planos sem um commit estão incompletos e serão executados novamente quando você executar o comando novamente.
### Se o executor commitou o código mas não gravou SUMMARY.md
O GSD detecta isso na próxima execução e apresenta uma porta de retomada segura com três opções:
- **Fechar manualmente** — inspecione os commits você mesmo, escreva `SUMMARY.md` e execute novamente.
- **Executar novamente do zero** — reverta ou substitua os commits parciais antes de despachar um novo executor.
- **Marcar e pular** — registre a anomalia e continue, apenas com sua confirmação explícita.
---
## Diagnosticar a causa raiz
### Execute `/gsd-debug --diagnose`
Se a execução produziu saída incorreta, código com stubs ou uma falha de verificação, use o modo somente de diagnóstico para investigar sem aplicar nenhuma correção:
```bash
/gsd-debug --diagnose "Phase 2 executor produced stubs instead of real code"
```
`--diagnose` para na causa raiz sem tocar nos seus arquivos. Ele cria um arquivo de sessão em `.planning/debug/<slug>.md` para que você possa retomar a investigação mais tarde, se necessário.
Para iniciar uma sessão de depuração completa que também aplica uma correção:
```bash
/gsd-debug "Login middleware not handling 401 correctly after phase 3"
```
O GSD coleta sintomas, executa uma investigação estruturada usando o método científico e propõe uma correção. Se `tdd_mode: true` estiver definido na sua configuração, ele exige um teste com falha antes de aplicar qualquer correção.
### Verificar sessões de depuração ativas
```bash
/gsd-debug list
```
Mostra todas as sessões abertas com sua hipótese atual e próxima ação. Para retomar uma sessão específica:
```bash
/gsd-debug continue <slug>
```
---
## Executar uma análise post-mortem com `/gsd-forensics`
Se a causa não estiver clara a partir da saída de erro — por exemplo, planos referenciam arquivos inexistentes, a execução produziu resultados inesperados ou o estado parece corrompido — execute uma investigação forense:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
O GSD analisa o histórico do git, a completude dos artefatos em `.planning/`, a consistência de STATE.md, o trabalho não commitado e as worktrees órfãs. Ele grava um relatório estruturado em `.planning/forensics/report-<timestamp>.md` e apresenta as etapas de remediação recomendadas.
`/gsd-forensics` é somente leitura — ele nunca modifica os arquivos do seu projeto.
**O que ele detecta:**
- **Loop travado** — o mesmo arquivo aparece em três ou mais commits consecutivos em uma janela de tempo curta (confiança ALTA se as mensagens de commit forem semelhantes)
- **Artefatos ausentes** — uma fase tem commits mas não tem `SUMMARY.md` ou `VERIFICATION.md`
- **Trabalho abandonado** — alterações não commitadas com STATE.md mostrando execução em andamento e o último commit com mais de duas horas de idade
- **Falha ou interrupção** — alterações não commitadas combinadas com um estado de execução ativo e worktrees órfãs
- **Desvio de escopo** — commits recentes tocam arquivos fora do conjunto de arquivos esperado da fase atual
---
## Retomar a execução após a recuperação
Assim que o problema subjacente for resolvido, execute novamente o comando de execução:
```bash
/gsd-execute-phase 1
```
O GSD ignora planos cujo `SUMMARY.md` já existe e despacha executores apenas para os planos restantes.
Se precisar executar novamente apenas uma onda específica:
```bash
/gsd-execute-phase 1 --wave 2
```
Se quiser validar a integridade de `.planning/` antes de despachar:
```bash
/gsd-execute-phase 1 --validate
```
---
## Reverter com `/gsd-undo`
Se a execução produziu código que você deseja descartar completamente, reverta usando o manifesto do plano em vez do `git revert` manual:
### Reverter um único plano
```bash
/gsd-undo --plan 03-02
```
Reverte todos os commits do plano `02` da fase `3`. O GSD exibe uma porta de confirmação antes de gravar qualquer alteração.
### Reverter uma fase inteira
```bash
/gsd-undo --phase 03
```
Reverte todos os commits da fase `3`. O GSD verifica se alguma fase subsequente depende desta fase e avisa você antes de prosseguir.
### Selecionar interativamente a partir de commits recentes
```bash
/gsd-undo --last 5
```
Mostra os cinco commits GSD mais recentes e permite que você selecione quais reverter.
---
## Restaurar o contexto da sessão após uma pausa
Se você retornou ao projeto após uma reinicialização de contexto ou uma nova sessão:
```bash
/gsd-resume-work
```
Restaura o contexto completo da sua sessão a partir do último handoff, incluindo a fase atual, bloqueadores e onde a execução parou.
Como alternativa, para ver sua posição atual e avançar automaticamente para o próximo passo correto:
```bash
/gsd-progress --next
```
---
## Relacionados
- [Executar uma fase](execute-a-phase.md)
- [Recuperar e solucionar problemas](recover-and-troubleshoot.md)
- [Comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)

149
docs/pt-BR/how-to/design-a-ui-phase.md Normal file
View File

@@ -0,0 +1,149 @@
# Como projetar uma fase de UI
**Objetivo:** Produzir um contrato de design de UI bloqueado (`UI-SPEC.md`) que fixe decisões de espaçamento, cores, tipografia e textos antes que o planejador escreva as tarefas, prevenindo inconsistências visuais causadas por escolhas de estilo ad-hoc durante a execução.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. A fase precisa ter trabalho de frontend ou UI. Executar `/gsd-discuss-phase N` antes é fortemente recomendado — o pesquisador de UI lê `CONTEXT.md` para evitar fazer perguntas sobre decisões que você já tomou.
---
## Decida se esta fase precisa de um contrato de UI
Nem todas as fases precisam de `/gsd-ui-phase`. Use quando:
- A fase introduz novas superfícies de UI (páginas, fluxos, layouts)
- Vários componentes serão construídos e a consistência visual é importante
- Você está iniciando o frontend de um novo projeto e precisa de uma linha de base do sistema de design
- Você está adicionando trabalho significativo de UI a um projeto existente e deseja bloquear tokens, espaçamento e cores antes da execução
Pule quando:
- A fase é puramente de backend, infraestrutura ou dados, sem saída voltada ao usuário
- Um UI-SPEC.md já existe para uma fase anterior e esta fase constrói sobre padrões visuais idênticos sem introduzir novas superfícies
Se não tiver certeza, a trava de segurança irá alertá-lo: quando `workflow.ui_safety_gate` está habilitado (padrão), `/gsd-plan-phase` avisa ao detectar trabalho de frontend sem `UI-SPEC.md` e pergunta se deve executar `/gsd-ui-phase` primeiro.
---
## Execute o contrato de design de UI
```bash
/gsd-ui-phase 2
```
Se nenhum número de fase for fornecido, o GSD Core usa a fase atual como alvo.
O comando é executado em dois estágios:
1. **`gsd-ui-researcher`** — lê `CONTEXT.md`, `RESEARCH.md` e `REQUIREMENTS.md` em busca de decisões existentes, detecta o estado do sistema de design (shadcn `components.json`, configuração do Tailwind, tokens existentes), e faz apenas as perguntas de design não respondidas em cinco áreas: espaçamento, cores, tipografia, textos e segurança do registro.
2. **`gsd-ui-checker`** — valida o `UI-SPEC.md` resultante em seis dimensões. Se problemas forem encontrados, um ciclo de revisão reexecuta o pesquisador (até duas iterações) visando apenas os itens sinalizados.
**Saída:** `{padded_phase}-UI-SPEC.md` em `.planning/phases/{phase-dir}/`.
---
## O que o UI-SPEC cobre
O pesquisador bloqueia decisões em cinco áreas:
| Área | Exemplos |
|---|---|
| **Espaçamento** | Escala base (4px ou 8px), alinhamento de grid, padding de componentes |
| **Cores** | Paleta primária, de destaque e neutra; regra 60/30/10; considerações de modo escuro |
| **Tipografia** | Famílias de fontes, restrições de escala de tamanho/peso, hierarquia de títulos |
| **Textos** | Rótulos de CTA, mensagens de estado vazio, textos de estado de erro, indicadores de carregamento |
| **Segurança do registro** | Protocolo de inspeção de componentes shadcn (veja abaixo) |
O verificador valida a especificação em seis pilares, com pontuação de 1 a 4 cada: Textos, Visuais, Cores, Tipografia, Espaçamento e Design de Experiência (cobertura de estados de carregamento / erro / vazio).
---
## Inicialização do shadcn
Para projetos React, Next.js e Vite, o pesquisador oferece inicializar o shadcn se nenhum `components.json` for encontrado. O fluxo:
1. Acesse `ui.shadcn.com/create` e configure seu preset (cores, raio de borda, fontes)
2. Copie a string do preset
3. Execute:
```bash
npx shadcn init --preset <cole aqui>
```
A string do preset torna-se um artefato de planejamento de primeira classe do GSD Core, reproduzível entre fases e marcos.
---
## Trava de segurança do registro
Registros shadcn de terceiros podem injetar código arbitrário. Quando `workflow.ui_safety_gate` está habilitado (padrão), a especificação exige estas etapas antes de instalar qualquer componente não oficial:
```bash
npx shadcn view <component> # inspect source before installing
npx shadcn diff <component> # compare against the official registry
```
O verificador sinalizará a especificação como BLOCKED se a segurança do registro não for tratada. Desative a trava via `/gsd-settings` se o seu projeto não usa shadcn ou você tem um processo alternativo de verificação.
---
## Use os achados do sketch como ponto de partida
Se você já executou `/gsd-sketch --wrap-up`, o pesquisador de UI carrega `.claude/skills/sketch-findings-[project]/` automaticamente. Decisões pré-validadas (layout, paleta, tipografia, espaçamento) são tratadas como bloqueadas — o pesquisador não as pergunta novamente. Você verá uma nota no início da execução:
```text
⚡ Sketch findings detected: .claude/skills/sketch-findings-[project]/SKILL.md
Pre-validated decisions (layout, palette, typography, spacing) should be treated
as locked — not re-asked.
```
Esta é a principal razão para executar `/gsd-sketch --wrap-up` antes de `/gsd-ui-phase`: transforma a exploração conversacional de design em entrada vinculante para o contrato.
---
## Auditoria visual retroativa com `/gsd-ui-review`
`/gsd-ui-review` é executado após a execução, não antes. Use-o para auditar o frontend implementado em relação ao UI-SPEC (ou em relação aos padrões abstratos de 6 pilares quando nenhuma especificação existir).
```bash
/gsd-ui-review # audit the current phase
/gsd-ui-review 3 # audit phase 3 specifically
```
Funciona em qualquer projeto com código frontend — a inicialização de projeto GSD não é necessária.
**O que verifica (6 pilares, pontuação de 1 a 4 cada):**
1. Textos — rótulos de CTA, estados vazios, estados de erro
2. Visuais — pontos focais, hierarquia visual, acessibilidade de ícones
3. Cores — disciplina de uso de destaque, conformidade 60/30/10
4. Tipografia — aderência às restrições de tamanho e peso de fonte
5. Espaçamento — alinhamento de grid, consistência de tokens
6. Design de Experiência — cobertura de estados de carregamento, erro e vazio
**Saída:** `{padded_phase}-UI-REVIEW.md` com pontuações e as três principais correções prioritárias. Quando um servidor MCP de navegador como `gsd-browser` estiver configurado, a auditoria também captura capturas de tela com evidências visuais.
**Armazenamento de capturas de tela:** As capturas de tela são salvas em `.planning/ui-reviews/`. Um `.gitignore` é criado automaticamente para evitar que arquivos binários cheguem ao git. As capturas de tela são limpas durante `/gsd-complete-milestone`.
---
## Posição recomendada no ciclo de vida da fase
```text
/gsd-discuss-phase N ← lock implementation preferences
/gsd-ui-phase N ← lock design contract (frontend phases)
/gsd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/gsd-execute-phase N ← parallel execution
/gsd-verify-work N ← manual UAT
/gsd-ui-review N ← retroactive visual audit (optional but recommended)
```
`/gsd-ui-phase` fica entre discussão e planejamento porque o planejador lê `UI-SPEC.md` como contexto de design — as tarefas em `PLAN.md` referenciam tokens de espaçamento, variáveis de cores e decisões de textos que a especificação bloqueou.
---
## Relacionados
- [Spike e sketch](spike-and-sketch.md)
- [Planejar uma fase](plan-a-phase.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

158
docs/pt-BR/how-to/discuss-a-phase.md Normal file
View File

@@ -0,0 +1,158 @@
# Como discutir uma fase
**Objetivo:** Reunir as decisões de implementação que uma fase precisa antes do planejamento começar — para que o pesquisador e o planejador possam agir sem precisar consultar você novamente.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. Caso contrário, execute `/gsd-new-project` primeiro.
---
## Escolha seu modo de discussão
GSD Core oferece dois modos. Escolha com base em quão bem compreendida é a base de código.
**Se você quiser expressar suas preferências de implementação antecipadamente** (modo de entrevista, padrão):
```bash
/gsd-discuss-phase 2
```
Claude identifica áreas cinzentas no escopo da fase, permite que você selecione quais discutir e trabalha com aproximadamente quatro perguntas por área.
**Se a base de código já tem padrões claros e você acha a maioria das perguntas óbvias** (modo de suposições):
```bash
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
/gsd-discuss-phase 2
```
Claude lê de 5 a 15 arquivos relevantes da base de código por meio de um subagente, formula suposições com evidências e níveis de confiança, e as apresenta para confirmação ou correção. Normalmente 2 a 4 interações em vez de 15 a 20.
Para voltar ao modo anterior:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
Veja [Modos de discussão explicados](../workflow-discuss-mode.md) para uma comparação completa, incluindo quando cada modo tende a economizar tempo.
---
## Discutir todas as áreas cinzentas sem a etapa de seleção
Por padrão, Claude apresenta as áreas cinzentas e pergunta quais você deseja cobrir. Se você quiser trabalhar em todas elas sem esse prompt de seleção:
```bash
/gsd-discuss-phase 2 --all
```
---
## Acelerar uma fase direta
**Se a fase é bem compreendida e você quer que Claude escolha os padrões recomendados sem fazer perguntas:**
```bash
/gsd-discuss-phase 3 --auto
```
Claude seleciona a resposta recomendada para cada pergunta e registra as escolhas. Use isso para fases em que as decisões são de baixo impacto ou já estão implícitas pelas fases anteriores.
**Se você tem restrições de sessão remota (sem menus TUI):**
```bash
/gsd-discuss-phase 2 --text
```
Todos os prompts são renderizados como listas numeradas em texto simples em vez de seletores interativos.
---
## Responder perguntas em grupos
Se você preferir responder várias perguntas de uma vez em vez de uma por uma:
```bash
/gsd-discuss-phase 2 --batch
```
Claude agrupa de 2 a 5 perguntas por turno.
---
## Adicionar análise de trade-offs a cada pergunta
Se você quiser uma tabela comparativa das opções antes de se comprometer:
```bash
/gsd-discuss-phase 2 --analyze
```
---
## Responder em massa a partir de um arquivo preparado
Se você tem um arquivo de respostas preparado e quer enviar todas as decisões em uma única passagem:
```bash
/gsd-discuss-phase 1 --power
```
---
## Visualizar as suposições de Claude antes de discutir
**Se você quiser ver o que Claude assumiria e faria antes de qualquer sessão interativa** — útil para validar o alinhamento antes de investir tempo em discussão:
```bash
/gsd-discuss-phase 3 --assumptions
```
Claude exibe suas suposições (com evidências da base de código e níveis de confiança) e encerra. Nenhum CONTEXT.md é escrito. Revise a saída e, se algo precisar de correção, execute uma sessão normal de discussão ou em modo de suposições.
---
## O que o CONTEXT.md contém
Tanto o modo de discussão quanto o modo de suposições produzem o mesmo `{phase}-CONTEXT.md` no diretório da fase. Os agentes downstream (pesquisador, planejador, verificador de plano) leem esse arquivo de forma idêntica independentemente do modo que o produziu. Ele contém seis seções:
| Seção | Finalidade |
|---|---|
| `<domain>` | Delimitação da fase — o que esta fase entrega |
| `<decisions>` | Decisões de implementação confirmadas durante a sessão |
| `<canonical_refs>` | Especificações, ADRs e documentos que os agentes downstream devem ler |
| `<code_context>` | Recursos reutilizáveis, padrões e pontos de integração |
| `<specifics>` | Referências e preferências do usuário |
| `<deferred>` | Ideias anotadas para fases futuras |
A seção `<canonical_refs>` é obrigatória. Se você referenciar um documento, especificação ou ADR durante a discussão, Claude o adiciona imediatamente e o lê para embasar as perguntas subsequentes.
Veja [Esquema do CONTEXT.md](../reference/context-md.md) para a referência completa dos campos.
---
## Como as decisões alimentam o planejamento
Quando você executar `/gsd-plan-phase` em seguida, o planejador lê CONTEXT.md para saber quais decisões estão confirmadas. Ele não vai refazer perguntas já respondidas aqui. O pesquisador o lê primeiro para saber o que investigar.
**Se o CONTEXT.md estiver ausente quando você executar `/gsd-plan-phase`**, você terá a opção de continuar sem contexto (os planos usam apenas pesquisa e requisitos, sem suas preferências de design) ou executar `/gsd-discuss-phase` primeiro.
---
## Se você tiver um PRD ou documento de critérios de aceitação
Pule a fase de discussão completamente e vá direto para o planejamento:
```bash
/gsd-plan-phase 1 --prd path/to/prd.md
```
O planejador sintetiza o CONTEXT.md a partir do PRD e trata todos os requisitos como decisões confirmadas.
---
## Relacionados
- [Planejar uma fase](plan-a-phase.md)
- [Modos de discussão](../workflow-discuss-mode.md)
- [Esquema do CONTEXT.md](../reference/context-md.md)
- [Índice de documentação](../README.md)

176
docs/pt-BR/how-to/drive-gsd-from-a-tracker-issue.md Normal file
View File

@@ -0,0 +1,176 @@
# Como conduzir o GSD Core a partir de uma issue do rastreador
**Objetivo:** Levar uma única issue bem delimitada do GitHub, Linear ou Jira por todo o pipeline do GSD — desde o workspace isolado até o PR mesclado — usando apenas comandos já existentes no GSD Core, sem scripts customizados ou integrações com rastreadores.
**Pré-requisitos:** GSD Core está instalado. A issue tem escopo delimitado, critérios de aceitação observáveis e nenhum bloqueador upstream.
Para os conceitos e a justificativa de design por trás desse padrão, consulte [Orquestração orientada a issues explicada](../issue-driven-orchestration.md).
---
## Passo 1: Mapear a issue para uma fase
Abra sua issue no rastreador e decida como ela se encaixa no `ROADMAP.md`:
- **A issue corresponde a uma fase existente** → anote o número da fase e avance para o Passo 2.
- **A issue é um trabalho novo independente** → adicione uma fase:
```bash
/gsd-phase "Descrição correspondente ao título da issue"
```
- **A issue é urgente e precisa ser inserida entre fases existentes** → insira uma fase decimal:
```bash
/gsd-phase --insert 3 "Fix: descrição da issue"
```
Copie a URL da issue do rastreador. Você irá colá-la no `CONTEXT.md` no Passo 3 para que a rastreabilidade sobreviva à compactação de contexto.
---
## Passo 2: Criar um workspace isolado
Cada issue recebe seu próprio workspace — um git worktree com um diretório `.planning/` independente. Trabalhos parciais, planos abandonados e commits exploratórios ficam fora do `main`.
```bash
/gsd-workspace --new --name my-issue-slug --repos . --strategy worktree
```
Entre no diretório do workspace antes de continuar:
```bash
cd ~/gsd-workspaces/my-issue-slug
```
---
## Passo 3: Discutir a fase
Execute discuss-phase para definir as decisões de implementação antes que qualquer planejamento aconteça. Quando a sessão abrir, cole a URL da issue do rastreador na discussão para que ela seja capturada no `CONTEXT.md`.
```bash
/gsd-discuss-phase N
```
O GSD pergunta sobre ambiguidades no escopo da issue — tratamento de erros, casos extremos, contratos de interface, escolhas tecnológicas. Suas respostas moldam o plano que se segue.
Se você já sabe todas as respostas e quer avançar rapidamente:
```bash
/gsd-discuss-phase N --auto
```
---
## Passo 4: Planejar a fase
```bash
/gsd-plan-phase N
```
O GSD cria agentes de pesquisa, lê suas decisões do `CONTEXT.md` (incluindo a URL da issue) e produz arquivos `PLAN.md` atômicos. Um verificador de planos valida cada plano antes de salvá-lo.
Se você quiser revisão por pares de CLIs externas de IA antes da execução (recomendado para mudanças significativas):
```bash
/gsd-review --phase N
/gsd-plan-phase N --reviews
```
Ou execute o loop completo de planejar–revisar–convergir até que não haja mais preocupações de nível HIGH:
```bash
/gsd-plan-review-convergence N
```
---
## Passo 5: Executar a fase
Para execução interativa, fase por fase:
```bash
/gsd-execute-phase N
```
Para uma execução sem supervisão por todas as fases restantes:
```bash
/gsd-autonomous
```
Para um painel interativo onde você pode acompanhar o progresso e despachar trabalho entre fases:
```bash
/gsd-manager
```
As três abordagens atualizam o `STATE.md`, fazem commit de cada tarefa atomicamente e executam o verificador pós-fase.
---
## Passo 6: Verificar o trabalho
```bash
/gsd-verify-work N
```
O GSD percorre os critérios de aceitação do objetivo da fase (que reflete sua issue do rastreador) um de cada vez. Se algo falhar, o GSD diagnostica a causa raiz e cria um plano de correção. Execute novamente e re-verifique até que todas as verificações passem.
Trate `verification_failed` como um bloqueador mesmo quando o código parece correto — a falha geralmente revela um critério de aceitação não atendido da issue original.
---
## Passo 7: Revisar e publicar
Execute uma revisão de código antes de abrir o PR:
```bash
/gsd-code-review N
/gsd-code-review N --fix
```
Em seguida, crie o PR:
```bash
/gsd-ship N
```
O GSD monta o corpo do PR a partir dos seus artefatos de planejamento: objetivo da fase, resumo das mudanças, requisitos atendidos, status de verificação e decisões-chave. Inclua `Closes #NNN` ou `Fixes #NNN` no corpo do PR (ou configure via `/gsd-config`) para que a issue do rastreador seja fechada automaticamente quando o PR for mesclado.
---
## Passo 8: Registrar trabalho de acompanhamento
Ao trabalhar na issue, você frequentemente descobrirá trabalhos relacionados. Registre-os sem perder o contexto:
```bash
/gsd-capture "Acompanhamento: descrição do trabalho descoberto" # Adicionar como tarefa
/gsd-capture --seed "Ideia que vale uma fase futura" # Preservar para o próximo milestone
/gsd-capture --backlog "Não urgente, mas vale registrar" # Arquivar no backlog
```
O GSD não publica no seu rastreador automaticamente. Criar uma issue no rastreador a partir dos acompanhamentos registrados é uma etapa manual separada — isso mantém a revisão humana no ciclo.
---
## Condicionais
| Situação | O que fazer |
|-----------|-----------|
| A issue é muito pequena (typo, mudança de config) | Pule workspace + discuss + plan; use `/gsd-quick` em vez disso |
| A issue tem múltiplas subtarefas independentes | Use `/gsd-manager` para paralelizar a execução entre planos |
| A issue está bloqueada em outra issue | Não inicie até que o bloqueador upstream seja resolvido; o GSD não possui poller automático de dependências |
| O escopo da issue se mostra maior do que o esperado durante a execução | Pare, execute `/gsd-phase --insert N` para adicionar subfases, continue |
| Você quer pular a discussão interativa | Use a flag `--auto` com `/gsd-discuss-phase`, ou defina `workflow.skip_discuss: true` para automação em todo o projeto |
| Múltiplas issues formam uma release coerente | Execute `/gsd-new-milestone` para agrupá-las e `/gsd-autonomous` para executar em sequência |
---
## Relacionados
- [Orquestração orientada a issues explicada](../issue-driven-orchestration.md)
- [Isolar trabalho com workspaces](isolate-work-with-workspaces.md)
- [Verificar e publicar](verify-and-ship.md)
- [índice de documentação](../README.md)

119
docs/pt-BR/how-to/execute-a-phase.md Normal file
View File

@@ -0,0 +1,119 @@
# Como executar uma fase
**Objetivo:** Executar uma fase planejada por meio de execução paralela em ondas e registrar cada plano como um commit git atômico.
**Pré-requisitos:** A fase deve ter pelo menos um arquivo `PLAN.md`. Se o planejamento ainda não foi concluído, execute `/gsd-plan-phase N` primeiro — consulte [Planejar uma fase](plan-a-phase.md).
---
## Executar a fase completa
```bash
/gsd-execute-phase 1
```
O GSD Core lê os arquivos de plano da fase, agrupa-os em ondas de dependência e cria um agente executor independente por plano. Cada executor confirma seu trabalho atomicamente antes de a próxima onda começar.
Antes de qualquer agente ser despachado, o GSD Core exibe uma tabela de ondas:
```
## Execution Plan
Phase 1: Core middleware — 3 plans across 2 wave(s)
| Wave | Plans | What it builds |
|------|----------------|---------------------------|
| 1 | 01-01, 01-02 | Core validation function |
| 2 | 01-03 | Express middleware wrapper |
```
Os planos da Onda 1 são executados em paralelo (cada um em um worktree git isolado). A Onda 2 aguarda até que todos os commits da Onda 1 sejam mesclados.
Para o modelo de coordenação de agentes subjacente, consulte [Orquestração multi-agente](../explanation/multi-agent-orchestration.md).
---
## Executar uma única onda
Se você quiser executar apenas uma onda — por exemplo, para inspecionar a saída da Onda 1 antes de avançar para a Onda 2 — use `--wave N`:
```bash
/gsd-execute-phase 1 --wave 2
```
O GSD Core executa apenas os planos da Onda 2. Ele primeiro verifica se todas as ondas anteriores estão completas; se algum plano da Onda 1 ainda estiver marcado como incompleto, ele para e solicita que você conclua as ondas anteriores.
---
## Validar o estado antes da execução
Se você suspeitar que o diretório `.planning/` está fora de sincronia com o sistema de arquivos — por exemplo, após uma falha ou uma execução anterior interrompida — passe `--validate`:
```bash
/gsd-execute-phase 1 --validate
```
O GSD Core executa uma verificação de consistência de estado antes de criar qualquer executor. Desvios detectados são relatados e você pode aceitá-los ou corrigi-los antes de prosseguir.
---
## Retomar uma execução paralisada
Se a execução parar no meio — um erro de cota, uma queda de rede ou uma sessão travada — o progresso no nível de onda é preservado. O GSD Core verifica a existência de um arquivo `SUMMARY.md` para cada plano; planos que já possuem esse arquivo são ignorados automaticamente ao reexecutar:
```bash
/gsd-execute-phase 1
```
O GSD Core ignorará os planos onde `SUMMARY.md` já existe e retomará a partir do primeiro plano incompleto.
**Se commits existem mas `SUMMARY.md` está ausente** (o executor confirmou o commit mas não escreveu o resumo antes de a sessão encerrar), o GSD Core exibe uma porta de retomada segura e oferece três opções:
- `close out manually` — inspecione os commits, escreva o `SUMMARY.md` e reexecute.
- `re-execute from scratch` — reverta ou substitua os commits parciais antes de despachar um novo executor.
- `mark-and-skip` — registre a anomalia e prossiga, somente com confirmação explícita.
Para diagnóstico sistemático de falhas, consulte [Depurar uma execução com falha](debug-a-failed-execution.md).
---
## Onde os resultados ficam armazenados
Após a conclusão de todas as ondas, o diretório da fase contém:
```
.planning/phases/01-<name>/
01-01-SUMMARY.md # O que o plano 01 construiu, arquivos principais, desvios
01-02-SUMMARY.md
01-03-SUMMARY.md
VERIFICATION.md # Status de aprovação/reprovação por requisito
```
`STATE.md` e `ROADMAP.md` são atualizados automaticamente após a conclusão de todas as ondas. `VERIFICATION.md` é gerado somente quando a fase está totalmente completa.
O histórico git exibirá um commit por tarefa (de cada executor), seguido de commits de rastreamento do orquestrador.
---
## Execução Cross-AI
Para delegar a execução a uma CLI de IA externa (Codex, Gemini, etc.) configurada em `workflow.cross_ai_command`:
```bash
/gsd-execute-phase 2 --cross-ai
```
Para forçar a execução local mesmo quando a execução cross-AI está habilitada na configuração:
```bash
/gsd-execute-phase 2 --no-cross-ai
```
---
## Relacionados
- [Planejar uma fase](plan-a-phase.md)
- [Verificar e publicar](verify-and-ship.md)
- [Depurar uma execução com falha](debug-a-failed-execution.md)
- [Comandos](../COMMANDS.md)

121
docs/pt-BR/how-to/handle-quick-and-fast-tasks.md Normal file
View File

@@ -0,0 +1,121 @@
# Como lidar com tarefas rápidas e ágeis
Nem todo trabalho cabe dentro de uma fase. O GSD oferece dois comandos leves para trabalhos que não precisam do ciclo completo de discussão → planejamento → execução → verificação.
Para contexto sobre quando o pipeline completo de fases vale o custo, consulte [Engenharia de contexto](../explanation/context-engineering.md).
---
## Decidindo qual comando usar
| Situação | Comando |
|-----------|---------|
| Corrigir um bug, adicionar uma funcionalidade pequena ou qualquer tarefa que não possa ser resumida como uma única edição trivial | `/gsd-quick` |
| Corrigir um erro de digitação, atualizar um valor de configuração, adicionar uma entrada ao `.gitignore` ou qualquer alteração que toque ≤ 3 arquivos e leve menos de um minuto | `/gsd-fast` |
| A tarefa tem incógnitas, precisa de pesquisa ou vai tocar em mais do que um punhado de arquivos | `/gsd-quick` com `--research` |
**A regra prática:** se você hesitar por um momento sobre se a tarefa é trivial, use `/gsd-quick`. O `/gsd-fast` redireciona automaticamente para `/gsd-quick` se o escopo parecer não trivial.
---
## `/gsd-quick` — tarefas ad-hoc com garantias GSD
O `/gsd-quick` executa um planejador e executor com as mesmas garantias de commit atômico e rastreamento no STATE.md que uma fase completa, mas sem o custo de uma fase (sem entrada no ROADMAP, sem fase de discussão, sem coordenação de ondas entre múltiplos planos).
### Uso básico
```bash
/gsd-quick
```
O GSD solicita uma descrição da tarefa, então planeja e executa. Os artefatos ficam em `.planning/quick/`.
Você também pode passar a descrição diretamente:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
### Flags
Adicione flags para incluir mais do pipeline de qualidade quando a tarefa exigir.
| Flag | O que adiciona |
|------|-------------|
| `--discuss` | Uma discussão leve de pré-planejamento que revela áreas cinzentas e registra suas decisões em um `CONTEXT.md` antes de o planejador rodar |
| `--research` | Um agente de pesquisa focado investiga abordagens, bibliotecas e armadilhas antes do planejamento |
| `--validate` | Verificação do plano (até 2 iterações) mais verificação pós-execução |
| `--full` | Tudo o que foi descrito acima — equivalente a `--discuss --research --validate` |
As flags se combinam livremente:
```bash
/gsd-quick --research --validate # research + plan-checking + verification, no discuss
/gsd-quick --discuss # just surface grey areas before planning
/gsd-quick --full # the complete quality pipeline
```
### Quando adicionar flags
- Adicione `--research` quando não tiver certeza de como abordar uma tarefa ou qual biblioteca usar.
- Adicione `--validate` quando a tarefa tocar caminhos de código críticos e você quiser que um agente verificador confirme se os requisitos foram atendidos.
- Adicione `--discuss` quando a tarefa tiver escolhas de design que você quer definir antes de o planejador rodar — por exemplo, quando o comportamento correto de tratamento de erros não é óbvio.
- Use `--full` quando uma tarefa for genuinamente significativa e você normalmente a planejaria como uma fase, mas ela não pertence ao ROADMAP.
### Listando e retomando tarefas rápidas
```bash
/gsd-quick list # show all quick tasks with status
/gsd-quick status my-task-slug # show status of a specific task
/gsd-quick resume my-task-slug # resume an interrupted task
```
---
## `/gsd-fast` — edições triviais inline
O `/gsd-fast` faz o trabalho diretamente no contexto atual. Não há subagentes, nenhum `PLAN.md` e nenhuma pesquisa. É adequado apenas para alterações que você mesmo poderia fazer em menos de um minuto.
```bash
/gsd-fast "fix typo in README"
/gsd-fast "add .env to .gitignore"
```
Se você omitir a descrição, o GSD vai solicitá-la.
O `/gsd-fast` verifica se a tarefa é realmente trivial antes de prosseguir. Se julgar o escopo muito grande, ele para e redireciona você:
```text
This looks like it needs planning. Use /gsd-quick instead:
/gsd-quick "your task description"
```
Após fazer a alteração, o `/gsd-fast` faz commit atomicamente e, se uma tabela `Quick Tasks Completed` existir em `.planning/STATE.md`, acrescenta uma linha a ela.
---
## O que o `/gsd-quick` faz que o `/gsd-fast` não faz
| Capacidade | `/gsd-fast` | `/gsd-quick` |
|------------|------------|--------------|
| Planejador subagente | Não | Sim |
| Executor subagente | Não | Sim |
| Agente de pesquisa | Não | Opcional (`--research`) |
| Verificação de plano | Não | Opcional (`--validate`) |
| Verificação pós-execução | Não | Opcional (`--validate`) |
| Fase de discussão | Não | Opcional (`--discuss`) |
| Isolamento em worktree | Não | Sim (padrão) |
| Commits atômicos por tarefa | Commit único | Um por tarefa do plano |
| Rastreamento no STATE.md | Linha acrescentada se a tabela existir | Sempre atualizado |
| Artefatos em `.planning/quick/` | Não | Sim |
A distinção principal é o isolamento de subagentes. O `/gsd-quick` gera um planejador e executor novos em janelas de contexto separadas, o que significa que o trabalho é planejado adequadamente, os commits são atômicos por tarefa e o orquestrador pode verificar os resultados. O `/gsd-fast` usa apenas a janela de contexto atual e é intencionalmente limitado a alterações triviais o suficiente para não precisar de nada disso.
---
## Relacionados
- [O ciclo de fases](../explanation/the-phase-loop.md)
- [Engenharia de contexto](../explanation/context-engineering.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

291
docs/pt-BR/how-to/install-on-your-runtime.md Normal file
View File

@@ -0,0 +1,291 @@
# Como instalar o GSD Core no seu ambiente de execução
Instale o GSD Core (`@opengsd/gsd-core`) no ambiente de codificação com IA que você usa no dia a dia. Este guia apresenta o caminho padrão de instalação para cada ambiente suportado e, em seguida, cobre o caminho manual para máquinas sem Node.js.
**O que você precisa:** Node.js 18+ e npm (ou npx). Se você não tem Node.js, vá para [Instalando sem Node.js](#instalando-sem-nodejs).
---
## Por que o instalador é necessário
O GSD Core distribui arquivos de agente e comando no formato nativo de frontmatter do Claude Code. Cada ambiente suportado espera um schema, layout de diretório e sintaxe de invocação de comandos diferente. O instalador realiza as transformações necessárias — por exemplo, convertendo listas de ferramentas e valores de cor para o OpenCode, escrevendo entradas TOML de agente para o Codex e reescrevendo o corpo de cada comando do formato com hífen (`/gsd-update`) para o formato com dois-pontos (`/gsd:update`) para o Gemini CLI.
**Não copie arquivos de `agents/` ou `commands/` diretamente.** Fazer isso ignora as transformações e produz erros de validação de schema ou comandos ausentes.
---
## Instalação padrão
Execute o instalador a partir de qualquer diretório. Ele solicita o seu ambiente e se a instalação deve ser global (todos os projetos) ou local (apenas este projeto).
```bash
npx @opengsd/gsd-core@latest
```
Esse é o único comando necessário para uma instalação nova ou para executar o instalador novamente após trocar de ambiente.
---
## Instruções por ambiente
### Claude Code
```bash
npx @opengsd/gsd-core@latest --claude --global
```
As habilidades são instaladas em `~/.claude/`. Os comandos aparecem como slash commands `/gsd-*` na sua próxima sessão do Claude Code. Reinicie o Claude Code para carregá-los.
**Substituir o diretório de instalação:**
```bash
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
```
---
### Gemini CLI
```bash
npx @opengsd/gsd-core@latest --gemini --global
```
As habilidades são instaladas em `~/.gemini/`. O instalador reescreve todos os corpos de comando para o namespace de dois-pontos do Gemini (`/gsd:update`, `/gsd:config`, etc.). Reinicie o Gemini CLI após a instalação.
**Substituir o diretório de instalação:**
```bash
GEMINI_CONFIG_DIR=~/.gemini-alt npx @opengsd/gsd-core@latest --gemini --global
```
---
### OpenCode
```bash
npx @opengsd/gsd-core@latest --opencode --global
```
As habilidades são instaladas em `~/.config/opencode/` (XDG) ou `~/.opencode/`. O instalador converte o frontmatter dos agentes para o schema do OpenCode — removendo o campo `tools:` e convertendo valores de cor para hex. Consulte [Instalando sem Node.js — transformações do OpenCode](#opencode--transformações-necessárias) se você precisar entender o que muda.
**Substituir o diretório de instalação:**
```bash
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
```
---
### Kilo
```bash
npx @opengsd/gsd-core@latest --kilo --global
```
As habilidades são instaladas em `~/.config/kilo/` (XDG) ou `~/.kilo/`. Usa o mesmo formato de comando markdown plano no estilo OpenCode.
**Substituir o diretório de instalação:**
```bash
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
```
---
### Codex
```bash
npx @opengsd/gsd-core@latest --codex --global
```
As habilidades são instaladas em `~/.codex/skills/gsd-*/SKILL.md`. Os agentes são registrados com entradas TOML por agente em `config.toml`. Reinicie o Codex (ou execute `codex --reload`) após a instalação.
**Versão mínima suportada:** Codex CLI 0.130.0. Versões anteriores tinham varredura adicional de raiz de habilidades que pode produzir listagens duplicadas.
---
### GitHub Copilot
```bash
npx @opengsd/gsd-core@latest --copilot --global
```
As habilidades são instaladas em `~/.copilot/`. O GSD é instalado como arquivos de agente `.md` e arquivos de instrução de repositório.
**Substituir o diretório de instalação:**
```bash
COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --global
```
---
### Cursor
```bash
npx @opengsd/gsd-core@latest --cursor --global
```
As habilidades são instaladas em `~/.cursor/`. O GSD instala habilidades, agentes e referências de regras.
**Substituir o diretório de instalação:**
```bash
CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
```
---
### Windsurf
```bash
npx @opengsd/gsd-core@latest --windsurf --global
```
As habilidades são instaladas em `~/.codeium/windsurf/`. O GSD instala habilidades, agentes e regras de workspace.
**Substituir o diretório de instalação:**
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @opengsd/gsd-core@latest --windsurf --global
```
---
### Cline
O Cline usa uma integração baseada em regras — o GSD é instalado como `.clinerules` em vez de slash commands.
```bash
# Instalação global (todos os projetos)
npx @opengsd/gsd-core@latest --cline --global
# Instalação local (apenas este projeto)
npx @opengsd/gsd-core@latest --cline --local
```
Instalações globais escrevem em `~/.cline/`. Instalações locais escrevem em `./.cline/`. As regras são carregadas automaticamente pelo Cline — nenhum slash command personalizado é registrado.
---
### CodeBuddy
```bash
npx @opengsd/gsd-core@latest --codebuddy --global
```
As habilidades são instaladas em `~/.codebuddy/skills/gsd-*/SKILL.md`.
---
### Qwen Code
O Qwen Code usa o mesmo padrão de habilidades abertas do Claude Code 2.1.88+.
```bash
npx @opengsd/gsd-core@latest --qwen --global
```
As habilidades são instaladas em `~/.qwen/skills/gsd-*/SKILL.md`.
**Substituir o diretório de instalação:**
```bash
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
```
---
### Augment Code
```bash
npx @opengsd/gsd-core@latest --augment --global
```
As habilidades são instaladas em `~/.augment/`. O GSD instala habilidades e agentes. Sem posse de hook ou statusline.
---
### Antigravity
```bash
npx @opengsd/gsd-core@latest --antigravity --global
```
O instalador detecta automaticamente o diretório de configuração do Antigravity (`~/.gemini/antigravity`, `~/.gemini/antigravity-ide` ou `~/.gemini/antigravity-cli`). Usa a política de configurações compatível com Gemini.
**Substituir o diretório de instalação:**
```bash
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
```
---
### Trae
```bash
npx @opengsd/gsd-core@latest --trae --global
```
As habilidades são instaladas em `~/.trae/`. O GSD instala habilidades, agentes e referências de regras.
---
## Instalação local vs global
Todos os exemplos acima usam `--global`, que instala o GSD uma vez para a sua conta de usuário. Para limitar uma instalação a um único projeto, substitua `--global` por `--local`:
```bash
npx @opengsd/gsd-core@latest --claude --local
```
Uma instalação local escreve no diretório `.claude/` na raiz do seu projeto. As configurações de instalação local têm precedência sobre as globais quando ambas existem.
---
## Instalando edições de pré-lançamento (Next / Nightly / Insiders / Preview)
As edições de pré-lançamento dos ambientes (Windsurf Next, Cursor Nightly, VS Code Insiders, canais de preview do Codex, etc.) leem de um diretório de configuração irmão. Defina a variável de ambiente `*_CONFIG_DIR` correspondente antes de executar o instalador:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
```
Selecione o ambiente estável correspondente no prompt do instalador. O GSD não enumera as edições de pré-lançamento como ambientes nomeados separados — elas são suportadas com melhor esforço por meio desse mecanismo de variável de ambiente e não são testadas separadamente no CI de lançamento.
---
## Instalando sem Node.js
Se você não pode executar `npx` (por exemplo, em uma máquina Windows sem Node.js), você tem duas opções.
**Opção A — Use uma máquina que tenha Node.js.** Qualquer máquina com Node.js serve: WSL, uma VM Linux, um runner de CI ou um contêiner Docker. Execute o instalador lá e, em seguida, copie o diretório de saída para a sua máquina de destino. Para o OpenCode:
```bash
npx @opengsd/gsd-core@latest --opencode --global
# Depois copie ~/.config/opencode/agents/ para a máquina Windows
```
**Opção B — Transforme manualmente os arquivos-fonte.** Os arquivos-fonte dos agentes estão em `agents/` no repositório do GSD Core e estão no formato nativo de frontmatter do Claude Code. Cada ambiente espera um formato diferente. Para as transformações de campo exatas por ambiente, consulte [Instalação manual / configuração sem Node.js](../USER-GUIDE.md#manual-install--no-nodejs-setup) no Guia do Usuário, que cobre as transformações do OpenCode em detalhes completos e aponta para as funções `convert*Frontmatter` do instalador para outros ambientes.
---
## Após a instalação
Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie seu primeiro projeto:
```bash
/gsd-new-project
```
Se o comando não for encontrado após o reinício, verifique se o diretório de instalação corresponde ao caminho de configuração esperado pelo ambiente. A seção de edições de pré-lançamento acima cobre a incompatibilidade mais comum.
---
## Relacionados
- [Seu primeiro projeto](../tutorials/your-first-project.md)
- [Atualizar o GSD Core](update-gsd.md)
- [Configuração](../CONFIGURATION.md)
- [Índice da documentação](../README.md)

144
docs/pt-BR/how-to/isolate-work-with-workspaces.md Normal file
View File

@@ -0,0 +1,144 @@
# Como isolar trabalho com workspaces
**Objetivo:** Criar um ambiente GSD completamente isolado — worktree git separado, raiz `.planning/` independente e, opcionalmente, múltiplos repositórios — para branches de funcionalidades ou trabalho em múltiplos repositórios.
**Pré-requisitos:** O `git` está instalado e o repositório oferece suporte a worktrees. Para workspaces com múltiplos repositórios, os repositórios de destino existem em sua máquina local ou são acessíveis por caminho.
---
## O que são workspaces
Um workspace é um ambiente autocontido que combina um ou mais worktrees git (ou clones) com seu próprio diretório raiz `.planning/`. Cada workspace possui:
- Seu próprio diretório `.planning/` que é **completamente independente** do `.planning/` do repositório de origem — não é um subdiretório dele
- Seu próprio manifesto `WORKSPACE.md` que rastreia os repositórios membros
- Worktrees git (padrão) ou clones completos dos repositórios especificados, com checkout em uma branch dedicada (padrão: `workspace/<nome>`)
Por padrão, os workspaces ficam em `~/gsd-workspaces/<nome>/`.
```
~/gsd-workspaces/
└── feature-b/
├── WORKSPACE.md ← manifesto
├── .planning/ ← estado GSD totalmente independente
│ ├── PROJECT.md
│ ├── ROADMAP.md
│ └── ...
├── hr-ui/ ← worktree ou clone do repositório hr-ui
└── ZeymoAPI/ ← worktree ou clone do repositório ZeymoAPI
```
Como o `.planning/` do workspace é separado dos repositórios de origem, não há sobreposição ou conflito com o estado de planejamento existente nos próprios repositórios de origem.
---
## Criar um workspace para múltiplos repositórios
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
```
O GSD cria worktrees de `hr-ui` e `ZeymoAPI` dentro de `~/gsd-workspaces/feature-b/`, faz checkout de uma branch `workspace/feature-b` em cada um, grava o `WORKSPACE.md` e cria um diretório `.planning/` vazio pronto para `/gsd-new-project`.
Para personalizar o local:
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
```
---
## Criar um workspace para o repositório atual
Quando você deseja isolamento por branch de funcionalidade em um único repositório — branch independente, `.planning/` independente, sem vazamento de estado da branch principal:
```bash
/gsd-workspace --new --name payments-rework --repos .
```
O `.` instrui o GSD a criar um worktree do repositório atual. O worktree recebe checkout em `workspace/payments-rework`.
Para forçar um clone completo em vez de um worktree:
```bash
/gsd-workspace --new --name payments-rework --repos . --strategy clone
```
---
## Especificar uma branch explicitamente
```bash
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
```
O flag `--branch` define o nome da branch para todos os repositórios do workspace. O padrão é `workspace/<nome>`.
---
## Ignorar perguntas interativas
```bash
/gsd-workspace --new --name payments-rework --repos . --auto
```
O GSD aceita todos os padrões sem solicitar confirmação.
---
## Inicializar o GSD dentro do workspace
Após criar um workspace, acesse-o e inicialize um projeto GSD:
```bash
cd ~/gsd-workspaces/feature-b
/gsd-new-project
```
O diretório `.planning/` dentro do workspace é a raiz para todos os comandos GSD subsequentes executados a partir desse diretório. Ele é completamente separado de qualquer `.planning/` existente nos repositórios de origem.
---
## Listar workspaces
```bash
/gsd-workspace --list
```
Exibe todos os workspaces GSD ativos e seus status.
---
## Remover um workspace
```bash
/gsd-workspace --remove feature-b
```
O GSD remove os worktrees git e limpa o diretório do workspace. Isso não exclui as branches do remote de origem — apenas os worktrees locais e o diretório do workspace.
---
## Quando usar workspaces em vez de workstreams
Escolha workspaces quando:
- Você está trabalhando em **múltiplos repositórios** que precisam ser coordenados sob um único projeto GSD (por exemplo, um repositório de API e um repositório de UI que fazem entregas juntos)
- Você precisa de um **worktree git separado** com sua própria branch, arquivos de lock e artefatos de build por funcionalidade — para que builds e instalações de dependências em um ambiente não afetem outro
- Você deseja uma **raiz `.planning/` completamente independente** em vez de um subdiretório do `.planning/` do repositório principal
- Você está seguindo um fluxo de trabalho orientado a issues em que cada issue do rastreador é mapeada para um workspace (consulte [Conduzir o GSD a partir de uma issue do rastreador](drive-gsd-from-a-tracker-issue.md))
Escolha [workstreams](work-in-parallel-with-workstreams.md) quando:
- Todo o trabalho está em **um único repositório** e compartilha o mesmo histórico git
- Você deseja executar `/gsd-plan-phase` ou `/gsd-discuss-phase` em diferentes áreas de interesse simultaneamente — API, UI, infra — sem vazamento de contexto entre os arquivos `STATE.md`
- Você não precisa de um worktree separado por área de interesse; alternar o contexto de planejamento é suficiente
---
## Relacionados
- [Trabalhar em paralelo com workstreams](work-in-parallel-with-workstreams.md)
- [Conduzir o GSD a partir de uma issue do rastreador](drive-gsd-from-a-tracker-issue.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

145
docs/pt-BR/how-to/migrate-from-gsd-2.md Normal file
View File

@@ -0,0 +1,145 @@
# Como migrar do GSD-2
**Objetivo:** Atualizar um projeto GSD-2 mais antigo (estrutura de diretório `.gsd/`) para o GSD Core (estrutura `.planning/`), e opcionalmente absorver quaisquer ADRs, PRDs ou especificações existentes no repositório para a nova estrutura de planejamento.
**Pré-requisitos:** GSD Core está instalado. O diretório do projeto GSD-2 está disponível em disco.
---
## Entenda o que é migrado
O GSD-2 usava um diretório `.gsd/` como raiz de planejamento. O GSD Core usa `.planning/`. A migração faz a conversão: lê os artefatos de `.gsd/` e os grava na estrutura padrão `.planning/` que todos os comandos GSD Core esperam.
| O que existe no GSD-2 | O que `/gsd-import --from-gsd2` produz |
|-----------------------|----------------------------------------|
| `.gsd/PROJECT.md` | `.planning/PROJECT.md` |
| `.gsd/ROADMAP.md` | `.planning/ROADMAP.md` |
| `.gsd/STATE.md` | `.planning/STATE.md` |
| `.gsd/phases/` diretórios | `.planning/phases/` diretórios |
| Arquivos `PLAN.md` de fase | Arquivos `{NN}-{MM}-PLAN.md` do GSD Core (renomeação aplicada) |
A detecção de conflitos é executada antes que qualquer arquivo seja gravado. Se o diretório de destino já tiver um `PROJECT.md` e o conteúdo importado contradizê-lo, a migração para no ponto de bloqueio (BLOCKER) e lista os conflitos para você resolver.
---
## Execute a migração
### Migrar o diretório atual
```bash
/gsd-import --from-gsd2
```
O GSD lê `.gsd/` no diretório de trabalho atual e grava os artefatos migrados em `.planning/`.
### Migrar a partir de um caminho diferente
```bash
/gsd-import --from-gsd2 --path ~/projects/old-project
```
Use `--path` quando o projeto GSD-2 não for seu diretório de trabalho atual.
---
## Resolva conflitos
Se a detecção de conflitos encontrar bloqueadores — por exemplo, uma declaração de stack tecnológico do GSD-2 que contradiz um `.planning/PROJECT.md` existente — ela imprime um relatório de conflitos e para sem gravar nenhum arquivo.
Leia o relatório, resolva a contradição (edite o documento de origem ou o artefato de planejamento existente) e execute `/gsd-import --from-gsd2` novamente. A migração pode ser executada novamente com segurança até ser concluída sem problemas.
---
## Importe um arquivo de plano externo
Se você tiver um documento de plano avulso (um documento de planejamento de equipe, uma especificação em Markdown, uma lista de tarefas exportada) em vez de um projeto GSD-2 completo, use `--from`:
```bash
/gsd-import --from /tmp/team-plan.md
```
O GSD executa a mesma passagem de detecção de conflitos, converte o conteúdo para o formato `PLAN.md` do GSD Core e valida o resultado com o verificador de planos. Após a validação, você verá o nome do arquivo de destino e os próximos passos.
---
## Absorva documentação existente
Se o seu repositório já contiver ADRs (Architecture Decision Records), PRDs ou documentos de especificação, use `/gsd-ingest-docs` para sintetizá-los na estrutura `.planning/` após a migração:
### Varrer o repositório inteiro (detecta o modo automaticamente)
```bash
/gsd-ingest-docs
```
Se `.planning/` já estiver presente (por exemplo, a partir da migração que você acabou de executar), o GSD usa o modo de mesclagem por padrão — ele sintetiza os documentos ingeridos junto com o que já existe, em vez de sobrescrevê-los.
### Limitar a um diretório específico
```bash
/gsd-ingest-docs docs/
/gsd-ingest-docs docs/adr/
```
### Usar um manifesto de precedência explícito
Quando os documentos têm tipos mistos ou você deseja controlar qual documento prevalece em caso de conflitos:
```bash
/gsd-ingest-docs --manifest ingest.yaml
```
O manifesto é um arquivo YAML que lista `{path, type, precedence?}` por documento. Consulte a descrição do flag `--manifest` em [Comandos](../COMMANDS.md) para o formato esperado.
### Forçar um modo específico
```bash
/gsd-ingest-docs --mode merge # Mesclar com o .planning/ existente
/gsd-ingest-docs --mode new # Inicializar do zero (sobrescreve)
```
**Saída:** `/gsd-ingest-docs` sempre produz um `INGEST-CONFLICTS.md` com três categorias — resolvidos automaticamente, variantes concorrentes e bloqueadores não resolvidos. Revise este arquivo após cada execução de ingestão. Paradas forçadas ocorrem apenas em contradições LOCKED-vs-LOCKED de ADRs; todo o resto é apresentado para sua revisão, não descartado silenciosamente.
---
## Verifique o projeto migrado
Após a migração e qualquer ingestão de documentos, confirme que o estado do projeto está consistente:
```bash
/gsd-health
/gsd-health --repair
```
`/gsd-health` verifica a integridade do diretório `.planning/` e relata qualquer desvio. `--repair` corrige automaticamente os problemas recuperáveis.
Em seguida, verifique se o GSD Core consegue ler o estado do seu projeto:
```bash
/gsd-progress
```
Se o projeto foi migrado corretamente, você verá o status da fase atual e o próximo passo recomendado. A partir daí, o fluxo de trabalho padrão do GSD Core se aplica.
---
## Condicionais: o que é migrado e o que não é
| Situação | O que fazer |
|----------|-------------|
| `.gsd/` existe no diretório atual | Execute `/gsd-import --from-gsd2` (sem `--path`) |
| `.gsd/` está em um diretório diferente | Use `--path ~/projects/old-project` |
| Você tem um documento de plano avulso, não um projeto GSD-2 completo | Use `/gsd-import --from /path/to/plan.md` |
| Você tem ADRs em `docs/adr/` | Execute `/gsd-ingest-docs docs/adr/` após a migração |
| Você tem uma mistura de ADRs, PRDs e especificações | Execute `/gsd-ingest-docs` na raiz do repositório; ele classifica automaticamente |
| A detecção de conflitos relata bloqueadores | Resolva as contradições listadas e execute novamente; nenhum arquivo é gravado até que todos os bloqueadores sejam resolvidos |
| Você não tem certeza se a migração funcionou | Execute `/gsd-health` e `/gsd-progress` para confirmar |
| INGEST-CONFLICTS.md lista bloqueadores não resolvidos | Estes exigem resolução manual antes que os documentos afetados sejam incorporados ao planejamento |
---
## Relacionados
- [Seu primeiro projeto](../tutorials/your-first-project.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

216
docs/pt-BR/how-to/plan-a-phase.md Normal file
View File

@@ -0,0 +1,216 @@
# Como planejar uma fase
**Objetivo:** Transformar decisões de fase e pesquisa em um plano de tarefas atômico e verificável, pronto para execução.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. Um `{fase}-CONTEXT.md` gerado pelo `/gsd-discuss-phase` é fortemente recomendado, mas não obrigatório.
---
## Execute o fluxo de planejamento padrão
```bash
/gsd-plan-phase 2
```
Isso executa três estágios em sequência:
1. **Pesquisa** — Um subagente `gsd-phase-researcher` investiga o domínio e escreve `{fase}-RESEARCH.md`.
2. **Planejamento** — Um subagente `gsd-planner` lê o contexto, a pesquisa e os requisitos, e então escreve um ou mais arquivos `{fase}-{N}-PLAN.md`.
3. **Verificação** — Um subagente `gsd-plan-checker` valida a qualidade do plano em oito dimensões e aciona um ciclo de revisão (até três iterações) até que os critérios de qualidade sejam aprovados.
Se nenhum número de fase for fornecido, o GSD Core seleciona a próxima fase não planejada do roadmap.
---
## Pular ou forçar a pesquisa
**Se o domínio for familiar e não houver necessidade de nova pesquisa:**
```bash
/gsd-plan-phase 3 --skip-research
```
**Se o RESEARCH.md já existir, mas você quiser forçar uma atualização:**
```bash
/gsd-plan-phase 3 --research
```
**Se você quiser executar apenas a pesquisa** — escrever o RESEARCH.md e encerrar antes do planejamento:
```bash
/gsd-plan-phase --research-phase 4
```
Se o RESEARCH.md já existir, será solicitado que você atualize, visualize ou pule. Para forçar a atualização sem o prompt:
```bash
/gsd-plan-phase --research-phase 4 --research
```
Para imprimir o RESEARCH.md existente no stdout sem acionar o pesquisador:
```bash
/gsd-plan-phase --research-phase 4 --view
```
Nota: `--research-phase <N>` é uma flag do `/gsd-plan-phase`. Não existe um comando standalone de fase de pesquisa — o comando standalone foi removido em favor desta flag.
---
## Planejar fatias verticais de funcionalidades em vez de camadas horizontais
**Se você quiser tarefas organizadas como fatias finas de ponta a ponta** (UI → API → BD por funcionalidade) em vez de por camada técnica:
```bash
/gsd-plan-phase 1 --mvp
```
Na Fase 1 de um novo projeto sem resumos de fases anteriores, `--mvp` também produz `SKELETON.md` — um Walking Skeleton que cobre o scaffold do projeto, roteamento, uma leitura/escrita real no BD, uma interação real de UI e implantação de desenvolvimento.
É possível persistir o modo MVP para uma fase sem a flag, adicionando `**Mode:** mvp` à entrada daquela fase no ROADMAP.md.
---
## Exigir um teste falho por tarefa que adiciona comportamento
**Se você quiser a aplicação de TDD** — cada tarefa que adiciona comportamento começa com um teste falho antes da implementação:
```bash
/gsd-plan-phase 1 --tdd
```
Combinável com `--mvp`:
```bash
/gsd-plan-phase 1 --mvp --tdd
```
Isso produz fatias verticais onde cada tarefa que adiciona comportamento segue o ciclo RED → GREEN → REFACTOR. O planejador aplica `type: tdd` às tarefas elegíveis (lógica de negócio, endpoints de API, transformações de dados) e usa o `type: execute` padrão para UI, configuração e código de integração.
O modo TDD também pode ser persistido em config:
```bash
node gsd-tools.cjs config-set workflow.tdd_mode true
```
---
## Replanejar usando feedback de revisão cruzada por IA
**Se você executou `/gsd-review --phase N` e um `REVIEWS.md` existe:**
```bash
/gsd-plan-phase 3 --reviews
```
O planejador lê o `REVIEWS.md` e revisa os planos para endereçar o feedback. Não pode ser combinado com `--gaps`.
**Se você quiser um ciclo automatizado** — replanejar e revisar até que não restem preocupações de nível HIGH:
```bash
/gsd-plan-review-convergence 3
```
O ciclo de convergência executa ciclos de planejar → revisar → replanejar → revisar novamente (até três por padrão). Use `--max-cycles N` para substituir o limite máximo.
---
## Fechar lacunas após uma verificação falha
**Se o `VERIFICATION.md` existir com lacunas não resolvidas e você quiser replanejar apenas para essas lacunas:**
```bash
/gsd-plan-phase 3 --gaps
```
A pesquisa é ignorada; o planejador lê as lacunas de verificação diretamente.
---
## Validar o estado do projeto antes de iniciar o planejamento
```bash
/gsd-plan-phase 2 --validate
```
Executa a validação de estado antes de acionar o pesquisador. Use isso se suspeitar que o ROADMAP.md ou STATE.md derivou.
---
## Executar uma validação externa de bounce após o planejamento
**Se `workflow.plan_bounce_script` estiver configurado e você quiser validação externa do plano concluído:**
```bash
/gsd-plan-phase 1 --bounce
```
Para pular o bounce mesmo que esteja habilitado em config:
```bash
/gsd-plan-phase 1 --skip-bounce
```
---
## Suprimir confirmações interativas
```bash
/gsd-plan-phase --auto
```
Ignora todos os prompts. Útil em pipelines automatizados. A pesquisa é ignorada se `research_enabled` for false em config.
---
## O que o plano produz
Uma execução bem-sucedida escreve:
| Arquivo | Finalidade |
|---|---|
| `{fase}-RESEARCH.md` | Pesquisa de domínio, auditoria de legitimidade de pacotes, arquitetura de validação |
| `{fase}-VALIDATION.md` | Mapeamento de testes Nyquist — os casos de teste que o plano deve satisfazer (Dimensão 8) |
| `{fase}-{N}-PLAN.md` | Plano de tarefas executável com frontmatter, atribuições de wave e critérios de aceitação |
| `{fase}/SKELETON.md` | Walking Skeleton (modo MVP, apenas Fase 1 de novo projeto) |
Cada PLAN.md contém tarefas com os campos obrigatórios `<read_first>` e `<acceptance_criteria>`. Cada entrada de `<acceptance_criteria>` é verificável como uma asserção de fonte, asserção de comportamento, comando de teste ou saída de CLI — nunca linguagem subjetiva.
Para a referência completa de campos, consulte o [schema do PLAN.md](../reference/plan-md.md).
### Dimensões de qualidade do plano
O `gsd-plan-checker` valida os planos em oito dimensões antes de permitir a execução:
1. Atomicidade das tarefas — cada tarefa abrange uma única preocupação
2. Correção das dependências — a ordenação de waves é consistente
3. Verificabilidade dos critérios de aceitação — nenhum critério subjetivo
4. Completude do `<read_first>` — o arquivo sendo modificado está sempre listado
5. Valores concretos de `<action>` — sem instruções vagas como "alinhar com"
6. `must_haves` derivados do objetivo da fase
7. Cobertura de IDs de requisitos — cada ID de requisito da fase aparece em pelo menos um plano
8. Mapeamento de testes Nyquist — os planos abordam a estratégia de validação no VALIDATION.md
O ciclo de revisão executa até três vezes. Se os critérios de qualidade não forem aprovados após três iterações, o verificador apresenta os problemas remanescentes para revisão manual.
---
## Replanejamento de uma fase encerrada
Se uma fase possui `VERIFICATION.md` com `status: passed`, ela é considerada encerrada. Tentar replanejá-la resulta em erro. Se o encerramento foi incorreto, substitua com `--force`:
```bash
/gsd-plan-phase 2 --force
```
Um aviso é emitido na transcrição e em quaisquer documentos de plano confirmados.
---
## Relacionados
- [Discutir uma fase](discuss-a-phase.md)
- [Executar uma fase](execute-a-phase.md)
- [Schema do PLAN.md](../reference/plan-md.md)
- [Comandos](../COMMANDS.md)

323
docs/pt-BR/how-to/recover-and-troubleshoot.md Normal file
View File

@@ -0,0 +1,323 @@
# Como recuperar e solucionar problemas
**Objetivo:** Identificar e corrigir problemas comuns — desde contexto perdido e estado corrompido até falhas de instalação e erros de permissão — usando uma estrutura de receitas condicionais.
**Pré-requisitos:** GSD Core está instalado. Para problemas específicos de instalação, consulte [Instalar no seu ambiente de execução](install-on-your-runtime.md).
---
## Problemas de contexto e sessão
### Se você perdeu o controle de onde está
```bash
/gsd-progress
```
Lê todos os arquivos de estado e informa exatamente onde você está e o que fazer a seguir.
Para avançar automaticamente para o próximo passo correto:
```bash
/gsd-progress --next
```
### Se você está iniciando uma nova sessão e precisa restaurar o contexto
```bash
/gsd-resume-work
```
Restaura o contexto completo da sua sessão a partir do último handoff, incluindo a fase atual, decisões de planejamento e onde o trabalho foi interrompido.
### Se a qualidade está caindo durante uma sessão longa
Limpe sua janela de contexto entre comandos principais:
```bash
/clear
```
Em seguida, restaure o estado:
```bash
/gsd-resume-work
```
O GSD foi projetado em torno de contextos frescos. Cada subagente já recebe uma janela limpa de 200k. A sessão principal se degrada com o tempo — limpá-la e retomar é o remédio correto, não continuar forçando.
### Se você quer salvar o contexto antes de parar
```bash
/gsd-pause-work
```
Cria `.planning/HANDOFF.json` com sua posição atual. Adicione `--report` para também gravar um resumo pós-sessão em `.planning/reports/`:
```bash
/gsd-pause-work --report
```
---
## Problemas de integridade do planejamento
### Se a integridade de `.planning/` está incerta
```bash
/gsd-health
```
Relata o status entre erros, avisos e notas informativas:
| Status | Significado |
|--------|-------------|
| `HEALTHY` | Todos os artefatos esperados estão presentes e bem formados |
| `DEGRADED` | Avisos que devem ser tratados, mas o trabalho pode continuar |
| `BROKEN` | Erros críticos que bloquearão a execução |
Problemas comuns que podem ser reparados automaticamente (erros E004, E005; avisos W003, W008):
```bash
/gsd-health --repair
```
Isso recria o `STATE.md` ausente, redefine um `config.json` corrompido para os padrões e adiciona quaisquer chaves de configuração ausentes. Não vai sobrescrever `PROJECT.md` ou `ROADMAP.md`.
### Se STATE.md referencia uma fase que não existe
Isso gera o aviso `W002`. Use a CLI de estado para diagnosticar e reparar:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state validate
```
Visualize o que uma sincronização mudaria sem gravar:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync --verify
```
Aplique a sincronização:
```bash
node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" state sync
```
Esses comandos reconstroem o `STATE.md` a partir do estado real do projeto em disco. Substituem a edição manual do `STATE.md`.
### Se você vê "Project already initialised"
`.planning/PROJECT.md` já existe. `/gsd-new-project` é uma verificação de segurança. Se você realmente quer começar do zero, delete o diretório `.planning/` primeiro:
```bash
rm -rf .planning/
```
Em seguida, execute novamente `/gsd-new-project`.
### Se a utilização da janela de contexto está alta
```bash
/gsd-health --context
```
Verifica a proteção de utilização da janela de contexto. Emite aviso em 60%, crítico em 70%. Se você estiver acima do limite de aviso, execute `/clear` seguido de `/gsd-resume-work` antes de iniciar o próximo comando principal.
---
## Problemas de execução
### Se um executor recebe "Permission denied" em comandos Bash
Os subagentes `gsd-executor` do GSD precisam de acesso Bash com permissão de escrita. Adicione os padrões necessários em `~/.claude/settings.json` sob `permissions.allow`. No mínimo:
```json
"Bash(git add:*)",
"Bash(git commit:*)",
"Bash(git merge:*)",
"Bash(git checkout:*)"
```
Para padrões específicos de stack (Rails, Python, Node, Rust), consulte a tabela completa em `docs/USER-GUIDE.md` em "Executor Subagent Gets Permission denied".
Alternativa por projeto: adicione o mesmo bloco em `.claude/settings.local.json` na raiz do seu projeto.
### Se a execução falha ou produz stubs
Verifique se o plano é ambicioso demais. Os planos devem ter no máximo duas ou três tarefas. Se as tarefas forem muito grandes, elas excedem o que uma única janela de contexto consegue produzir de forma confiável. Replaneje a fase com escopo menor:
```bash
/gsd-plan-phase 1
```
Para diagnóstico sistemático do que deu errado, consulte [Depurar uma execução com falha](debug-a-failed-execution.md).
### Se a execução paralela causa erros de bloqueio de build ou falhas no hook de pré-commit
Isso é causado por múltiplos agentes acionando ferramentas de build simultaneamente. O GSD lida com isso automaticamente desde a v1.26. Se você estiver em uma versão mais antiga, ou ainda vendo contenção, desative a execução paralela:
```bash
/gsd-settings
```
Defina `parallelization.enabled` como `false`.
### Se um subagente parece ter falhado, mas commits foram feitos
Verifique o log do git antes de concluir que algo quebrou:
```bash
git log --oneline -10
```
Um bug de classificação conhecido do Claude Code pode reportar falha enquanto o trabalho foi concluído com sucesso. Os orquestradores do GSD verificam a saída real, mas se você vir uma discrepância, os commits são a fonte da verdade.
---
## Problemas de plano e fase
### Se os planos parecem errados ou desalinhados com sua intenção
Execute `/gsd-discuss-phase N` antes de planejar. A maioria dos problemas de qualidade do plano vem de suposições que o `CONTEXT.md` teria prevenido:
```bash
/gsd-discuss-phase 1
```
Para ver quais suposições o GSD está fazendo atualmente sem iniciar uma sessão completa:
```bash
/gsd-discuss-phase 3 --assumptions
```
### Se você precisa mudar algo após a execução
Não execute novamente `/gsd-execute-phase`. Use `/gsd-quick` para correções direcionadas:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
```
Ou use `/gsd-verify-work N` para identificar e corrigir problemas sistematicamente por meio de UAT.
### Se um comando parece congelado em "Spawning…"
Aguarde. Os subagentes do GSD são executados em uma janela de contexto separada. O trabalho deles é invisível para a sessão pai enquanto está em andamento. A nota de atividade na linha de spawn confirma que isso é esperado. Agentes de pesquisa e planejamento rotineiramente levam de 1 a 5 minutos; agentes de verificação podem levar mais tempo em fases grandes.
Não interrompa a sessão. Encerrá-la descarta o trabalho em andamento do subagente.
Se já passou mais de 10 minutos, verifique se a tarefa do agente ainda aparece como ativa na barra lateral do Claude Code.
---
## Problemas de estado do fluxo de trabalho
### Se o fluxo de trabalho parece corrompido ou o estado está inconsistente
```bash
/gsd-forensics
```
Ou com uma descrição:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
```
`/gsd-forensics` executa uma investigação post-mortem: anomalias no histórico do git, integridade dos artefatos, consistência do STATE.md, trabalho não commitado e worktrees órfãs. Grava um relatório em `.planning/forensics/` e apresenta etapas de remediação recomendadas. É somente leitura e nunca modifica os arquivos do seu projeto.
### Se você precisa reverter uma fase ou plano
```bash
/gsd-undo --phase 03 # Reverte todos os commits da fase 3
/gsd-undo --plan 03-02 # Reverte os commits do plano 02 da fase 3
/gsd-undo --last 5 # Escolhe interativamente entre os 5 commits GSD mais recentes
```
`/gsd-undo` verifica as fases dependentes antes de reverter e sempre apresenta uma confirmação.
---
## Problemas de instalação e atualização
### Se o GSD não é reconhecido após a instalação
Reinicie seu ambiente de execução. O GSD instala comandos slash no diretório de comandos do seu ambiente de execução (por exemplo, `~/.claude/commands/gsd/`). A maioria dos ambientes de execução descobre novos comandos apenas na inicialização.
Se o problema persistir, verifique a instalação:
```bash
npx @opengsd/gsd-core@latest --claude --local
```
Para caminhos de instalação específicos do ambiente de execução e solução de problemas, consulte [Instalar no seu ambiente de execução](install-on-your-runtime.md).
### Se uma atualização sobrescreveu suas alterações locais
Desde a v1.17, o instalador faz backup dos arquivos modificados localmente em `gsd-local-patches/`. Reaplique suas alterações:
```bash
/gsd-update --reapply
```
### Se você não consegue atualizar via npm
Se `npx @opengsd/gsd-core` falhar devido a interrupções do npm ou restrições de rede, consulte `docs/manual-update.md` para um procedimento de atualização manual passo a passo que funciona sem acesso ao npm.
Para atualizações de rotina, consulte [Atualizar o GSD](update-gsd.md).
---
## Problemas de custo
### Se os custos do modelo estão muito altos
Mude para o perfil de orçamento:
```bash
/gsd-config --profile budget
```
Desative os agentes de pesquisa e verificação de plano via configurações se o domínio for familiar:
```bash
/gsd-settings
```
Audite também quais servidores MCP estão habilitados. Cada servidor MCP habilitado injeta seu esquema de ferramentas em cada turno. Ferramentas específicas de navegador e plataforma podem custar mais de 20k tokens cada. Desabilite os que a fase atual não precisa em `.claude/settings.json`:
```json
{
"disabledMcpjsonServers": ["playwright", "mac-tools"]
}
```
---
## Referência rápida de recuperação
| Problema | Solução |
|----------|---------|
| Contexto perdido ou nova sessão | `/gsd-resume-work` ou `/gsd-progress` |
| Não sabe qual é o próximo passo | `/gsd-progress --next` |
| Fase deu errado | `/gsd-undo --phase NN`, depois replaneje |
| Algo quebrou | `/gsd-debug "descrição"` (adicione `--diagnose` para análise sem correções) |
| STATE.md fora de sincronia | `state validate` depois `state sync` |
| Integridade de `.planning/` incerta | `/gsd-health`, depois `/gsd-health --repair` |
| Estado do fluxo de trabalho parece corrompido | `/gsd-forensics` |
| Correção direcionada rápida | `/gsd-quick` |
| Plano não corresponde à sua visão | `/gsd-discuss-phase N` depois replaneje |
| Custos elevados | `/gsd-config --profile budget` e `/gsd-settings` para desativar agentes |
| Atualização quebrou alterações locais | `/gsd-update --reapply` |
| Quer resumo da sessão | `/gsd-pause-work --report` |
| Erros de build por execução paralela | Atualize o GSD ou defina `parallelization.enabled: false` |
---
## Relacionados
- [Depurar uma execução com falha](debug-a-failed-execution.md)
- [Instalar no seu ambiente de execução](install-on-your-runtime.md)
- [Comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)

124
docs/pt-BR/how-to/run-phases-autonomously.md Normal file
View File

@@ -0,0 +1,124 @@
# Como executar fases de forma autônoma
Execute todas as fases restantes — ou um intervalo delimitado delas — sem supervisão, para que o GSD avance por discuss → plan → execute em cada fase sem que você precise conduzir cada etapa.
Para mais informações sobre o que o loop de fases faz durante uma execução autônoma, consulte [O loop de fases](../explanation/the-phase-loop.md).
---
## Pré-requisitos
- Um projeto ativo com `.planning/ROADMAP.md` e `.planning/STATE.md`
- Todas as fases que você deseja executar devem estar em um estado que o modo autônomo possa conduzir (pendente ou em andamento; não já concluídas)
- Qualquer decisão de design que você se importe já deve estar em `PROJECT.md` ou registrada via um `/gsd-discuss-phase` anterior — o modo autônomo só consegue apresentar áreas cinzentas de forma interativa quando você usa `--interactive`
---
## Executar todas as fases restantes
```bash
/gsd-autonomous
```
O GSD lê o `ROADMAP.md`, descobre cada fase incompleta em ordem numérica e executa discuss → plan → execute em cada uma. Após todas as fases serem concluídas, ele executa automaticamente o ciclo de vida do milestone: audit → complete → cleanup.
---
## Executar um intervalo específico de fases
Use `--from` e `--to` para delimitar a execução. Ambos os flags aceitam números de fase decimais (ex.: `3.1`).
```bash
/gsd-autonomous --from 3 # fases 3, 4, 5 … (ignora as fases 1 e 2 já concluídas)
/gsd-autonomous --to 5 # fases até e incluindo a 5
/gsd-autonomous --from 3 --to 5 # exatamente as fases 3, 4 e 5
```
Quando `--to` é atingido, a etapa de ciclo de vida é ignorada, pois nem todas as fases do milestone foram concluídas. O banner de conclusão informa como retomar:
```text
Resume with: /gsd-autonomous --from 6
```
---
## Executar com discuss interativo
Por padrão, o modo autônomo responde às perguntas de discuss automaticamente usando o smart discuss (propostas em tabela em lote). Se você quiser responder às perguntas de design você mesmo, mantendo plan e execute fora do contexto principal:
```bash
/gsd-autonomous --interactive
```
No modo interativo:
- `/gsd-discuss-phase` é executado inline e aguarda suas respostas
- Planejamento e execução são despachados como agentes em segundo plano para que você possa discutir a próxima fase enquanto a atual está sendo construída
- O contexto principal permanece enxuto — apenas as conversas de discuss se acumulam
---
## Quais barreiras de segurança ainda se aplicam
O modo autônomo não ignora o pipeline de qualidade do GSD. Cada fase ainda:
- Executa o plan-checker antes da execução
- Lê o `VERIFICATION.md` após a execução e decide o caminho com base no resultado
- Pausa e pergunta o que fazer quando o status de verificação é `human_needed` ou `gaps_found`
- Para e apresenta opções (corrigir e tentar novamente, ignorar fase ou parar) se alguma etapa falhar
A única diferença em relação à execução manual é que a verificação com resultado `passed` avança automaticamente — você não é questionado entre as fases a menos que uma decisão seja necessária.
A barreira de legitimidade de pacotes também permanece ativa. Se um plano incluir uma tarefa `checkpoint:human-verify` para um pacote suspeito, o executor irá parar e apresentar o checkpoint. O modo autônomo não instalará silenciosamente pacotes sinalizados.
---
## Quando não usar o modo autônomo
Não use `/gsd-autonomous` quando:
- **As fases têm decisões de design não resolvidas.** Se você não executou `/gsd-discuss-phase` e seu `PROJECT.md` não registra suas preferências, o smart discuss fará escolhas autônomas com as quais você pode não concordar. Execute o discuss de forma interativa primeiro, ou use `--interactive`.
- **Você precisa de controle detalhado sobre uma única fase.** Para uma fase, `/gsd-execute-phase N` fornece saída passo a passo e permite que você reaja antes de continuar. O modo autônomo é projetado para execuções em lote sem supervisão.
- **A fase tem trabalho novo ou de alto risco.** O modo autônomo ignora pausas a menos que encontre um bloqueador. Em uma fase onde você espera surpresas, mantenha-se no loop com execução manual.
- **Você está no meio de uma fase com execução parcial.** O modo autônomo retoma fases incompletas, mas não retoma uma onda parcialmente executada. Use `/gsd-execute-phase N` para concluir uma fase que já está em andamento.
Se uma execução parar no meio do caminho, consulte [Depurar uma execução com falha](debug-a-failed-execution.md) para saber como diagnosticar o que deu errado.
---
## Verificar o progresso durante uma execução
O modo autônomo exibe um banner de progresso antes de cada fase:
```text
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
```
Se você precisar verificar onde a execução está no meio da sessão, abra outro terminal e execute:
```bash
/gsd-progress
```
---
## Retomar após uma parada
Se o modo autônomo parar — seja porque você escolheu "Stop autonomous mode" no prompt de bloqueio, ou a sessão foi interrompida — retome de onde parou:
```bash
/gsd-autonomous --from 4 # substitua 4 pelo número da primeira fase incompleta
```
O GSD ignora automaticamente as fases já concluídas, portanto é seguro executar novamente a partir de um número de fase anterior caso não tenha certeza de onde a execução parou.
---
## Relacionados
- [Executar uma fase](execute-a-phase.md)
- [Depurar uma execução com falha](debug-a-failed-execution.md)
- [Comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)

159
docs/pt-BR/how-to/set-up-cross-ai-review.md Normal file
View File

@@ -0,0 +1,159 @@
# Como configurar a revisão entre diferentes IAs
**Objetivo:** Configurar quais revisores de IA participam da revisão de planos, executar uma revisão de uma fase planejada e usar o feedback para convergir para um plano sem preocupações de severidade ALTA.
**Pré-requisitos:** A fase foi planejada (os arquivos `{phase}-PLAN.md` existem em `.planning/phases/`). Pelo menos um CLI de IA externo está instalado e autenticado.
---
## Decidir quais revisores usar
O GSD Core pode encaminhar solicitações de revisão para qualquer combinação de: Gemini CLI, Claude (sessão separada), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio e llama.cpp.
Cada revisor executa o mesmo prompt estruturado contra seus arquivos `PLAN.md` de forma independente. Como diferentes modelos têm diferentes pontos cegos, o consenso de múltiplos revisores detecta mais problemas do que qualquer revisor individual.
**Se você ainda não tem CLIs externos instalados**, instale pelo menos um:
```bash
# Gemini CLI (gratuito com credenciais Google)
npm install -g @google/gemini-cli
# Antigravity CLI (gratuito com credenciais Google)
curl -fsSL https://antigravity.google/cli/install.sh | bash
# Codex CLI
npm install -g @openai/codex
```
---
## Definir revisores padrão (opcional)
Por padrão, `/gsd-review` executa todos os CLIs detectados. Para fixar um subconjunto como padrões do projeto:
```bash
/gsd-config --integrations
```
O assistente de integrações cobre chaves de API, roteamento de CLIs para revisão de código e a lista `review.default_reviewers`. Defina a lista com os revisores que você deseja como padrão sem flags — por exemplo `["gemini","codex"]`.
Como alternativa, defina diretamente com `gsd-tools`:
```bash
gsd config-set review.default_reviewers '["gemini","codex"]'
```
Para o esquema completo de configurações de integração (chaves de API, substituições de modelo por revisor, endereços de servidor local), consulte [Configuração](../CONFIGURATION.md).
---
## Executar uma revisão
### Revisão padrão (usa seus padrões configurados ou todos os CLIs detectados)
```bash
/gsd-review --phase 3
```
O GSD invoca cada revisor em sequência, coleta feedback estruturado (Resumo, Pontos Fortes, Preocupações em ALTA/MÉDIA/BAIXA, Sugestões, Avaliação de Risco) e grava a saída combinada em `.planning/phases/03-.../03-REVIEWS.md`.
### Selecionar um único revisor para uma execução pontual
```bash
/gsd-review --phase 3 --gemini
/gsd-review --phase 3 --codex
/gsd-review --phase 3 --cursor
```
Qualquer flag explícita substitui tanto o padrão `--all` quanto `review.default_reviewers` para aquela execução.
### Executar todos os revisores disponíveis em paralelo
```bash
/gsd-review --phase 3 --all
```
`--all` sempre substitui a configuração e executa o conjunto completo detectado, incluindo quaisquer servidores de modelos locais configurados (Ollama, LM Studio, llama.cpp).
### Revisores com servidor de modelo local
Se você executa Ollama ou LM Studio localmente, eles são incluídos automaticamente com `--all` quando o servidor está acessível. Você também pode direcioná-los explicitamente:
```bash
/gsd-review --phase 3 --ollama
/gsd-review --phase 3 --lm-studio
```
Configure os endereços de host e a seleção de modelo nas chaves `review.*` via `/gsd-config --integrations` se os padrões (`localhost:11434` / `localhost:1234`) não se aplicarem.
---
## Ler a saída da revisão
O arquivo `{padded_phase}-REVIEWS.md` contém:
- Revisões individuais de cada revisor com preocupações classificadas por severidade
- Uma seção de **Resumo de Consenso** que sintetiza preocupações levantadas por dois ou mais revisores — comece aqui para obter o sinal de maior prioridade
- Uma seção de **Visões Divergentes** para áreas onde os revisores discordaram
---
## Incorporar o feedback ao plano
Após revisar a saída, replaneje incorporando o feedback:
```bash
/gsd-plan-phase 3 --reviews
```
O planejador lê `REVIEWS.md` e ajusta os planos para endereçar as preocupações antes de salvar.
---
## Automatizar o ciclo planejar–revisar–replanejar
Para fases em que você deseja iterar até que todas as preocupações de severidade ALTA sejam resolvidas, use o ciclo de convergência:
```bash
/gsd-plan-review-convergence 3
```
Isso executa `plan-phase → review → replan → re-review` por até três ciclos (padrão). O ciclo termina quando a contagem de preocupações ALTAS chega a zero.
### Convergência com um revisor específico
```bash
/gsd-plan-review-convergence 3 --codex
/gsd-plan-review-convergence 3 --gemini
```
### Convergência com todos os revisores e um limite maior de ciclos
```bash
/gsd-plan-review-convergence 3 --all --max-cycles 5
```
**Detecção de estagnação:** se a contagem de preocupações ALTAS não estiver diminuindo entre os ciclos, o GSD avisa você. Quando o limite de ciclos é atingido com preocupações ALTAS em aberto, um portão de escalação pergunta se você deseja prosseguir ou revisar manualmente.
---
## Condicionais: quais revisores escolher
| Situação | Abordagem recomendada |
|-----------|---------------------|
| Você já tem o Gemini CLI instalado | `--gemini` é sempre um bom revisor inicial |
| Você quer cobertura gratuita com múltiplos revisores | `--gemini` + `--agy` (ambos usam credenciais Google) |
| Seu projeto é fortemente baseado em OpenAI | adicione `--codex` para uma perspectiva de modelo OpenAI |
| Você quer o modelo do GitHub Copilot | adicione `--opencode` |
| Você quer evitar custos de API completamente | configure o Ollama com um modelo local e use `--ollama` |
| Você precisa de cobertura máxima antes de um lançamento | `/gsd-plan-review-convergence N --all` |
| Você está iterando rapidamente e quer feedback rápido | escolha um CLI: `/gsd-review --phase N --gemini` |
---
## Relacionados
- [Verificar e publicar](verify-and-ship.md)
- [Configuração](../CONFIGURATION.md)
- [Comandos](../COMMANDS.md)
- [Índice da documentação](../README.md)

160
docs/pt-BR/how-to/spike-and-sketch.md Normal file
View File

@@ -0,0 +1,160 @@
# Como fazer spike e sketch antes de se comprometer
**Objetivo:** Reduzir riscos de implementação por meio de experimentos de viabilidade focados (spikes) e exploração de direções visuais com maquetes HTML descartáveis (sketches) antes de se comprometer com uma fase em uma abordagem específica.
**Pré-requisitos:** Nenhum. `/gsd-spike` e `/gsd-sketch` criam seus próprios diretórios de armazenamento e não exigem um projeto GSD inicializado.
---
## Decida: spike, sketch ou ambos
| Você quer responder… | Use |
|---|---|
| "Essa abordagem técnica vai funcionar de verdade?" | `/gsd-spike` |
| "Este layout / interação / tratamento visual parece certo?" | `/gsd-sketch` |
| "Qual é a abordagem técnica correta e como ela deve parecer?" | Ambos, em ordem: spike primeiro, depois sketch |
Spikes respondem perguntas binárias de viabilidade com código executável e um veredicto VALIDATED / INVALIDATED / PARTIAL. Sketches respondem perguntas visuais com 2 a 3 variantes HTML comparáveis no navegador. Eles são complementares — um spike prova que a abordagem é construível, um sketch prova que o design vale a pena construir.
---
## Executar um spike
### Coleta interativa (padrão)
```bash
/gsd-spike
```
GSD pergunta sobre a questão técnica, a decompõe em 2 a 5 experimentos independentes estruturados como hipóteses **Given / When / Then**, e solicita confirmação antes de construir.
### Fornecer a ideia diretamente
```bash
/gsd-spike "can we stream LLM tokens through SSE"
```
### Pular a coleta e executar imediatamente
```bash
/gsd-spike --quick "websocket vs SSE latency"
```
`--quick` ignora a conversa de decomposição e trata o argumento como uma única pergunta de spike. Use isso quando a pergunta já for específica o suficiente para executar sem refinamento.
### O que cada experimento produz
Cada spike em `.planning/spikes/NNN-descriptive-name/` inclui:
- Código funcional (não pseudocódigo)
- Uma hipótese **Given / When / Then** escrita antes de qualquer código
- Um rastro de investigação documentando casos extremos, pivôs e surpresas
- Um veredicto **VALIDATED**, **INVALIDATED** ou **PARTIAL** com evidências
- Um `README.md` com frontmatter, instruções de como executar e resultados
Todos os spikes são indexados em `.planning/spikes/MANIFEST.md`.
### Empacotar os resultados
Quando você tiver um sinal, empacote os resultados em uma skill local do projeto para que sessões futuras os carreguem automaticamente:
```bash
/gsd-spike --wrap-up
```
Isso grava em `.claude/skills/spike-findings-[project]/`. A skill é descoberta automaticamente e carregada por execuções subsequentes de `/gsd-sketch`, `/gsd-ui-phase` e `/gsd-plan-phase` — você não precisa referenciá-la explicitamente.
---
## Executar um sketch
### Coleta de mood (padrão)
```bash
/gsd-sketch
```
GSD abre uma conversa breve para explorar sensação, referências visuais e a ação principal do usuário antes de qualquer código ser escrito. Faz uma pergunta por vez e só começa a construir quando você diz para ir.
### Fornecer uma direção de design diretamente
```bash
/gsd-sketch "dashboard layout"
```
### Pular a coleta de mood e executar imediatamente
```bash
/gsd-sketch --quick "sidebar navigation"
```
`--quick` ignora completamente a conversa de coleta e usa o argumento como direção de design.
### Runtimes não-Claude (Codex, Gemini CLI, etc.)
```bash
/gsd-sketch --text "onboarding flow"
```
`--text` substitui prompts interativos por listas numeradas em texto simples. Use isso quando seu runtime não suporta `AskUserQuestion`.
### O que cada sketch produz
Cada sketch em `.planning/sketches/NNN-descriptive-name/` inclui:
- `index.html` com 2 a 3 variantes acessíveis via navegação por abas — abra diretamente no navegador, sem etapa de build
- Elementos interativos funcionais (hover, clique, transições)
- Conteúdo realista usando nomes de campos e formatos de dados de qualquer resultado de spike anterior
- Variáveis CSS compartilhadas de `.planning/sketches/themes/default.css`
- Um `README.md` com a pergunta de design, variantes e o que observar
Todos os sketches são indexados em `.planning/sketches/MANIFEST.md`.
### Empacotar as decisões de design vencedoras
Após escolher uma variante, capture as decisões visuais em uma skill local do projeto:
```bash
/gsd-sketch --wrap-up
```
Isso grava em `.claude/skills/sketch-findings-[project]/`. A skill é carregada automaticamente por `/gsd-ui-phase` — decisões pré-validadas (layout, paleta de cores, tipografia, espaçamento) são tratadas como bloqueadas e não serão solicitadas novamente.
---
## Fluxo combinado: spike → sketch → fase
Esta é a sequência recomendada quando você está incerto tanto sobre a viabilidade técnica quanto sobre a direção visual:
```bash
/gsd-spike "SSE vs WebSocket for real-time feed"
/gsd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
```
Os resultados do spike informam o sketch (formatos de dados reais, estados de interação reais, restrições realistas). Ambos os wrap-ups persistem decisões que o planejador e o pesquisador de UI carregam automaticamente, portanto você não precisa re-explicar escolhas durante `/gsd-discuss-phase` ou `/gsd-ui-phase`.
---
## Como um spike ou sketch alimenta uma fase
Artefatos de spike e sketch não precisam ser referenciados manualmente. GSD os lê automaticamente em dois pontos:
1. **`/gsd-sketch`** — carrega `.claude/skills/spike-findings-*/` antes de construir maquetes, para que as variantes reflitam restrições comprovadas (estados de streaming, nomes de campos reais, etc.)
2. **`/gsd-ui-phase N`** — carrega `.claude/skills/sketch-findings-*/` antes de gerar o contrato de design de UI; decisões de design pré-validadas são tratadas como bloqueadas
O planejador também lê os resultados do spike quando uma skill `spike-findings-*` está presente, de modo que escolhas técnicas validadas (qual biblioteca, qual protocolo, qual formato de dados) fluem diretamente para os planos de tarefas sem explicação repetida.
---
## Relacionados
- [Projetar uma fase de UI](design-a-ui-phase.md)
- [Planejar uma fase](plan-a-phase.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

120
docs/pt-BR/how-to/update-gsd.md Normal file
View File

@@ -0,0 +1,120 @@
# Como atualizar o GSD Core
Atualize uma instalação existente do GSD Core para a versão mais recente, visualize o changelog antes de confirmar e recupere personalizações locais que a atualização sobrescreveria.
**O que você precisa:** O mesmo ambiente de execução para o qual o GSD está instalado. O comando de atualização re-executa o instalador internamente, portanto requer Node.js e npx disponíveis (mesmos requisitos da instalação original).
---
## O caminho padrão de atualização
De dentro do seu ambiente de execução de IA, execute:
```bash
/gsd-update
```
O GSD irá:
1. Detectar a versão instalada e o escopo da instalação (global ou local).
2. Verificar no npm a versão mais recente do `@opengsd/gsd-core`.
3. Buscar o changelog e exibir o que mudou entre sua versão instalada e a mais recente.
4. Solicitar confirmação antes de alterar qualquer coisa.
5. Fazer backup de quaisquer arquivos adicionados pelo usuário encontrados dentro de diretórios gerenciados pelo GSD para `gsd-user-files-backup/`.
6. Executar o instalador (`npx @opengsd/gsd-core@latest --<runtime> --<scope>`).
7. Limpar o cache de verificação de atualização para que o indicador na barra de status seja redefinido.
8. Informar se arquivos GSD modificados localmente foram copiados para `gsd-local-patches/`.
Reinicie seu ambiente de execução após a atualização para carregar os novos comandos e agentes.
---
## Flags
| Flag | O que faz |
|------|-----------|
| `--sync` | Após atualizar, sincroniza habilidades do registro GSD |
| `--reapply` | Após atualizar, mescla arquivos GSD modificados localmente de volta a partir de `gsd-local-patches/` |
```bash
/gsd-update --sync # Update and sync skills
/gsd-update --reapply # Update and reapply local patches
```
---
## Revisando o changelog antes de atualizar
`/gsd-update` sempre exibe o diff do changelog entre sua versão instalada e a mais recente *antes* de solicitar confirmação. Não é necessário acessar o GitHub separadamente. A saída tem a seguinte aparência:
```text
## GSD Update Available
Installed: 1.39.0
Latest: 1.41.0
### What's New
────────────────────────────────────────────────────────────
[changelog entries for 1.40.0 and 1.41.0]
────────────────────────────────────────────────────────────
Proceed with update? [Yes, update now / No, cancel]
```
Se o changelog não puder ser obtido (sem acesso à rede, falha no npm), a atualização ainda prossegue após a confirmação — ela não é bloqueada pela disponibilidade do changelog.
---
## Recuperando personalizações locais
### Arquivos que você adicionou dentro de diretórios gerenciados pelo GSD
Se você colocou arquivos personalizados dentro de diretórios que o GSD gerencia (por exemplo, agentes personalizados com o prefixo `gsd-` ou arquivos extras em `commands/gsd/`), o instalador os detectará e os copiará para `gsd-user-files-backup/` antes de limpar esses diretórios. Após a atualização, restaure-os manualmente a partir desse local de backup.
Arquivos colocados fora de diretórios gerenciados pelo GSD — agentes personalizados sem o prefixo `gsd-`, comandos personalizados fora de `commands/gsd/`, seus arquivos `CLAUDE.md` e hooks personalizados — nunca são tocados pelo instalador.
### Arquivos GSD que você modificou diretamente
Se você editou um arquivo instalado pelo GSD (por exemplo, ajustando o prompt de sistema de um agente), o instalador detecta a modificação por meio de uma comparação de hash com seu manifesto, faz backup do arquivo em `gsd-local-patches/` e, em seguida, o substitui pela nova versão. Após a atualização:
```bash
/gsd-update --reapply
```
Esse comando mescla suas modificações de `gsd-local-patches/` de volta aos arquivos recém-instalados.
Se você pulou o `--reapply` após uma atualização anterior e deseja aplicar os patches agora:
```bash
/gsd-update --reapply
```
É seguro executar `--reapply` de forma independente sem acionar um novo download — se você já estiver na versão mais recente, o GSD ignora a etapa de instalação e vai direto para a reaplicação dos patches.
---
## Quando o npm está indisponível
Se `npx @opengsd/gsd-core@latest` falhar devido a uma falha no npm, restrições de rede ou porque você está trabalhando a partir do repositório de código-fonte, use o procedimento de atualização manual em [docs/manual-update.md](../../manual-update.md). Esse documento aborda como fazer pull do commit mais recente, compilar o dist dos hooks e executar `node bin/install.js` diretamente.
---
## Se você já está na versão mais recente
`/gsd-update` encerra imediatamente com uma mensagem de confirmação — sem download, sem instalação, sem necessidade de reinicialização.
---
## Migrações do instalador
Cada versão do GSD pode incluir migrações do instalador que renomeiam, movem ou removem arquivos gerenciados. A camada de migração é executada automaticamente antes que o novo payload do pacote seja gravado. Migrações que afetariam arquivos que você modificou solicitam confirmação em vez de agir silenciosamente. Para o design completo e o registro do contrato de configuração de tempo de execução, consulte [docs/installer-migrations.md](../../installer-migrations.md).
---
## Relacionados
- [Instalar no seu ambiente de execução](install-on-your-runtime.md)
- [Referência de comandos](../COMMANDS.md)
- [Atualização manual](../../manual-update.md)
- [Migrações do instalador](../../installer-migrations.md)
- [Índice da documentação](../README.md)

124
docs/pt-BR/how-to/verify-and-ship.md Normal file
View File

@@ -0,0 +1,124 @@
# Como verificar e publicar uma fase
**Objetivo:** Conduzir o trabalho executado pelo processo de testes de aceitação do usuário, diagnosticar e corrigir eventuais falhas e, em seguida, abrir um pull request com o corpo gerado automaticamente.
**Pré-requisitos:** A fase deve ter sido executada e possuir arquivos `SUMMARY.md`. Se a execução ainda não foi concluída, consulte [Executar uma fase](execute-a-phase.md).
---
## Executar os testes de aceitação do usuário
```bash
/gsd-verify-work 1
```
O GSD lê os arquivos `SUMMARY.md` da fase, extrai as entregas observáveis pelo usuário e guia você por elas uma de cada vez. Para cada ponto de verificação, ele apresenta o que *deveria* acontecer e pergunta se a realidade corresponde.
- `yes` / `y` / vazio → aprovado, avança para o próximo teste
- Qualquer outra coisa → registrado como um problema; a severidade é inferida a partir da sua descrição
Você nunca precisa categorizar a severidade — o GSD a infere a partir das suas palavras ("trava" → bloqueador, "não funciona" → grave, "está estranho" → cosmético).
O progresso é gravado em `.planning/phases/01-<name>/01-UAT.md` e sobrevive a um `/clear`. Se uma sessão for interrompida, execute novamente `/gsd-verify-work 1` e o GSD oferece a opção de retomar a partir do último ponto de verificação.
---
## Quando falhas são encontradas: diagnóstico automático e planejamento de correção
Se algum teste reportar problemas, o GSD prossegue automaticamente:
1. **Diagnostica as causas raiz** — cria agentes de depuração paralelos, um por problema, e atualiza o `UAT.md` com as causas raiz.
2. **Planeja o fechamento das lacunas** — cria um `gsd-planner` no modo de fechamento de lacunas, que lê o `UAT.md` (com os diagnósticos) e escreve novos arquivos `PLAN.md`.
3. **Verifica os planos de correção** — cria um `gsd-plan-checker` para garantir que os planos são executáveis. Se problemas forem encontrados, o planner e o checker iterarão até três vezes.
4. **Apresenta o próximo passo** — quando os planos passam pelo checker:
```
Plans verified and ready for execution.
`/clear` then `/gsd-execute-phase 1 --gaps-only`
```
Execute o comando sugerido para aplicar as correções e, em seguida, execute novamente `/gsd-verify-work 1` para confirmar que tudo passa.
---
## Quando todos os testes passam: publicar a fase
Quando todos os testes de aceitação passam (ou se esta é a primeira execução e nenhum problema é encontrado), a fase é marcada como concluída em `ROADMAP.md` e `STATE.md` automaticamente.
```bash
/gsd-ship 1
```
O GSD executa verificações de pré-voo (status de verificação, árvore de trabalho limpa, branch, remoto, autenticação da CLI `gh`), envia o branch e cria um PR:
```bash
/gsd-ship 1 # PR pronto para revisão
/gsd-ship 1 --draft # PR em rascunho — útil quando mais fases virão a seguir
```
O corpo do PR é montado automaticamente a partir dos artefatos de planejamento:
- Objetivo da fase em `ROADMAP.md`
- Resumos por plano dos arquivos `SUMMARY.md` e seus arquivos principais
- Requisitos atendidos (REQ-IDs)
- Status de verificação em `VERIFICATION.md`
- Decisões-chave em `STATE.md`
Não é necessário escrever o corpo manualmente.
---
## Opcional: revisão de código antes ou depois de publicar
`/gsd-ship` não executa uma revisão de código automaticamente, mas você pode incluir uma a qualquer momento:
**Antes da verificação** (identifica problemas antes dos testes de aceitação):
```bash
/gsd-code-review 1 # Revisão padrão
/gsd-code-review 1 --fix # Revisão com correção automática de achados Críticos + Avisos
```
**Depois que o PR estiver aberto** (para controlar a qualidade antes do merge):
```bash
/gsd-code-review 1 --depth=deep # Análise entre arquivos incluindo grafos de importação
```
Consulte [Configurar revisão entre IAs](set-up-cross-ai-review.md) para configurar o Gemini, Codex ou outros revisores para revisão de planos mais cedo no ciclo.
---
## Opcional: criar um branch de PR limpo
Se o seu branch contiver commits de `.planning/` que você não quer que os revisores vejam:
```bash
/gsd-pr-branch # Filtrar contra main
/gsd-pr-branch develop # Filtrar contra develop
```
`/gsd-pr-branch` cria um novo branch apenas com mudanças de código — commits de artefatos de planejamento são excluídos. Execute antes de `/gsd-ship` se a política de revisão da sua equipe exclui ruído de planejamento.
---
## Encerrando um marco
Se esta foi a última fase do marco, execute a auditoria do marco e arquive-o:
```bash
/gsd-audit-milestone # Verificar se todos os requisitos foram entregues
/gsd-complete-milestone # Arquivar, criar tag git
```
`/gsd-complete-milestone` é o próximo passo natural após o merge do PR. Consulte [O ciclo de fases](../explanation/the-phase-loop.md) para entender como a verificação e a publicação se encaixam no ciclo de vida completo do projeto.
---
## Relacionados
- [Executar uma fase](execute-a-phase.md)
- [Configurar revisão entre IAs](set-up-cross-ai-review.md)
- [O ciclo de fases](../explanation/the-phase-loop.md)
- [Comandos](../COMMANDS.md)

157
docs/pt-BR/how-to/work-in-parallel-with-workstreams.md Normal file
View File

@@ -0,0 +1,157 @@
# Como trabalhar em múltiplas áreas em paralelo com workstreams
**Objetivo:** Executar trabalho simultâneo em diferentes áreas de um milestone — API backend, painel frontend, infraestrutura ou qualquer outra preocupação — sem que o estado de planejamento de uma área vaze para outra.
**Pré-requisitos:** Um projeto GSD Core ativo (`.planning/ROADMAP.md` existe). Se não existir, execute `/gsd-new-project` primeiro.
---
## O que são workstreams
Um workstream é um contexto de planejamento isolado dentro de um único repositório de código. Cada workstream possui seu próprio subárvore `.planning/workstreams/<name>/` contendo diretórios independentes `STATE.md`, `ROADMAP.md`, `REQUIREMENTS.md` e `phases/`. O próprio repositório — código-fonte, histórico git e branches — é compartilhado entre todos os workstreams.
```
.planning/
├── PROJECT.md ← compartilhado
├── config.json ← compartilhado
├── codebase/ ← compartilhado
└── workstreams/
├── backend-api/
│ ├── STATE.md
│ ├── ROADMAP.md
│ ├── REQUIREMENTS.md
│ └── phases/
└── frontend-dash/
├── STATE.md
├── ROADMAP.md
├── REQUIREMENTS.md
└── phases/
```
Quando um workstream está ativo, todos os comandos GSD — `/gsd-progress`, `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase` — leem e escrevem no diretório desse workstream. Alternar workstreams redireciona todos esses comandos para uma subárvore diferente sem tocar na árvore de código-fonte.
---
## Criar um workstream
```bash
/gsd-workstreams create backend-api
```
O GSD cria o diretório do workstream em `.planning/workstreams/backend-api/` e o inicializa com um `STATE.md` e `ROADMAP.md` esqueleto. O workstream não é ativado automaticamente — você precisa alternar para ele explicitamente.
---
## Listar workstreams
```bash
/gsd-workstreams list
```
Exibe todos os workstreams e qual está atualmente ativo na sua sessão.
---
## Alternar para um workstream
```bash
/gsd-workstreams switch backend-api
```
A partir deste ponto, todos os comandos de fluxo de trabalho GSD operam no contexto `backend-api`. A alternância é vinculada à sessão: quando múltiplos terminais do Claude Code estão abertos no mesmo repositório, cada sessão pode ter um workstream ativo diferente sem interferir nos demais.
Após alternar, execute o fluxo normal de fases:
```bash
/gsd-discuss-phase 1
/gsd-plan-phase 1
/gsd-execute-phase 1
/gsd-verify-work 1
```
Para trabalhar em outra área, alterne workstreams em um segundo terminal:
```bash
/gsd-workstreams switch frontend-dash
/gsd-discuss-phase 1
/gsd-plan-phase 1
```
---
## Verificar o progresso em todos os workstreams
```bash
/gsd-workstreams progress
```
Exibe um resumo entre workstreams — status das fases, posição atual e trabalho pendente para cada workstream — sem exigir que você alterne entre eles.
Para status detalhado de um único workstream:
```bash
/gsd-workstreams status backend-api
```
---
## Retomar o trabalho em um workstream
Após uma redefinição de contexto ou uma nova sessão, restaure sua posição:
```bash
/gsd-workstreams resume backend-api
```
Isso ativa o workstream e restaura sua última posição conhecida dentro dele, equivalente a alternar e então executar `/gsd-resume-work`.
---
## Arquivar um workstream concluído
Quando o trabalho do milestone de um workstream estiver concluído:
```bash
/gsd-workstreams complete backend-api
```
O GSD marca o workstream como arquivado e o remove da listagem ativa. Os artefatos de planejamento são preservados em `.planning/workstreams/backend-api/` para fins de auditoria.
---
## Executar um único comando em um workstream sem alternar
Se você precisar executar um comando em um workstream específico sem alterar o contexto ativo da sua sessão, use a flag `--ws`:
```bash
/gsd-progress --ws frontend-dash
/gsd-plan-phase 2 --ws backend-api
```
`--ws` tem a maior prioridade na ordem de resolução e não altera o ponteiro vinculado à sessão.
---
## Quando usar workstreams em vez de workspaces
Escolha workstreams quando:
- Todo o trabalho está no **mesmo repositório** e compartilha o mesmo histórico git
- Você quer planejar ou discutir diferentes áreas de preocupação (API, UI, infra) **de forma simultânea** sem que o `STATE.md` de um workstream sobrescreva o de outro
- Você não precisa de um branch separado por workstream no momento da criação (embora possa criar branches normalmente dentro da execução de cada workstream)
- O custo de criação de worktrees git completos não é justificado pelo nível de isolamento necessário
Escolha [workspaces](isolate-work-with-workspaces.md) quando:
- Você está trabalhando em **múltiplos repositórios** (por exemplo, `hr-ui` e `ZeymoAPI`)
- Você precisa do isolamento de uma **worktree ou clone git separado** por funcionalidade — branches, arquivos de lock e artefatos de build totalmente independentes
- Você quer executar `/gsd-new-project` independentemente em cada workspace com uma raiz `.planning/` completamente separada, não um subdiretório do `.planning/` do repositório principal
---
## Relacionados
- [Isolar trabalho com workspaces](isolate-work-with-workspaces.md)
- [O ciclo de fases](../explanation/the-phase-loop.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

191
docs/pt-BR/issue-driven-orchestration.md Normal file
View File

@@ -0,0 +1,191 @@
# Orquestração Orientada a Issues com o GSD
**Status:** guia de fluxo de trabalho estável
**Público:** desenvolvedores que rastreiam trabalho no GitHub Issues, Linear, Jira ou
sistemas similares de rastreamento de issues e querem conduzir a implementação
assistida por IA através dos primitivos existentes do GSD.
## O que é este guia
Uma receita para combinar comandos que o GSD já inclui em um loop
rastreador de issues → workspace → planejar/executar → verificar/revisar → PR.
É documentação somente. Sem novos comandos, sem daemon, sem integração com
rastreador — cada comando referenciado abaixo já existe no GSD hoje.
O formato é inspirado pela referência de orquestração open-source [Symphony da
OpenAI](https://openai.com/index/open-source-codex-orchestration-symphony/)
([repositório](https://github.com/openai/symphony)). O GSD não vende nem
encapsula o Symphony. Os *conceitos* de orquestração se mapeiam claramente
nos primitivos que o GSD já expõe; este guia apenas descreve esse mapeamento
para que você possa adotar o padrão sem escrever código de integração ou
contornar os controles de segurança do GSD.
## Por que isso existe
O GSD tem os blocos de construção para desenvolvimento de IA orientado a issues —
`/gsd-workspace --new`, `/gsd-manager`, `/gsd-autonomous`, `/gsd-verify-work`,
`/gsd-review`, `/gsd-ship`, além de `STATE.md` e o conjunto de artefatos de fase
— mas não havia um guia que mostrasse como conduzir tudo isso a partir de uma
única issue do rastreador sem escrever scripts de orquestração personalizados.
Sem esse guia, os modos de falha são:
- Subutilização: desenvolvedores executam discuss/plan/execute manualmente e
nunca recorrem a `/gsd-manager` ou `/gsd-autonomous`, mesmo quando seu padrão
de trabalho se encaixa.
- Scripts alternativos: desenvolvedores criam loops de shell ad-hoc entre seu
rastreador e invocações de `claude`, contornando `STATE.md`, o manifesto de
fases e os controles de verificação.
Este guia torna o loop canônico descobrível.
## Mapeamento de conceitos
Cada linha mapeia um conceito de orquestração no estilo Symphony para o
primitivo do GSD que já o serve. Use esta tabela como chave de tradução ao
ler documentações do Symphony, posts de blog ou descrições de orquestração
de terceiros.
| Conceito Symphony | Primitivo GSD |
|---|---|
| `WORKFLOW.md` (intenção de alto nível) | `ROADMAP.md` (intenção do projeto), `STATE.md` (status em tempo real), `CONTEXT.md` de fase (escopo por fase), `PLAN.md` de fase (etapas executáveis) |
| Um workspace isolado de agente por tarefa | `/gsd-workspace --new --strategy worktree` |
| Despacho e concorrência de agentes | `/gsd-manager` (painel interativo), `/gsd-autonomous` (sem supervisão) |
| Etapas de discussão e planejamento por fase | `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase` |
| Prova de trabalho / evidência de testes | `/gsd-verify-work` (UAT.md persistido entre `/clear`) |
| Revisão adversarial | `/gsd-review` (revisão por pares entre IAs do plano) |
| Controle humano de merge | `/gsd-ship` (cria PR, revisão de código opcional, prepara merge) |
| Captura de trabalho subsequente | `/gsd-capture`, `/gsd-capture --seed`, `/gsd-new-milestone`, ou uma issue aberta manualmente no rastreador |
| Controle de concorrência | Semântica de agente gerenciador / segundo plano (sem poller sempre ativo) |
O mapeamento é unidirecional: o GSD é responsável pelos controles de segurança
(verificação, revisão humana, confirmação explícita para criação de trabalho
subsequente). O enquadramento de "orquestração contínua" do Symphony é
intencionalmente não adotado — veja [Não-objetivos](#não-objetivos).
## Fluxo completo
O loop canônico issue → PR, escrito para poder ser executado a partir de uma
única issue do rastreador de ponta a ponta. Substitua os marcadores entre
colchetes antes de executar.
1. **Escolha a issue do rastreador.** Selecione uma issue do seu rastreador
(GitHub, Linear, etc.) com escopo suficientemente bem definido para
implementação autônoma — escopo delimitado, critérios de aceitação
observáveis, sem dependências upstream que bloqueiem a execução.
2. **Mapeie para uma fase do GSD.** Se a issue se mapear para uma fase
existente em `ROADMAP.md`, selecione-a. Caso contrário, execute
`/gsd-new-milestone` (para um novo marco de issues relacionadas) ou abra
uma fase via `/gsd-phase` / `/gsd-phase --insert`. Capture a URL da issue
do rastreador no `CONTEXT.md` da fase para que a rastreabilidade sobreviva
à compactação.
3. **Crie um workspace isolado.** Execute
`/gsd-workspace --new --strategy worktree <slug>` para criar uma git
worktree com um diretório `.planning/` independente. A worktree é o limite
de segurança: qualquer exploração, commits parciais ou planos abandonados
ficam fora do `main`.
4. **Execute discuss → plan → execute através do GSD.** De dentro do
workspace, execute `/gsd-discuss-phase` para esclarecer ambiguidades,
`/gsd-plan-phase` para produzir `PLAN.md`, e `/gsd-manager`
(painel interativo) ou `/gsd-execute-phase` / `/gsd-autonomous`
(sem supervisão) para implementar. Evite conduzir invocações brutas de
`claude` de fora do GSD — isso contorna as atualizações de `STATE.md`
e o manifesto de fases.
5. **Exija prova de trabalho.** Execute `/gsd-verify-work` para conduzir o
usuário pelo UAT em relação aos critérios de aceitação da fase. Testes,
capturas de tela, registros de log e diffs de configuração são todos
gravados em `UAT.md`, que persiste entre `/clear` e alimenta lacunas no
`/gsd-plan-phase --gaps` quando a verificação revela escopo não coberto.
6. **Passe pelos controles de revisão e envio.** Execute `/gsd-review` para
obter revisão por pares adversarial do plano por IAs independentes (detecta
pontos cegos modelo a modelo), depois `/gsd-ship` para abrir o PR com um
corpo rico montado a partir dos artefatos de planejamento. Ambos os
controles exigem uma decisão humana antes de qualquer coisa chegar ao
repositório remoto.
7. **Capture trabalho subsequente explicitamente.** Use `/gsd-capture` para
notas inline, `/gsd-capture --seed` para ideias que valem uma fase futura,
ou `/gsd-new-milestone` para um grupo coerente de trabalhos subsequentes.
Criar uma issue no rastreador a partir de um trabalho subsequente
descoberto requer confirmação explícita do usuário — o GSD não publica em
rastreadores remotos automaticamente.
Quando o PR é mesclado, o loop se fecha. Palavras-chave de fechamento
automático no corpo do PR (`Closes #NNN` / `Fixes #NNN`) fecham a issue do
rastreador no momento do merge.
## Limites de segurança
O loop é seguro porque quatro invariantes se mantêm por construção:
- **Worktrees isoladas.** Cada issue roda em uma worktree de
`/gsd-workspace --new`, para que trabalho parcial, planos abandonados e
commits exploratórios nunca toquem o `main`. `gsd-local-patches/` é a
superfície de recuperação se edições manuais de uma worktree precisarem
voltar após uma atualização.
- **Revisão humana explícita.** `/gsd-review` e `/gsd-ship` ambos param para
aprovação humana. Não há auto-merge e nenhum caminho de auto-PR a partir
da execução. Se você quiser remover o controle humano para um repositório
específico, essa é a sua decisão de política de proteção de branch /
fila de merge — não algo que o GSD decide por você.
- **Nenhuma publicação automática.** O GSD nunca abre, comenta ou fecha uma
issue do rastreador sem um comando explicitamente iniciado pelo usuário.
A captura de trabalho subsequente padrão são artefatos locais (notas,
seeds, marcos); empurrar de volta para o rastreador é uma etapa manual
separada.
- **Verificação antes do envio.** O `UAT.md` do `/gsd-verify-work` deve
registrar evidências antes que `/gsd-ship` seja executado. A disciplina
recomendada é tratar `verification_failed` como um bloqueador mesmo quando
a implementação parece correta — a falha geralmente revela um critério de
aceitação perdido, não um teste instável.
Se qualquer um desses invariantes for contornado (ex: executar `claude`
diretamente na worktree, pular `/gsd-verify-work`, ou criar issues via a API
do rastreador sem confirmação do usuário), as garantias deste guia não se
aplicam.
## Não-objetivos
Este guia deliberadamente **não** propõe nada do seguinte. Eles estão listados
aqui para que futuros contribuidores não voltem a discuti-los em revisão de
código:
- **Sem venda ou cópia do código Symphony.** O GSD reutiliza seus próprios
primitivos. O mapeamento acima é conceitual; nenhum código derivado do
Symphony está incluído neste repositório.
- **Sem daemon de longa execução.** O GSD não faz polling no GitHub ou Linear.
Os fluxos de trabalho de manager e autonomous lidam com concorrência através
da semântica de agente em segundo plano, não de um daemon.
- **Sem dependência obrigatória de rastreador.** O loop funciona sem qualquer
integração com rastreador. A etapa "issue do rastreador" é uma *entrada
humana* — a URL vai para `CONTEXT.md`. O GSD não tem opinião sobre qual
rastreador você usa, ou se você usa algum.
- **Sem contorno dos controles de verificação, revisão ou decisão humana.**
Mesmo ao executar `/gsd-autonomous`, os controles de verificação e revisão
ainda disparam. O rótulo "autonomous" se refere à progressão de fase a fase,
não ao pulo da aprovação humana.
- **Sem expansão da superfície padrão de habilidades / comandos.** Cada
comando referenciado neste guia já existe. Este guia é uma superfície de
documentação, não uma superfície de funcionalidades.
## Possível trabalho subsequente
Se a experiência dos mantenedores com esse loop justificar, uma melhoria
aprovada poderá adicionar posteriormente uma ponte *mínima* com rastreadores:
- Importar uma issue do GitHub ou Linear para um workspace / fase do GSD.
- Exportar evidências de `UAT.md` como comentário na issue de origem.
- Gerar issues de trabalho subsequente no rastreador a partir da saída de
`/gsd-capture --seed`.
Cada uma dessas seria sua própria proposta de melhoria, pois cada uma adiciona
superfície de integração e carga de manutenção contínua. Elas estão fora do
escopo deste guia.
## Relacionados
- [O loop de fase](explanation/the-phase-loop.md) — como discuss → plan → execute → verify → ship se encaixam como um ciclo repetitivo.
- [Como trabalhar com workspaces](how-to/work-in-parallel-with-workstreams.md) — guia passo a passo para criar e gerenciar worktrees paralelas.
- [Índice de documentação](README.md) — sumário completo da documentação do GSD Core.
- [docs/USER-GUIDE.md](./USER-GUIDE.md) — guias orientados a tarefas dos comandos individuais referenciados acima.
- [docs/COMMANDS.md](COMMANDS.md) — referência completa dos comandos `/gsd-*`.
- [docs/FEATURES.md](FEATURES.md) — matriz de capacidades por funcionalidade (workspaces, manager, autonomous, verify, review, ship).
- [docs/ARCHITECTURE.md](ARCHITECTURE.md) — ciclo de vida dos artefatos de fase e mecânica do `STATE.md`.

148
docs/pt-BR/reference/context-md.md Normal file
View File

@@ -0,0 +1,148 @@
# Referência do esquema CONTEXT.md
Um `CONTEXT.md` por fase é o mecanismo do GSD Core para capturar decisões de implementação durante `/gsd:discuss-phase`. É a principal entrada upstream para os agentes de pesquisa e planejamento. Esta página documenta sua estrutura. Consulte o [índice de documentação](../README.md).
---
## Visão geral
Toda fase que passou pelo fluxo de trabalho de discussão produz um `CONTEXT.md` em:
```
.planning/phases/<NN>-<slug>/<NN>-CONTEXT.md
```
Por exemplo: `.planning/phases/03-post-feed/03-CONTEXT.md`.
O arquivo é produzido por `write_context` em `get-shit-done/workflows/discuss-phase.md` (ou seus caminhos expressos de ingestão de PRD / ADR). Ele nunca é editado manualmente durante a operação normal — o fluxo de trabalho discuss-phase o escreve e os agentes downstream o leem como uma fonte de verdade selada.
---
## Frontmatter
`CONTEXT.md` não possui frontmatter YAML. Os metadados ficam inline no topo do corpo:
```markdown
# Phase [X]: [Name] - Context
**Gathered:** [ISO date]
**Status:** Ready for planning
```
O campo `Status` é sempre `Ready for planning` quando o arquivo é escrito pela primeira vez. Ele não é atualizado após a criação.
---
## Estrutura de blocos
O corpo é dividido em blocos nomeados no estilo XML. Os blocos aparecem em uma ordem fixa e são lidos pelos agentes downstream pelo nome do bloco, não pelo número de linha.
| Bloco | Finalidade | Preenchido por | Consumido por |
|---|---|---|---|
| `<domain>` | Define o limite da fase — o que esta fase entrega e o que está explicitamente fora do escopo. Ancora a barreira de escopo ao longo do planejamento e execução. | `discuss-phase` (do objetivo da fase em ROADMAP.md) | `gsd-planner`, `gsd-plan-checker` (conformidade de escopo) |
| `<spec_lock>` | Presente apenas quando um `*-SPEC.md` foi encontrado pela etapa `check_spec`. Lista contagens de requisitos bloqueados e limites de escopo; os agentes são orientados a ler `SPEC.md` diretamente para requisitos completos. | `discuss-phase` (condicional) | `gsd-planner` (lê SPEC.md em vez de reler os requisitos aqui) |
| `<decisions>` | Decisões de implementação capturadas durante a discussão, identificadas com identificadores `D-NN`. As categorias emergem do que foi realmente discutido, em vez de uma taxonomia fixa. Inclui uma subseção `Claude's Discretion` para áreas que o usuário delegou. | `discuss-phase` (discussão interativa) | `gsd-planner` (decisões bloqueadas devem ser implementadas), `gsd-plan-checker` (conformidade com a Dimensão 7) |
| `<canonical_refs>` | Caminhos relativos completos para cada spec, ADR, documento de funcionalidade ou documento de design relevante para esta fase. Obrigatório — todo CONTEXT.md deve ter esta seção. Os agentes devem ler os arquivos listados antes de planejar ou implementar. | `discuss-phase` (acumulado de refs do ROADMAP.md + referências do usuário durante a discussão + exploração do código) | `gsd-phase-researcher`, `gsd-planner` |
| `<code_context>` | Ativos reutilizáveis, padrões estabelecidos e pontos de integração descobertos durante a etapa `scout_codebase`. Orienta os agentes em direção ao código existente em vez de reimplementar. | `discuss-phase` (exploração do código) | `gsd-planner`, `gsd-phase-researcher` |
| `<specifics>` | Referências concretas do tipo "quero assim", comparações de produtos ou exemplos específicos capturados verbatim durante a discussão. | `discuss-phase` (entrada livre do usuário) | `gsd-planner` |
| `<deferred>` | Ideias que surgiram na discussão mas pertencem a outras fases. Preservadas para não serem perdidas. Inclui uma subseção `Reviewed Todos` quando os todos foram revisados mas não incorporados ao escopo. | `discuss-phase` (redirecionamento de escopo expandido) | Não consumido por agentes automatizados; somente referência humana |
---
## Formato do identificador de decisão
Cada decisão em `<decisions>` carrega um identificador sequencial `D-NN`:
```markdown
### Layout style
- **D-01:** Card-based layout, not timeline or list
- **D-02:** Each card shows: author avatar, name, timestamp, full post content, reaction counts
```
Os identificadores têm escopo por fase. `D-01` na Fase 3 não tem relação com `D-01` na Fase 7. O verificador de planos (Dimensão 7) verifica se cada `D-NN` é atendido por pelo menos uma ação de tarefa nos planos gerados.
---
## Referências canônicas
O bloco `<canonical_refs>` é **obrigatório**. Agentes que o encontram ausente tratam o CONTEXT.md como incompleto e exibem um aviso. As entradas são agrupadas por tópico e contêm um caminho relativo completo mais uma breve declaração do que o arquivo decide ou define:
```markdown
<canonical_refs>
## Canonical References
**Downstream agents MUST read these before planning or implementing.**
### Feed display
- `docs/features/social-feed.md` — Feed requirements, post card fields, engagement display rules
- `docs/decisions/adr-012-infinite-scroll.md` — Scroll strategy decision, virtualisation requirements
### Empty states
- `docs/design/empty-states.md` — Empty state patterns, illustration guidelines
</canonical_refs>
```
Quando um projeto não tem specs externas, a seção declara isso explicitamente:
```
No external specs — requirements fully captured in decisions above
```
Menções inline como "ver ADR-019" espalhadas em `<decisions>` são insuficientes; os agentes precisam do caminho completo na seção dedicada.
---
## Relação com o portão de cobertura de decisões
A **Dimensão 7: Conformidade com o Contexto** do verificador de planos impõe um portão de cobertura após o planejamento:
1. Todo identificador `D-NN` em `<decisions>` deve aparecer em pelo menos um `<action>` ou justificativa de tarefa do plano.
2. Nenhuma tarefa pode implementar algo listado em `<deferred>` (expansão de escopo).
3. Áreas de `Claude's Discretion` são isentas desta verificação — o planejador pode escolher livremente.
Um CONTEXT.md cujas decisões sobrevivem aos planos é considerado conforme. Um CONTEXT.md cujas decisões são silenciosamente descartadas ou parcialmente entregues aciona a **Dimensão 7b: Detecção de Redução de Escopo**, que é sempre um BLOQUEADOR.
---
## Integração com SPEC.md
Quando `/gsd:spec-phase` foi executado antes de discutir uma fase, a etapa `check_spec` encontra o arquivo `*-SPEC.md` e ativa o `<spec_lock>`:
```markdown
<spec_lock>
## Requirements (locked via SPEC.md)
**12 requirements are locked.** See `03-SPEC.md` for full requirements, boundaries, and acceptance criteria.
Downstream agents MUST read `03-SPEC.md` before planning or implementing. Requirements are not duplicated here.
**In scope (from SPEC.md):** [copied from SPEC.md Boundaries]
**Out of scope (from SPEC.md):** [copied from SPEC.md Boundaries]
</spec_lock>
```
Quando `<spec_lock>` está presente, `<decisions>` contém apenas decisões de implementação da discussão — o "como", não o "o quê". Os requisitos não são duplicados entre os dois arquivos.
---
## Rodapé
Todo CONTEXT.md termina com um rodapé de identidade:
```markdown
---
*Phase: XX-name*
*Context gathered: [date]*
```
---
## Relacionados
- [Esquema PLAN.md](plan-md.md)
- [Artefatos de planejamento](planning-artifacts.md)
- [Modos de discussão](../workflow-discuss-mode.md)
- [Índice de documentação](../README.md)

249
docs/pt-BR/reference/plan-md.md Normal file
View File

@@ -0,0 +1,249 @@
# Referência do esquema PLAN.md
Um `PLAN.md` por plano é a unidade executável de trabalho do GSD Core — um documento estruturado que instrui exatamente um agente executor sobre o que construir e como verificar se foi construído corretamente. Esta página documenta sua estrutura. Veja o [índice da documentação](../README.md).
---
## Visão geral
Os planos ficam dentro de diretórios de fase em:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-PLAN.md
```
Por exemplo: `.planning/phases/03-post-feed/03-02-PLAN.md` (Fase 3, Plano 2).
Os planos são produzidos pelo agente `gsd-planner` (disparado por `/gsd:plan-phase`) e consumidos por `execute-phase`. Uma fase normalmente contém entre um e quatro planos; os planos dentro de uma fase são atribuídos a ondas de execução para que trabalhos independentes sejam executados em paralelo.
---
## Frontmatter YAML
Todo PLAN.md começa com um bloco de frontmatter YAML entre delimitadores `---`.
### Exemplo comentado
```yaml
---
phase: 03-post-feed
plan: 02
type: execute
wave: 2
depends_on: ["03-01"]
files_modified:
- src/components/PostFeed.tsx
- src/components/PostCard.tsx
- src/app/feed/page.tsx
autonomous: true
requirements: ["FEED-01", "FEED-03"]
user_setup: []
must_haves:
truths:
- "User can scroll through posts from followed accounts"
- "Each post shows author avatar, name, timestamp, and content"
- "Empty state appears when no posts exist"
artifacts:
- path: "src/components/PostFeed.tsx"
provides: "Scrollable post list"
min_lines: 40
- path: "src/components/PostCard.tsx"
provides: "Individual post card"
exports: ["PostCard"]
key_links:
- from: "src/components/PostFeed.tsx"
to: "/api/feed"
via: "fetch in useEffect"
pattern: "fetch.*api/feed"
---
```
### Referência dos campos de frontmatter
| Campo | Obrigatório | Tipo | Finalidade |
|---|---|---|---|
| `phase` | Sim | string | Identificador da fase, ex.: `03-post-feed`. |
| `plan` | Sim | string | Número do plano dentro da fase, ex.: `02`. |
| `type` | Sim | `execute` ou `tdd` | `execute` para planos padrão; `tdd` para planos orientados a testes, onde os testes são escritos antes da implementação. |
| `wave` | Sim | inteiro | Onda de execução. Planos na onda 1 são executados em paralelo (sem dependências). Planos na onda 2 ou superior aguardam a conclusão de todos os planos da onda anterior. Pré-calculado durante o planejamento pelo `gsd-planner`. |
| `depends_on` | Sim | array de IDs de planos | Planos dos quais este plano depende. Array vazio = onda 1. Exemplo: `["03-01"]` significa que este plano é executado após o Plano 01 da Fase 3. |
| `files_modified` | Sim | array de caminhos | Todos os arquivos que este plano cria ou modifica. Usado pelo verificador de planos para detectar conflitos de arquivos na mesma onda e pelo execute-phase para rastreamento de merge. |
| `autonomous` | Sim | booleano | `true` quando todas as tarefas são do tipo `auto`. `false` quando o plano contém alguma tarefa `checkpoint:*` que requer interação humana. |
| `requirements` | Sim | array de IDs | IDs de requisitos do ROADMAP.md que este plano atende. Todo ID de requisito de fase deve aparecer no campo `requirements` de pelo menos um plano. Arrays vazios são um BLOQUEADOR. |
| `user_setup` | Não | array de objetos | Etapas de configuração de serviços externos que o Claude não pode automatizar (criação de conta, recuperação de segredos, configuração de painel). Quando presente, o execute-phase gera um checklist `USER-SETUP.md` para o desenvolvedor. |
| `must_haves` | Sim | objeto | Critérios de verificação orientados ao objetivo final. Veja abaixo. |
---
## Campo `must_haves`
`must_haves` captura o que deve ser observavelmente verdadeiro para que o objetivo da fase seja alcançado. É derivado durante o planejamento e verificado após a execução pelo agente `gsd-verifier`.
### Sub-campos
| Sub-campo | Tipo | Finalidade |
|---|---|---|
| `truths` | array de strings | Comportamentos observáveis do ponto de vista do usuário. Cada um deve ser verificável. Exemplo: `"User can send a message"`, não `"WebSocket library installed"`. |
| `artifacts` | array de objetos | Arquivos que devem existir com implementação substantiva (não stubs). |
| `artifacts[].path` | string | Caminho do arquivo relativo à raiz do projeto. |
| `artifacts[].provides` | string | Qual capacidade este arquivo entrega. |
| `artifacts[].min_lines` | inteiro (opcional) | Contagem mínima de linhas para não ser considerado um stub. |
| `artifacts[].exports` | array de strings (opcional) | Exportações nomeadas esperadas para verificação. |
| `artifacts[].contains` | string (opcional) | Expressão regular ou padrão literal que deve aparecer no arquivo. |
| `key_links` | array de objetos | Conexões críticas entre artefatos — a ligação que faz o sistema funcionar de ponta a ponta. |
| `key_links[].from` | string | Arquivo ou componente de origem. |
| `key_links[].to` | string | Arquivo, endpoint ou módulo de destino. |
| `key_links[].via` | string | Descrição de como eles se conectam (ex.: `fetch in useEffect`, `Prisma query`, `import`). |
| `key_links[].pattern` | string (opcional) | Expressão regular para verificar se a conexão existe no código-fonte. |
---
## Estrutura do corpo
Após o frontmatter, o corpo do plano utiliza blocos no estilo XML lidos pelo agente executor.
### `<objective>`
Declara o que o plano entrega e por que isso importa para o projeto:
```xml
<objective>
Implement the post feed as a scrollable card list.
Purpose: Core display feature for the social feed phase.
Output: PostFeed and PostCard components wired to /api/feed.
</objective>
```
### `<execution_context>`
Lista os arquivos de workflow que o executor lê antes de começar. Sempre inclui o workflow execute-plan; adiciona a referência de checkpoints quando o plano contém tarefas de checkpoint:
```xml
<execution_context>
@~/.claude/get-shit-done/workflows/execute-plan.md
@~/.claude/get-shit-done/templates/summary.md
</execution_context>
```
### `<context>`
Referencia os arquivos-fonte que o executor precisa ler. Inclui documentos de planejamento no nível do projeto e quaisquer arquivos-fonte cujos padrões ou tipos o plano deve replicar. Arquivos `SUMMARY.md` de planos anteriores são incluídos apenas quando há uma dependência genuína (tipos importados, decisão compartilhada) — não de forma reflexiva:
```xml
<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@src/components/UserCard.tsx
</context>
```
### `<tasks>`
Contém um ou mais elementos `<task>`. Todo elemento de tarefa deve ter `<name>`, `<files>`, `<read_first>`, `<action>`, `<verify>`, `<acceptance_criteria>` e `<done>` para tarefas do tipo `type="auto"`.
---
## Tipos de tarefa
| Tipo | Uso | Autonomia |
|---|---|---|
| `auto` | Tudo o que o executor pode fazer de forma independente. | Totalmente autônomo. |
| `checkpoint:human-verify` | Verificação visual ou funcional que requer que um humano observe uma UI ou serviço em execução. | Pausa a execução; apresenta ao desenvolvedor; retoma com aprovação. |
| `checkpoint:decision` | Escolhas de implementação que surgiram durante a execução e requerem a contribuição do desenvolvedor. | Pausa a execução; apresenta opções; retoma com a seleção. |
| `checkpoint:human-action` | Etapas manuais verdadeiramente inevitáveis (criação de conta, interação com hardware). Usadas com parcimônia. | Pausa a execução; retoma com confirmação. |
Planos que contêm qualquer tarefa de checkpoint devem definir `autonomous: false` no frontmatter.
---
## Estrutura de tarefa `auto`
```xml
<task type="auto">
<name>Task 1: Create PostCard component</name>
<files>src/components/PostCard.tsx</files>
<read_first>src/components/UserCard.tsx, src/types/post.ts</read_first>
<action>Create PostCard component accepting a Post prop (id, authorId, content, createdAt,
reactionCount). Render author avatar using UserAvatar from UserCard pattern. Show timestamp
using date-fns formatDistanceToNow. Export as named export PostCard.</action>
<verify>npx tsc --noEmit</verify>
<acceptance_criteria>
- src/components/PostCard.tsx exports named export PostCard
- PostCard.tsx contains "reactionCount" prop usage
- npx tsc --noEmit exits 0
</acceptance_criteria>
<done>PostCard renders post content with author and timestamp</done>
</task>
```
### Campos obrigatórios para tarefas `auto`
| Campo | Regra |
|---|---|
| `<files>` | Todo arquivo que a tarefa cria ou modifica. O executor escreve apenas nesses arquivos. |
| `<read_first>` | Arquivos que o executor deve ler antes de tocar em qualquer coisa — o arquivo sendo modificado, qualquer arquivo de padrão de referência, qualquer arquivo cujos tipos ou convenções devem ser replicados. |
| `<action>` | Instruções concretas com identificadores exatos, caminhos de arquivo, assinaturas de função e valores esperados. Nunca diz "alinhe X com Y" sem especificar o estado-alvo. Nunca contém blocos de código cercados ou implementações completas. |
| `<verify>` | Um comando ou verificação executável que comprova o sucesso da tarefa. Deve distinguir aprovação de falha — `echo "done"` não é válido. |
| `<acceptance_criteria>` | Condições verificáveis: strings verificáveis por grep, códigos de saída de comandos, comportamentos observáveis. Sem linguagem subjetiva ("parece correto", "configurado corretamente"). |
| `<done>` | Uma declaração curta e mensurável do resultado concluído. |
---
## Dimensões de qualidade do plano
O agente `gsd-plan-checker` avalia cada PLAN.md em 12 dimensões antes do início da execução. Um plano que falha em qualquer verificação de severidade BLOQUEADOR é devolvido ao `gsd-planner` para revisão (até 3 iterações):
| Dimensão | O que verifica |
|---|---|
| **1 — Cobertura de Requisitos** | Todo ID de requisito de fase do ROADMAP.md aparece no campo de frontmatter `requirements` de pelo menos um plano e possui tarefa(s) correspondente(s). |
| **2 — Completude das Tarefas** | Toda tarefa `auto` contém todos os campos obrigatórios (`<files>`, `<action>`, `<verify>`, `<acceptance_criteria>`, `<done>`). Nenhum campo vago ou vazio. |
| **3 — Correção de Dependências** | As referências de `depends_on` são válidas, acíclicas e consistentes com os números de onda. Um plano da Onda N depende apenas de planos em ondas < N. |
| **4 — Links Principais Planejados** | Artefatos em `must_haves.key_links` possuem tarefas correspondentes que implementam a ligação — não apenas a criação do artefato. |
| **5 — Sanidade do Escopo** | Os planos permanecem dentro do orçamento de contexto: 2–3 tarefas por plano (4 = aviso, 5+ = BLOQUEADOR), ≤ 8–10 arquivos por plano (15+ = BLOQUEADOR). |
| **6 — Derivação de Verificação** | `must_haves.truths` são comportamentos observáveis pelo usuário, não detalhes de implementação. Artefatos mapeiam para truths. Links principais cobrem a ligação crítica. |
| **7 — Conformidade de Contexto** | Toda decisão `D-NN` do CONTEXT.md é abordada por pelo menos uma tarefa. Nenhuma tarefa implementa nada de `<deferred>`. |
| **7b — Detecção de Redução de Escopo** | As ações das tarefas não reduzem silenciosamente uma decisão bloqueada para um "v1", "stub" ou "melhoria futura" sem entregar o escopo completo da decisão. Sempre é um BLOQUEADOR quando encontrado. |
| **7c — Conformidade de Nível Arquitetural** | As tarefas atribuem capacidades ao nível correto conforme o Mapa de Responsabilidade Arquitetural do RESEARCH.md (quando presente). Capacidades sensíveis à segurança no nível errado são BLOCKEADOREs. |
| **8 — Conformidade Nyquist** | Quando `workflow.nyquist_validation` está habilitado e RESEARCH.md existe, toda tarefa tem um comando de verificação `<automated>`, nenhuma janela consecutiva de 3 tarefas carece de cobertura, e VALIDATION.md está presente. |
| **9 — Contratos de Dados Entre Planos** | Quando planos compartilham pipelines de dados, suas transformações são compatíveis — nenhum plano remove dados que outro plano precisa em sua forma original. |
| **10 — Conformidade com CLAUDE.md** | Os planos respeitam convenções específicas do projeto, padrões proibidos, ferramentas obrigatórias e requisitos de segurança do `./CLAUDE.md`. |
| **11 — Resolução de Pesquisa** | Quando RESEARCH.md existe, sua seção `## Open Questions` está marcada como `(RESOLVED)` antes de o planejamento prosseguir. |
| **12 — Conformidade de Padrões** | Quando PATTERNS.md existe, as tarefas referenciam os padrões analógicos corretos para cada arquivo novo ou modificado. |
---
## Modelo de execução por ondas
Os números de onda são pré-calculados durante o planejamento. O execute-phase agrupa os planos por número de onda e executa os planos de cada onda em paralelo:
```
Wave 1: Plan 01, Plan 02, Plan 03 (all run simultaneously — no dependencies)
Wave 2: Plan 04 (waits for Wave 1 to complete)
Wave 3: Plan 05 (waits for Wave 2 to complete)
```
Planos dentro de uma mesma onda que modificam arquivos sobrepostos não devem estar na mesma onda — a Dimensão 3 do verificador de planos sinaliza isso como um BLOQUEADOR.
---
## Saída do plano
Após a execução bem-sucedida de um plano, o executor escreve um SUMMARY.md em:
```
.planning/phases/<NN>-<slug>/<NN>-<PP>-SUMMARY.md
```
O SUMMARY.md é o registro canônico do que foi construído. Planos subsequentes na mesma fase podem referenciá-lo quando há uma dependência genuína em seus tipos ou decisões.
---
## Relacionados
- [Esquema CONTEXT.md](context-md.md)
- [Artefatos de planejamento](planning-artifacts.md)
- [Funcionalidades](../FEATURES.md)
- [Índice da documentação](../README.md)

225
docs/pt-BR/reference/planning-artifacts.md Normal file
View File

@@ -0,0 +1,225 @@
# Referência de artefatos de planejamento
O diretório `.planning/` é a memória compartilhada do GSD Core para um projeto. Todos os fluxos de trabalho leem, gravam e deixam um rastro auditável de decisões. Esta página mapeia cada arquivo, sua finalidade e qual comando o produz ou consome. Consulte o [índice de documentação](../README.md).
---
## Estrutura de diretórios
```
.planning/
├── PROJECT.md # Identidade do projeto e valor central
├── ROADMAP.md # Listagem de marcos e fases com objetivos
├── REQUIREMENTS.md # Critérios de aceitação numerados
├── STATE.md # Rastreador de posição em andamento
├── config.json # Configuração de fluxo de trabalho e modelo
├── MILESTONES.md # Arquivo de marcos (opcional)
├── BACKLOG.md # Trabalho adiado e futuro (opcional)
├── LEARNINGS.md # Aprendizados acumulados entre fases (opcional)
├── DECISIONS-INDEX.md # Resumo contínuo de decisões anteriores (opcional)
├── METHODOLOGY.md # Frameworks interpretativos reutilizáveis (opcional)
├── HANDOFF.json # Estado de pausa legível por máquina (transitório)
├── codebase/ # Mapas do código-base (opcional)
│ ├── architecture.md
│ ├── stack.md
│ └── ...
├── intel/ # Índice de símbolos consultável (opcional, intel.enabled)
│ └── API-SURFACE.md
└── phases/
└── <NN>-<slug>/ # Um diretório por fase
├── <NN>-CONTEXT.md # Decisões de implementação (discuss-phase)
├── <NN>-DISCUSSION-LOG.md # Auditoria legível da discussão (discuss-phase)
├── <NN>-RESEARCH.md # Resultados de pesquisa técnica (plan-phase)
├── <NN>-VALIDATION.md # Estratégia de cobertura de testes Nyquist (plan-phase)
├── <NN>-PATTERNS.md # Mapa de análogos do código-base (plan-phase, opcional)
├── <NN>-<PP>-PLAN.md # Plano executável (plan-phase, um por plano)
├── <NN>-<PP>-SUMMARY.md # Registro de execução (execute-phase, um por plano)
├── <NN>-VERIFICATION.md # Relatório de verificação dos objetivos da fase (verify-phase)
├── <NN>-UAT.md # Estado persistente de sessão UAT (execute-phase)
└── .continue-here.md # Instruções de retomada após pausa (pause-work)
```
---
## Artefatos no nível raiz
### `PROJECT.md`
| | |
|---|---|
| **Finalidade** | Identidade canônica do projeto: o que é, para quem é, valor central, requisitos, restrições e decisões-chave. Atualizado ao longo do ciclo de vida do projeto conforme o produto evolui. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-complete-milestone` à medida que as decisões são validadas. |
| **Consumido por** | Todos os fluxos de trabalho de planejamento; `gsd-phase-researcher`, `gsd-planner` (contexto); `discuss-phase` (decisões anteriores); `gsd-plan-checker` (restrições do projeto). |
### `ROADMAP.md`
| | |
|---|---|
| **Finalidade** | Listagem de marcos e fases com objetivos, IDs de requisitos, critérios de sucesso e referências canônicas por fase. A fonte única de verdade sobre o que o projeto está construindo e em que ordem. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado por `/gsd-phase --insert` e `/gsd-complete-milestone`. |
| **Consumido por** | `/gsd-discuss-phase`, `/gsd-plan-phase`, `/gsd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `gsd-planner`, `gsd-plan-checker`, `gsd-phase-researcher`. |
### `REQUIREMENTS.md`
| | |
|---|---|
| **Finalidade** | Critérios de aceitação numerados e verificáveis para o projeto. Cada requisito possui um ID (ex.: `AUTH-01`) que mapeia para as fases do roadmap. Marca os requisitos como concluídos conforme as fases são executadas. |
| **Produzido por** | `/gsd-new-project` (criação inicial); requisitos marcados como concluídos por `execute-phase`. |
| **Consumido por** | `gsd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `gsd-plan-checker` Dimensão 1 (cobertura de requisitos); `discuss-phase` (requisitos anteriores). |
### `STATE.md`
| | |
|---|---|
| **Finalidade** | Rastreador de posição em andamento — fase e plano atuais, métricas de progresso, decisões acumuladas, notas de continuidade de sessão. Lido no início de toda execução de fluxo de trabalho. Atualizado após cada ação significativa. |
| **Produzido por** | `/gsd-new-project` (criação inicial); atualizado continuamente por todos os fluxos de fase, `/gsd-pause-work`, `/gsd-resume-work`. |
| **Consumido por** | Todos os fluxos de orquestração; `/gsd-progress`; execução de tarefas avulsas via `/gsd-quick`; `gsd-planner` e `gsd-phase-researcher` (decisões do projeto). |
Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
### `config.json`
| | |
|---|---|
| **Finalidade** | Configuração do fluxo de trabalho: perfis de modelo, alternâncias de pesquisa e verificador de plano, estratégia de ramificação git, validação Nyquist, configurações de paralelização e substituições de modelo por agente. |
| **Produzido por** | `/gsd-new-project` (criação inicial); `/gsd-settings` (edição interativa). |
| **Consumido por** | Todos os fluxos de trabalho e subagentes — lido no momento de inicialização via `gsd-tools query config-get`. |
Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
### `MILESTONES.md` (opcional)
| | |
|---|---|
| **Finalidade** | Registro histórico de marcos concluídos. Preenchido à medida que cada marco é encerrado; fornece um instantâneo de arquivo do que foi entregue e quando. |
| **Produzido por** | `/gsd-complete-milestone`. |
| **Consumido por** | `/gsd-audit-milestone`; revisão humana. |
### `DECISIONS-INDEX.md` (opcional)
| | |
|---|---|
| **Finalidade** | Resumo contínuo limitado de decisões capturadas em arquivos CONTEXT.md de fases anteriores. Quando presente, o `discuss-phase` lê este único arquivo em vez de ler até três arquivos CONTEXT.md anteriores individualmente, economizando orçamento de contexto. |
| **Produzido por** | Gerado quando o número de fases anteriores ultrapassa o limite de leitura contínua. |
| **Consumido por** | `discuss-phase` (etapa `load_prior_context`). |
### `HANDOFF.json` (transitório)
| | |
|---|---|
| **Finalidade** | Estado de pausa legível por máquina gravado quando o trabalho é interrompido. Contém o ponto de retomada, contexto em andamento e instruções de continuação. Consumido exatamente uma vez — na retomada. |
| **Produzido por** | `/gsd-pause-work`. |
| **Consumido por** | `/gsd-resume-work`. |
---
## Artefatos por fase
Todos os arquivos por fase ficam em `.planning/phases/<NN>-<slug>/`, onde `NN` é o número da fase com zero à esquerda e `slug` é o nome da fase com hifens.
### `<NN>-CONTEXT.md`
| | |
|---|---|
| **Finalidade** | Decisões de implementação capturadas antes do início do planejamento. Contém o limite da fase (`<domain>`), decisões bloqueadas com identificadores `D-NN` (`<decisions>`), referências canônicas de documentos (`<canonical_refs>`), insights de código existente (`<code_context>`), inspirações específicas (`<specifics>`) e ideias adiadas (`<deferred>`). |
| **Produzido por** | `/gsd-discuss-phase` (discussão interativa ou caminhos expressos PRD/ADR). |
| **Consumido por** | `gsd-phase-researcher` (o que investigar); `gsd-planner` (decisões bloqueadas); `gsd-plan-checker` Dimensão 7 (conformidade de contexto). |
Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de campos.
### `<NN>-DISCUSSION-LOG.md`
| | |
|---|---|
| **Finalidade** | Rastro de auditoria legível da sessão de discuss-phase: áreas discutidas, opções apresentadas, seleções feitas, ideias adiadas e itens deixados ao critério do Claude. Não é consumido por fluxos de trabalho automatizados. |
| **Produzido por** | `/gsd-discuss-phase` (etapa `git_commit`). |
| **Consumido por** | Revisão humana; retrospectivas. |
### `<NN>-RESEARCH.md`
| | |
|---|---|
| **Finalidade** | Resultados de pesquisa técnica produzidos antes do planejamento. Responde à pergunta "O que preciso saber para planejar bem esta fase?" — abrange análise de domínio, padrões, riscos, um Mapa de Responsabilidade Arquitetural e uma seção de Arquitetura de Validação (usada pelo gate Nyquist). |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-phase-researcher`. |
| **Consumido por** | `gsd-planner` (entradas de planejamento); `gsd-plan-checker` Dimensão 7c (conformidade de camada), Dimensão 8 (Nyquist), Dimensão 11 (resolução de pesquisa); `gsd-pattern-mapper` (fonte de lista de arquivos). |
### `<NN>-VALIDATION.md`
| | |
|---|---|
| **Finalidade** | Estratégia de validação inspirada no Nyquist, derivada da seção `## Validation Architecture` do RESEARCH.md. Especifica requisitos de cobertura de testes automatizados que os planos devem respeitar. |
| **Produzido por** | `/gsd-plan-phase` (Etapa 5.5, quando `workflow.nyquist_validation` está habilitado e o RESEARCH.md contém uma seção de Arquitetura de Validação). |
| **Consumido por** | `gsd-plan-checker` Dimensão 8 (gate Check 8e — deve existir antes de os checks Nyquist prosseguirem); `gsd-verifier`. |
### `<NN>-PATTERNS.md`
| | |
|---|---|
| **Finalidade** | Mapa de análogos do código-base produzido pelo `gsd-pattern-mapper`. Para cada arquivo a ser criado ou modificado nesta fase, identifica o análogo existente mais próximo, classifica o papel e o fluxo de dados do arquivo e extrai trechos concretos de código. Orienta o planejador em direção a padrões consistentes. |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-pattern-mapper` (opcional; ignorado se `workflow.pattern_mapper: false`). |
| **Consumido por** | `gsd-planner` (orientação de padrões); `gsd-plan-checker` Dimensão 12 (conformidade de padrões). |
### `<NN>-<PP>-PLAN.md`
| | |
|---|---|
| **Finalidade** | Plano executável para uma única unidade de trabalho dentro da fase. Contém frontmatter YAML (onda, dependências, arquivos, requisitos, `must_haves`), um objetivo, referências de contexto, tarefas estruturadas em XML com campos `<read_first>`, `<action>`, `<verify>` e `<acceptance_criteria>`, e critérios de verificação. |
| **Produzido por** | `/gsd-plan-phase` via agente `gsd-planner`. Um arquivo por plano — ex.: `03-02-PLAN.md` é Fase 3, Plano 2. |
| **Consumido por** | `/gsd-execute-phase` (agente executor lê o plano e executa as tarefas); `gsd-plan-checker` (revisão de qualidade pré-execução); `gsd-verifier` (lê `must_haves` para verificação pós-execução). |
Consulte o [esquema de PLAN.md](plan-md.md) para a referência completa de campos.
### `<NN>-<PP>-SUMMARY.md`
| | |
|---|---|
| **Finalidade** | Registro de execução gravado após a conclusão de um plano. Documenta o que foi construído, desvios em relação ao plano, uma autoverificação em relação aos critérios de aceitação e o grafo de dependências da fase. |
| **Produzido por** | Agente executor de `execute-phase` (gravado ao final da execução de cada plano). |
| **Consumido por** | `/gsd-progress` (status da fase); `gsd-planner` (quando um plano subsequente tem dependência genuína da saída de um plano anterior); `milestone-summary`. |
### `<NN>-VERIFICATION.md`
| | |
|---|---|
| **Finalidade** | Relatório de verificação dos objetivos da fase. Verifica `must_haves.truths`, `must_haves.artifacts` e `must_haves.key_links` de todos os planos em relação ao código-base real após a execução. Registra `status: passed | gaps_found | human_needed`. |
| **Produzido por** | `/gsd-verify-work` (ou a etapa de verificação dentro de `/gsd-execute-phase`). |
| **Consumido por** | Gate de fase encerrada do `plan-phase` (um VERIFICATION.md com `status: passed` marca a fase como `Complete` e bloqueia replanejamento sem `--force`); `/gsd-progress`; revisão humana. |
### `<NN>-UAT.md`
| | |
|---|---|
| **Finalidade** | Rastreamento persistente de sessão UAT. Registra cada caso de teste, comportamento observável esperado, resultado e resposta do desenvolvedor ao longo de uma sessão UAT ativa. Carrega frontmatter YAML (`status`, `phase`, `source`, timestamps). |
| **Produzido por** | `/gsd-audit-uat` (sessão UAT interativa). |
| **Consumido por** | `/gsd-audit-uat` (retomada de uma sessão UAT anterior). |
### `.continue-here.md`
| | |
|---|---|
| **Finalidade** | Instruções de retomada legíveis gravadas quando o trabalho em uma fase é pausado. Contém contexto para agentes retomarem: antipadrões críticos, problemas bloqueantes, leitura obrigatória e o comando exato para retomar. |
| **Produzido por** | `/gsd-pause-work`. |
| **Consumido por** | Qualquer fluxo de trabalho que inicia em uma fase — tanto `discuss-phase` quanto `plan-phase` verificam a existência deste arquivo na entrada e exigem que o agente demonstre compreensão de quaisquer antipadrões `blocking` antes de prosseguir. |
---
## Convenções de nomenclatura
| Segmento | Formato | Exemplo |
|---|---|---|
| Diretório de fase | `<NN>-<slug>` | `03-post-feed` |
| Arquivo de nível de fase | `<NN>-<ARTIFACT>.md` | `03-CONTEXT.md` |
| Arquivo de nível de plano | `<NN>-<PP>-<ARTIFACT>.md` | `03-02-PLAN.md` |
| `NN` | Número da fase com zero à esquerda | `03` para Fase 3 |
| `PP` | Número do plano com zero à esquerda dentro da fase | `02` para Plano 2 |
Quando `project_code` está definido no `config.json`, os diretórios de fase usam o código do projeto como prefixo: `CK-03-post-feed` para o código de projeto `CK`, Fase 3.
---
## Relacionados
- [Esquema de STATE.md](state-md.md)
- [Esquema de CONTEXT.md](context-md.md)
- [Esquema de PLAN.md](plan-md.md)
- [Índice de documentação](../README.md)

201
docs/pt-BR/reference/state-md.md Normal file
View File

@@ -0,0 +1,201 @@
# Referência do esquema STATE.md
`STATE.md` é o arquivo de memória viva do projeto do GSD Core — um único documento Markdown que registra em que ponto o projeto se encontra, o que aconteceu por último e o que executar a seguir. Esta página documenta sua estrutura. Consulte o [índice da documentação](../README.md).
---
## Visão geral
Todo projeto gerenciado pelo GSD Core mantém um único `STATE.md` em `.planning/STATE.md`. Ele é lido no início de todo fluxo de trabalho e escrito após toda ação significativa. O arquivo combina:
- **Frontmatter YAML** — campos legíveis por máquina consumidos pelo hook de linha de status (`parseStateMd`) e pelos comandos `gsd-tools state`.
- **Corpo Markdown** — seções legíveis por humanos cobrindo a posição atual, contexto acumulado, continuidade de sessão e métricas de desempenho.
O arquivo é intencionalmente pequeno (meta: menos de 100 linhas). Ele é um resumo do estado do projeto, não um arquivo histórico.
---
## Frontmatter YAML
O frontmatter aparece entre delimitadores `---` no início do arquivo. Todos os campos, exceto `gsd_state_version` e `status`, são opcionais; os campos podem estar ausentes quando seus dados ainda não estão disponíveis.
### Exemplo comentado
```yaml
---
gsd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
# Campos de ciclo de vida de fase — todos opcionais (adicionados na v1.40.0, issue #2833)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]
progress:
total_phases: 17
completed_phases: 10
total_plans: 84
completed_plans: 47
percent: 59
# Campos adicionais escritos por syncStateFrontmatter
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---
```
### Referência de campos
| Campo | Tipo | Quando populado | Finalidade |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | Sempre | Versão do esquema; escrito na primeira chamada `state.*` por `syncStateFrontmatter`. |
| `milestone` | string (ex.: `v2.0`) | Quando um milestone está configurado | Versão do milestone atual, lida da configuração do projeto. |
| `milestone_name` | string | Quando um milestone está configurado | Rótulo legível do milestone (ex.: `Code Quality`). |
| `status` | string | Sempre | Estágio atual do ciclo de vida. Normalizado por `normalizeStateStatus()` — veja [valores de status](#valores-de-status). |
| `active_phase` | string (ex.: `"4.5"`) | Um comando do orquestrador está em andamento nesta fase | O número da fase atualmente sendo processada. Definido como `null` entre fases. |
| `next_action` | string | Ocioso, com um comando recomendado | O slash command a executar a seguir: `discuss-phase`, `plan-phase`, `execute-phase` ou `verify-phase`. Definido como `null` quando um orquestrador está em andamento ou nenhuma recomendação está disponível. |
| `next_phases` | array YAML flow (ex.: `["4.5"]`) | Acompanha `next_action` | Os IDs de fase aos quais o `next_action` se aplica (tipicamente 1–2 entradas). Definido como `null` nas mesmas condições que `next_action`. |
| `progress.total_phases` | inteiro | Quando dados de fase estão disponíveis | Número total de fases no milestone atual, derivado do ROADMAP.md e do diretório de fases. |
| `progress.completed_phases` | inteiro | Quando dados de fase estão disponíveis | Número de fases que têm todos os resumos de planos em disco (ou seja, todos os planos concluídos). |
| `progress.total_plans` | inteiro | Quando arquivos de plano existem | Soma de todos os arquivos de plano nas fases do milestone atual. |
| `progress.completed_plans` | inteiro | Quando arquivos de resumo existem | Soma dos resumos de planos concluídos (um SUMMARY.md por plano executado). |
| `progress.percent` | inteiro 0–100 | Quando dados de progresso estão disponíveis | Progresso do milestone na **dimensão de fases** (`min(completed_plans/total_plans, completed_phases/total_phases)`). A barra de progresso da linha de status é renderizada somente quando este campo está presente — sua ausência suprime a barra. |
| `current_phase` | string | Quando uma fase está em execução | Número da fase extraído do campo `Current Phase:` do corpo. |
| `current_phase_name` | string | Quando uma fase tem nome | Nome da fase extraído do campo `Current Phase Name:` do corpo. |
| `current_plan` | string | Quando um plano está em andamento | Número do plano extraído do campo `Current Plan:` do corpo. |
| `last_updated` | timestamp ISO-8601 | Sempre (na escrita) | Timestamp da última chamada a `syncStateFrontmatter`; escrito por `realClock.nowIso()`. |
| `last_activity` | string | Quando definido no corpo | Data da última atividade, extraída do campo `Last Activity:` do corpo. |
| `stopped_at` | string | Quando um ponto de parada foi registrado | Descrição da última ação concluída; limitada à seção `## Session` do corpo para evitar correspondência com prosa de arquivo. |
| `paused_at` | string | Quando o projeto está pausado | Descrição de forma livre do ponto de pausa; ausente ou `null` quando não pausado. |
### Valores de status
`normalizeStateStatus()` em `get-shit-done/bin/lib/state-document.cjs` mapeia o texto bruto do corpo para estes valores canônicos:
| Valor canônico | Texto correspondente (sem diferenciação de maiúsculas/minúsculas) |
|---|---|
| `discussing` | contém `discussing` |
| `planning` | contém `planning` ou `ready to plan` |
| `executing` | contém `executing`, `in progress` ou `ready to execute` |
| `verifying` | contém `verif` |
| `completed` | contém `complete` ou `done` |
| `paused` | contém `paused` ou `stopped`, ou `paused_at` está presente |
| `unknown` | nenhuma das anteriores |
Quando um comando do orquestrador está em andamento, a convenção (issue #2833) é escrever o estágio do ciclo de vida diretamente em `status`:
| Comando | `status` durante a execução |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
---
## Cenas de renderização da linha de status
`formatGsdState()` em `hooks/gsd-statusline.js` lê o frontmatter analisado e emite a **primeira cena correspondente**. Se nenhum campo novo do ciclo de vida se aplicar, a renderização cai para o formato original byte a byte, inalterado desde a v1.38.x.
| Cena | Gatilho | Exemplo de exibição |
|---|---|---|
| **1. Fase ativa** | `active_phase` está populado | `v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing` |
| **2. Ocioso, próximo recomendado** | `active_phase` é null E tanto `next_action` quanto `next_phases` estão populados | `v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5` |
| **3. Milestone completo** | `percent` é `100` OU `completed_phases == total_phases` | `v2.0 [██████████] 100% · milestone complete` |
| **4. Fallback padrão** | Nenhuma das anteriores corresponde | `v1.9 Code Quality · executing · ph 1/5` (formato existente) |
**Prioridade de cena:** quando `active_phase` e `next_action` estão populados, a Cena 1 prevalece — um orquestrador está em andamento, portanto uma "próxima recomendação" seria enganosa. Essa prioridade é imposta pela ordem de verificação em `formatGsdState()` e coberta pelo conjunto `"scene priority"` em `tests/enh-2833-phase-lifecycle-statusline.test.cjs`.
A barra de progresso (`[██░░░░░░░░] 20%`) é anexada ao segmento do milestone somente quando `progress.percent` está presente no frontmatter; ausente significa sem barra.
---
## Restrições de análise do frontmatter
O hook de linha de status usa análise baseada em regex (sem biblioteca YAML completa), portanto as seguintes restrições se aplicam. Elas são testadas em `tests/enh-2833-phase-lifecycle-statusline.test.cjs`.
1. **O frontmatter deve começar no primeiro caractere do arquivo.** Qualquer coisa — incluindo comentários — acima do `---` de abertura invalida a correspondência. A linha `---` de abertura deve ser exatamente isso, sem espaços no final.
2. **Comentários dentro de blocos aninhados não são suportados.** O analisador do bloco `progress:` requer que a próxima linha seja `[ \t]+\w+:`. Inserir um `# comment` entre `progress:` e sua primeira chave quebra a correspondência e a barra desaparece. Qualquer documentação pertence ao corpo do `STATE.md`, não dentro dos blocos do frontmatter.
3. **O formato primário de `next_phases` é flow de linha única.** O analisador tenta primeiro `next_phases: ["4.5", "4.6"]`. Sequências em bloco (`- 4.5\n- 4.6`) também são analisadas, mas são menos confiáveis para renderização da linha de status. Prefira flow de linha única para `next_phases` para manter o analisador baseado em regex previsível. Se muitas fases candidatas precisarem ser registradas para fins de documentação, armazene-as no corpo do `STATE.md`.
Se uma mudança futura substituir o analisador de regex por uma biblioteca YAML completa, essas restrições poderão ser relaxadas e os testes atualizados adequadamente.
---
## Seções do corpo Markdown
O corpo (tudo após o `---` de fechamento) segue o template em `get-shit-done/templates/state.md`. As seções padrão são:
### Referência do Projeto
Aponta para `.planning/PROJECT.md`. Contém:
- **Valor central** — a frase de uma linha da seção Core Value do `PROJECT.md`.
- **Foco atual** — qual fase está ativa.
### Posição Atual
Onde o projeto está agora:
| Campo | Formato |
|---|---|
| `Phase:` | `X of Y (Phase name)` |
| `Plan:` | `A of B in current phase` |
| `Status:` | Texto livre, ex.: `Ready to execute`, `Executing Phase 4`, `Phase complete — ready for verification` |
| `Last activity:` | Data ISO (`YYYY-MM-DD`) quando escrito por handler; prosa narrativa quando elaborado pelo executor |
| `Progress:` | Barra visual, ex.: `[████░░░░░░] 40%` |
Os campos `Status:` e `Last activity:` nesta seção são atualizados pelos handlers do GSD quando o valor existente é um padrão de template conhecido (invariante de Knuth: valores elaborados pelo executor são preservados). A lista completa de padrões de handler conhecidos está em `KNOWN_TEMPLATE_DEFAULTS` dentro de `get-shit-done/bin/lib/state-document.cjs`.
### Métricas de Desempenho
Rastreamento de velocidade de execução:
- Total de planos concluídos, duração média por plano.
- Tabela de detalhamento por fase (`Phase | Plans | Total | Avg/Plan`).
- Tendência recente: Improving / Stable / Degrading.
Atualizado após cada conclusão de plano.
### Contexto Acumulado
**Decisões** — um resumo das decisões recentes que afetam o trabalho atual (o log completo vive em `PROJECT.md`). Adicionado via `gsd-tools state add-decision`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/gsd-capture`.
**Bloqueadores/Preocupações** — problemas que afetam trabalhos futuros, prefixados com a fase de origem. Adicionado via `gsd-tools state add-blocker`; resolvido via `gsd-tools state resolve-blocker`.
### Continuidade de Sessão
Permite retomada instantânea de sessão:
- `Last session:` — timestamp ISO-8601 da última sessão.
- `Stopped at:` — descrição da última ação concluída.
- `Resume file:` — caminho para um arquivo `.continue-here*.md` se existir, caso contrário `None`.
---
## Compatibilidade retroativa
Os campos de ciclo de vida de fase (`active_phase`, `next_action`, `next_phases` e `progress.percent` para a barra) são **aditivos e opt-in por projeto**:
- Um `STATE.md` sem nenhum dos campos de ciclo de vida populados é renderizado **byte a byte de forma idêntica** à v1.38.x e anteriores.
- Adicionar qualquer campo de ciclo de vida é opt-in — o renderizador degrada graciosamente quando os campos estão ausentes.
- A barra de progresso é opt-in mesmo quando o bloco `progress` existe: somente `progress.percent` ativa a barra; `total_phases` e `completed_phases` sozinhos não ativam.
O conjunto de testes `formatGsdState #2833 backward compatibility` em `tests/enh-2833-phase-lifecycle-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
---
## Relacionados
- [Artefatos de planejamento](planning-artifacts.md)
- [Configuração](../CONFIGURATION.md)
- [O ciclo de fases](../explanation/the-phase-loop.md)
- [índice da documentação](../README.md)

2
docs/pt-BR/superpowers/README.md
View File

@@ -4,7 +4,7 @@ Documentos avançados traduzidos:
## Plans
- [2026-03-18-materialize-new-project-config](plans/2026-03-18-materialize-new-project-config.md)
- [2026-03-23-materialize-new-project-config](plans/2026-03-23-materialize-new-project-config.md)
## Specs

226
docs/pt-BR/tutorials/onboarding-an-existing-codebase.md Normal file
View File

@@ -0,0 +1,226 @@
# Integrando uma base de código existente
Neste tutorial você integrará o GSD Core a um repositório que já possui código. Você mapeará a base de código, criará um projeto que descreve o que está *adicionando* e executará seu primeiro ciclo de discussão e planejamento para uma mudança pequena e focada. Ao final, o pipeline de planejamento do GSD Core conhecerá sua stack, suas convenções e suas preocupações — e usará esse conhecimento toda vez que planejar.
---
## O que você vai construir
Adicionaremos um único endpoint `GET /health` a uma aplicação Express existente. A mudança é pequena o suficiente para nunca desviar do objetivo real da lição: como o GSD Core aprende sua base de código antes de planejar qualquer coisa.
---
## Pré-requisitos
- **Node.js 18 ou superior** — `node --version` deve exibir `v18.x.x` ou mais recente.
- **Um projeto existente** — qualquer repositório com código. Não precisa ser Express; os passos se aplicam a qualquer stack.
- **Claude Code** — aberto na raiz do seu repositório.
---
## Passo 1 — Instalar o GSD Core
Na raiz do seu repositório:
```bash
npx @opengsd/gsd-core@latest
```
Escolha **Claude Code** e **local** quando solicitado. Você verá:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
---
## Passo 2 — Iniciar o Claude Code com permissões
```bash
claude --dangerously-skip-permissions
```
---
## Passo 3 — Mapear a base de código
Antes de criar um projeto, deixe o GSD Core aprender o que já existe. Este é o passo que torna o planejamento brownfield preciso.
```text
/gsd-map-codebase
```
O GSD Core cria quatro sub-agentes mapeadores paralelos (você verá "Spawning 4 parallel codebase mapper agents…" — isso leva de 1 a 5 minutos; não interrompa). Cada agente foca em uma preocupação diferente:
| Agente | Foco |
|--------|------|
| Tech mapper | Stack, frameworks, dependências |
| Architecture mapper | Padrões, camadas, fluxo de dados |
| Quality mapper | Convenções, práticas de teste |
| Concerns mapper | Dívida técnica, áreas de risco |
Quando os quatro retornarem, você verá:
```text
Codebase mapping complete.
Created .planning/codebase/:
- STACK.md (47 lines) - Technologies and dependencies
- ARCHITECTURE.md (62 lines) - System design and patterns
- STRUCTURE.md (38 lines) - Directory layout and organisation
- CONVENTIONS.md (55 lines) - Code style and patterns
- TESTING.md (41 lines) - Test structure and practices
- INTEGRATIONS.md (29 lines) - External services and APIs
- CONCERNS.md (33 lines) - Technical debt and issues
```
Abra `.planning/codebase/STACK.md`. Você verá a linguagem, o runtime, as versões do framework e as dependências principais que o GSD Core detectou — fundamentadas nos arquivos reais que leu, não em suposições.
Abra `.planning/codebase/CONVENTIONS.md`. Você verá as convenções de nomenclatura, os padrões de tratamento de erros e as regras de estilo de código que ele observou no seu código-fonte. Todos os planos que o GSD Core produzir para este repositório seguirão essas convenções automaticamente.
Abra `.planning/codebase/CONCERNS.md`. Este é o arquivo mais útil para ler antes de qualquer trabalho em novo recurso — ele expõe dívidas técnicas e áreas frágeis que podem afetar seus planos.
---
## Passo 4 — Limpar o contexto e criar o projeto
Limpe a janela de sessão:
```text
/clear
```
Agora crie o projeto. Como o GSD Core encontrou código existente no passo anterior, já sabe que se trata de um projeto brownfield. Quando você executa `/gsd-new-project`, as perguntas focam no que você está *adicionando*, e não em reconstruir o que já existe:
```text
/gsd-new-project
```
O GSD Core pergunta o que você quer construir. Responda com o recurso que está adicionando, e não com uma descrição de toda a base de código:
```text
Add a GET /health endpoint to the Express app. It should return
{ "status": "ok", "uptime": <seconds> }. We'll use it for load-balancer
health checks.
```
O GSD Core faz um pequeno número de perguntas de esclarecimento e depois prossegue para a criação de requisitos e roteiro. Como já leu `ARCHITECTURE.md` e `STACK.md`, mapeará as capacidades existentes para a seção **Validated** de `PROJECT.md` automaticamente — você não precisa descrever a superfície de API existente.
Escolha os padrões recomendados para todas as configurações do fluxo de trabalho.
Quando o sub-agente roadmapper retornar, você verá um roteiro proposto. Para uma única mudança pequena, haverá uma fase:
```text
Proposed Roadmap
1 phase | 2 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|----------------|-----------------------------------------------|--------------|
| 1 | Health endpoint| GET /health returning status and uptime JSON | HLT-01, HLT-02 |
```
Aprove o roteiro.
**O que é criado em `.planning/`:**
```text
.planning/
PROJECT.md ← descrição do projeto; capacidades existentes em "Validated"
REQUIREMENTS.md ← HLT-01, HLT-02
ROADMAP.md ← Fase 1, status: pending
STATE.md ← memória de sessão
config.json ← configurações do fluxo de trabalho
codebase/ ← os sete arquivos de mapa do Passo 3
```
Observe que `.planning/codebase/` já está lá desde o Passo 3. O GSD Core leu esses arquivos ao escrever `PROJECT.md`, por isso conseguiu preencher os requisitos Validated sem que você os descrevesse.
---
## Passo 5 — Limpar o contexto e discutir a Fase 1
```text
/clear
```
```text
/gsd-discuss-phase 1
```
Como o GSD Core leu seu `CONVENTIONS.md` e `ARCHITECTURE.md`, suas perguntas são fundamentadas na sua base de código real — não em conselhos genéricos. Você pode ver:
```text
> Your routes are registered in src/routes/index.js. Should the health
endpoint live there, or in a dedicated src/routes/health.js?
A dedicated health.js — keep routes separated.
> Your existing error middleware returns { error: "message" }. Should
/health use the same shape for error responses?
Yes, stay consistent.
> Should uptime be calculated from process.uptime() or a stored start time?
process.uptime() is fine.
```
Quando a discussão encerrar, o GSD Core escreverá:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
```
Abra esse arquivo. A seção `## Implementation Decisions` captura suas respostas. O planejador lerá este arquivo antes de escrever qualquer tarefa — portanto, suas preferências sobre posicionamento de arquivos e formato de resposta aparecerão nos planos, não apenas na discussão.
---
## Passo 6 — Planejar a Fase 1
```text
/gsd-plan-phase 1
```
Quatro sub-agentes de pesquisa rodam em paralelo (1–5 minutos). Quando retornarem, o planejador lê `CONTEXT.md`, os resultados da pesquisa e o mapa da sua base de código para criar planos de tarefas que correspondem às suas convenções.
**O que é criado:**
```text
.planning/phases/01-health-endpoint/
RESEARCH.md ← descobertas sobre padrões de health endpoint
01-01-PLAN.md ← Tarefa: criar src/routes/health.js
01-02-PLAN.md ← Tarefa: registrar rota health em src/routes/index.js
```
Abra `01-01-PLAN.md`. Observe que a tag `<files>` referencia `src/routes/health.js` — exatamente o caminho que você especificou na discussão, consistente com o padrão de roteamento que o GSD Core observou no mapa da sua base de código. Isso é o mapa da base de código em ação.
---
## Próximos passos
Você agora tem um projeto com um mapa da base de código, um registro de decisões de discussão e planos de tarefas verificados — tudo fundamentado no seu código real. A partir daqui, o fluxo de trabalho é idêntico ao de um projeto greenfield:
```text
/gsd-execute-phase 1
/gsd-verify-work 1
/gsd-ship 1
```
Para cada recurso futuro, execute `/gsd-map-codebase` novamente sempre que a estrutura mudar significativamente, para manter o mapa da base de código atualizado.
---
## O que você aprendeu
- Como `/gsd-map-codebase` executa quatro agentes paralelos para produzir `STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`, `STRUCTURE.md`, `TESTING.md` e `INTEGRATIONS.md` em `.planning/codebase/`.
- Como `/gsd-new-project` em um repositório brownfield concentra as perguntas no que você está *adicionando* e preenche os requisitos Validated a partir do código existente.
- Como o mapa da base de código orienta cada pergunta em `/gsd-discuss-phase` — caminhos de arquivos, padrões e convenções vêm do seu código real.
- Como o planejador lê `CONTEXT.md` e `CONVENTIONS.md` para produzir planos que correspondem ao estilo do seu repositório.
---
## Relacionados
- [Seu primeiro projeto](your-first-project.md) — o ciclo greenfield completo, da instalação ao PR
- [Mapear base de código via Comandos](../COMMANDS.md) — todos os flags e subcomandos de `/gsd-map-codebase`
- [Índice de documentação](../README.md)

291
docs/pt-BR/tutorials/your-first-project.md Normal file
View File

@@ -0,0 +1,291 @@
# Seu primeiro projeto
Neste tutorial você instalará o GSD Core e construirá um pequeno aplicativo de linha de comando para gerenciar tarefas do zero — uma fase, um PR, o ciclo completo. Ao final, você terá executado cada comando do ciclo de fase principal pelo menos uma vez e terá visto os artefatos de planejamento que cada comando produz.
---
## O que você vai construir
Um CLI em Node.js que permite adicionar, listar e concluir itens de tarefas armazenados em um arquivo JSON local. É pequeno o suficiente para terminar em uma sessão e não utiliza nada além da biblioteca padrão do Node.js, portanto não há nada incomum para instalar.
---
## Pré-requisitos
- **Node.js 18 ou superior** — `node --version` deve exibir `v18.x.x` ou maior.
- **Claude Code** — aberto no diretório do projeto que você deseja utilizar.
- Uma conexão com a internet para a instalação inicial.
Nenhuma outra ferramenta é necessária. O próprio GSD Core é instalado no próximo passo.
---
## Passo 1 — Instalar o GSD Core
Abra um terminal no diretório do seu projeto e execute:
```bash
npx @opengsd/gsd-core@latest
```
O instalador pergunta qual ambiente de execução de IA você está usando e se deseja instalar globalmente ou no projeto atual. Escolha **Claude Code** e **local** (apenas este projeto) por enquanto.
Você verá uma saída como:
```text
✓ Installed 86 skills to .claude/commands/
✓ Installed agents to .claude/agents/
✓ GSD Core ready — run /gsd-new-project to start
```
Observe que um diretório `.claude/` agora existe no seu projeto. É onde os comandos e agentes do GSD Core residem.
> Por que local vs global? Uma instalação local mantém a versão das skills fixada neste projeto. Consulte [Instalar no seu ambiente de execução](../how-to/install-on-your-runtime.md) quando quiser instalar globalmente.
---
## Passo 2 — Iniciar o Claude Code com permissões
O GSD Core spawna sub-agentes que leem e escrevem arquivos. Inicie o Claude Code com o sinalizador de permissões para que ele não pause para perguntar sobre cada operação de arquivo:
```bash
claude --dangerously-skip-permissions
```
Você chegará ao prompt do Claude Code no diretório do seu projeto.
---
## Passo 3 — Criar o projeto
Digite este comando slash no prompt do Claude Code:
```text
/gsd-new-project
```
O GSD Core abrirá uma conversa. Ele faz uma pergunta primeiro:
```text
What do you want to build?
```
Digite algo como:
```text
A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
`todo list`, and `todo done 1`. Items are saved to a local todos.json file.
No external dependencies — Node built-ins only.
```
O GSD Core faz uma série de perguntas de esclarecimento. Responda naturalmente. Ele está aprendendo o que é importante para você antes de escrever qualquer plano.
Após as perguntas, ele oferece a opção de realizar pesquisa de domínio. Para um projeto deste tamanho você pode pular a pesquisa — escolha **Skip research** quando solicitado.
O GSD Core então pede que você escolha as configurações de fluxo de trabalho (modo, granularidade, agentes de pesquisa). Escolha os padrões recomendados para cada um. Eles são gravados em `.planning/config.json`.
Por fim, um sub-agente de roadmap é executado (você verá o aviso "Spawning roadmapper…" — isso é normal e leva cerca de um minuto). Quando ele retornar, o GSD Core apresentará um roadmap proposto. Para um projeto de uma única fase, ele terá uma aparência semelhante a:
```text
Proposed Roadmap
1 phase | 4 requirements mapped | All v1 requirements covered ✓
| # | Phase | Goal | Requirements |
|---|--------------------|-----------------------------------------|-------------------|
| 1 | Core CLI | add / list / done commands, todos.json | CLI-01 … CLI-04 |
```
Digite **Approve** para aceitar o roadmap.
**O que é criado em `.planning/`:**
```text
.planning/
PROJECT.md ← descrição e requisitos do seu projeto
REQUIREMENTS.md ← REQ-IDs para cada capacidade v1
ROADMAP.md ← Fase 1, status: pending
STATE.md ← memória de sessão, posição atual
config.json ← configurações de fluxo de trabalho
```
Abra `.planning/ROADMAP.md` agora e leia. Observe que a Fase 1 tem uma Meta, uma lista de Requisitos que deve satisfazer e Critérios de Sucesso — estes são os comportamentos observáveis que a execução deve entregar.
---
## Passo 4 — Limpar o contexto e discutir a Fase 1
O GSD Core é projetado em torno de contextos frescos. Limpe a janela de sessão principal antes de cada fase:
```text
/clear
```
Em seguida, inicie a discussão para a Fase 1:
```text
/gsd-discuss-phase 1
```
O GSD Core lê a meta da fase e pergunta sobre suas preferências de implementação. Estas são as decisões que moldam *como* ele constrói, não apenas *o que* ele constrói. Exemplo de troca:
```text
> How should done items be stored — mark them in place or move them?
Mark them in place with a "done" flag.
> Should `todo list` show completed items by default?
No, hide them unless --all is passed.
> Error format when todos.json doesn't exist yet?
Create it silently on first add.
```
Quando a discussão encerra, o GSD Core escreve:
```text
.planning/phases/01-core-cli/CONTEXT.md
```
Abra esse arquivo. Você verá uma seção `## Implementation Decisions` capturando exatamente o que você disse. O planejador lê este arquivo — portanto, as decisões que você tomou aqui fluirão para cada plano de tarefa.
---
## Passo 5 — Planejar a Fase 1
```text
/gsd-plan-phase 1
```
Quatro sub-agentes de pesquisa se expandem em paralelo (você verá o aviso "Spawning 4 researchers…"). Eles levam de 1 a 5 minutos. Não interrompa.
Quando retornarem, um planejador lê o CONTEXT.md mais os resultados da pesquisa e cria planos de tarefa atômicos. Um verificador de planos então verifica se cada plano atinge a meta da fase antes de salvar.
**O que é criado:**
```text
.planning/phases/01-core-cli/
RESEARCH.md ← descobertas de domínio
01-01-PLAN.md ← Tarefa: criar helpers de leitura/escrita de todos.json
01-02-PLAN.md ← Tarefa: implementar os comandos add / list / done
```
Abra `01-01-PLAN.md`. Você verá um bloco `<task>` com um nome, os arquivos que toca, as etapas de ação, um comando de verificação e uma condição de conclusão. Observe a tag `<verify>` — o executor do GSD Core executará esse comando após escrever o código.
---
## Passo 6 — Executar a Fase 1
```text
/gsd-execute-phase 1
```
O GSD Core agrupa os planos em ondas (planos independentes são executados em paralelo), spawna um executor fresco com 200k de contexto por plano e confirma cada tarefa atomicamente.
Você verá algo como:
```text
Wave 1 (parallel):
[Executor A] → 01-01-PLAN.md (read/write helpers) ✓ committed
[Executor B] → 01-02-PLAN.md (CLI commands) ✓ committed
[Verifier] Checking codebase against phase goals...
CLI-01 todo add ✓
CLI-02 todo list ✓
CLI-03 todo done ✓
CLI-04 --all flag ✓
Status: PASS
```
**O que é criado:**
```text
.planning/phases/01-core-cli/
01-01-SUMMARY.md ← o que o Executor A construiu e confirmou
01-02-SUMMARY.md ← o que o Executor B construiu e confirmou
VERIFICATION.md ← cobertura de REQ: PASS
```
Execute seu CLI agora:
```bash
node todo.js add "buy milk"
node todo.js add "write tests"
node todo.js list
node todo.js done 1
node todo.js list
```
Você deve ver os itens aparecerem e o item 1 desaparecer da lista padrão após marcá-lo como concluído. Esse é o seu primeiro resultado visível entregue pelo GSD Core.
---
## Passo 7 — Verificar o trabalho
```text
/gsd-verify-work 1
```
O GSD Core extrai os critérios de sucesso da fase e os percorre um a um:
```text
[1/3] Can you run `node todo.js add "buy milk"` without errors?
> yes
[2/3] Does `node todo.js list` show only incomplete items by default?
> yes
[3/3] Does `node todo.js done 1` mark item 1 complete and hide it from the default list?
> yes
All 3 checks passed. Phase 1 verified.
```
Se alguma verificação falhar, o GSD Core diagnostica a causa raiz e cria um plano de correção. Execute `/gsd-execute-phase 1` novamente para aplicá-lo e depois re-execute `/gsd-verify-work 1`.
**O que é criado:**
```text
.planning/phases/01-core-cli/UAT.md ← todas as verificações e seus resultados
```
---
## Passo 8 — Publicar
```text
/gsd-ship 1
```
O GSD Core cria um pull request com um corpo gerado automaticamente. O corpo do PR sempre inclui: Resumo, Alterações, Requisitos Atendidos, Verificação e Decisões Principais.
Você verá:
```text
Pull request created: https://github.com/your-org/your-repo/pull/1
Title: feat(phase-1): core CLI — add / list / done commands
```
Esse é o ciclo completo — da ideia ao PR mesclado — para uma fase.
---
## O que você aprendeu
- Como instalar o GSD Core com `npx @opengsd/gsd-core@latest`.
- Como `/gsd-new-project` transforma uma conversa em um roadmap respaldado por artefatos em `.planning/`.
- Como `/gsd-discuss-phase` captura decisões de implementação antes de qualquer planejamento acontecer.
- Como `/gsd-plan-phase` spawna pesquisadores em paralelo e produz planos de tarefa atômicos.
- Como `/gsd-execute-phase` executa esses planos em ondas paralelas e confirma cada tarefa.
- Como `/gsd-verify-work` percorre os critérios de sucesso e gera planos de correção quando necessário.
- Como `/gsd-ship` transforma uma fase verificada em um pull request.
Para um projeto de múltiplas fases, repita os Passos 4–8 para cada fase e depois execute `/gsd-progress --next` para deixar o GSD Core detectar o próximo passo automaticamente.
---
## Relacionados
- [O ciclo de fase](../explanation/the-phase-loop.md) — por que o ciclo tem esse formato
- [Guias práticos](../README.md#how-to-guides) — receitas focadas em tarefas para situações específicas
- [Integrando uma base de código existente](onboarding-an-existing-codebase.md) — traga o GSD Core para um repositório já existente

99
docs/pt-BR/workflow-discuss-mode.md
View File

@@ -1,62 +1,75 @@
# Discuss Mode (Modo de Discussão)
# Modo Discuss: Suposições vs Entrevista
O GSD oferece dois estilos para `/gsd-discuss-phase`:
A fase de discuss do GSD Core oferece dois modos para coletar o contexto de implementação antes do início do planejamento. Entender quando usar cada um ajuda a passar da fase de perguntas para um `CONTEXT.md` confirmado com menos idas e vindas.
- **`standard`**: entrevista aberta para levantar preferências
- **`assumptions`**: análise do código primeiro, seguida de confirmação/correção de suposições
Para instruções passo a passo sobre como executar cada modo, consulte o [Como realizar discuss de uma fase](how-to/discuss-a-phase.md).
Para referência completa, veja [workflow-discuss-mode.md em inglês](../workflow-discuss-mode.md).
## Modos
---
### `discuss` (padrão)
## Quando usar `standard`
O fluxo original no estilo de entrevista. O Claude identifica áreas cinzentas na fase, apresenta-as para seleção e faz aproximadamente quatro perguntas por área. Adequado para:
Use quando:
- Fases iniciais em que o código-base é novo
- Fases em que o usuário tem opiniões firmes que deseja expressar proativamente
- Usuários que preferem coleta de contexto guiada e conversacional
- o projeto ainda não tem padrões claros
- você quer explorar alternativas livremente
- há decisões de produto/UX em aberto
### `assumptions`
Vantagem: descoberta ampla.
Trade-off: pode consumir mais tempo de perguntas.
Um fluxo com foco no código-base. O Claude analisa profundamente o código-base por meio de um subagente (lendo de 5 a 15 arquivos relevantes), formula suposições com evidências e as apresenta para confirmação ou correção. Adequado para:
## Quando usar `assumptions`
- Código-bases consolidados com padrões bem definidos
- Usuários que consideram as perguntas da entrevista óbvias
- Coleta de contexto mais rápida (~2–4 interações vs ~15–20)
Use quando:
## Configuração
- 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
```bash
# Habilitar o modo assumptions
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
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"
}
}
# Voltar ao modo de entrevista
node gsd-tools.cjs config-set workflow.discuss_mode discuss
```
## Fluxo no modo `assumptions`
A configuração é por projeto (armazenada em `.planning/config.json`). Consulte o [esquema do CONTEXT.md](reference/context-md.md) para ver a estrutura completa do arquivo produzido por ambos os modos.
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
## Como o Modo Assumptions Funciona
## Boas práticas
1. **Inicialização** — Igual ao modo discuss (carrega contexto anterior, explora o código-base, verifica pendências)
2. **Análise aprofundada** — O subagente de exploração lê de 5 a 15 arquivos do código-base relacionados à fase
3. **Apresentação das suposições** — Cada suposição inclui:
- O que o Claude faria e por quê (citando caminhos de arquivo)
- O que dá errado se a suposição estiver incorreta
- Nível de confiança (Confident / Likely / Unclear)
4. **Confirmar ou corrigir** — O usuário revisa as suposições e seleciona as que precisam ser alteradas
5. **Escrever o CONTEXT.md** — Formato de saída idêntico ao do modo discuss
- Revise suposições antes do `plan-phase`
- Corrija ambiguidades de nomes/paths cedo
- Se o plano sair desalinhado, volte ao discuss-phase e refine
## Compatibilidade de Flags
---
| Flag | modo `discuss` | modo `assumptions` |
|------|----------------|-------------------|
| `--auto` | Seleciona automaticamente as respostas recomendadas | Ignora a etapa de confirmação e resolve automaticamente itens Unclear |
| `--batch` | Agrupa perguntas em lotes | N/A (correções já agrupadas) |
| `--text` | Perguntas em texto puro (sessões remotas) | Perguntas em texto puro (sessões remotas) |
| `--analyze` | Exibe tabelas de trade-off por pergunta | N/A (suposições já incluem evidências) |
> [!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.
## Saída
Ambos os modos produzem um `CONTEXT.md` idêntico com as mesmas seis seções:
- `<domain>` — Limite da fase
- `<decisions>` — Decisões de implementação confirmadas
- `<canonical_refs>` — Especificações/documentos que os agentes downstream devem ler
- `<code_context>` — Ativos reutilizáveis, padrões, pontos de integração
- `<specifics>` — Referências e preferências do usuário
- `<deferred>` — Ideias registradas para fases futuras
Os agentes downstream (researcher, planner, checker) consomem esse arquivo de forma idêntica, independentemente do modo que o produziu. Consulte o [esquema do CONTEXT.md](reference/context-md.md) para a referência completa dos campos.
## Relacionados
- [Realizar discuss de uma fase](how-to/discuss-a-phase.md) — passo a passo para executar `/gsd-discuss-phase` em qualquer modo.
- [Esquema do CONTEXT.md](reference/context-md.md) — referência completa dos campos do arquivo produzido por ambos os modos.
- [O ciclo de fases](explanation/the-phase-loop.md) — como o discuss se encaixa no ciclo mais amplo de discuss → plan → execute → verify → ship.
- [Índice de documentação](README.md) — sumário completo da documentação do GSD Core.