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

refactor: hard-fork GSD -> MSD (Make Software Done)

Browse Source 
Mechanical rename produced by scripts/msd-rename.cjs: gsd/Gsd/GSD -> msd/Msd/MSD
across contents and paths, upstream package/repo coordinates -> @golem15/msd-core
and golem15com/msd-core. Deep links into upstream history, sibling upstream
packages, the GSD-2 import feature, CHANGELOG.md and .changeset/ are kept as-is.

Hand edits on top: MSD block-letter banner and logos, LICENSE copyright line,
package/plugin identity, regenerated lockfile, install-tree fixtures, derived
registries and benchmark baseline; migration checksum baseline re-locked
(MSD keeps its own install state, so no install had applied the old sums);
sort-order and regex-escaped expectations in tests adjusted.
This commit is contained in:
Jakub Zych
2026-10-06 01:47:40 +02:00
parent fe069b2a56
commit a9a7a328e6
2763 changed files with 78465 additions and 78434 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/pt-BR/AGENTS.md
View File

@@ -1,13 +1,13 @@
# Referência de Agentes do GSD
# Referência de Agentes do MSD
Este documento descreve os papéis dos agentes especializados no ecossistema GSD.
Este documento descreve os papéis dos agentes especializados no ecossistema MSD.
Para a listagem completa com regras detalhadas, consulte [AGENTS.md em inglês](../AGENTS.md).
---
## Visão geral
O GSD usa um **orquestrador leve** para coordenar subagentes especializados por etapa:
O MSD usa um **orquestrador leve** para coordenar subagentes especializados por etapa:
- pesquisa
- planejamento

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

@@ -1,4 +1,4 @@
# Arquitetura do GSD Core
# Arquitetura do MSD Core
> 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).
@@ -21,7 +21,7 @@
## Visão Geral do Sistema
O GSD Core é um **framework de meta-prompting** que fica entre o usuário e os agentes de codificação com IA (Claude Code, Kimi CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). Ele fornece:
O MSD Core é um **framework de meta-prompting** que fica entre o usuário e os agentes de codificação com IA (Claude Code, Kimi CLI, OpenCode, Kilo, Codex, Copilot, Antigravity, Trae, Cline, Augment Code). Ele fornece:
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))
@@ -31,19 +31,19 @@ O GSD Core é um **framework de meta-prompting** que fica entre o usuário e os
```
┌──────────────────────────────────────────────────────┐
│ USUÁRIO │
│ /gsd-command [args] │
│ /msd-command [args] │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ CAMADA DE COMANDOS │
│ commands/gsd/*.md — Arquivos de comandos baseados │
│ commands/msd/*.md — Arquivos de comandos baseados │
│ em prompts (comandos customizados Claude Code / │
│ skills do Codex) │
└─────────────────────┬────────────────────────────────┘
│
┌─────────────────────▼────────────────────────────────┐
│ CAMADA DE WORKFLOWS │
│ gsd-core/workflows/*.md — Lógica de │
│ msd-core/workflows/*.md — Lógica de │
│ orquestração │
│ (Lê referências, cria agentes, gerencia estado) │
└──────┬──────────────┬─────────────────┬──────────────┘
@@ -56,7 +56,7 @@ O GSD Core é um **framework de meta-prompting** que fica entre o usuário e os
│ │ │
┌──────▼──────────────▼─────────────────▼──────────────┐
│ CAMADA DE FERRAMENTAS CLI │
│ gsd-tools.cjs command families + domain modules │
│ msd-tools.cjs command families + domain modules │
│ command-routing-hub + observability seams │
└──────────────────────┬───────────────────────────────┘
│
@@ -77,9 +77,9 @@ Cada agente criado por um orquestrador recebe uma janela de contexto limpa (até
### 2. Orquestradores Leves
Os arquivos de workflow (`gsd-core/workflows/*.md`) nunca fazem trabalho pesado. Eles:
Os arquivos de workflow (`msd-core/workflows/*.md`) nunca fazem trabalho pesado. Eles:
- Carregam contexto via `gsd-tools.cjs init <workflow>`
- Carregam contexto via `msd-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
@@ -109,33 +109,33 @@ Múltiplas camadas previnem modos comuns de falha:
## Arquitetura de Componentes
### Comandos (`commands/gsd/*.md`)
### Comandos (`commands/msd/*.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`)
- **Claude Code:** Comandos slash customizados (forma com hífen, `/msd-command-name`)
- **OpenCode / Kilo:** Comandos slash (forma com hífen, `/msd-command-name`)
- **Codex:** Skills (`$msd-command-name`)
- **Copilot:** Comandos slash (forma com hífen, `/msd-command-name`)
- **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.
Para manter baixo o custo em tokens da listagem de skills antecipada, a v1.40 introduz seis **meta-skills** de namespace (`msd-workflow`, `msd-project`, `msd-quality`, `msd-context`, `msd-manage`, `msd-ideate` — originados de `commands/msd/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.
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 MSD. 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 (`gsd-core/workflows/*.md`)
### Workflows (`msd-core/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`
- Carregamento de contexto via handlers `msd-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
@@ -146,7 +146,7 @@ Lógica de orquestração que os comandos referenciam. Contém o processo passo
#### 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
comando `/msd-*` correspondente é invocado. Para manter esse custo limitado, o
orçamento de tamanho de workflow aplicado por `tests/workflow-size-budget.test.cjs`
espelha a convenção de orçamento de tamanho de agentes:
@@ -160,7 +160,7 @@ espelha a convenção de orçamento de tamanho de agentes:
o orçamento de bytes do discuss-phase (#717; a divisão discuss-phase/modes mantém ≈32000 bytes). 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
`gsd-core/references/`. O arquivo pai se torna um despachante leve que
`msd-core/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 —
@@ -181,7 +181,7 @@ Definições de agentes especializados com frontmatter especificando:
**Total de agentes:** 33
### Referências (`gsd-core/references/*.md`)
### Referências (`msd-core/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):
@@ -219,7 +219,7 @@ Documentos de conhecimento compartilhado que workflows e agentes `@-referenciam`
**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:
Referências para integrar modelos de classe thinking (o3, o4-mini, Gemini 2.5 Pro) aos workflows do MSD:
- `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
@@ -229,15 +229,15 @@ Referências para integrar modelos de classe thinking (o3, o4-mini, Gemini 2.5 P
**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:
O agente planner (`agents/msd-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-reviews.md` — Integração de revisão entre IAs (lê REVIEWS.md do `/msd-review`)
- `planner-revision.md` — Padrões de revisão de plano para refinamento iterativo
### Templates (`gsd-core/templates/`)
### Templates (`msd-core/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:
Templates Markdown para todos os artefatos de planejamento. Usados por `msd-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
@@ -253,28 +253,28 @@ 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-secret-read-guard.js` | `PreToolUse` | Bloqueia rigorosamente leituras de `.env`, `.env.<suffix>` (exceto templates como `.env.example`) e `.secrets` via Read / Grep / Bash; substitui as regras deny `Read(.env*)` que o instalador escrevia (#4221) |
| `gsd-read-guard.js` | `PreToolUse` | Guarda consultivo que impede Edit/Write em arquivos ainda não lidos na sessão |
| `gsd-session-state.sh` | `SessionStart` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `gsd-validate-commit.sh` | `PreToolUse` | 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 |
| `msd-statusline.js` | `statusLine` | Exibe modelo, tarefa, diretório e barra de uso do contexto |
| `msd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injeta avisos de contexto voltados ao agente em 35%/25% restante |
| `msd-check-update.js` | `SessionStart` | Gatilho em primeiro plano para a verificação de atualização em segundo plano |
| `msd-check-update-worker.js` | (auxiliar) | Worker em segundo plano criado por `msd-check-update.js`; sem registro de evento direto |
| `msd-prompt-guard.js` | `PreToolUse` | Escaneia escritas em `.planning/` em busca de padrões de injeção de prompt (consultivo) |
| `msd-read-injection-scanner.js` | `PostToolUse` | Escaneia saídas da ferramenta Read em busca de instruções injetadas em conteúdo não confiável |
| `msd-workflow-guard.js` | `PreToolUse` | Detecta edições de arquivos fora do contexto de workflow do MSD (consultivo, ativado via `hooks.workflow_guard`) |
| `msd-secret-read-guard.js` | `PreToolUse` | Bloqueia rigorosamente leituras de `.env`, `.env.<suffix>` (exceto templates como `.env.example`) e `.secrets` via Read / Grep / Bash; substitui as regras deny `Read(.env*)` que o instalador escrevia (#4221) |
| `msd-read-guard.js` | `PreToolUse` | Guarda consultivo que impede Edit/Write em arquivos ainda não lidos na sessão |
| `msd-session-state.sh` | `SessionStart` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `msd-validate-commit.sh` | `PreToolUse` | Validação de commit para aplicação de commits convencionais |
| `msd-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 (`gsd-core/bin/lib/command-routing-hub.cjs`)
### Hub de Roteamento de Comandos (`msd-core/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`.
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-msd-sdk-package-boundary.md`.
### Ferramentas CLI (`gsd-core/bin/`)
### Ferramentas CLI (`msd-core/bin/`)
Utilitário CLI Node.js (`gsd-tools.cjs`) com módulos de domínio distribuídos em `gsd-core/bin/lib/` (consulte [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) para o roster oficial):
Utilitário CLI Node.js (`msd-tools.cjs`) com módulos de domínio distribuídos em `msd-core/bin/lib/` (consulte [`docs/INVENTORY.md`](INVENTORY.md#cli-modules-33-shipped) para o roster oficial):
| Módulo | Responsabilidade |
@@ -310,10 +310,10 @@ Utilitário CLI Node.js (`gsd-tools.cjs`) com módulos de domínio distribuídos
```
Orquestrador (workflow .md)
│
├── Carregar contexto: gsd-tools.cjs init <workflow> <phase>
├── Carregar contexto: msd-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>
├── Resolver modelo: msd-tools.cjs resolve-model <agent-name>
│ Retorna: opus | sonnet | haiku | inherit
│
├── Criar Agente (chamada Task/SubAgent)
@@ -324,28 +324,28 @@ Orquestrador (workflow .md)
│
├── Coletar resultado
│
└── Atualizar estado: gsd-tools.cjs state update / state patch / state advance-plan
└── Atualizar estado: msd-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).
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 `msd-pattern-mapper`, `msd-code-reviewer`, `msd-code-fixer`, `msd-ai-researcher`, `msd-domain-researcher`, `msd-eval-planner`, `msd-eval-auditor`, `msd-framework-selector`, `msd-debug-session-manager`, `msd-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) |
| **Pesquisadores** | msd-project-researcher, msd-phase-researcher, msd-ui-researcher, msd-advisor-researcher | 4 paralelos (stack, features, architecture, pitfalls); advisor criado durante a discuss-phase |
| **Sintetizadores** | msd-research-synthesizer | Sequencial (após a conclusão dos pesquisadores) |
| **Planejadores** | msd-planner, msd-roadmapper | Sequencial |
| **Verificadores de plano** | msd-plan-checker, msd-integration-checker, msd-ui-checker, msd-nyquist-auditor | Sequencial (loop de verificação, máximo 3 iterações) |
| **Executores** | msd-executor | Paralelo dentro de ondas, sequencial entre ondas |
| **Verificadores** | msd-verifier | Sequencial (após a conclusão de todos os executores) |
| **Mapeadores** | msd-codebase-mapper | 4 paralelos (tech, arch, quality, concerns) |
| **Depuradores** | msd-debugger | Sequencial (interativo) |
| **Auditores** | msd-ui-auditor, msd-security-auditor | Sequencial |
| **Escritores de doc** | msd-doc-writer, msd-doc-verifier | Sequencial (escritor depois verificador) |
| **Perfiladores** | msd-user-profiler | Sequencial |
| **Analisadores** | msd-assumptions-analyzer | Sequencial (durante a discuss-phase) |
### Modelo de Execução em Ondas
@@ -375,7 +375,7 @@ Quando a janela de contexto tem 500 mil tokens ou mais (modelos classe 1 M como
- **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.
O orquestrador lê `context_window` da configuração (`msd-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
@@ -479,10 +479,10 @@ UI-SPEC.md (por fase) ───────────────────
```
~/.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
├── gsd-core/
│ ├── bin/gsd-tools.cjs # Utilitário CLI
├── skills/msd-*/SKILL.md # Skills globais (roster oficial: docs/INVENTORY.md)
├── commands/msd/*.md # Instalações locais do Claude usam slash commands em vez de skills globais
├── msd-core/
│ ├── bin/msd-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)
@@ -520,14 +520,14 @@ Caminhos equivalentes para outros runtimes:
├── 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
├── research/ # Pesquisa de domínio do /msd-new-project
│ ├── SUMMARY.md
│ ├── STACK.md
│ ├── FEATURES.md
│ ├── ARCHITECTURE.md
│ └── PITFALLS.md
├── codebase/ # Mapeamento de brownfield (do /gsd-map-codebase ou /gsd-onboard)
├── onboarding/ # Resumo de onboarding brownfield (do /gsd-onboard)
├── codebase/ # Mapeamento de brownfield (do /msd-map-codebase ou /msd-onboard)
├── onboarding/ # Resumo de onboarding brownfield (do /msd-onboard)
│ ├── STACK.md # Frontmatter YAML carrega `last_mapped_commit`
│ ├── ARCHITECTURE.md # para o portão de desvio pós-execução (#2003)
│ ├── CONVENTIONS.md
@@ -553,19 +553,19 @@ Caminhos equivalentes para outros runtimes:
├── todos/
│ ├── pending/ # Ideias capturadas
│ └── completed/ # Todos concluídos
├── threads/ # Threads de contexto persistentes (do /gsd-thread)
├── seeds/ # Ideias prospectivas (do /gsd-capture --seed)
├── threads/ # Threads de contexto persistentes (do /msd-thread)
├── seeds/ # Ideias prospectivas (do /msd-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)
├── ui-reviews/ # Screenshots do /msd-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
Após a última onda de commits do `/msd-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
@@ -577,9 +577,9 @@ elementos estruturais:
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,
**avisa** (padrão) com o comando `/msd-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
`msd-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.
@@ -607,15 +607,15 @@ O instalador (`bin/install.js`, ~10.700 linhas) trata de:
- 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/`
- Hermes Agent: Skills por categoria em `skills/msd/`
- 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
7. **Backup de patches** — Desde a v1.17, faz backup de arquivos modificados localmente em `msd-local-patches/` para `/msd-update --reapply`
8. **Rastreamento de manifesto** — Escreve `msd-file-manifest.json` para desinstalação limpa
9. **Modo de desinstalação** — `--uninstall` remove todos os arquivos, hooks e configurações do MSD
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
@@ -642,17 +642,17 @@ O guarda de desvio de plano (`plan_review.source_grounding`) — que verifica re
```
Motor de Runtime (Claude Code / Antigravity CLI)
│
├── evento statusLine ──► gsd-statusline.js
├── evento statusLine ──► msd-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
├── evento PostToolUse/AfterTool ──► msd-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
└── evento SessionStart ──► msd-check-update.js
Lê: arquivo VERSION
Escreve: ~/.claude/cache/gsd-update-check.json (cria processo em segundo plano)
Escreve: ~/.claude/cache/msd-update-check.json (cria processo em segundo plano)
```
### Limites do Monitor de Contexto
@@ -679,15 +679,15 @@ Debounce: 5 usos de ferramenta entre avisos repetidos. A escalada de severidade
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.
**Modelo de ameaça:** O MSD 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 `gsd-tools query package-legitimacy check --ecosystem <npm\|pypi\|crates> <pkgs>`; 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 |
| Pesquisa | `msd-phase-researcher` | Executa `msd-tools query package-legitimacy check --ecosystem <npm\|pypi\|crates> <pkgs>`; escreve tabela `## Package Legitimacy Audit` no RESEARCH.md; remove pacotes `[SLOP]` antes de o RESEARCH.md ser escrito |
| Planejamento | `msd-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 | `msd-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.
@@ -703,25 +703,25 @@ O pipeline pesquisador → planner → executor inclui um portão de cadeia de s
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`):
**Prompt Guard** (`msd-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`):
**Workflow Guard** (`msd-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
- Detecta edições fora do contexto de workflow do MSD (sem comando `/msd-` ativo ou subagente Task)
- Aconselha o uso de `/msd-quick` ou `/msd-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:
O MSD 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
@@ -731,20 +731,20 @@ A propriedade específica de migração e os snapshots de fonte vivem em
| 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 |
| 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 |
| Claude Code | `~/.claude` | `./.claude` | `skills/msd-*/SKILL.md` global; `commands/msd/*.md` local | `agents/msd-*.md` | Entradas de hook e statusLine em `settings.json` |
| OpenCode | `~/.config/opencode` | `./.opencode` | `command/msd-*.md` | `agents/msd-*.md` | `opencode.json` ou `opencode.jsonc`; sem hooks do MSD |
| Kilo | `~/.config/kilo` | `./.kilo` | `command/msd-*.md` | `agents/msd-*.md` | `kilo.json` ou `kilo.jsonc`; sem hooks do MSD |
| Codex | `~/.codex` | `./.codex` | `skills/msd-*/SKILL.md` | markdown de origem de agentes mais TOML por agente | `config.toml` `[agents.msd-*]`, `[features].hooks` (canônico; alias legado `codex_hooks` é reconhecido e migrado no reinstall, #3566) e tabelas de hooks |
| GitHub Copilot | `~/.copilot` | `./.github` | `skills/msd-*/SKILL.md` e `copilot-instructions.md` | arquivos `.agent.md` | Sem hooks ou statusline do MSD |
| Antigravity | detectado automaticamente: `~/.gemini/antigravity`, `~/.gemini/antigravity-ide`, ou `~/.gemini/antigravity-cli` | `./.agent` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Entradas de hook `settings.json` no estilo Gemini quando instalado pelo MSD |
| Cursor | `~/.cursor` | `./.cursor` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Referências de regras em `rules/`; sem hooks do MSD |
| Windsurf | `~/.codeium/windsurf` | `./.windsurf` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Referências de regras em `rules/`; sem hooks do MSD |
| Augment Code | `~/.augment` | `./.augment` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Sem hooks ou statusline do MSD |
| Trae | `~/.trae` | `./.trae` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Referências de regras em `rules/`; sem hooks do MSD |
| Qwen Code | `~/.qwen` | `./.qwen` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Configurações comuns do MSD e entradas de hook onde suportado |
| Hermes Agent | `~/.hermes` | `./.hermes` | `skills/msd/DESCRIPTION.md` mais `skills/msd/msd-*/SKILL.md` | `agents/msd-*.md` | Configurações comuns do MSD e entradas de hook onde suportado |
| CodeBuddy | `~/.codebuddy` | `./.codebuddy` | `skills/msd-*/SKILL.md` | `agents/msd-*.md` | Configurações comuns do MSD e entradas de hook onde suportado |
| Cline | `~/.cline` | raiz do projeto | `.clinerules` | Somente regras | Sem hooks ou statusline do MSD |
### Fontes do Contrato Upstream
@@ -764,7 +764,7 @@ disponível. O snapshot de fonte atual é 2026-05-11:
2. **Nomes de eventos de hook** — Claude usa `PostToolUse`, Antigravity 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
5. **Referências de modelo** — O perfil `inherit` permite que o MSD 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.

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

@@ -1,25 +1,25 @@
# Referência de Ferramentas CLI do GSD
# Referência de Ferramentas CLI do MSD
> Referência para o CLI `gsd-tools` (`gsd-core/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).
> Referência para o CLI `msd-tools` (`msd-core/bin/msd-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).
---
## Visão Geral
`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.
`msd-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 MSD.
| | |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Caminho instalado** | `gsd-core/bin/gsd-tools.cjs` |
| **Implementação** | 20 módulos de domínio em `gsd-core/bin/lib/` (o diretório é autoritativo) |
| **Caminho instalado** | `msd-core/bin/msd-tools.cjs` |
| **Implementação** | 20 módulos de domínio em `msd-core/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. |
**Uso (CJS):**
```bash
node gsd-tools.cjs <command> [args] [--raw] [--cwd <path>]
node msd-tools.cjs <command> [args] [--raw] [--cwd <path>]
```
**Flags globais (CJS):**
@@ -40,47 +40,47 @@ 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
node msd-tools.cjs state load
# Exibe o frontmatter do STATE.md como JSON
node gsd-tools.cjs state json
node msd-tools.cjs state json
# Atualiza um único campo
node gsd-tools.cjs state update <field> <value>
node msd-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]
node msd-tools.cjs state get [section]
# Atualiza múltiplos campos em lote
node gsd-tools.cjs state patch --field1 val1 --field2 val2
node msd-tools.cjs state patch --field1 val1 --field2 val2
# Incrementa o contador de planos
node gsd-tools.cjs state advance-plan
node msd-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]
node msd-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
node msd-tools.cjs state update-progress
# Adiciona uma decisão
node gsd-tools.cjs state add-decision --summary "..." [--phase N] [--rationale "..."]
node msd-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]
node msd-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 "..."
node msd-tools.cjs state add-blocker --text "..."
node msd-tools.cjs state resolve-blocker --text "..."
# Registra continuidade da sessão
node gsd-tools.cjs state record-session --stopped-at "..." [--resume-file path]
node msd-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
node msd-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
node msd-tools.cjs state signal-waiting --type TYPE --question "..." --options "A|B" --phase P
node msd-tools.cjs state signal-resume
```
### Snapshot de Estado
@@ -88,7 +88,7 @@ node gsd-tools.cjs state signal-resume
Análise estruturada do STATE.md completo:
```bash
node gsd-tools.cjs state-snapshot
node msd-tools.cjs state-snapshot
```
Retorna JSON com: posição atual, fase, plano, status, decisões, bloqueadores, métricas, última atividade.
@@ -101,28 +101,28 @@ 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>
node msd-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>
node msd-tools.cjs phase next-decimal <phase>
# Adiciona nova fase ao roadmap + cria diretório
node gsd-tools.cjs phase add <description>
node msd-tools.cjs phase add <description>
# Insere fase decimal após a existente
node gsd-tools.cjs phase insert <after> <description>
node msd-tools.cjs phase insert <after> <description>
# Remove fase, renumera as subsequentes
node gsd-tools.cjs phase remove <phase> [--force]
node msd-tools.cjs phase remove <phase> [--force]
# Marca a fase como concluída, atualiza estado + roadmap
node gsd-tools.cjs phase complete <phase>
node msd-tools.cjs phase complete <phase>
# Indexa planos com ondas e status
node gsd-tools.cjs phase-plan-index <phase>
node msd-tools.cjs phase-plan-index <phase>
# Lista fases com filtragem
node gsd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
node msd-tools.cjs phases list [--type planned|executed|all] [--phase N] [--include-archived]
```
---
@@ -133,13 +133,13 @@ Analisa e atualiza o `ROADMAP.md`.
```bash
# Extrai a seção de fase do ROADMAP.md
node gsd-tools.cjs roadmap get-phase <phase>
node msd-tools.cjs roadmap get-phase <phase>
# Análise completa do roadmap com status em disco
node gsd-tools.cjs roadmap analyze
node msd-tools.cjs roadmap analyze
# Atualiza linha da tabela de progresso a partir do disco
node gsd-tools.cjs roadmap update-plan-progress <N>
node msd-tools.cjs roadmap update-plan-progress <N>
```
---
@@ -150,16 +150,16 @@ Lê e grava em `.planning/config.json`.
```bash
# Inicializa config.json com valores padrão
node gsd-tools.cjs config-ensure-section
node msd-tools.cjs config-ensure-section
# Define um valor de configuração (notação de ponto)
node gsd-tools.cjs config-set <key> <value>
node msd-tools.cjs config-set <key> <value>
# Obtém um valor de configuração
node gsd-tools.cjs config-get <key>
node msd-tools.cjs config-get <key>
# Define o perfil de modelo
node gsd-tools.cjs config-set-model-profile <profile>
node msd-tools.cjs config-set-model-profile <profile>
```
---
@@ -168,13 +168,13 @@ node gsd-tools.cjs config-set-model-profile <profile>
```bash
# Obtém o modelo para um agente com base no perfil atual
node gsd-tools.cjs resolve-model <agent-name>
node msd-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`
Nomes de agentes: `msd-planner`, `msd-executor`, `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-roadmapper`, `msd-debugger`, `msd-codebase-mapper`, `msd-nyquist-auditor`
---
@@ -184,25 +184,25 @@ Valida planos, fases, referências e commits.
```bash
# Verifica arquivo SUMMARY.md
node gsd-tools.cjs verify-summary <path> [--check-count N]
node msd-tools.cjs verify-summary <path> [--check-count N]
# Verifica estrutura + tarefas do PLAN.md
node gsd-tools.cjs verify plan-structure <file>
node msd-tools.cjs verify plan-structure <file>
# Verifica se todos os planos têm resumos
node gsd-tools.cjs verify phase-completeness <phase>
node msd-tools.cjs verify phase-completeness <phase>
# Verifica se @-refs + caminhos resolvem
node gsd-tools.cjs verify references <file>
node msd-tools.cjs verify references <file>
# Verifica hashes de commit em lote
node gsd-tools.cjs verify commits <hash1> [hash2] ...
node msd-tools.cjs verify commits <hash1> [hash2] ...
# Verifica must_haves.artifacts
node gsd-tools.cjs verify artifacts <plan-file>
node msd-tools.cjs verify artifacts <plan-file>
# Verifica must_haves.key_links
node gsd-tools.cjs verify key-links <plan-file>
node msd-tools.cjs verify key-links <plan-file>
```
---
@@ -213,21 +213,21 @@ Verifica a integridade do projeto.
```bash
# Verifica numeração de fases, sincronização disco/roadmap
node gsd-tools.cjs validate consistency
node msd-tools.cjs validate consistency
# Verifica integridade de .planning/, com opção de reparo
node gsd-tools.cjs validate health [--repair]
node msd-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
node msd-tools.cjs validate context
# Utilização de contexto como superfície JSON tipada (#455)
node gsd-tools.cjs validate context --json
node msd-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`.
string `suggestion`. Os mesmos dados sustentam `/msd-health --context`.
Passe `--json` para receber o IR tipado diretamente (útil em scripts e asserções de teste).
---
@@ -238,10 +238,10 @@ Seleção e preenchimento de templates.
```bash
# Seleciona o template de resumo com base na granularidade
node gsd-tools.cjs template select <type>
node msd-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}']
node msd-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`
@@ -254,16 +254,16 @@ Operações CRUD de frontmatter YAML em qualquer arquivo Markdown.
```bash
# Extrai frontmatter como JSON
node gsd-tools.cjs frontmatter get <file> [--field key]
node msd-tools.cjs frontmatter get <file> [--field key]
# Atualiza único campo
node gsd-tools.cjs frontmatter set <file> --field key --value jsonVal
node msd-tools.cjs frontmatter set <file> --field key --value jsonVal
# Mescla JSON no frontmatter
node gsd-tools.cjs frontmatter merge <file> --data '{json}'
node msd-tools.cjs frontmatter merge <file> --data '{json}'
# Valida campos obrigatórios
node gsd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
node msd-tools.cjs frontmatter validate <file> --schema plan|summary|verification
```
---
@@ -274,48 +274,48 @@ Cria arquivos e diretórios pré-estruturados.
```bash
# Cria template CONTEXT.md
node gsd-tools.cjs scaffold context --phase N
node msd-tools.cjs scaffold context --phase N
# Cria template UAT.md
node gsd-tools.cjs scaffold uat --phase N
node msd-tools.cjs scaffold uat --phase N
# Cria template VERIFICATION.md
node gsd-tools.cjs scaffold verification --phase N
node msd-tools.cjs scaffold verification --phase N
# Cria diretório de fase
node gsd-tools.cjs scaffold phase-dir --phase N --name "phase name"
node msd-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. `init onboard [--fast] [--text]` retorna, para `/gsd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.
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. `init onboard [--fast] [--text]` retorna, para `/msd-onboard`, sinais de brownfield, candidatos a docs de planning, completude do mapa de código, prontidão do mapa fast, roteamento em modo texto, estado parcial de planning e status do resumo de onboarding.
```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 onboard [--fast] [--text]
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
node msd-tools.cjs init execute-phase <phase>
node msd-tools.cjs init plan-phase <phase>
node msd-tools.cjs init new-project
node msd-tools.cjs init new-milestone
node msd-tools.cjs init onboard [--fast] [--text]
node msd-tools.cjs init quick <description>
node msd-tools.cjs init resume
node msd-tools.cjs init verify-work <phase>
node msd-tools.cjs init phase-op <phase>
node msd-tools.cjs init todos [area]
node msd-tools.cjs init milestone-op
node msd-tools.cjs init map-codebase
node msd-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>
node msd-tools.cjs init execute-phase <phase> --ws <name>
node msd-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:
**Tratamento de payloads grandes:** Quando a saída excede ~50KB, o CLI grava em um arquivo temporário e retorna `@file:/tmp/msd-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")
INIT=$(node msd-tools.cjs init execute-phase "1")
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```
@@ -325,10 +325,10 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
```bash
# Arquiva milestone
node gsd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
node msd-tools.cjs milestone complete <version> (--confirm | --dry-run) [--name <name>] [--no-archive-phases] [--force] [--archive-quick]
# Marca requisitos como concluídos
node gsd-tools.cjs requirements mark-complete <ids>
node msd-tools.cjs requirements mark-complete <ids>
# Aceita: REQ-01,REQ-02 ou REQ-01 REQ-02 ou [REQ-01, REQ-02]
```
@@ -340,10 +340,10 @@ 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>
node msd-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
node msd-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.
@@ -356,13 +356,13 @@ Pré-computa e armazena em cache a descoberta de habilidades para carregamento m
```bash
# Gera manifesto de habilidades (grava em .claude/skill-manifest.json)
node gsd-tools.cjs skill-manifest
node msd-tools.cjs skill-manifest
# Gera com caminho de saída personalizado
node gsd-tools.cjs skill-manifest --output <path>
node msd-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.
Retorna mapeamento JSON de todas as habilidades MSD 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.
---
@@ -370,47 +370,47 @@ Retorna mapeamento JSON de todas as habilidades GSD disponíveis com seus metada
```bash
# Converte texto em slug seguro para URL
node gsd-tools.cjs generate-slug "Some Text Here"
node msd-tools.cjs generate-slug "Some Text Here"
# → some-text-here
# Obtém timestamp
node gsd-tools.cjs current-timestamp [full|date|filename]
node msd-tools.cjs current-timestamp [full|date|filename]
# Conta e lista tarefas pendentes
node gsd-tools.cjs list-todos [area]
node msd-tools.cjs list-todos [area]
# Verifica existência de arquivo/diretório
node gsd-tools.cjs verify-path-exists <path>
node msd-tools.cjs verify-path-exists <path>
# Agrega todos os dados de SUMMARY.md
node gsd-tools.cjs history-digest
node msd-tools.cjs history-digest
# Extrai dados estruturados de SUMMARY.md
node gsd-tools.cjs summary-extract <path> [--fields field1,field2]
node msd-tools.cjs summary-extract <path> [--fields field1,field2]
# Estatísticas do projeto
node gsd-tools.cjs stats [json|table]
node msd-tools.cjs stats [json|table]
# Renderização de progresso (legível por humanos)
node gsd-tools.cjs progress [json|table|bar]
node msd-tools.cjs progress [json|table|bar]
# Progresso como superfície JSON tipada (#455)
node gsd-tools.cjs progress --json
node msd-tools.cjs progress --json
# Conclui uma tarefa
node gsd-tools.cjs todo complete <filename> [--dry-run]
node msd-tools.cjs todo complete <filename> [--dry-run]
# Auditoria UAT — verifica todas as fases em busca de itens não resolvidos
node gsd-tools.cjs audit-uat
node msd-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]
node msd-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]
# Migração reversa de um projeto GSD-2 para a estrutura atual (suporta `/msd-import --from-gsd2`)
node msd-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]
node msd-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.
@@ -418,7 +418,7 @@ node gsd-tools.cjs commit <message> [--files f1 f2] [--amend] [--no-verify] [--r
```bash
# Busca na web (requer chave de API do Brave)
node gsd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
node msd-tools.cjs websearch <query> [--limit N] [--freshness day|week|month]
```
---
@@ -429,22 +429,22 @@ Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.plannin
```bash
# Constrói ou reconstrói o grafo de conhecimento
node gsd-tools.cjs graphify build
node msd-tools.cjs graphify build
# Pesquisa um termo no grafo
node gsd-tools.cjs graphify query <term>
node msd-tools.cjs graphify query <term>
# Exibe atualidade e estatísticas do grafo
node gsd-tools.cjs graphify status
node msd-tools.cjs graphify status
# Exibe alterações desde a última construção
node gsd-tools.cjs graphify diff
node msd-tools.cjs graphify diff
# Grava um snapshot nomeado do grafo atual
node gsd-tools.cjs graphify snapshot [name]
node msd-tools.cjs graphify snapshot [name]
```
Ponto de entrada para o usuário: `/gsd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#gsd-graphify)).
Ponto de entrada para o usuário: `/msd-graphify` (consulte a [Referência de Comandos](COMMANDS.md#msd-graphify)).
---
@@ -468,30 +468,30 @@ Ponto de entrada para o usuário: `/gsd-graphify` (consulte a [Referência de Co
| 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`) |
| Graphify | `lib/graphify.cjs` | Construção/consulta/status/diff/snapshot do grafo de conhecimento (suporta `/msd-graphify`) |
| Learnings | `lib/learnings.cjs` | Extrai aprendizados de artefatos de fases/SUMMARY (suporta `/msd-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`) |
| MSD2 Import | `lib/gsd2-import.cjs` | Importador de migração reversa de projetos GSD-2 (suporta `/msd-import --from-gsd2`) |
| Intel | `lib/intel.cjs` | Índice de inteligência de código consultável (suporta `/msd-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:
`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 [`/msd-config --integrations`](COMMANDS.md#msd-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.agy "gemini-3.1-pro-preview"
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
node msd-tools.cjs config-set review.models.codex "codex exec --model gpt-5"
node msd-tools.cjs config-set review.models.agy "gemini-3.1-pro-preview"
node msd-tools.cjs config-set review.models.opencode "opencode run --model claude-sonnet-4"
node msd-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 `gsd-core/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).
As chaves de API configuradas via `/msd-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 `msd-core/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).
---

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

File diff suppressed because it is too large Load Diff

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

@@ -1,4 +1,4 @@
# Referência de Configuração do GSD
# Referência de Configuração do MSD
Referência completa do esquema para `.planning/config.json`. Para tutoriais de configuração e guias orientados a tarefas, consulte o [índice da documentação](README.md).
@@ -8,7 +8,7 @@ Referência completa do esquema para `.planning/config.json`. Para tutoriais de
## Arquivo de Configuração
O GSD armazena as configurações do projeto em `.planning/config.json`. Criado durante `/gsd-new-project`, atualizado via `/gsd-settings`.
O MSD armazena as configurações do projeto em `.planning/config.json`. Criado durante `/msd-new-project`, atualizado via `/msd-settings`.
### Esquema Completo
@@ -99,8 +99,8 @@ O GSD armazena as configurações do projeto em `.planning/config.json`. Criado
"git": {
"branching_strategy": "none",
"create_tag": true,
"phase_branch_template": "gsd/phase-{phase}-{slug}",
"milestone_branch_template": "gsd/{milestone}-{slug}",
"phase_branch_template": "msd/phase-{phase}-{slug}",
"milestone_branch_template": "msd/{milestone}-{slug}",
"quick_branch_template": null
},
"gates": {
@@ -146,7 +146,7 @@ O GSD armazena as configurações do projeto em `.planning/config.json`. Criado
| `runtime` | string | `claude`, `codex`, ou qualquer string | (nenhum) | Runtime ativo para [resolução de perfil com reconhecimento de runtime](#runtime-aware-profiles-2517). Quando definido, os níveis de perfil (opus/sonnet/haiku) resolvem para IDs de modelo nativos do runtime. Atualmente, apenas o caminho de instalação do Codex emite IDs de modelo por agente a partir deste resolvedor; outros runtimes (`opencode`, `gemini`, `qwen`, `copilot`, …) consomem o resolvedor no momento do spawn e ganham suporte a caminho de instalação dedicado em [#2612](https://github.com/open-gsd/gsd-core/issues/2612). Quando não definido (padrão), o comportamento não se altera em relação às versões anteriores. Adicionado na v1.39 |
| `model_profile_overrides.<runtime>.<tier>` | string \| object | substituição de nível por runtime | (nenhum) | Substitui o mapeamento de nível com reconhecimento de runtime para um `(runtime, tier)` específico. O nível é um de `opus`, `sonnet`, `haiku`. O valor é uma string de ID de modelo (por exemplo, `"gpt-5-pro"`) ou `{ model, reasoning_effort }`. Consulte [Perfis com Reconhecimento de Runtime](#runtime-aware-profiles-2517). Adicionado na v1.39 |
| `model_policy.provider` | string | `openai`, `anthropic`, `anthropic-fable`, `google`, `qwen`, `generic` | (nenhum) | Declara o provedor de modelo. Provedores conhecidos (`openai`, `anthropic`, `anthropic-fable`, `google`, `qwen`) desbloqueiam predefinições baseadas em catálogo. `generic` trata todos os IDs de modelo como strings opacas — sem inferência de prefixo, sem padrões de esforço de raciocínio. `model_policy.runtime_tiers` resolve antes do legado `model_profile_overrides`. Consulte [Predefinições de Política de Modelo](#model-policy-presets-model_policy--added-in-v142). Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.budget` | enum | `high`, `medium`, `low` | (nenhum) | Seleciona um nível de orçamento ao usar um provedor conhecido. O GSD materializa a predefinição de catálogo correspondente em mapeamentos de nível explícitos no momento da resolução. Ignorado quando `provider` é `generic` ou `custom`. Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.budget` | enum | `high`, `medium`, `low` | (nenhum) | Seleciona um nível de orçamento ao usar um provedor conhecido. O MSD materializa a predefinição de catálogo correspondente em mapeamentos de nível explícitos no momento da resolução. Ignorado quando `provider` é `generic` ou `custom`. Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.high` | string | ID do modelo | (nenhum) | ID do modelo de nível de custo alto para provedor `generic`/`custom`. Usado quando `provider: "generic"` ou `"custom"`. Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.medium` | string | ID do modelo | (nenhum) | ID do modelo de nível de custo médio para provedor `generic`/`custom`. Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
| `model_policy.low` | string | ID do modelo | (nenhum) | ID do modelo de nível de custo baixo para provedor `generic`/`custom`. Adicionado na v1.42 ([#49](https://github.com/open-gsd/gsd-core/issues/49)) |
@@ -157,17 +157,17 @@ O GSD armazena as configurações do projeto em `.planning/config.json`. Criado
| `dynamic_routing.escalate_on_failure` | boolean | `true`, `false` | `true` | Quando `false`, a escalada é desabilitada mesmo se `enabled: true` — cada tentativa usa o nível padrão. Adicionado na v1.40 |
| `dynamic_routing.max_escalations` | integer | `0`, `1`, `2`, … | `1` | Limite máximo de tentativas por invocação de agente. Além do limite, o resolvedor retorna o modelo do nível-limite. Adicionado na v1.40 |
| `project_code` | string | qualquer string curta | (nenhum) | Prefixo para nomes de diretórios de fase (por exemplo, `"ABC"` produz `ABC-01-setup/`). Adicionado na v1.31 |
| `phase_id_convention` | enum | `"milestone-prefixed"`, `null` | `null` | Convenção de nomenclatura para IDs de fase. `null` = IDs numéricos legados (`Phase 1`, `Phase 2`). `"milestone-prefixed"` = IDs globalmente únicos que codificam o marco envolvente (`Phase 1-01`, `Phase 1-02`). Execute `gsd-tools roadmap upgrade --convention milestone-prefixed` para migrar um ROADMAP.md existente. |
| `phase_id_convention` | enum | `"milestone-prefixed"`, `null` | `null` | Convenção de nomenclatura para IDs de fase. `null` = IDs numéricos legados (`Phase 1`, `Phase 2`). `"milestone-prefixed"` = IDs globalmente únicos que codificam o marco envolvente (`Phase 1-01`, `Phase 1-02`). Execute `msd-tools roadmap upgrade --convention milestone-prefixed` para migrar um ROADMAP.md existente. |
| `response_language` | string | código de idioma | (nenhum) | Idioma para respostas dos agentes (por exemplo, `"pt"`, `"ko"`, `"ja"`). Propagado para todos os agentes gerados para consistência de idioma entre fases. Adicionado na v1.32 |
| `context_window` | number | qualquer inteiro | `200000` | Tamanho da janela de contexto em tokens. Defina `1000000` para modelos com contexto de 1M (por exemplo, `claude-fable-5`). Valores `>= 500000` habilitam enriquecimento adaptativo de contexto (leituras completas de SUMMARY.md anteriores, leituras mais profundas de antipadrões). Configurado via `/gsd-config --advanced`. |
| `context_window` | number | qualquer inteiro | `200000` | Tamanho da janela de contexto em tokens. Defina `1000000` para modelos com contexto de 1M (por exemplo, `claude-fable-5`). Valores `>= 500000` habilitam enriquecimento adaptativo de contexto (leituras completas de SUMMARY.md anteriores, leituras mais profundas de antipadrões). Configurado via `/msd-config --advanced`. |
| `context_profile` | string | `dev`, `research`, `review` | (nenhum) | Predefinição de contexto de execução que aplica um conjunto pré-configurado de configurações de modo, modelo e fluxo de trabalho para o tipo atual de trabalho. Adicionado na v1.34 |
| `claude_md_path` | string | qualquer caminho de arquivo | `./CLAUDE.md` | Caminho de saída personalizado para o arquivo CLAUDE.md gerado. Útil para monorepos ou projetos que precisam do CLAUDE.md em um local fora da raiz. Padrão é `./CLAUDE.md` na raiz do projeto. Adicionado na v1.36 |
| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | Controla como as seções gerenciadas são escritas no CLAUDE.md. `embed` (padrão) incorpora conteúdo entre marcadores GSD. `link` escreve `@.planning/<source-path>` — o Claude Code expande a referência em tempo de execução, reduzindo o tamanho do CLAUDE.md em ~65% em projetos típicos. `link` aplica-se apenas a seções que possuem um arquivo-fonte real; as seções `workflow` e fallback sempre são incorporadas. Substituições por bloco: `claude_md_assembly.blocks.<section>` (por exemplo `claude_md_assembly.blocks.architecture: link`). Adicionado na v1.38 |
| `claude_md_assembly.mode` | enum | `embed`, `link` | `embed` | Controla como as seções gerenciadas são escritas no CLAUDE.md. `embed` (padrão) incorpora conteúdo entre marcadores MSD. `link` escreve `@.planning/<source-path>` — o Claude Code expande a referência em tempo de execução, reduzindo o tamanho do CLAUDE.md em ~65% em projetos típicos. `link` aplica-se apenas a seções que possuem um arquivo-fonte real; as seções `workflow` e fallback sempre são incorporadas. Substituições por bloco: `claude_md_assembly.blocks.<section>` (por exemplo `claude_md_assembly.blocks.architecture: link`). Adicionado na v1.38 |
| `context` | string | qualquer texto | (nenhum) | String de contexto personalizado injetada em todos os prompts de agente do projeto. Use para fornecer orientações persistentes específicas do projeto (por exemplo, convenções de código, práticas da equipe) que todos os agentes devem conhecer |
| `phase_naming` | string | qualquer string | (nenhum) | Prefixo personalizado para nomes de diretórios de fase. Quando definido, substitui o slug de fase gerado automaticamente (por exemplo, `"feature"` produz `feature-01-setup/` em vez do slug derivado do roadmap) |
| `brave_search` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Brave Search. Quando não definido, o GSD verifica a variável de ambiente `BRAVE_API_KEY` ou o arquivo `~/.gsd/brave_api_key` |
| `firecrawl` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Firecrawl. Quando não definido, o GSD verifica a variável de ambiente `FIRECRAWL_API_KEY` ou o arquivo `~/.gsd/firecrawl_api_key` |
| `exa_search` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Exa Search. Quando não definido, o GSD verifica a variável de ambiente `EXA_API_KEY` ou o arquivo `~/.gsd/exa_api_key` |
| `brave_search` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Brave Search. Quando não definido, o MSD verifica a variável de ambiente `BRAVE_API_KEY` ou o arquivo `~/.msd/brave_api_key` |
| `firecrawl` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Firecrawl. Quando não definido, o MSD verifica a variável de ambiente `FIRECRAWL_API_KEY` ou o arquivo `~/.msd/firecrawl_api_key` |
| `exa_search` | boolean | `true`/`false` | detectado automaticamente | Substitui a detecção automática de disponibilidade da API Exa Search. Quando não definido, o MSD verifica a variável de ambiente `EXA_API_KEY` ou o arquivo `~/.msd/exa_api_key` |
| `search_gitignored` | boolean | `true`/`false` | `false` | Alias legado de nível superior para `planning.search_gitignored`. Prefira a forma com namespace; este alias é aceito para compatibilidade retroativa |
> **Nota:** `granularity` foi renomeado de `depth` na v1.22.3. Configurações existentes são migradas automaticamente.
@@ -176,11 +176,11 @@ O GSD armazena as configurações do projeto em `.planning/config.json`. Criado
## Configurações de Integração
Configuradas interativamente via [`/gsd-config --integrations`](COMMANDS.md#gsd-config). Estas são configurações de *conectividade* — chaves de API e roteamento entre ferramentas — e são mantidas intencionalmente separadas de `/gsd-settings` (controles de fluxo de trabalho).
Configuradas interativamente via [`/msd-config --integrations`](COMMANDS.md#msd-config). Estas são configurações de *conectividade* — chaves de API e roteamento entre ferramentas — e são mantidas intencionalmente separadas de `/msd-settings` (controles de fluxo de trabalho).
### Chaves de API de Busca
Os campos de chave de API aceitam um valor string (a própria chave). Também podem ser definidos como os valores especiais `true`/`false`/`null` para substituir a detecção automática de variáveis de ambiente / arquivos `~/.gsd/*_api_key` (comportamento legado, consulte as linhas acima).
Os campos de chave de API aceitam um valor string (a própria chave). Também podem ser definidos como os valores especiais `true`/`false`/`null` para substituir a detecção automática de variáveis de ambiente / arquivos `~/.msd/*_api_key` (comportamento legado, consulte as linhas acima).
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
@@ -188,7 +188,7 @@ Os campos de chave de API aceitam um valor string (a própria chave). Também po
| `firecrawl` | string \| boolean \| null | `null` | Chave de API Firecrawl para raspagem profunda. Mascarada na exibição |
| `exa_search` | string \| boolean \| null | `null` | Chave de API Exa Search para busca semântica. Mascarada na exibição |
**Convenção de mascaramento (`gsd-core/bin/lib/secrets.cjs`):** chaves com 8 ou mais caracteres são renderizadas como `****<últimos-4>`; chaves menores são renderizadas como `****`; `null`/vazio é renderizado como `(unset)`. O texto simples é escrito como está em `.planning/config.json` — esse arquivo é o limite de segurança — mas a CLI, tabelas de confirmação, logs e descrições de `AskUserQuestion` nunca exibem o texto simples. Isso se aplica à própria saída do comando `config-set`: `config-set brave_search <chave>` retorna um payload JSON com o valor mascarado.
**Convenção de mascaramento (`msd-core/bin/lib/secrets.cjs`):** chaves com 8 ou mais caracteres são renderizadas como `****<últimos-4>`; chaves menores são renderizadas como `****`; `null`/vazio é renderizado como `(unset)`. O texto simples é escrito como está em `.planning/config.json` — esse arquivo é o limite de segurança — mas a CLI, tabelas de confirmação, logs e descrições de `AskUserQuestion` nunca exibem o texto simples. Isso se aplica à própria saída do comando `config-set`: `config-set brave_search <chave>` retorna um payload JSON com o valor mascarado.
### Roteamento de CLI para Revisão de Código
@@ -202,13 +202,13 @@ Os campos de chave de API aceitam um valor string (a própria chave). Também po
O slug `<cli>` é validado contra `[a-zA-Z0-9_-]+`. Slugs vazios ou que contenham caminhos são rejeitados pelo `config-set`.
### Revisores Padrão para `/gsd-review`
### Revisores Padrão para `/msd-review`
Use `review.default_reviewers` para limitar a execução de `/gsd-review` sem flags a um subconjunto de revisores detectados.
Use `review.default_reviewers` para limitar a execução de `/msd-review` sem flags a um subconjunto de revisores detectados.
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `review.default_reviewers` | string[] \| null | `null` (todos os revisores detectados) | Subconjunto padrão opcional para `/gsd-review` sem flags, por exemplo `["codex","claude"]`. Precedência: flags de revisor explícitas > `--all` > `review.default_reviewers` > todos detectados. Slugs desconhecidos são ignorados com aviso; slugs conhecidos mas não detectados são ignorados com uma nota informativa; arrays vazios são rejeitados pelo `config-set`. |
| `review.default_reviewers` | string[] \| null | `null` (todos os revisores detectados) | Subconjunto padrão opcional para `/msd-review` sem flags, por exemplo `["codex","claude"]`. Precedência: flags de revisor explícitas > `--all` > `review.default_reviewers` > todos detectados. Slugs desconhecidos são ignorados com aviso; slugs conhecidos mas não detectados são ignorados com uma nota informativa; arrays vazios são rejeitados pelo `config-set`. |
Exemplo:
@@ -222,7 +222,7 @@ Exemplo:
### Injeção de Habilidades de Agente (dinâmica)
`agent_skills.<agent-type>` estende o mapa `agent_skills` documentado abaixo. O slug é validado contra `[a-zA-Z0-9_-]+` — sem separadores de caminho, sem espaços em branco, sem metacaracteres shell. Configurado interativamente via `/gsd-config --integrations`.
`agent_skills.<agent-type>` estende o mapa `agent_skills` documentado abaixo. O slug é validado contra `[a-zA-Z0-9_-]+` — sem separadores de caminho, sem espaços em branco, sem metacaracteres shell. Configurado interativamente via `/msd-config --integrations`.
---
@@ -238,61 +238,61 @@ Todos os controles de fluxo de trabalho seguem o padrão **ausente = habilitado*
| `workflow.auto_advance` | boolean | `false` | Encadeia automaticamente discuss → plan → execute sem parar |
| `workflow.nyquist_validation` | boolean | `true` | Mapeamento de cobertura de testes durante a pesquisa de fase de planejamento |
| `workflow.ui_phase` | boolean | `true` | Gera contratos de design de UI para fases de frontend |
| `workflow.ui_safety_gate` | boolean | `true` | Solicita executar /gsd-ui-phase para fases de frontend durante a fase de planejamento |
| `workflow.ui_review` | boolean | `true` | Executa auditoria de qualidade visual (`/gsd-ui-review`) após execução de fase no modo autônomo. Quando `false`, o passo de auditoria de UI é ignorado. |
| `workflow.ui_safety_gate` | boolean | `true` | Solicita executar /msd-ui-phase para fases de frontend durante a fase de planejamento |
| `workflow.ui_review` | boolean | `true` | Executa auditoria de qualidade visual (`/msd-ui-review`) após execução de fase no modo autônomo. Quando `false`, o passo de auditoria de UI é ignorado. |
| `workflow.node_repair` | boolean | `true` | Reparação autônoma de tarefas em falha de verificação |
| `workflow.node_repair_budget` | number | `2` | Máximo de tentativas de reparo por tarefa com falha |
| `workflow.research_before_questions` | boolean | `false` | Executa pesquisa antes das perguntas de discussão em vez de após |
| `workflow.discuss_mode` | string | `'discuss'` | Controla como `/gsd-discuss-phase` coleta contexto. `'discuss'` (padrão) faz perguntas uma a uma. `'assumptions'` lê a base de código primeiro, gera premissas estruturadas com níveis de confiança e só pede para corrigir o que está errado. Adicionado na v1.28 |
| `workflow.discuss_mode` | string | `'discuss'` | Controla como `/msd-discuss-phase` coleta contexto. `'discuss'` (padrão) faz perguntas uma a uma. `'assumptions'` lê a base de código primeiro, gera premissas estruturadas com níveis de confiança e só pede para corrigir o que está errado. Adicionado na v1.28 |
| `workflow.max_discuss_passes` | number | `3` | Número máximo de rodadas de perguntas na fase de discussão antes que o fluxo de trabalho pare de perguntar. Útil em modo headless/automático para evitar loops de discussão infinitos. |
| `workflow.skip_discuss` | boolean | `false` | Quando `true`, `/gsd-autonomous` ignora totalmente a fase de discussão, escrevendo um CONTEXT.md mínimo a partir do objetivo de fase do ROADMAP. Útil para projetos onde as preferências do desenvolvedor estão totalmente capturadas em PROJECT.md/REQUIREMENTS.md. Adicionado na v1.28 |
| `workflow.skip_discuss` | boolean | `false` | Quando `true`, `/msd-autonomous` ignora totalmente a fase de discussão, escrevendo um CONTEXT.md mínimo a partir do objetivo de fase do ROADMAP. Útil para projetos onde as preferências do desenvolvedor estão totalmente capturadas em PROJECT.md/REQUIREMENTS.md. Adicionado na v1.28 |
| `workflow.text_mode` | boolean | `false` | Substitui menus TUI de AskUserQuestion por listas numeradas em texto simples. Necessário para sessões remotas do Claude Code (modo `/rc`) onde menus TUI não são renderizados. Também pode ser definido por sessão com a flag `--text` na fase de discussão. Adicionado na v1.28 |
| `workflow.use_worktrees` | boolean | `true` | Quando `false`, desabilita o isolamento de worktree git para execução paralela. Usuários que preferem execução sequencial ou cujo ambiente não suporta worktrees podem desabilitar isso. Adicionado na v1.31 |
| `workflow.worktree_skip_hooks` | boolean | `false` | Quando `true`, os agentes executores no modo worktree passam `--no-verify` (ignorando hooks de pré-commit) e a validação de hook pós-onda é executada contra o resultado mesclado. Válvula de escape opt-in para projetos cujos hooks não podem ser executados em worktrees de agente. Padrão `false` executa hooks em cada commit (#2924). |
| `workflow.code_review` | boolean | `true` | Habilita os comandos `/gsd-code-review` e `/gsd-code-review --fix`. Quando `false`, os comandos saem com uma mensagem de gate de configuração. Adicionado na v1.34 |
| `workflow.code_review_depth` | string | `standard` | Profundidade de revisão padrão para `/gsd-code-review`: `quick` (somente correspondência de padrão), `standard` (análise por arquivo) ou `deep` (entre arquivos com grafos de importação). Pode ser substituído por execução com `--depth=`. Adicionado na v1.34 |
| `workflow.code_review_depth_overrides` | array | `[]` | Lista ordenada de regras `{ paths: string[], depth }` que aumentam a profundidade de `/gsd-code-review` para diretórios específicos, ex.: `[{ "paths": ["src/auth"], "depth": "deep" }]`. Cada `paths` da regra é comparado com o conjunto de arquivos alterados da revisão por prefixo de diretório com segmentos completos (`src/auth` corresponde a `src/auth/token.ts`, nunca a `src/authfoo/x.ts` ou `docs/src/auth/x.ts`); a comparação diferencia maiúsculas/minúsculas, como o git. Sintaxe glob (`*`, `?`) é um erro de configuração, não um atalho para prefixo. Um único arquivo correspondido eleva a profundidade de toda a revisão — a profundidade não é aplicada por arquivo. Ordem de resolução: flag `--depth=` → regra correspondente mais forte → `workflow.code_review_depth` → `standard`; uma regra correspondente prevalece mesmo quando seu nível é mais fraco que o padrão global. Uma regra malformada (`depth` inválido, sintaxe glob, caminho absoluto, segmento `..`, caminho vazio, `overrides` que não é array, regra que não é objeto, `paths` malformado) é um erro de configuração e a revisão é interrompida em vez de usar um valor padrão silenciosamente. A profundidade resolvida e a regra correspondente são exibidas na saída da revisão. Adicionado em #2554 |
| `workflow.code_review` | boolean | `true` | Habilita os comandos `/msd-code-review` e `/msd-code-review --fix`. Quando `false`, os comandos saem com uma mensagem de gate de configuração. Adicionado na v1.34 |
| `workflow.code_review_depth` | string | `standard` | Profundidade de revisão padrão para `/msd-code-review`: `quick` (somente correspondência de padrão), `standard` (análise por arquivo) ou `deep` (entre arquivos com grafos de importação). Pode ser substituído por execução com `--depth=`. Adicionado na v1.34 |
| `workflow.code_review_depth_overrides` | array | `[]` | Lista ordenada de regras `{ paths: string[], depth }` que aumentam a profundidade de `/msd-code-review` para diretórios específicos, ex.: `[{ "paths": ["src/auth"], "depth": "deep" }]`. Cada `paths` da regra é comparado com o conjunto de arquivos alterados da revisão por prefixo de diretório com segmentos completos (`src/auth` corresponde a `src/auth/token.ts`, nunca a `src/authfoo/x.ts` ou `docs/src/auth/x.ts`); a comparação diferencia maiúsculas/minúsculas, como o git. Sintaxe glob (`*`, `?`) é um erro de configuração, não um atalho para prefixo. Um único arquivo correspondido eleva a profundidade de toda a revisão — a profundidade não é aplicada por arquivo. Ordem de resolução: flag `--depth=` → regra correspondente mais forte → `workflow.code_review_depth` → `standard`; uma regra correspondente prevalece mesmo quando seu nível é mais fraco que o padrão global. Uma regra malformada (`depth` inválido, sintaxe glob, caminho absoluto, segmento `..`, caminho vazio, `overrides` que não é array, regra que não é objeto, `paths` malformado) é um erro de configuração e a revisão é interrompida em vez de usar um valor padrão silenciosamente. A profundidade resolvida e a regra correspondente são exibidas na saída da revisão. Adicionado em #2554 |
| `workflow.plan_bounce` | boolean | `false` | Executa script de validação externo nos planos gerados. Quando habilitado, o orquestrador de fase de planejamento encaminha cada PLAN.md pelo script especificado por `plan_bounce_script` e bloqueia em saída diferente de zero. Adicionado na v1.36 |
| `workflow.plan_bounce_script` | string | (nenhum) | Caminho para o script externo invocado na validação de bounce de plano. Recebe o caminho do PLAN.md como primeiro argumento. Obrigatório quando `plan_bounce` é `true`. Adicionado na v1.36 |
| `workflow.plan_bounce_passes` | number | `2` | Número de passagens sequenciais de bounce a executar. Cada passagem alimenta a saída da passagem anterior de volta no validador. Valores maiores aumentam o rigor ao custo de latência. Adicionado na v1.36 |
| `workflow.post_planning_gaps` | boolean | `true` | Relatório unificado de lacunas pós-planejamento (#2493). Após todos os planos serem gerados e commitados, verifica REQUIREMENTS.md e as `<decisions>` de CONTEXT.md em relação a cada PLAN.md no diretório da fase, então imprime uma tabela `Source \| Item \| Status`. Correspondência por limite de palavra (REQ-1 vs REQ-10) e ordenação natural (REQ-02 antes de REQ-10). Não bloqueante — apenas relatório informativo. Defina como `false` para pular o Passo 13e da fase de planejamento. |
| `workflow.plan_review_convergence` | boolean | `false` | Habilita o comando `/gsd-plan-review-convergence`. Desabilitado por padrão — o comando sai com instrução de habilitação quando esta chave é `false`. O comando automatiza o loop manual de plan→review→replan: gera revisores configurados (Codex, Claude, OpenCode, Ollama, LM Studio, llama.cpp), conta preocupações HIGH não resolvidas via contrato CYCLE_SUMMARY, replaneja com feedback `--reviews` e repete até convergir ou atingir o número máximo de ciclos. Habilite com `gsd config-set workflow.plan_review_convergence true`. Adicionado na v1.39 |
| `workflow.plan_chunked` | boolean | `false` | Habilita o modo de planejamento em chunks. Quando `true` (ou quando a flag `--chunked` é passada para `/gsd-plan-phase`), o orquestrador divide a única Task de planejamento de longa duração em uma Task curta de esboço seguida de N Tasks curtas por plano (~3-5 min cada). Cada plano é commitado individualmente para resiliência a falhas. Se uma Task travar e o terminal for forçado a fechar, reexecutar com `--chunked` retoma a partir do último plano concluído. Particularmente útil no Windows onde Tasks de longa duração podem travar em stdio. Adicionado na v1.38 |
| `workflow.code_review_command` | string | (nenhum) | Comando shell para integração de revisão de código externa em `/gsd-ship`. Recebe caminhos de arquivos alterados via stdin. Saída diferente de zero bloqueia o fluxo de trabalho de ship. Adicionado na v1.36 |
| `workflow.plan_review_convergence` | boolean | `false` | Habilita o comando `/msd-plan-review-convergence`. Desabilitado por padrão — o comando sai com instrução de habilitação quando esta chave é `false`. O comando automatiza o loop manual de plan→review→replan: gera revisores configurados (Codex, Claude, OpenCode, Ollama, LM Studio, llama.cpp), conta preocupações HIGH não resolvidas via contrato CYCLE_SUMMARY, replaneja com feedback `--reviews` e repete até convergir ou atingir o número máximo de ciclos. Habilite com `msd config-set workflow.plan_review_convergence true`. Adicionado na v1.39 |
| `workflow.plan_chunked` | boolean | `false` | Habilita o modo de planejamento em chunks. Quando `true` (ou quando a flag `--chunked` é passada para `/msd-plan-phase`), o orquestrador divide a única Task de planejamento de longa duração em uma Task curta de esboço seguida de N Tasks curtas por plano (~3-5 min cada). Cada plano é commitado individualmente para resiliência a falhas. Se uma Task travar e o terminal for forçado a fechar, reexecutar com `--chunked` retoma a partir do último plano concluído. Particularmente útil no Windows onde Tasks de longa duração podem travar em stdio. Adicionado na v1.38 |
| `workflow.code_review_command` | string | (nenhum) | Comando shell para integração de revisão de código externa em `/msd-ship`. Recebe caminhos de arquivos alterados via stdin. Saída diferente de zero bloqueia o fluxo de trabalho de ship. Adicionado na v1.36 |
| `workflow.tdd_mode` | boolean | `false` | Habilita o pipeline TDD como modo de execução de primeira classe. Quando `true`, o planejador aplica agressivamente `type: tdd` a tarefas elegíveis (lógica de negócios, APIs, validações, algoritmos) e o executor impõe a sequência de gate RED/GREEN/REFACTOR. Um ponto de revisão colaborativa ao final da fase verifica a conformidade com o gate. Adicionado na v1.36 |
| `workflow.human_verify_mode` | string | `'end-of-phase'` | Controla os pontos de verificação humana. `'end-of-phase'` (padrão desde #3309) suprime as tasks `checkpoint:human-verify` e incorpora verificações nos blocos `<verify><human-check>` para revisão ao final da fase. `'mid-flight'` restaura as tasks de checkpoint bloqueantes. `checkpoint:decision` e `checkpoint:human-action` não são afetados. Consulte [Referência de Checkpoints](../../gsd-core/references/checkpoints.md#checkpoint_types). |
| `workflow.human_verify_mode` | string | `'end-of-phase'` | Controla os pontos de verificação humana. `'end-of-phase'` (padrão desde #3309) suprime as tasks `checkpoint:human-verify` e incorpora verificações nos blocos `<verify><human-check>` para revisão ao final da fase. `'mid-flight'` restaura as tasks de checkpoint bloqueantes. `checkpoint:decision` e `checkpoint:human-action` não são afetados. Consulte [Referência de Checkpoints](../../msd-core/references/checkpoints.md#checkpoint_types). |
| `workflow.cross_ai_execution` | boolean | `false` | Delega a execução de fase para uma CLI de IA externa em vez de gerar agentes executores locais. Útil para aproveitar os pontos fortes de um modelo diferente para fases específicas. Adicionado na v1.36 |
| `workflow.cross_ai_command` | string | (nenhum) | Template de comando shell para execução cross-AI. Recebe o prompt de fase via stdin. Deve produzir saída compatível com SUMMARY.md. Obrigatório quando `cross_ai_execution` é `true`. Adicionado na v1.36 |
| `workflow.cross_ai_timeout` | number | `300` | Timeout em segundos para comandos de execução cross-AI. Previne processos externos que não terminam. Adicionado na v1.36 |
| `workflow.ai_integration_phase` | boolean | `true` | Habilita o comando `/gsd-ai-integration-phase`. Quando `false`, o comando sai com uma mensagem de gate de configuração |
| `workflow.ai_integration_phase` | boolean | `true` | Habilita o comando `/msd-ai-integration-phase`. Quando `false`, o comando sai com uma mensagem de gate de configuração |
| `workflow.auto_prune_state` | boolean | `false` | Quando `true`, poda automaticamente entradas obsoletas de STATE.md nos limites de fase em vez de solicitar confirmação |
| `workflow.pattern_mapper` | boolean | `true` | Executa o agente `gsd-pattern-mapper` entre pesquisa e planejamento para mapear novos arquivos para análogos existentes na base de código |
| `workflow.pattern_mapper` | boolean | `true` | Executa o agente `msd-pattern-mapper` entre pesquisa e planejamento para mapear novos arquivos para análogos existentes na base de código |
| `workflow.subagent_timeout` | number | `600` | Timeout em segundos para invocações individuais de subagente. Aumente para fases de pesquisa ou execução de longa duração |
| `executor.stall_detect_interval_minutes` | number | `5` | Minutos entre verificações de travamento do executor enquanto um agente executor está ativo. O orquestrador de fase de execução usa essa cadência para inspecionar commits recentes e evitar espera eterna por um agente silencioso. |
| `executor.stall_threshold_minutes` | number | `10` | Minutos sem conclusão do executor ou atividade de commit no branch esperado antes que a fase de execução ofereça opções de recuperação para um possível executor travado. |
| `planner.stall_detection_enabled` | boolean | `true` | Controla a detecção limitada de travamento do planejador padrão, dos planejadores de esboço/por plano em chunks, do verificador de planos e do planejador de revisão. Use `gsd config-set planner.stall_detection_enabled false` para ignorar o polling do watchdog e aguardar cada agente pelo mecanismo de conclusão nativa do runtime. **Aviso:** `false` abre mão da recuperação limitada se o runtime perder a entrega da conclusão; pode ser necessário interromper e usar o fallback existente do sistema de arquivos. A execução e o tratamento do resultado nunca são ignorados. |
| `planner.stall_detection_enabled` | boolean | `true` | Controla a detecção limitada de travamento do planejador padrão, dos planejadores de esboço/por plano em chunks, do verificador de planos e do planejador de revisão. Use `msd config-set planner.stall_detection_enabled false` para ignorar o polling do watchdog e aguardar cada agente pelo mecanismo de conclusão nativa do runtime. **Aviso:** `false` abre mão da recuperação limitada se o runtime perder a entrega da conclusão; pode ser necessário interromper e usar o fallback existente do sistema de arquivos. A execução e o tratamento do resultado nunca são ignorados. |
| `planner.stall_detect_interval_minutes` | number | `5` | Minutos entre verificações de travamento enquanto um planejador ou verificador de planos está ativo. O orquestrador inspeciona a atividade em disco de `*-PLAN.md` nessa cadência (#2650). |
| `planner.stall_threshold_minutes` | number | `10` | Minutos sem marcador de conclusão ou atividade recente em planos antes que a fase de planejamento ofereça automaticamente as opções aceitar/tentar novamente/parar (#2650). |
| `workflow.inline_plan_threshold` | number | `3` | Número máximo de tasks em uma fase antes que o planejador gere um arquivo PLAN.md separado em vez de incorporar tasks no prompt |
| `workflow.drift_threshold` | number | `3` | Número mínimo de novos elementos estruturais (novos diretórios, exportações barrel, migrações, módulos de rota) introduzidos durante uma fase antes que o gate de deriva pós-execução da base de código tome ação. Consulte [#2003](https://github.com/open-gsd/gsd-core/issues/2003). Adicionado na v1.39 |
| `workflow.drift_action` | string | `warn` | O que fazer quando `workflow.drift_threshold` é excedido após `/gsd-execute-phase`. `warn` imprime uma mensagem sugerindo `/gsd-map-codebase --paths …`; `auto-remap` gera `gsd-codebase-mapper` com escopo para os caminhos afetados. Adicionado na v1.39 |
| `workflow.drift_action` | string | `warn` | O que fazer quando `workflow.drift_threshold` é excedido após `/msd-execute-phase`. `warn` imprime uma mensagem sugerindo `/msd-map-codebase --paths …`; `auto-remap` gera `msd-codebase-mapper` com escopo para os caminhos afetados. Adicionado na v1.39 |
| `workflow.build_command` | string | (nenhum) | Comando shell para compilar o projeto no gate de build pós-merge (Passo A do passo 5.6 na fase de execução). Quando não definido, o gate detecta automaticamente: Xcode (`.xcodeproj` presente) → `xcodebuild build`, `Makefile` com alvo `build:` → `make build`, Justfile → `just build`, `Cargo.toml` → `cargo build`, `go.mod` → `go build ./...`, Python → `python -m py_compile`, `package.json` com script `build` → `npm run build`. Executa com timeout de 5 minutos; falha incrementa `WAVE_FAILURE_COUNT`. Adicionado na v1.39 |
| `workflow.test_command` | string | (nenhum) | Comando shell para executar a suíte de testes do projeto no gate de teste pós-merge (Passo B do passo 5.6 na fase de execução) e no gate de regressão. Quando não definido, o gate detecta automaticamente: Xcode (`.xcodeproj` presente) → `xcodebuild test`, `Makefile` com alvo `test:` → `make test`, Justfile → `just test`, `package.json` → `npm test`, `Cargo.toml` → `cargo test`, `go.mod` → `go test ./...`, Python → `python -m pytest`. Executa com timeout de 5 minutos; falha incrementa `WAVE_FAILURE_COUNT`. Adicionado na v1.39 |
## Configurações de Qualidade de Código
O namespace `code_quality.*` controla ferramentas opcionais de análise estrutural que complementam `/gsd-code-review`. As configurações são aditivas: cada ferramenta é habilitada independentemente e está desativada por padrão.
O namespace `code_quality.*` controla ferramentas opcionais de análise estrutural que complementam `/msd-code-review`. As configurações são aditivas: cada ferramenta é habilitada independentemente e está desativada por padrão.
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `code_quality.fallow.enabled` | boolean | `false` | Habilita a pré-passagem estrutural fallow para `/gsd-code-review`. Quando `false`, nenhuma sondagem de binário fallow ou artefato JSON é produzido. |
| `code_quality.fallow.enabled` | boolean | `false` | Habilita a pré-passagem estrutural fallow para `/msd-code-review`. Quando `false`, nenhuma sondagem de binário fallow ou artefato JSON é produzido. |
| `code_quality.fallow.scope` | string | `phase` | Escopo para análise fallow: `phase` (escopo de arquivo de revisão atual) ou `repo` (repositório inteiro). |
| `code_quality.fallow.profile` | string | `standard` | Seletor de perfil fallow passado para o executor de pré-passagem (`minimal`, `standard`, `strict`). |
| `code_quality.fallow.mcp` | boolean | `false` | **Reservado — ainda não implementado.** Quando `true`, habilita o modo de descobertas estruturais suportadas por MCP para runtimes que suportam roteamento de servidor MCP. Definir como `true` atualmente é um no-op e emite um aviso de runtime. |
## Configurações de Ship
`ship.pr_body_sections` adiciona seções adicionais ao corpo do PR para conteúdo de PRD/corpo do PR específico do projeto em `/gsd-ship` sem editar `gsd-core/workflows/ship.md`.
`ship.pr_body_sections` adiciona seções adicionais ao corpo do PR para conteúdo de PRD/corpo do PR específico do projeto em `/msd-ship` sem editar `msd-core/workflows/ship.md`.
Para um guia do usuário com exemplos de integração e solução de problemas, consulte [Seções Personalizadas do Corpo do PR](../ship-pr-body-sections.md).
@@ -310,7 +310,7 @@ Cada entrada suporta:
| `template` | string | (nenhum) | Markdown literal com tokens fechados: `{phase_number}`, `{phase_name}`, `{phase_dir}`, `{base_branch}`, `{padded_phase}`. |
| `fallback` | string | (nenhum) | Markdown literal usado quando `source` não produz conteúdo e nenhum `template` é fornecido. |
Pelo menos um de `source`, `template` ou `fallback` é obrigatório para cada seção. O padrão é `[]`, portanto projetos existentes mantêm sua saída atual de `/gsd-ship` até que a integração adicione entradas habilitadas.
Pelo menos um de `source`, `template` ou `fallback` é obrigatório para cada seção. O padrão é `[]`, portanto projetos existentes mantêm sua saída atual de `/msd-ship` até que a integração adicione entradas habilitadas.
Exemplo:
@@ -357,13 +357,13 @@ As seguintes combinações de `mode`, `granularity`, `model_profile` e controles
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `planning.commit_docs` | boolean | `true` | Define se os arquivos de `.planning/` são commitados no git |
| `planning.pr_strict` | boolean | `false` | Modo de filtro para `/gsd-pr-branch`. `false` mantém o estado estrutural de planejamento (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md, REQUIREMENTS.md, milestones/) no branch de PR; `true` remove todos os caminhos de `.planning/` |
| `planning.pr_strict` | boolean | `false` | Modo de filtro para `/msd-pr-branch`. `false` mantém o estado estrutural de planejamento (STATE.md, ROADMAP.md, MILESTONES.md, PROJECT.md, REQUIREMENTS.md, milestones/) no branch de PR; `true` remove todos os caminhos de `.planning/` |
| `planning.search_gitignored` | boolean | `false` | Adiciona `--no-ignore` em buscas amplas para incluir `.planning/` |
| `planning.sub_repos` | array de strings | `[]` | Caminhos de sub-repositórios aninhados relativos à raiz do projeto. Quando definido, as ferramentas com reconhecimento de GSD limitam a busca de fase, resolução de caminho e operações de commit por sub-repo em vez de tratar o repositório externo como um monorepo |
| `planning.sub_repos` | array de strings | `[]` | Caminhos de sub-repositórios aninhados relativos à raiz do projeto. Quando definido, as ferramentas com reconhecimento de MSD limitam a busca de fase, resolução de caminho e operações de commit por sub-repo em vez de tratar o repositório externo como um monorepo |
### Resolução da Raiz do Projeto em Workspaces Multi-Repositório
Quando `sub_repos` está definido e `gsd-tools.cjs` ou `gsd-tools query` é invocado de dentro de um repositório filho listado, ambas as CLIs sobem até o workspace pai que possui `.planning/` antes de despachar os manipuladores. Ordem de resolução (verificada em cada ancestral até 10 níveis, nunca acima de `$HOME`):
Quando `sub_repos` está definido e `msd-tools.cjs` ou `msd-tools query` é invocado de dentro de um repositório filho listado, ambas as CLIs sobem até o workspace pai que possui `.planning/` antes de despachar os manipuladores. Ordem de resolução (verificada em cada ancestral até 10 níveis, nunca acima de `$HOME`):
1. Se o diretório inicial já possui seu próprio `.planning/`, ele é a raiz do projeto (sem subida).
2. O pai possui `.planning/config.json` listando o segmento de nível superior do diretório inicial em `sub_repos` (ou o formato legado `planning.sub_repos`).
@@ -383,21 +383,21 @@ Se `.planning/` estiver em `.gitignore`, `commit_docs` é automaticamente `false
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `hooks.context_warnings` | boolean | `true` | Exibe avisos de uso da janela de contexto via hook do monitor de contexto |
| `hooks.workflow_guard` | boolean | `false` | Avisa quando edições de arquivo ocorrem fora do contexto do fluxo de trabalho GSD (aconselha usar `/gsd-quick` ou `/gsd-fast`) |
| `hooks.workflow_guard` | boolean | `false` | Avisa quando edições de arquivo ocorrem fora do contexto do fluxo de trabalho MSD (aconselha usar `/msd-quick` ou `/msd-fast`) |
| `statusline.show_last_command` | boolean | `false` | Acrescenta o sufixo `last: /<cmd>` à statusline mostrando o comando slash invocado mais recentemente. Opt-in; lê a transcrição da sessão ativa para extrair a última tag `<command-name>` (fecha #2538) |
| `statusline.context_position` | string | `"end"` | Posição do medidor de janela de contexto. `"end"` (padrão) renderiza no final da linha; `"front"` renderiza imediatamente após o nome do modelo para que o medidor permaneça visível em terminais estreitos. Fecha #2937 |
O hook guardião de injeção de prompt (`gsd-prompt-guard.js`) está sempre ativo e não pode ser desabilitado — é uma funcionalidade de segurança, não um controle de fluxo de trabalho.
O hook guardião de injeção de prompt (`msd-prompt-guard.js`) está sempre ativo e não pode ser desabilitado — é uma funcionalidade de segurança, não um controle de fluxo de trabalho.
### Configuração de Planejamento Privado
Quando `planning.commit_docs` é `false` e `.planning/` está listado em `.gitignore`, o GSD trata os artefatos de planejamento como locais apenas. `planning.search_gitignored: true` garante que buscas amplas ainda incluam o diretório `.planning/` nesta configuração. Consulte [Configurar planejamento privado](how-to/configure-model-profiles.md) para os passos de configuração.
Quando `planning.commit_docs` é `false` e `.planning/` está listado em `.gitignore`, o MSD trata os artefatos de planejamento como locais apenas. `planning.search_gitignored: true` garante que buscas amplas ainda incluam o diretório `.planning/` nesta configuração. Consulte [Configurar planejamento privado](how-to/configure-model-profiles.md) para os passos de configuração.
---
## Injeção de Habilidades de Agente
Injeta arquivos de habilidades personalizados nos prompts de subagentes GSD. As habilidades são lidas pelos agentes no momento do spawn, fornecendo instruções específicas do projeto além do que o CLAUDE.md oferece.
Injeta arquivos de habilidades personalizados nos prompts de subagentes MSD. As habilidades são lidas pelos agentes no momento do spawn, fornecendo instruções específicas do projeto além do que o CLAUDE.md oferece.
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
@@ -410,9 +410,9 @@ Adicione uma seção `agent_skills` em `.planning/config.json` mapeando tipos de
```json
{
"agent_skills": {
"gsd-executor": ["skills/testing-standards", "skills/api-conventions"],
"gsd-planner": ["skills/architecture-rules"],
"gsd-verifier": ["skills/acceptance-criteria"]
"msd-executor": ["skills/testing-standards", "skills/api-conventions"],
"msd-planner": ["skills/architecture-rules"],
"msd-verifier": ["skills/acceptance-criteria"]
}
}
```
@@ -421,25 +421,25 @@ Cada caminho deve ser um diretório contendo um arquivo `SKILL.md`. Os caminhos
### Tipos de Agente Suportados
Qualquer tipo de agente GSD pode receber habilidades. Tipos comuns:
Qualquer tipo de agente MSD pode receber habilidades. Tipos comuns:
- `gsd-executor` -- executa planos de implementação
- `gsd-planner` -- cria planos de fase
- `gsd-checker` -- verifica a qualidade do plano
- `gsd-verifier` -- verificação pós-execução
- `gsd-researcher` -- pesquisa de fase
- `gsd-project-researcher` -- pesquisa de novo projeto
- `gsd-debugger` -- agentes de diagnóstico
- `gsd-codebase-mapper` -- análise da base de código
- `gsd-advisor` -- consultores da fase de discussão
- `gsd-ui-researcher` -- criação de contrato de design de UI
- `gsd-ui-checker` -- verificação de especificação de UI
- `gsd-roadmapper` -- criação de roadmap
- `gsd-synthesizer` -- síntese de pesquisa
- `msd-executor` -- executa planos de implementação
- `msd-planner` -- cria planos de fase
- `msd-checker` -- verifica a qualidade do plano
- `msd-verifier` -- verificação pós-execução
- `msd-researcher` -- pesquisa de fase
- `msd-project-researcher` -- pesquisa de novo projeto
- `msd-debugger` -- agentes de diagnóstico
- `msd-codebase-mapper` -- análise da base de código
- `msd-advisor` -- consultores da fase de discussão
- `msd-ui-researcher` -- criação de contrato de design de UI
- `msd-ui-checker` -- verificação de especificação de UI
- `msd-roadmapper` -- criação de roadmap
- `msd-synthesizer` -- síntese de pesquisa
### Como Funciona
No momento do spawn, os fluxos de trabalho chamam `gsd-tools query agent-skills <type>` (ou o legado `node gsd-tools.cjs agent-skills <type>`) para carregar as habilidades configuradas. Se existirem habilidades para o tipo de agente, elas são injetadas como um bloco `<agent_skills>` no prompt de Task():
No momento do spawn, os fluxos de trabalho chamam `msd-tools query agent-skills <type>` (ou o legado `node msd-tools.cjs agent-skills <type>`) para carregar as habilidades configuradas. Se existirem habilidades para o tipo de agente, elas são injetadas como um bloco `<agent_skills>` no prompt de Task():
```xml
<agent_skills>
@@ -456,7 +456,7 @@ Se nenhuma habilidade estiver configurada, o bloco é omitido (zero overhead).
Defina habilidades via CLI:
```bash
gsd-tools query config-set agent_skills.gsd-executor '["skills/my-skill"]'
msd-tools query config-set agent_skills.msd-executor '["skills/my-skill"]'
```
---
@@ -470,7 +470,7 @@ Ative capacidades opcionais via o namespace de configuração `features.*`. Feat
| `features.thinking_partner` | boolean | `false` | Habilita análise de parceiro de raciocínio em pontos de decisão do fluxo de trabalho |
| `features.global_learnings` | boolean | `false` | Habilita o pipeline de aprendizados entre projetos (cópia automática na conclusão de fase, injeção no planejador) |
| `learnings.max_inject` | number | `10` | Número máximo de aprendizados entre projetos injetados em cada prompt do planejador. Valores menores reduzem o tamanho do prompt; valores maiores fornecem contexto histórico mais amplo |
| `intel.enabled` | boolean | `false` | Habilita o sistema de inteligência consultável da base de código. Quando `true`, os comandos `/gsd-map-codebase --query` constroem e consultam um índice JSON em `.planning/intel/`. Adicionado na v1.34 |
| `intel.enabled` | boolean | `false` | Habilita o sistema de inteligência consultável da base de código. Quando `true`, os comandos `/msd-map-codebase --query` constroem e consultam um índice JSON em `.planning/intel/`. Adicionado na v1.34 |
<a id="plan-review-settings"></a>
### Configurações de Revisão de Plano
@@ -479,25 +479,25 @@ O namespace `plan_review.*` controla o guardião de deriva de plano, que verific
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `plan_review.source_grounding` | boolean | `true` | Habilita o guardião de deriva de plano. Quando `true` (padrão), a revisão de plano resolve cada referência de símbolo citada em um PLAN.md em relação à árvore de fontes ativa. Planos que citam uma função, classe, decorador ou flag CLI inexistente produzem um aviso `needs-acknowledgement` antes do plano ser aprovado. Desabilite com `false` para ignorar completamente a verificação de símbolo. Ative durante a configuração (`/gsd-new-project`) ou a qualquer momento via `/gsd-settings`. |
| `plan_review.source_grounding_authority` | enum | `grep` | Seleciona o adaptador de resolução usado para verificar a existência de símbolos. Valores permitidos: `grep` (padrão — busca ripgrep/grep de arquivos de fonte, funciona em qualquer projeto sem ferramental adicional), `intel` (consulta o índice `.planning/intel/api-map.json` construído por `/gsd-map-codebase`; requer `intel.enabled: true`), `treesitter` (reservado para adaptador tree-sitter futuro), `lsp` (reservado para adaptador LSP futuro), `scip` (reservado para adaptador SCIP/LSIF futuro). Use `intel` quando tiver executado `/gsd-map-codebase` e quiser a busca mais rápida e pré-indexada. Todos os outros valores além de `grep` e `intel` são reservados e não têm efeito na versão atual. |
| `plan_review.source_grounding` | boolean | `true` | Habilita o guardião de deriva de plano. Quando `true` (padrão), a revisão de plano resolve cada referência de símbolo citada em um PLAN.md em relação à árvore de fontes ativa. Planos que citam uma função, classe, decorador ou flag CLI inexistente produzem um aviso `needs-acknowledgement` antes do plano ser aprovado. Desabilite com `false` para ignorar completamente a verificação de símbolo. Ative durante a configuração (`/msd-new-project`) ou a qualquer momento via `/msd-settings`. |
| `plan_review.source_grounding_authority` | enum | `grep` | Seleciona o adaptador de resolução usado para verificar a existência de símbolos. Valores permitidos: `grep` (padrão — busca ripgrep/grep de arquivos de fonte, funciona em qualquer projeto sem ferramental adicional), `intel` (consulta o índice `.planning/intel/api-map.json` construído por `/msd-map-codebase`; requer `intel.enabled: true`), `treesitter` (reservado para adaptador tree-sitter futuro), `lsp` (reservado para adaptador LSP futuro), `scip` (reservado para adaptador SCIP/LSIF futuro). Use `intel` quando tiver executado `/msd-map-codebase` e quiser a busca mais rápida e pré-indexada. Todos os outros valores além de `grep` e `intel` são reservados e não têm efeito na versão atual. |
<a id="graphify-settings"></a>
### Configurações do Graphify
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `graphify.enabled` | boolean | `false` | Habilita o grafo de conhecimento do projeto. Quando `true`, `/gsd-graphify` constrói e consulta um grafo em `.planning/graphs/`. Adicionado na v1.36 |
| `graphify.build_timeout` | number (segundos) | `300` | Segundos máximos permitidos para uma execução de `/gsd-graphify build` antes de abortar. Adicionado na v1.36 |
| `graphify.auto_update` | boolean | `false` | **Opt-in (issue #3347).** Quando `true` (e `graphify.enabled` também é `true`), o hook PostToolUse incluído `hooks/gsd-graphify-update.sh` reconstrói automaticamente o grafo de conhecimento do projeto em um processo em segundo plano após `git commit/merge/pull/rebase --continue/cherry-pick` no branch padrão (substituição `git.base_branch`, senão `main`/`master`/`trunk`). O hook retorna instantaneamente; a reconstrução atualiza `.planning/graphs/{graph.json,graph.html,GRAPH_REPORT.md}` e escreve `.planning/graphs/.last-build-status.json` (`{ts, status: "running"\|"ok"\|"failed", exit_code, duration_ms, head_at_build}`). Bloqueado por PID, ciente de CI (`$CI` env suprime), aborta silenciosamente se `graphify` não estiver no `PATH`. Padrão `false` para que o comportamento existente não mude após atualização. |
| `graphify.enabled` | boolean | `false` | Habilita o grafo de conhecimento do projeto. Quando `true`, `/msd-graphify` constrói e consulta um grafo em `.planning/graphs/`. Adicionado na v1.36 |
| `graphify.build_timeout` | number (segundos) | `300` | Segundos máximos permitidos para uma execução de `/msd-graphify build` antes de abortar. Adicionado na v1.36 |
| `graphify.auto_update` | boolean | `false` | **Opt-in (issue #3347).** Quando `true` (e `graphify.enabled` também é `true`), o hook PostToolUse incluído `hooks/msd-graphify-update.sh` reconstrói automaticamente o grafo de conhecimento do projeto em um processo em segundo plano após `git commit/merge/pull/rebase --continue/cherry-pick` no branch padrão (substituição `git.base_branch`, senão `main`/`master`/`trunk`). O hook retorna instantaneamente; a reconstrução atualiza `.planning/graphs/{graph.json,graph.html,GRAPH_REPORT.md}` e escreve `.planning/graphs/.last-build-status.json` (`{ts, status: "running"\|"ok"\|"failed", exit_code, duration_ms, head_at_build}`). Bloqueado por PID, ciente de CI (`$CI` env suprime), aborta silenciosamente se `graphify` não estiver no `PATH`. Padrão `false` para que o comportamento existente não mude após atualização. |
#### Configuração para múltiplos desenvolvedores
Quando vários desenvolvedores reconstroem o grafo no mesmo repositório, `graphify hook install` (executado uma vez por clone) instala um driver de merge git que mescla por união gravações concorrentes de `graph.json`, eliminando marcadores de conflito. Também registra o hook de reconstrução pós-commit, escreve `.gitattributes` e adiciona `graphify merge-driver` em `.git/config`. Projetos solo podem pular esta etapa. Introduzido upstream no graphify v0.7.0 junto com o sinal de atualidade `built_at_commit` exibido por `/gsd-graphify status`.
Quando vários desenvolvedores reconstroem o grafo no mesmo repositório, `graphify hook install` (executado uma vez por clone) instala um driver de merge git que mescla por união gravações concorrentes de `graph.json`, eliminando marcadores de conflito. Também registra o hook de reconstrução pós-commit, escreve `.gitattributes` e adiciona `graphify merge-driver` em `.git/config`. Projetos solo podem pular esta etapa. Introduzido upstream no graphify v0.7.0 junto com o sinal de atualidade `built_at_commit` exibido por `/msd-graphify status`.
#### Obsolescência baseada em commit
`/gsd-graphify status` relata dois sinais ortogonais de obsolescência:
`/msd-graphify status` relata dois sinais ortogonais de obsolescência:
- **`stale`** (baseado em mtime, janela de 24 horas) — quando o arquivo do grafo foi gravado pela última vez. Útil quando graphify não é executado automaticamente.
- **`commit_stale`** (baseado em commit, requer graphify v0.7+) — se o grafo foi construído contra o `git HEAD` atual. Confiável quando presente.
@@ -509,10 +509,10 @@ Um grafo construído por CI há alguns minutos contra um checkout antigo aparece
```bash
# Habilitar uma feature
gsd-tools query config-set features.global_learnings true
msd-tools query config-set features.global_learnings true
# Desabilitar uma feature
gsd-tools query config-set features.thinking_partner false
msd-tools query config-set features.thinking_partner false
```
O namespace `features.*` é um padrão de chave dinâmico — novos feature flags podem ser adicionados sem modificar `VALID_CONFIG_KEYS`. Qualquer chave correspondente a `features.<name>` é aceita pelo sistema de configuração.
@@ -537,7 +537,7 @@ O namespace `features.*` é um padrão de chave dinâmico — novos feature flag
## Frontmatter do STATE.md (Ciclo de Vida de Fase)
`STATE.md` carrega frontmatter YAML que o hook da linha de status lê a cada renderização. A v1.40 adiciona quatro campos opcionais de ciclo de vida de fase lidos por `parseStateMd()` e renderizados por `formatGsdState()`:
`STATE.md` carrega frontmatter YAML que o hook da linha de status lê a cada renderização. A v1.40 adiciona quatro campos opcionais de ciclo de vida de fase lidos por `parseStateMd()` e renderizados por `formatMsdState()`:
| Campo | Tipo | Finalidade |
|-------|------|---------|
@@ -557,9 +557,9 @@ Todos os quatro campos são **opcionais e aditivos** — arquivos STATE.md sem e
| `git.branching_strategy` | enum | `none` | `none`, `phase` ou `milestone` |
| `git.base_branch` | string | `main` | O branch de integração a partir do qual os branches de fase/marco são criados e nos quais são mesclados de volta. Substitua quando seu repositório usar `master` ou um branch de release |
| `git.create_tag` | boolean | `true` | Cria uma tag git (`v[X.Y]`) na conclusão do marco. Defina como `false` para projetos com seu próprio fluxo de release |
| `git.phase_branch_template` | string | `gsd/phase-{phase}-{slug}` | Template de nome de branch para estratégia de fase |
| `git.milestone_branch_template` | string | `gsd/{milestone}-{slug}` | Template de nome de branch para estratégia de marco |
| `git.quick_branch_template` | string ou null | `null` | Template opcional de nome de branch para tasks `/gsd-quick` |
| `git.phase_branch_template` | string | `msd/phase-{phase}-{slug}` | Template de nome de branch para estratégia de fase |
| `git.milestone_branch_template` | string | `msd/{milestone}-{slug}` | Template de nome de branch para estratégia de marco |
| `git.quick_branch_template` | string ou null | `null` | Template opcional de nome de branch para tasks `/msd-quick` |
### Comparação de Estratégias
@@ -582,7 +582,7 @@ Exemplo de ramificação para task rápida:
```json
"git": {
"quick_branch_template": "gsd/quick-{num}-{slug}"
"quick_branch_template": "msd/quick-{num}-{slug}"
}
```
@@ -631,7 +631,7 @@ Essas chaves ficam sob `workflow.*` — é onde os fluxos de trabalho e o instal
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
| `workflow.security_enforcement` | boolean | `true` | Habilita verificação de segurança ancorada em modelo de ameaças via `/gsd-secure-phase`. Quando `false`, as verificações de segurança são completamente ignoradas |
| `workflow.security_enforcement` | boolean | `true` | Habilita verificação de segurança ancorada em modelo de ameaças via `/msd-secure-phase`. Quando `false`, as verificações de segurança são completamente ignoradas |
| `workflow.security_asvs_level` | number (1-3) | `1` | Nível de verificação OWASP ASVS. Nível 1 = oportunístico, Nível 2 = padrão, Nível 3 = abrangente |
| `workflow.security_block_on` | string | `"high"` | Severidade mínima que bloqueia o avanço de fase. Opções: `"high"`, `"medium"`, `"low"` |
@@ -693,7 +693,7 @@ registro ou itens já adiados para uma fase posterior.
## Configurações de Revisão
Configure a seleção de modelo por CLI para `/gsd-review`. Quando definido, substitui o modelo padrão da CLI para aquele revisor.
Configure a seleção de modelo por CLI para `/msd-review`. Quando definido, substitui o modelo padrão da CLI para aquele revisor.
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
@@ -702,13 +702,13 @@ Configure a seleção de modelo por CLI para `/gsd-review`. Quando definido, sub
| `review.models.opencode` | string | (padrão da CLI) | Modelo usado quando o revisor `--opencode` é invocado |
| `review.models.qwen` | string | (padrão da CLI) | Modelo usado quando o revisor `--qwen` é invocado |
| `review.models.cursor` | string | (padrão da CLI) | Modelo usado quando o revisor `--cursor` é invocado |
| `review.models.ollama` | string | (padrão do servidor) | Nome do modelo passado ao Ollama quando o revisor `--ollama` é invocado. Se não definido, o primeiro modelo disponível reportado pelo servidor é usado (por exemplo `llama3`). Defina para uma tag específica: `gsd config-set review.models.ollama codellama` |
| `review.models.ollama` | string | (padrão do servidor) | Nome do modelo passado ao Ollama quando o revisor `--ollama` é invocado. Se não definido, o primeiro modelo disponível reportado pelo servidor é usado (por exemplo `llama3`). Defina para uma tag específica: `msd config-set review.models.ollama codellama` |
| `review.models.lm_studio` | string | (padrão do servidor) | Nome do modelo passado ao LM Studio quando o revisor `--lm-studio` é invocado. Se não definido, o primeiro modelo disponível reportado pelo servidor é usado. |
| `review.models.llama_cpp` | string | (padrão do servidor) | Nome do modelo passado ao llama.cpp quando o revisor `--llama-cpp` é invocado. Se não definido, o primeiro modelo reportado por `/v1/models` é usado. |
| `review.default_reviewers` | string[] \| null | (todos os revisores detectados) | Subconjunto de revisores padrão para `/gsd-review` sem flags. Exemplo: `["codex","claude"]`. Flags explícitas e `--all` substituem esta configuração. |
| `review.default_reviewers` | string[] \| null | (todos os revisores detectados) | Subconjunto de revisores padrão para `/msd-review` sem flags. Exemplo: `["codex","claude"]`. Flags explícitas e `--all` substituem esta configuração. |
| `review.max_prompt_tokens` | number\|null | null | Máximo padrão de tokens estimados para o prompt de revisão montado. Quando definido, o prompt é cortado deterministicamente antes de ser enviado a cada revisor. Substituições por revisor via `review.max_prompt_tokens_per_reviewer` têm precedência. null = sem corte (comportamento atual). |
| `review.max_prompt_tokens_per_reviewer` | object | {} | Substituições de orçamento de tokens por revisor. As chaves são slugs de revisor (ollama, llama_cpp, lm_studio, claude, codex, opencode, qwen, cursor). Os valores substituem `review.max_prompt_tokens` para aquele revisor. Recomendado para servidores de modelos locais. |
| `review.ollama_host` | string | `http://localhost:11434` | URL base do servidor Ollama. Substitua quando executar o Ollama em uma porta não padrão ou host remoto: `gsd config-set review.ollama_host http://192.168.1.10:11434` |
| `review.ollama_host` | string | `http://localhost:11434` | URL base do servidor Ollama. Substitua quando executar o Ollama em uma porta não padrão ou host remoto: `msd config-set review.ollama_host http://192.168.1.10:11434` |
| `review.lm_studio_host` | string | `http://localhost:1234` | URL base do servidor local LM Studio. Substitua quando usar uma porta não padrão. |
| `review.llama_cpp_host` | string | `http://localhost:8080` | URL base do servidor llama.cpp (`llama-server`). Substitua quando usar uma porta não padrão. |
@@ -735,7 +735,7 @@ Usa o padrão configurado de cada CLI quando uma chave está ausente. Adicionado
## Flags de Passagem do Manager
Configure flags por etapa que `/gsd-manager` acrescenta a cada comando despachado. Isso permite personalizar como o manager executa as etapas de discuss, plan e execute sem entrada manual de flags.
Configure flags por etapa que `/msd-manager` acrescenta a cada comando despachado. Isso permite personalizar como o manager executa as etapas de discuss, plan e execute sem entrada manual de flags.
| Configuração | Tipo | Padrão | Descrição |
|---------|------|---------|-------------|
@@ -757,7 +757,7 @@ Configure flags por etapa que `/gsd-manager` acrescenta a cada comando despachad
}
```
Tokens de flag inválidos são sanitizados e registrados como avisos. Apenas flags GSD reconhecidas são repassadas.
Tokens de flag inválidos são sanitizados e registrados como avisos. Apenas flags MSD reconhecidas são repassadas.
---
@@ -767,26 +767,26 @@ Tokens de flag inválidos são sanitizados e registrados como avisos. Apenas fla
| Agente | `quality` | `balanced` | `budget` | `adaptive` | `inherit` |
|-------|-----------|------------|----------|------------|-----------|
| gsd-planner | Opus | Opus | Sonnet | Opus | Inherit |
| gsd-roadmapper | Opus | Sonnet | Sonnet | Opus | Inherit |
| gsd-executor | Opus | Sonnet | Sonnet | Sonnet | Inherit |
| gsd-phase-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-project-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-research-synthesizer | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-debugger | Opus | Sonnet | Sonnet | Opus | Inherit |
| gsd-codebase-mapper | Sonnet | Haiku | Haiku | Haiku | Inherit |
| gsd-verifier | Sonnet | Sonnet | Haiku | Sonnet | Inherit |
| gsd-plan-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-integration-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-nyquist-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-pattern-mapper | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-ui-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-ui-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-ui-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| gsd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit |
| gsd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-planner | Opus | Opus | Sonnet | Opus | Inherit |
| msd-roadmapper | Opus | Sonnet | Sonnet | Opus | Inherit |
| msd-executor | Opus | Sonnet | Sonnet | Sonnet | Inherit |
| msd-phase-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-project-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-research-synthesizer | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-debugger | Opus | Sonnet | Sonnet | Opus | Inherit |
| msd-codebase-mapper | Sonnet | Haiku | Haiku | Haiku | Inherit |
| msd-verifier | Sonnet | Sonnet | Haiku | Sonnet | Inherit |
| msd-plan-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-integration-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-nyquist-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-pattern-mapper | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-ui-researcher | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-ui-checker | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-ui-auditor | Sonnet | Sonnet | Haiku | Haiku | Inherit |
| msd-doc-writer | Opus | Sonnet | Haiku | Sonnet | Inherit |
| msd-doc-verifier | Sonnet | Sonnet | Haiku | Haiku | Inherit |
> **Todos os 33 agentes incluídos possuem atribuições explícitas de nível por perfil** no catálogo (`gsd-core/bin/shared/model-catalog.json`). A tabela acima mostra um subconjunto representativo dos agentes mais usados. Para agentes não listados aqui, `model_overrides` aceita qualquer nome de agente incluído. Os dados autoritativos de perfil são derivados de `gsd-core/bin/shared/model-catalog.json` via `src/model-catalog.cts`.
> **Todos os 33 agentes incluídos possuem atribuições explícitas de nível por perfil** no catálogo (`msd-core/bin/shared/model-catalog.json`). A tabela acima mostra um subconjunto representativo dos agentes mais usados. Para agentes não listados aqui, `model_overrides` aceita qualquer nome de agente incluído. Os dados autoritativos de perfil são derivados de `msd-core/bin/shared/model-catalog.json` via `src/model-catalog.cts`.
### Substituições por Agente
@@ -796,8 +796,8 @@ Substitua agentes específicos sem alterar o perfil inteiro:
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-planner": "haiku"
"msd-executor": "opus",
"msd-planner": "haiku"
}
}
```
@@ -805,21 +805,21 @@ Substitua agentes específicos sem alterar o perfil inteiro:
Valores de substituição válidos: `opus`, `sonnet`, `haiku`, `inherit` ou qualquer ID de modelo totalmente qualificado (por exemplo, `"openai/o3"`, `"google/gemini-2.5-pro"`).
`model_overrides` pode ser definido em `.planning/config.json` (por projeto)
ou `~/.gsd/defaults.json` (global). Entradas por projeto ganham em conflito e
ou `~/.msd/defaults.json` (global). Entradas por projeto ganham em conflito e
entradas globais sem conflito são preservadas, então você pode ajustar o modelo de um único
agente em um repositório sem redefinir os padrões globais. Isso se aplica
uniformemente em Claude Code, Codex, OpenCode, Kilo e outros
runtimes suportados. No Codex e OpenCode, o modelo resolvido é incorporado
na configuração estática de cada agente no momento da instalação — `spawn_agent` e
a interface `task` do OpenCode não aceitam um parâmetro `model` inline, então
executar `gsd install <runtime>` após editar `model_overrides` é obrigatório
executar `msd install <runtime>` após editar `model_overrides` é obrigatório
para que a alteração entre em vigor. Consulte a issue #2256.
### Modelos Por Tipo de Fase (`models`) — adicionado na v1.41
> Expresse ajuste no nível de **fase** (planning, research, execution, verification) sem precisar conhecer a taxonomia de agentes. Adicionado em [#3023](https://github.com/open-gsd/gsd-core/pull/3030).
`model_overrides` é por **agente** (preciso mas verboso; você precisa saber que `gsd-codebase-mapper` é pesquisa e `gsd-doc-writer` é execução). O bloco `models` permite dizer "Opus para planejamento e execução, Sonnet para o restante" em duas linhas:
`model_overrides` é por **agente** (preciso mas verboso; você precisa saber que `msd-codebase-mapper` é pesquisa e `msd-doc-writer` é execução). O bloco `models` permite dizer "Opus para planejamento e execução, Sonnet para o restante" em duas linhas:
```json
{
@@ -833,7 +833,7 @@ para que a alteração entre em vigor. Consulte a issue #2256.
"completion": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
@@ -842,11 +842,11 @@ para que a alteração entre em vigor. Consulte a issue #2256.
| Tipo de fase | Agentes |
|---|---|
| `planning` | `gsd-planner`, `gsd-roadmapper`, `gsd-pattern-mapper` |
| `discuss` | `gsd-assumptions-analyzer` |
| `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`, `gsd-code-reviewer` |
| `planning` | `msd-planner`, `msd-roadmapper`, `msd-pattern-mapper` |
| `discuss` | `msd-assumptions-analyzer` |
| `research` | `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-codebase-mapper`, `msd-ui-researcher` |
| `execution` | `msd-executor`, `msd-debugger`, `msd-doc-writer` |
| `verification` | `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-nyquist-auditor`, `msd-ui-checker`, `msd-ui-auditor`, `msd-doc-verifier`, `msd-code-reviewer` |
| `completion` | (reservado — sem subagente atualmente) |
`discuss` e `completion` são aceitos pelo esquema para compatibilidade futura; defini-los hoje é um no-op até que um subagente seja mapeado para eles.
@@ -861,7 +861,7 @@ para que a alteração entre em vigor. Consulte a issue #2256.
5. Padrão de runtime ← quando nada mais se aplica
```
As cinco camadas compõem de cima para baixo: `model_profile` é o nível base, `models[<phase_type>]` substitui no nível de fase, `dynamic_routing` (quando habilitado) escala por tentativa em falha soft, `model_overrides[<agent>]` cria exceções por agente no topo, e o padrão de runtime se aplica quando nada mais se aplica. No exemplo acima, todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `gsd-codebase-mapper`, que a substituição por agente fixa em `haiku`. `dynamic_routing` está desabilitado por padrão — quando desativado (`enabled: false` ou bloco omitido), o comportamento desta seção não se altera em relação ao atual.
As cinco camadas compõem de cima para baixo: `model_profile` é o nível base, `models[<phase_type>]` substitui no nível de fase, `dynamic_routing` (quando habilitado) escala por tentativa em falha soft, `model_overrides[<agent>]` cria exceções por agente no topo, e o padrão de runtime se aplica quando nada mais se aplica. No exemplo acima, todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `msd-codebase-mapper`, que a substituição por agente fixa em `haiku`. `dynamic_routing` está desabilitado por padrão — quando desativado (`enabled: false` ou bloco omitido), o comportamento desta seção não se altera em relação ao atual.
#### Valores aceitos
@@ -890,11 +890,11 @@ Combine livremente — a regra de precedência acima resolve qualquer sobreposi
`config-set` rejeita tipos de fase desconhecidos:
```bash
$ gsd config-set models.deployment opus
$ msd config-set models.deployment opus
Error: 'models.deployment' is not a valid config key
# Válido:
$ gsd config-set models.research sonnet
$ msd config-set models.research sonnet
```
Edições diretas em `.planning/config.json` são mais permissivas — o resolvedor simplesmente ignora valores que não reconhece e cai para o nível de perfil — então um erro de digitação não quebra silenciosamente a resolução de nível.
@@ -926,9 +926,9 @@ Cada agente em `MODEL_PROFILES` declara um de três níveis padrão. O resolvedo
| Nível | Agentes | Caso de uso |
|---|---|---|
| `light` | gsd-codebase-mapper, gsd-doc-classifier, gsd-doc-verifier, gsd-integration-checker, gsd-intel-updater, gsd-nyquist-auditor, gsd-pattern-mapper, gsd-plan-checker, gsd-research-synthesizer, gsd-ui-auditor, gsd-ui-checker | Barato/rápido — mapeadores puros, scanners, auditorias de baixo risco |
| `standard` | gsd-advisor-researcher, gsd-ai-researcher, gsd-code-fixer, gsd-code-reviewer, gsd-doc-synthesizer, gsd-doc-writer, gsd-domain-researcher, gsd-eval-auditor, gsd-executor, gsd-phase-researcher, gsd-project-researcher, gsd-ui-researcher, gsd-verifier | Motor padrão — pesquisa, escrita, verificação primária |
| `heavy` | gsd-assumptions-analyzer, gsd-debug-session-manager, gsd-debugger, gsd-eval-planner, gsd-framework-selector, gsd-planner, gsd-roadmapper, gsd-security-auditor, gsd-user-profiler | Raciocínio profundo — já no topo, não pode escalar mais |
| `light` | msd-codebase-mapper, msd-doc-classifier, msd-doc-verifier, msd-integration-checker, msd-intel-updater, msd-nyquist-auditor, msd-pattern-mapper, msd-plan-checker, msd-research-synthesizer, msd-ui-auditor, msd-ui-checker | Barato/rápido — mapeadores puros, scanners, auditorias de baixo risco |
| `standard` | msd-advisor-researcher, msd-ai-researcher, msd-code-fixer, msd-code-reviewer, msd-doc-synthesizer, msd-doc-writer, msd-domain-researcher, msd-eval-auditor, msd-executor, msd-phase-researcher, msd-project-researcher, msd-ui-researcher, msd-verifier | Motor padrão — pesquisa, escrita, verificação primária |
| `heavy` | msd-assumptions-analyzer, msd-debug-session-manager, msd-debugger, msd-eval-planner, msd-framework-selector, msd-planner, msd-roadmapper, msd-security-auditor, msd-user-profiler | Raciocínio profundo — já no topo, não pode escalar mais |
#### Fluxo de escalada
@@ -1013,7 +1013,7 @@ O hint `reasoning_effort` por nível do catálogo de modelos é um campo legado
"heavy": "xhigh"
},
"agent_overrides": {
"gsd-planner": "max"
"msd-planner": "max"
}
}
}
@@ -1076,7 +1076,7 @@ Controla se fast_mode é propagado para invocações de agente. Aceita apenas bo
### Consulta de Execução (`resolve-execution`)
Use `node gsd-tools.cjs resolve-execution <agent-type> [--effort <level>] [--fast-mode <true|false>] [--attempt <n>]` para obter o contexto completo de execução resolvido para um agente:
Use `node msd-tools.cjs resolve-execution <agent-type> [--effort <level>] [--fast-mode <true|false>] [--attempt <n>]` para obter o contexto completo de execução resolvido para um agente:
```json
{
@@ -1099,9 +1099,9 @@ Use `node gsd-tools.cjs resolve-execution <agent-type> [--effort <level>] [--fas
> **Versão mínima suportada do Codex CLI: `0.130.0`** (issue [#3562](https://github.com/open-gsd/gsd-core/issues/3562)).
>
> O [Codex CLI 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) (lançado em 2026-05-08) removeu a descoberta de extra-skills-roots via [openai/codex#21485](https://github.com/openai/codex/pull/21485). A partir desta versão, o Codex CLI só verifica `~/.codex/skills/<name>/SKILL.md`, `<project>/.codex/skills/` e raízes de plugin registradas para habilidades invocáveis. O GSD instala a superfície `$gsd-*` como `~/.codex/skills/gsd-<name>/SKILL.md` para que os comandos resolvam após uma reinicialização do Codex. Versões anteriores do Codex CLI podem mostrar uma listagem duplicada (a varredura legada de extra-roots mais as cópias da raiz do usuário) — reinicie o Codex e atualize para ≥ 0.130.0 ou aceite as duplicatas até fazê-lo.
> O [Codex CLI 0.130.0](https://github.com/openai/codex/releases/tag/rust-v0.130.0) (lançado em 2026-05-08) removeu a descoberta de extra-skills-roots via [openai/codex#21485](https://github.com/openai/codex/pull/21485). A partir desta versão, o Codex CLI só verifica `~/.codex/skills/<name>/SKILL.md`, `<project>/.codex/skills/` e raízes de plugin registradas para habilidades invocáveis. O MSD instala a superfície `$msd-*` como `~/.codex/skills/msd-<name>/SKILL.md` para que os comandos resolvam após uma reinicialização do Codex. Versões anteriores do Codex CLI podem mostrar uma listagem duplicada (a varredura legada de extra-roots mais as cópias da raiz do usuário) — reinicie o Codex e atualize para ≥ 0.130.0 ou aceite as duplicatas até fazê-lo.
Quando o GSD é instalado para um runtime não-Claude, o instalador automaticamente define `resolve_model_ids: "omit"` em `~/.gsd/defaults.json`. Isso faz o GSD retornar um parâmetro de modelo vazio para todos os agentes, para que cada agente use o modelo com que o runtime está configurado. Nenhuma configuração adicional é necessária para o caso padrão.
Quando o MSD é instalado para um runtime não-Claude, o instalador automaticamente define `resolve_model_ids: "omit"` em `~/.msd/defaults.json`. Isso faz o MSD retornar um parâmetro de modelo vazio para todos os agentes, para que cada agente use o modelo com que o runtime está configurado. Nenhuma configuração adicional é necessária para o caso padrão.
Se você quiser que agentes diferentes usem modelos diferentes, use `model_overrides` com IDs de modelo totalmente qualificados que seu runtime reconhece:
@@ -1109,10 +1109,10 @@ Se você quiser que agentes diferentes usem modelos diferentes, use `model_overr
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3",
"gsd-codebase-mapper": "o4-mini"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3",
"msd-codebase-mapper": "o4-mini"
}
}
```
@@ -1164,7 +1164,7 @@ A saída JSON de `resolve-model` inclui `reasoning_effort` quando o nível de ru
}
```
Isso resolve `gsd-planner` → `gpt-5.6-sol` (xhigh), `gsd-executor` → `gpt-5.6-terra` (medium), `gsd-codebase-mapper` → `gpt-5.6-luna` (medium). O instalador do Codex incorpora `model = "..."` e `model_reasoning_effort = "..."` em cada TOML de agente gerado.
Isso resolve `msd-planner` → `gpt-5.6-sol` (xhigh), `msd-executor` → `gpt-5.6-terra` (medium), `msd-codebase-mapper` → `gpt-5.6-luna` (medium). O instalador do Codex incorpora `model = "..."` e `model_reasoning_effort = "..."` em cada TOML de agente gerado.
**Exemplo Claude** — opt-in explícito resolve para IDs Claude completos (sem necessidade de `resolve_model_ids: true`):
@@ -1200,7 +1200,7 @@ Isso resolve `gsd-planner` → `gpt-5.6-sol` (xhigh), `gsd-executor` → `gpt-5.
**Compatibilidade retroativa.** Configurações sem `runtime` definido não veem nenhuma mudança de comportamento — cada configuração existente continua funcionando identicamente. Instalações Codex que auto-definem `resolve_model_ids: "omit"` continuam omitindo o campo de modelo a menos que o usuário opte por definir `runtime: "codex"`.
**Runtimes desconhecidos.** Se `runtime` for definido para um valor sem mapa de nível integrado e sem `model_profile_overrides[<runtime>]`, o GSD cai de volta para o padrão seguro de alias Claude em vez de emitir um ID de modelo que o runtime não pode aceitar. Para suportar um novo runtime, popule `model_profile_overrides.<runtime>.{opus,sonnet,haiku}` com IDs válidos.
**Runtimes desconhecidos.** Se `runtime` for definido para um valor sem mapa de nível integrado e sem `model_profile_overrides[<runtime>]`, o MSD cai de volta para o padrão seguro de alias Claude em vez de emitir um ID de modelo que o runtime não pode aceitar. Para suportar um novo runtime, popule `model_profile_overrides.<runtime>.{opus,sonnet,haiku}` com IDs válidos.
### Filosofia de Perfil
@@ -1217,11 +1217,11 @@ Isso resolve `gsd-planner` → `gpt-5.6-sol` (xhigh), `gsd-executor` → `gpt-5.
> **[#49](https://github.com/open-gsd/gsd-core/issues/49)** — superfície de configuração de política de modelo neutra em relação ao provedor. Resolve antes do legado `model_profile_overrides`.
`model_policy` fornece uma maneira mais simples e neutra em relação ao provedor de configurar níveis de modelo entre runtimes. É a superfície preferida para runtimes não-Anthropic onde `model_profile_overrides` exigiria conhecer manualmente os IDs de modelo corretos. Configure via `/gsd-settings` → Seção 8 (Model Policy).
`model_policy` fornece uma maneira mais simples e neutra em relação ao provedor de configurar níveis de modelo entre runtimes. É a superfície preferida para runtimes não-Anthropic onde `model_profile_overrides` exigiria conhecer manualmente os IDs de modelo corretos. Configure via `/msd-settings` → Seção 8 (Model Policy).
### Predefinição de provedor conhecido
Escolha um provedor e nível de orçamento via o fluxo de configurações; o GSD escreve os IDs de modelo canônicos para aquela combinação de provedor/orçamento:
Escolha um provedor e nível de orçamento via o fluxo de configurações; o MSD escreve os IDs de modelo canônicos para aquela combinação de provedor/orçamento:
```json
{
@@ -1258,7 +1258,7 @@ Para controle avançado por runtime, `runtime_tiers` aceita entradas explícitas
### Provedor genérico (saída de escape)
Use `provider: "generic"` (ou `"custom"`) para OpenRouter, LiteLLM, gateways locais ou qualquer runtime onde você fornece IDs de modelo exatos. O GSD trata IDs de modelo como strings opacas — sem inferência de prefixo, sem padrões específicos do provedor:
Use `provider: "generic"` (ou `"custom"`) para OpenRouter, LiteLLM, gateways locais ou qualquer runtime onde você fornece IDs de modelo exatos. O MSD trata IDs de modelo como strings opacas — sem inferência de prefixo, sem padrões específicos do provedor:
```json
{
@@ -1297,10 +1297,10 @@ A resolução de `model_policy` fica acima de `model_profile_overrides` no resol
|----------|---------|
| `CLAUDE_CONFIG_DIR` | Substitui o diretório de configuração padrão (`~/.claude/`) |
| `GEMINI_API_KEY` | Detectada pelo monitor de contexto para alternar o nome do evento hook |
| `GSD_AUDIT` | Defina como `1` para habilitar o arquivo de auditoria de despacho (`.planning/.gsd-trace.jsonl`) |
| `GSD_AUDIT_ARGS` | Defina como `1` para incluir args de comando nos eventos de auditoria/erro (omitidos por padrão) |
| `GSD_PROJECT` | Substitui a raiz do projeto para suporte a workspace multi-projeto (v1.32) |
| `GSD_SKIP_SCHEMA_CHECK` | Ignora a detecção de deriva de esquema durante a fase de execução (v1.31) |
| `MSD_AUDIT` | Defina como `1` para habilitar o arquivo de auditoria de despacho (`.planning/.msd-trace.jsonl`) |
| `MSD_AUDIT_ARGS` | Defina como `1` para incluir args de comando nos eventos de auditoria/erro (omitidos por padrão) |
| `MSD_PROJECT` | Substitui a raiz do projeto para suporte a workspace multi-projeto (v1.32) |
| `MSD_SKIP_SCHEMA_CHECK` | Ignora a detecção de deriva de esquema durante a fase de execução (v1.31) |
| `WSL_DISTRO_NAME` | Detectado pelo instalador para tratamento de caminhos WSL |
---
@@ -1309,9 +1309,9 @@ A resolução de `model_policy` fica acima de `model_profile_overrides` no resol
Salve configurações como padrões globais para projetos futuros:
**Localização:** `~/.gsd/defaults.json`
**Localização:** `~/.msd/defaults.json`
Quando `/gsd-new-project` cria um novo `config.json`, ele lê os padrões globais e os mescla como configuração inicial. Configurações por projeto sempre substituem os globais.
Quando `/msd-new-project` cria um novo `config.json`, ele lê os padrões globais e os mescla como configuração inicial. Configurações por projeto sempre substituem os globais.
---
@@ -1327,7 +1327,7 @@ Quando um despacho falha, uma linha JSON é emitida para stderr:
{ "kind": "HandlerFailure", "traceId": "...", "command": "plan", "timestamp": "...", "message": "..." }
```
O campo `kind` corresponde a uma das variantes de erro do Hub: `UnknownCommand`, `InvalidArgs`, `HandlerRefusal` ou `HandlerFailure`. Args são omitidos por padrão (privacidade); consulte `GSD_AUDIT_ARGS` abaixo.
O campo `kind` corresponde a uma das variantes de erro do Hub: `UnknownCommand`, `InvalidArgs`, `HandlerRefusal` ou `HandlerFailure`. Args são omitidos por padrão (privacidade); consulte `MSD_AUDIT_ARGS` abaixo.
### Trilha de auditoria (opt-in)
@@ -1335,7 +1335,7 @@ Habilite o arquivo de auditoria somente-acréscimo para registrar cada despacho
**Via variável de ambiente:**
```bash
GSD_AUDIT=1 gsd plan
MSD_AUDIT=1 msd plan
```
**Via configuração (`config.audit.enabled`):**
@@ -1347,7 +1347,7 @@ GSD_AUDIT=1 gsd plan
}
```
**Localização do arquivo de auditoria:** `.planning/.gsd-trace.jsonl` (gitignored)
**Localização do arquivo de auditoria:** `.planning/.msd-trace.jsonl` (gitignored)
Cada linha é um objeto JSON completo de `DispatchEvent` contendo tanto `traceId` (um UUID v4 único por despacho) quanto `parentTraceId` (presente quando um chamador passa `req.parentTraceId` para `Hub.dispatch`). Um futuro init-composer (Fase 2) irá conectar `parentTraceId` automaticamente para que todos os despachos filhos de uma única invocação de nível superior compartilhem um pai comum; até então, despachos folha emitem `parentTraceId: undefined`. Você pode correlacionar eventos filhos a um pai filtrando o arquivo de auditoria em `parentTraceId === <rootTraceId>`. O arquivo é somente-acréscimo e nunca truncado; rotacione ou remova-o manualmente quando desejado. `parentTraceId` deve ser um UUID v4 canônico (RFC 4122, formato `xxxxxxxx-xxxx-4xxx-[89ab]xxx-xxxxxxxxxxxx`); valores que não correspondem a este formato são silenciosamente descartados do evento emitido e não aparecerão na saída de auditoria.
@@ -1356,10 +1356,10 @@ Cada linha é um objeto JSON completo de `DispatchEvent` contendo tanto `traceId
Por padrão, os args de comando são **omitidos** de todos os eventos emitidos (tanto erros de stderr quanto o arquivo de auditoria). Para incluir args verbatim:
```bash
GSD_AUDIT_ARGS=1 GSD_AUDIT=1 gsd plan --tdd
MSD_AUDIT_ARGS=1 MSD_AUDIT=1 msd plan --tdd
```
`GSD_AUDIT_ARGS` aplica-se simultaneamente tanto à linha de erro do stderr quanto ao arquivo de auditoria.
`MSD_AUDIT_ARGS` aplica-se simultaneamente tanto à linha de erro do stderr quanto ao arquivo de auditoria.
---

30
docs/pt-BR/FEATURES.md
View File

@@ -1,6 +1,6 @@
# Referência de Recursos do GSD
# Referência de Recursos do MSD
Visão em Português dos recursos centrais do GSD.
Visão em Português dos recursos centrais do MSD.
Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em inglês](../FEATURES.md).
---
@@ -13,8 +13,8 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
- **Execução em ondas paralelas** com controle por dependências
- **Commits atômicos por tarefa** para rastreabilidade e rollback
- **Verificação pós-execução** com foco em objetivos da fase
- **UAT guiado** via `/gsd-verify-work`
- **Suporte brownfield** com `/gsd-onboard` e `/gsd-map-codebase`
- **UAT guiado** via `/msd-verify-work`
- **Suporte brownfield** com `/msd-onboard` e `/msd-map-codebase`
- **Workstreams** para trilhas paralelas sem colisão de estado
- **Backlog, seeds e threads** para memória de médio/longo prazo
@@ -28,21 +28,21 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
## UX de frontend
- **`/gsd-ui-phase`**: contrato visual antes da execução
- **`/gsd-ui-review`**: auditoria visual em 6 pilares
- **`/msd-ui-phase`**: contrato visual antes da execução
- **`/msd-ui-review`**: auditoria visual em 6 pilares
- **UI safety gate** para uso de registries de terceiros
## Operação e manutenção
- **Perfis de modelo** (`quality`, `balanced`, `budget`, `inherit`)
- **Ajuste por toggles** para custo/qualidade/velocidade
- **Diagnóstico forense** com `/gsd-forensics`
- **Relatório de sessão** com `/gsd-pause-work --report`
- **Diagnóstico forense** com `/msd-forensics`
- **Relatório de sessão** com `/msd-pause-work --report`
## Novidades v1.31--v1.32
- **Schema drift detection** — detecta alterações em ORM schema sem migração correspondente
- **Security enforcement** — verificação de segurança ancorada em threat model (`/gsd-secure-phase`)
- **Security enforcement** — verificação de segurança ancorada em threat model (`/msd-secure-phase`)
- **Discuss chain mode** — encadeia discuss → plan → execute com `--chain`
- **Single-phase autonomous** — executa apenas uma fase com `--only N`
- **Scope reduction detection** — defesa em 3 camadas contra remoção silenciosa de requisitos
@@ -54,8 +54,8 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
- **Read-before-edit guard** — hook que previne loops infinitos de retry (v1.32)
- **Context reduction** — truncamento de markdown e ordenação cache-friendly (v1.32)
- **`--power` flag** — respostas em batch via arquivo para discuss-phase (v1.32)
- **`--diagnose` flag** — modo diagnóstico sem modificações no `/gsd-debug` (v1.32)
- **`/gsd-manager --analyze-deps`** — detecta dependências entre fases (v1.32)
- **`--diagnose` flag** — modo diagnóstico sem modificações no `/msd-debug` (v1.32)
- **`/msd-manager --analyze-deps`** — detecta dependências entre fases (v1.32)
- **Response language config** — `response_language` para saída consistente em idioma (v1.32)
- **Novos runtimes** — Trae IDE, Cline, Augment Code (v1.32)
- **Manual update** — procedimento de atualização sem npm (v1.32)
@@ -66,10 +66,10 @@ Para catálogo completo e detalhamento exaustivo, consulte [FEATURES.md em ingl
| Cenário | Comandos |
|--------|----------|
| Projeto novo | `/gsd-new-project` -> `/gsd-discuss-phase` -> `/gsd-plan-phase` -> `/gsd-execute-phase` |
| Correção rápida | `/gsd-quick` |
| Código existente | `/gsd-onboard` -> handoffs para `/gsd-map-codebase`, `/gsd-ingest-docs`, `/gsd-new-project` |
| Fechamento de release | `/gsd-audit-milestone` -> `/gsd-complete-milestone` |
| Projeto novo | `/msd-new-project` -> `/msd-discuss-phase` -> `/msd-plan-phase` -> `/msd-execute-phase` |
| Correção rápida | `/msd-quick` |
| Código existente | `/msd-onboard` -> handoffs para `/msd-map-codebase`, `/msd-ingest-docs`, `/msd-new-project` |
| Fechamento de release | `/msd-audit-milestone` -> `/msd-complete-milestone` |
---

494
docs/pt-BR/INVENTORY.md
View File

@@ -1,64 +1,64 @@
# Inventário de Superfícies Entregues do GSD
# Inventário de Superfícies Entregues do MSD
> 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.
> Registro autoritativo de toda superfície MSD 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.
- 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/msd/*.md | wc -l`, `ls agents/msd-*.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. O teste de controle de drift em `tests/inventory-manifest-sync.test.cjs` ancora 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.
Este é o registro autoritativo de toda superfície do MSD 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*).
Registro completo em `agents/msd-*.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 |
| msd-project-researcher | Pesquisa o ecossistema do domínio antes da criação do roadmap (stack, funcionalidades, arquitetura, armadilhas). | `/msd-new-project`, `/msd-new-milestone` | primary |
| msd-phase-researcher | Pesquisa a abordagem de implementação para uma fase específica antes do planejamento. | `/msd-plan-phase` | primary |
| msd-ui-researcher | Produz contratos de design de UI para fases de frontend. | `/msd-ui-phase` | primary |
| msd-assumptions-analyzer | Produz premissas embasadas em evidências para a discuss-phase (modo de premissas). | workflow `discuss-phase-assumptions` | primary |
| msd-advisor-researcher | Pesquisa uma única decisão em zona cinzenta durante o modo advisordiscuss-phase. | workflow `discuss-phase` (modo advisor) | primary |
| msd-research-synthesizer | Combina saídas de pesquisadores paralelos em um SUMMARY.md unificado. | `/msd-new-project` | primary |
| msd-planner | Cria planos de fase executáveis com detalhamento de tarefas e verificação retroativa a partir dos objetivos. | `/msd-plan-phase`, `/msd-quick` | primary |
| msd-roadmapper | Cria roadmaps de projeto com detalhamento de fases e mapeamento de requisitos. | `/msd-new-project` | primary |
| msd-executor | Executa planos MSD com commits atômicos e tratamento de desvios. | `/msd-execute-phase`, `/msd-quick` | primary |
| msd-plan-checker | Verifica se os planos vão atingir os objetivos da fase (8 dimensões de verificação). | `/msd-plan-phase` (loop de verificação) | primary |
| msd-integration-checker | Verifica a integração entre fases e fluxos de ponta a ponta. | `/msd-audit-milestone` | primary |
| msd-ui-checker | Valida contratos de design UI-SPEC.md contra dimensões de qualidade. | `/msd-ui-phase` (loop de validação) | primary |
| msd-verifier | Verifica o alcance dos objetivos da fase por meio de análise retroativa a partir dos objetivos. | `/msd-execute-phase` | primary |
| msd-nyquist-auditor | Preenche lacunas de validação Nyquist gerando testes. | `/msd-validate-phase` | primary |
| msd-ui-auditor | Auditoria visual retroativa de 6 pilares do código frontend implementado. | `/msd-ui-review` | primary |
| msd-codebase-mapper | Explora a base de código e escreve documentos de análise estruturados. | `/msd-map-codebase` | primary |
| msd-debugger | Investiga bugs usando o método científico com estado persistente. | `/msd-debug`, `/msd-verify-work` | primary |
| msd-user-profiler | Avalia o comportamento do desenvolvedor em 8 dimensões. | `/msd-profile-user` | primary |
| msd-doc-writer | Escreve e atualiza a documentação do projeto. | `/msd-docs-update` | primary |
| msd-doc-verifier | Verifica afirmações factuais na documentação gerada. | `/msd-docs-update` | primary |
| msd-security-auditor | Verifica mitigações de ameaças do modelo de ameaças do PLAN.md. | `/msd-secure-phase` | primary |
| msd-pattern-mapper | Mapeia novos arquivos para os análogos existentes mais próximos; escreve PATTERNS.md para o planejador. | `/msd-plan-phase` (entre pesquisa e planejamento) | advanced stub |
| msd-debug-session-manager | Executa o loop completo de checkpoint e continuação do `/msd-debug` em contexto isolado para manter o contexto principal enxuto. | `/msd-debug` | advanced stub |
| msd-code-reviewer | Revisa arquivos-fonte em busca de bugs, problemas de segurança e qualidade de código; produz REVIEW.md. | `/msd-code-review` | advanced stub |
| msd-code-fixer | Aplica correções às descobertas do REVIEW.md com commits atômicos por correção; produz REVIEW-FIX.md. | `/msd-code-review --fix` | advanced stub |
| msd-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). | `/msd-ai-integration-phase` | advanced stub |
| msd-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). | `/msd-ai-integration-phase` | advanced stub |
| msd-eval-planner | Projeta uma estratégia de avaliação estruturada para uma fase de IA (AI-SPEC.md §5–§7). | `/msd-ai-integration-phase` | advanced stub |
| msd-eval-auditor | Auditoria retroativa da cobertura de avaliação de uma fase de IA; produz EVAL-REVIEW.md (COVERED/PARTIAL/MISSING). | `/msd-eval-review` | advanced stub |
| msd-framework-selector | Matriz de decisão interativa com ≤6 perguntas que pontua e recomenda um framework de IA/LLM. | `/msd-ai-integration-phase` | advanced stub |
| msd-intel-updater | Escreve arquivos de intel estruturados (`.planning/intel/*.json`) usados como base de conhecimento consultável da base de código. | `/msd-map-codebase --query` | advanced stub |
| msd-doc-classifier | Classifica um único documento de planejamento como ADR, PRD, SPEC, DOC ou UNKNOWN; invocado em paralelo para processar o corpus de documentos. | `/msd-ingest-docs` | advanced stub |
| msd-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. | `/msd-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`.
**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/msd-*.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.
Registro completo em `commands/msd/*.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
@@ -66,199 +66,199 @@ Esses seis roteadores são entradas apenas descritivas que o modelo seleciona pr
| 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) |
| `/msd-workflow` | Roteador de pipeline de fase — discuss / plan / execute / verify / phase / progress. | [commands/msd/ns-workflow.md](../../commands/msd/ns-workflow.md) |
| `/msd-project` | Roteador de ciclo de vida do projeto — milestones, auditorias, resumo. | [commands/msd/ns-project.md](../../commands/msd/ns-project.md) |
| `/msd-quality` | Roteador de portão de qualidade — revisão de código, debug, auditoria, segurança, avaliação, ui. | [commands/msd/ns-review.md](../../commands/msd/ns-review.md) |
| `/msd-context` | Roteador de inteligência da base de código — map, graphify, docs, learnings. | [commands/msd/ns-context.md](../../commands/msd/ns-context.md) |
| `/msd-manage` | Roteador de gerenciamento — config, workspace, workstreams, thread, update, ship, inbox. | [commands/msd/ns-manage.md](../../commands/msd/ns-manage.md) |
| `/msd-ideate` | Roteador de exploração e captura — explore, sketch, spike, spec, capture. | [commands/msd/ns-ideate.md](../../commands/msd/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-onboard` | Guia código existente por mapeamento, ingestão de docs, configuração de projeto e onboarding summary. | [commands/gsd/onboard.md](../../commands/gsd/onboard.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) |
| `/msd-new-project` | Inicializa um novo projeto com coleta profunda de contexto e PROJECT.md. | [commands/msd/new-project.md](../../commands/msd/new-project.md) |
| `/msd-onboard` | Guia código existente por mapeamento, ingestão de docs, configuração de projeto e onboarding summary. | [commands/msd/onboard.md](../../commands/msd/onboard.md) |
| `/msd-workspace` | Gerencia workspaces MSD — criar (`--new`), listar (`--list`) ou remover (`--remove`) ambientes de workspace isolados. | [commands/msd/workspace.md](../../commands/msd/workspace.md) |
| `/msd-discuss-phase` | Coleta contexto da fase por meio de perguntas adaptativas antes do planejamento. | [commands/msd/discuss-phase.md](../../commands/msd/discuss-phase.md) |
| `/msd-mvp-phase` | Planeja uma fase como uma fatia vertical de MVP — história de usuário, divisão SPIDR, depois plan-phase. | [commands/msd/mvp-phase.md](../../commands/msd/mvp-phase.md) |
| `/msd-spec-phase` | Refinamento socrático de especificação produzindo um SPEC.md com requisitos falsificáveis. | [commands/msd/spec-phase.md](../../commands/msd/spec-phase.md) |
| `/msd-ui-phase` | Gera contrato de design de UI (UI-SPEC.md) para fases de frontend. | [commands/msd/ui-phase.md](../../commands/msd/ui-phase.md) |
| `/msd-ai-integration-phase` | Gera contrato de design de IA (AI-SPEC.md) via seleção de framework, pesquisa e planejamento de avaliação. | [commands/msd/ai-integration-phase.md](../../commands/msd/ai-integration-phase.md) |
| `/msd-plan-phase` | Cria plano de fase detalhado (PLAN.md) com loop de verificação. | [commands/msd/plan-phase.md](../../commands/msd/plan-phase.md) |
| `/msd-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/msd/plan-review-convergence.md](../../commands/msd/plan-review-convergence.md) |
| `/msd-ultraplan-phase` | [BETA] Delega a fase de planejamento ao ultraplan cloud do Claude Code — rascunhos remotamente, revisar no navegador, importar de volta via `/msd-import`. Apenas Claude Code. | [commands/msd/ultraplan-phase.md](../../commands/msd/ultraplan-phase.md) |
| `/msd-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/msd/spike.md](../../commands/msd/spike.md) |
| `/msd-sketch` | Esboça rapidamente ideias de UI/design usando mockups HTML descartáveis; use `--wrap-up` para empacotar as descobertas. | [commands/msd/sketch.md](../../commands/msd/sketch.md) |
| `/msd-execute-phase` | Executa todos os planos de uma fase com paralelização baseada em ondas. | [commands/msd/execute-phase.md](../../commands/msd/execute-phase.md) |
| `/msd-verify-work` | Valida funcionalidades construídas por meio de UAT conversacional com autodiagnóstico. | [commands/msd/verify-work.md](../../commands/msd/verify-work.md) |
| `/msd-ship` | Cria PR, executa revisão e prepara para merge após verificação. | [commands/msd/ship.md](../../commands/msd/ship.md) |
| `/msd-fast` | Executa uma tarefa trivial inline — sem subagentes, sem overhead de planejamento. | [commands/msd/fast.md](../../commands/msd/fast.md) |
| `/msd-quick` | Executa uma tarefa rápida com garantias MSD (commits atômicos, rastreamento de estado) mas pula agentes opcionais. | [commands/msd/quick.md](../../commands/msd/quick.md) |
| `/msd-ui-review` | Auditoria visual retroativa de 6 pilares do código frontend implementado. | [commands/msd/ui-review.md](../../commands/msd/ui-review.md) |
| `/msd-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/msd/code-review.md](../../commands/msd/code-review.md) |
| `/msd-eval-review` | Audita retroativamente a cobertura de avaliação de uma fase de IA executada; produz EVAL-REVIEW.md. | [commands/msd/eval-review.md](../../commands/msd/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) |
| `/msd-phase` | CRUD de fases — adicionar (padrão), inserir (`--insert`), remover (`--remove`) ou editar (`--edit`) fases no ROADMAP.md. | [commands/msd/phase.md](../../commands/msd/phase.md) |
| `/msd-add-tests` | Gera testes para uma fase concluída com base nos critérios de UAT e na implementação. | [commands/msd/add-tests.md](../../commands/msd/add-tests.md) |
| `/msd-validate-phase` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída. | [commands/msd/validate-phase.md](../../commands/msd/validate-phase.md) |
| `/msd-secure-phase` | Verifica retroativamente as mitigações de ameaças para uma fase concluída. | [commands/msd/secure-phase.md](../../commands/msd/secure-phase.md) |
| `/msd-audit-milestone` | Audita a conclusão do milestone contra a intenção original antes do arquivamento. | [commands/msd/audit-milestone.md](../../commands/msd/audit-milestone.md) |
| `/msd-audit-uat` | Auditoria entre fases de todos os itens de UAT e verificação pendentes. | [commands/msd/audit-uat.md](../../commands/msd/audit-uat.md) |
| `/msd-audit-fix` | Pipeline autônomo de auditoria para correção — encontrar problemas, classificar, corrigir, testar, commitar. | [commands/msd/audit-fix.md](../../commands/msd/audit-fix.md) |
| `/msd-complete-milestone` | Arquiva o milestone concluído e prepara para a próxima versão. | [commands/msd/complete-milestone.md](../../commands/msd/complete-milestone.md) |
| `/msd-new-milestone` | Inicia um novo ciclo de milestone — atualizar PROJECT.md e rotear para os requisitos. | [commands/msd/new-milestone.md](../../commands/msd/new-milestone.md) |
| `/msd-milestone-summary` | Gera um resumo abrangente do projeto a partir dos artefatos do milestone. | [commands/msd/milestone-summary.md](../../commands/msd/milestone-summary.md) |
| `/msd-cleanup` | Arquiva diretórios de fases acumulados de milestones concluídos. | [commands/msd/cleanup.md](../../commands/msd/cleanup.md) |
| `/msd-manager` | Central de comando interativa para gerenciar múltiplas fases de um terminal. | [commands/msd/manager.md](../../commands/msd/manager.md) |
| `/msd-workstreams` | Gerencia workstreams paralelos — listar, criar, alternar, status, progresso, concluir, retomar. | [commands/msd/workstreams.md](../../commands/msd/workstreams.md) |
| `/msd-autonomous` | Executa todas as fases restantes de forma autônoma — discuss → plan → execute por fase. | [commands/msd/autonomous.md](../../commands/msd/autonomous.md) |
| `/msd-undo` | Reversão git segura — reverter commits de fase ou plano usando o manifesto da fase. | [commands/msd/undo.md](../../commands/msd/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) |
| `/msd-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/msd/progress.md](../../commands/msd/progress.md) |
| `/msd-capture` | Captura ideias, tarefas, notas e seeds — todo (padrão), `--note`, `--backlog`, `--seed` ou `--list` de todos pendentes. | [commands/msd/capture.md](../../commands/msd/capture.md) |
| `/msd-stats` | Exibe estatísticas do projeto — fases, planos, requisitos, métricas git, linha do tempo. | [commands/msd/stats.md](../../commands/msd/stats.md) |
| `/msd-pause-work` | Cria handoff de contexto ao pausar o trabalho no meio de uma fase. | [commands/msd/pause-work.md](../../commands/msd/pause-work.md) |
| `/msd-resume-work` | Retoma o trabalho da sessão anterior com restauração completa do contexto. | [commands/msd/resume-work.md](../../commands/msd/resume-work.md) |
| `/msd-explore` | Ideação socrática e roteamento de ideias — pensar nas ideias antes de se comprometer. | [commands/msd/explore.md](../../commands/msd/explore.md) |
| `/msd-review-backlog` | Revisa e promove itens do backlog para o milestone ativo. | [commands/msd/review-backlog.md](../../commands/msd/review-backlog.md) |
| `/msd-thread` | Gerencia threads de contexto persistentes para trabalho entre sessões. | [commands/msd/thread.md](../../commands/msd/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) |
| `/msd-map-codebase` | Analisa a base de código com agentes mapeadores paralelos; use `--fast` para varredura leve ou `--query` para consultas de intel. | [commands/msd/map-codebase.md](../../commands/msd/map-codebase.md) |
| `/msd-graphify` | Constrói, consulta e inspeciona o grafo de conhecimento do projeto em `.planning/graphs/`. | [commands/msd/graphify.md](../../commands/msd/graphify.md) |
| `/msd-extract-learnings` | Extrai decisões, lições, padrões e surpresas de artefatos de fases concluídas. | [commands/msd/extract-learnings.md](../../commands/msd/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) |
| `/msd-review` | Solicita revisão de pares entre IAs de planos de fase a partir de CLIs de IA externos. | [commands/msd/review.md](../../commands/msd/review.md) |
| `/msd-debug` | Depuração sistemática com estado persistente entre resets de contexto. | [commands/msd/debug.md](../../commands/msd/debug.md) |
| `/msd-forensics` | Investigação post-mortem de workflows MSD com falha — analisa git, artefatos, estado. | [commands/msd/forensics.md](../../commands/msd/forensics.md) |
| `/msd-health` | Diagnostica a integridade do diretório de planejamento e opcionalmente repara problemas. | [commands/msd/health.md](../../commands/msd/health.md) |
| `/msd-import` | Ingere planos externos com detecção de conflitos contra decisões do projeto. | [commands/msd/import.md](../../commands/msd/import.md) |
| `/msd-inbox` | Faz triagem e revisão de todas as issues e PRs abertas do GitHub contra os templates do projeto. | [commands/msd/inbox.md](../../commands/msd/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) |
| `/msd-docs-update` | Gera ou atualiza a documentação do projeto verificada contra a base de código. | [commands/msd/docs-update.md](../../commands/msd/docs-update.md) |
| `/msd-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/msd/ingest-docs.md](../../commands/msd/ingest-docs.md) |
| `/msd-profile-user` | Gera perfil comportamental do desenvolvedor e artefatos descobríveis pelo Claude. | [commands/msd/profile-user.md](../../commands/msd/profile-user.md) |
| `/msd-settings` | Configura alternâncias de workflow MSD e perfil de modelo. | [commands/msd/settings.md](../../commands/msd/settings.md) |
| `/msd-config` | Configura as definições MSD — alternâncias de workflow (padrão), parâmetros avançados (`--advanced`), integrações (`--integrations`) ou perfil de modelo (`--profile`). | [commands/msd/config.md](../../commands/msd/config.md) |
| `/msd-pr-branch` | Cria um branch limpo de PR filtrando commits de `.planning/`. | [commands/msd/pr-branch.md](../../commands/msd/pr-branch.md) |
| `/msd-surface` | Alterna quais habilidades são expostas — aplica um perfil, lista ou desativa um cluster sem reinstalar. | [commands/msd/surface.md](../../commands/msd/surface.md) |
| `/msd-update` | Atualiza o MSD para a versão mais recente; use `--sync` para sincronizar habilidades entre runtimes ou `--reapply` para reaplicar patches locais. | [commands/msd/update.md](../../commands/msd/update.md) |
| `/msd-help` | Exibe os comandos MSD disponíveis e o guia de uso. | [commands/msd/help.md](../../commands/msd/help.md) |
---
## Workflows (88 entregues)
Registro completo em `gsd-core/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.
Registro completo em `msd-core/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) |
| `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` |
| `add-backlog.md` | Adiciona um item de backlog ao ROADMAP.md usando numeração 999.x. | `/msd-capture --backlog` |
| `add-phase.md` | Adiciona uma nova fase inteira ao final do milestone atual no roadmap. | `/msd-phase` (padrão) |
| `add-tests.md` | Gera testes unitários e E2E para uma fase concluída com base em seus artefatos. | `/msd-add-tests` |
| `add-todo.md` | Captura uma ideia ou tarefa que surge durante uma sessão como um todo estruturado. | `/msd-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. | `/msd-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`. | `/msd-manager --analyze-deps` |
| `audit-fix.md` | Pipeline autônomo de auditoria para correção — executar auditoria, analisar, classificar, corrigir, testar, commitar. | `/msd-audit-fix` |
| `audit-milestone.md` | Verifica se o milestone atendeu sua definição de pronto ao agregar verificações de fase. | `/msd-audit-milestone` |
| `audit-uat.md` | Auditoria entre fases de arquivos de UAT e verificação; produz lista priorizada de itens pendentes. | `/msd-audit-uat` |
| `autonomous.md` | Conduz as fases do milestone de forma autônoma — todas restantes, um intervalo ou uma única fase. | `/msd-autonomous` |
| `check-todos.md` | Lista todos pendentes, permite seleção, carrega contexto e roteia para a ação apropriada. | `/msd-capture --list` |
| `cleanup.md` | Arquiva diretórios de fases acumulados de milestones concluídos. | `/msd-cleanup` |
| `code-review-fix.md` | Autocorrige problemas do REVIEW.md via msd-code-fixer com commits atômicos por correção. | `/msd-code-review --fix` |
| `code-review.md` | Revisa alterações de código-fonte da fase via msd-code-reviewer; produz REVIEW.md. | `/msd-code-review` |
| `complete-milestone.md` | Marca uma versão entregue como concluída — entrada no MILESTONES.md, evolução do PROJECT.md, tag. | `/msd-complete-milestone` |
| `diagnose-issues.md` | Orquestra agentes de debug paralelos para investigar lacunas de UAT e encontrar causas raiz. | `/msd-verify-work` (autodiagnóstico) |
| `discuss-phase-assumptions.md` | Discuss no modo de premissas — extrai decisões de implementação via análise com base no código primeiro. | `/msd-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. | `/msd-discuss-phase --power` |
| `discuss-phase.md` | Extrai decisões de implementação por meio de discussão iterativa de zonas cinzentas. | `/msd-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. | `/msd-mvp-phase` |
| `do.md` | Roteia texto livre do usuário para o comando MSD mais adequado. | `/msd-progress --do` |
| `docs-update.md` | Gera, atualiza e verifica documentação canônica e escrita à mão do projeto. | `/msd-docs-update` |
| `edit-phase.md` | Edita qualquer campo de uma fase existente no ROADMAP.md no lugar, preservando número e posição. | `/msd-phase --edit` |
| `eval-review.md` | Auditoria retroativa da cobertura de avaliação de uma fase de IA implementada. | `/msd-eval-review` |
| `execute-phase.md` | Executa todos os planos de uma fase usando execução paralela baseada em ondas. | `/msd-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` |
| `explore.md` | Ideação socrática — guia o desenvolvedor por perguntas investigativas. | `/msd-explore` |
| `debug.md` | Depuração sistemática — roteamento de subcomandos, criação de sessão, delegação para msd-debug-session-manager. | `/msd-debug` |
| `extract-learnings.md` | Extrai decisões, lições, padrões e surpresas de artefatos de fases concluídas. | `/msd-extract-learnings` |
| `fast.md` | Executa uma tarefa trivial inline sem overhead de subagente. | `/msd-fast` |
| `forensics.md` | Investigação forense de workflows com falha — análise de git, artefatos e estado. | `/msd-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` |
| `onboard.md` | Orquestração de onboarding brownfield — mapear código, ingerir docs, inicializar planning e resumir próximo passo. | `/gsd-onboard` |
| `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` |
| `health.md` | Valida a integridade do diretório `.planning/` e reporta problemas acionáveis. | `/msd-health` |
| `help.md` | Exibe a referência completa de comandos do MSD Core. | `/msd-help` |
| `import.md` | Ingere planos externos com detecção de conflitos contra decisões existentes do projeto. | `/msd-import` |
| `inbox.md` | Faz triagem de issues e PRs abertas do GitHub contra templates de contribuição do projeto. | `/msd-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. | `/msd-ingest-docs` |
| `insert-phase.md` | Insere uma fase decimal para trabalho urgente descoberto no meio de um milestone. | `/msd-phase --insert` |
| `list-phase-assumptions.md` | Levanta as premissas do Claude sobre uma fase antes do planejamento. | `/msd-discuss-phase --assumptions` |
| `list-workspaces.md` | Lista todos os workspaces MSD encontrados em `~/msd-workspaces/` com seu status. | `/msd-workspace --list` |
| `manager.md` | Central de comando interativa de milestone — dashboard, discuss inline, plan/execute em segundo plano. | `/msd-manager` |
| `map-codebase.md` | Orquestra agentes mapeadores paralelos da base de código para produzir documentos em `.planning/codebase/`. | `/msd-map-codebase` |
| `milestone-summary.md` | Síntese do resumo do milestone — artefato de onboarding e revisão a partir dos artefatos do milestone. | `/msd-milestone-summary` |
| `new-milestone.md` | Inicia um novo ciclo de milestone — carregar contexto do projeto, coletar objetivos, atualizar PROJECT.md/STATE.md. | `/msd-new-milestone` |
| `new-project.md` | Fluxo unificado de novo projeto — questionamento, pesquisa (opcional), requisitos, roadmap. | `/msd-new-project` |
| `onboard.md` | Orquestração de onboarding brownfield — mapear código, ingerir docs, inicializar planning e resumir próximo passo. | `/msd-onboard` |
| `new-workspace.md` | Cria um workspace isolado com worktrees/clones do repositório e um `.planning/` independente. | `/msd-workspace --new` |
| `next.md` | Detecta o estado atual do projeto e avança automaticamente para o próximo passo lógico. | `/msd-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-work.md` | UAT conversacional com autodiagnóstico — produz UAT.md e planos de correção. | `/gsd-verify-work` |
| `note.md` | Captura de ideia sem atrito — uma chamada Write, uma linha de confirmação. | `/msd-capture --note` |
| `pause-work.md` | Cria os arquivos de handoff estruturados `.planning/HANDOFF.json` e `.continue-here.md`. | `/msd-pause-work` |
| `plan-phase.md` | Cria arquivos PLAN.md executáveis com pesquisa integrada e loop de verificação. | `/msd-plan-phase`, `/msd-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. | `/msd-plan-review-convergence` |
| `plant-seed.md` | Captura uma ideia prospectiva como um arquivo de seed estruturado com condições de acionamento. | `/msd-capture --seed` |
| `pr-branch.md` | Cria um branch limpo para pull requests filtrando commits de `.planning/`. | `/msd-pr-branch` |
| `profile-user.md` | Orquestra o fluxo completo de perfil do desenvolvedor — consentimento, varredura de sessão, geração de perfil. | `/msd-profile-user` |
| `progress.md` | Renderização de progresso — contexto do projeto, posição e roteamento para próxima ação. | `/msd-progress` |
| `quick.md` | Execução de tarefa rápida com garantias MSD (commits atômicos, rastreamento de estado). | `/msd-quick` |
| `reapply-patches.md` | Reaaplica modificações locais após uma atualização do MSD. | `/msd-update --reapply` |
| `remove-phase.md` | Remove uma fase futura do roadmap e renumera as fases subsequentes. | `/msd-phase --remove` |
| `remove-workspace.md` | Remove um workspace MSD e limpa worktrees. | `/msd-workspace --remove` |
| `resume-project.md` | Retoma o trabalho — restaura o contexto completo do STATE.md, HANDOFF.json e artefatos. | `/msd-resume-work` |
| `review.md` | Revisão de plano entre IAs via CLIs externos; produz REVIEWS.md. | `/msd-review` |
| `scan.md` | Varredura rápida e focada da base de código — alternativa leve ao map-codebase. | `/msd-map-codebase --fast` |
| `secure-phase.md` | Auditoria retroativa de mitigação de ameaças para uma fase concluída. | `/msd-secure-phase` |
| `session-report.md` | Relatório de sessão — uso de tokens, resumo do trabalho, resultados. | `/msd-pause-work --report` |
| `settings.md` | Configura alternâncias de workflow MSD e perfil de modelo. | `/msd-settings`, `/msd-config --profile` |
| `settings-advanced.md` | Configura parâmetros avançados do MSD — bouncing de plano, timeouts, templates de branch, execução entre IAs, parâmetros de runtime. | `/msd-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>`). | `/msd-config --integrations` |
| `ship.md` | Cria PR, executa revisão e prepara para merge após verificação. | `/msd-ship` |
| `sketch.md` | Explora direções de design por meio de mockups HTML descartáveis com 2–3 variantes por sketch. | `/msd-sketch` |
| `sketch-wrap-up.md` | Curadoria das descobertas do sketch e empacotamento como uma habilidade persistente `sketch-findings-[project]`. | `/msd-sketch --wrap-up` |
| `spec-phase.md` | Refinamento socrático de especificação com pontuação de ambiguidade; produz SPEC.md. | `/msd-spec-phase` |
| `spike.md` | Validação rápida de viabilidade por meio de experimentos focados e descartáveis. | `/msd-spike` |
| `spike-wrap-up.md` | Curadoria das descobertas do spike e empacotamento como uma habilidade persistente `spike-findings-[project]`. | `/msd-spike --wrap-up` |
| `stats.md` | Renderização de estatísticas do projeto — fases, planos, requisitos, métricas git. | `/msd-stats` |
| `sync-skills.md` | Sincronização de habilidades MSD entre runtimes — diff e aplicação de diretórios de habilidades `msd-*` entre raízes de runtime. | `/msd-update --sync` |
| `transition.md` | Workflow de transição de limite de fase — verificações de workstream, avanço de estado. | `execute-phase.md`, `/msd-progress --next` |
| `ui-phase.md` | Gera contrato de design UI-SPEC.md via msd-ui-researcher. | `/msd-ui-phase` |
| `ui-review.md` | Auditoria visual retroativa de 6 pilares via msd-ui-auditor. | `/msd-ui-review` |
| `ultraplan-phase.md` | [BETA] Delega o planejamento ao ultraplan cloud do Claude Code; rascunhos remotamente e importa de volta via `/msd-import`. | `/msd-ultraplan-phase` |
| `undo.md` | Reversão git segura — commits de fase ou plano usando o manifesto da fase. | `/msd-undo` |
| `thread.md` | Cria, lista, fecha ou retoma threads de contexto persistentes para trabalho entre sessões. | `/msd-thread` |
| `update.md` | Atualiza o MSD para a versão mais recente com exibição do changelog. | `/msd-update` |
| `validate-phase.md` | Audita retroativamente e preenche lacunas de validação Nyquist para uma fase concluída. | `/msd-validate-phase` |
| `verify-work.md` | UAT conversacional com autodiagnóstico — produz UAT.md e planos de correção. | `/msd-verify-work` |
> **Nota:** Alguns workflows não têm comando direto voltado ao usuário (p. ex. `execute-plan.md`, `transition.md`, `node-repair.md`, `diagnose-issues.md`) — eles são invocados internamente por workflows orquestradores.
@@ -266,7 +266,7 @@ Registro completo em `gsd-core/workflows/*.md`. Workflows são orquestradores en
## Referências (62 entregues)
Registro completo em `gsd-core/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-gsd-corereferencesmd) — clusters principais, de workflow, de modelo de raciocínio e a decomposição modular do planejador.
Registro completo em `msd-core/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-msd-corereferencesmd) — clusters principais, de workflow, de modelo de raciocínio e a decomposição modular do planejador.
### Referências Principais
@@ -278,7 +278,7 @@ Registro completo em `gsd-core/references/*.md`. Referências são documentos de
| `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. |
| `verifier-phase-gates.md` | Gates de verificação carregados eager pelo gsd-verifier (migrados do workflow verify-phase aposentado, #1892): validação de cobertura de decisões (#2492), auditoria de qualidade de testes, escopo de human-verification para fases de infraestrutura (#2504). | |
| `verifier-phase-gates.md` | Gates de verificação carregados eager pelo msd-verifier (migrados do workflow verify-phase aposentado, #1892): validação de cobertura de decisões (#2492), auditoria de qualidade de testes, escopo de human-verification para fases de infraestrutura (#2504). | |
| `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. |
@@ -286,7 +286,7 @@ Registro completo em `gsd-core/references/*.md`. Referências são documentos de
| `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`. |
| `debugger-philosophy.md` | Disciplinas de depuração perenes carregadas pelo `msd-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. |
@@ -311,9 +311,9 @@ Registro completo em `gsd-core/references/*.md`. Referências são documentos de
| `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. |
| `ai-evals.md` | Referência de design de avaliação de IA para `/msd-ai-integration-phase`. |
| `ai-frameworks.md` | Referência da matriz de decisão de frameworks de IA para `msd-framework-selector`. |
| `executor-examples.md` | Exemplos resolvidos para o agente msd-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. |
@@ -321,7 +321,7 @@ Registro completo em `gsd-core/references/*.md`. Referências são documentos de
### Referências de Sketch
Referências consumidas pelo workflow `/gsd-sketch` e seu companion de wrap-up.
Referências consumidas pelo workflow `/msd-sketch` e seu companion de wrap-up.
| Referência | Função |
|------------|--------|
@@ -332,7 +332,7 @@ Referências consumidas pelo workflow `/gsd-sketch` e seu companion de wrap-up.
### 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ências para integrar modelos de classe de raciocínio (o3, o4-mini, Gemini 2.5 Pro) em workflows MSD.
| Referência | Função |
|------------|--------|
@@ -344,14 +344,14 @@ Referências para integrar modelos de classe de raciocínio (o3, o4-mini, Gemini
### 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.
O agente `msd-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-reviews.md` | Integração de revisão entre IAs (lê REVIEWS.md do `/msd-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. |
@@ -362,26 +362,26 @@ O agente `gsd-planner` é decomposto em um agente principal mais módulos de ref
| `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:** `gsd-core/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.
> **Subdiretório:** `msd-core/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: `gsd-core/bin/lib/*.cjs`.
Listagem completa: `msd-core/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 |
| `active-workstream-store.cjs` | Precedência de fonte e seleção de workstream (CLI `--ws` > env `MSD_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` |
| `agent-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-tools agent` |
| `artifacts.cjs` | Registro canônico de artefatos — nomes de arquivos raiz conhecidos de `.planning/`; usado pelo lint W019 do `msd-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` |
| `check-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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` |
| `code-review-flags.cjs` | Analisador de flags tipado para `/msd-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) |
@@ -390,63 +390,63 @@ Listagem completa: `gsd-core/bin/lib/*.cjs`.
| `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) |
| `context-utilization.cjs` | Classificador puro para `msd-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 (`node_modules/.bin` depois `PATH`), erros acionáveis de binário ausente e normalização de descobertas estruturais |
| `fallow-runner.cjs` | Adaptador de auditoria fallow para `/msd-code-review`: resolução binária (`node_modules/.bin` depois `PATH`), 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` |
| `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 (`msd-tools gap-analysis`) |
| `graphify.cjs` | Build/consulta/status/diff do grafo de conhecimento para `/msd-graphify` |
| `gsd2-import.cjs` | Ingestão de plano externo para `/msd-import --from-gsd2` |
| `init-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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 |
| `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 `msd-*` 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` |
| `intel.cjs` | Armazenamento de intel da base de código suportando `/msd-map-codebase --query` e `msd-intel-updater` |
| `learnings.cjs` | Extração de aprendizados entre fases para `/msd-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` |
| `package-identity.cjs` | Fonte única gerada para as coordenadas do pacote publicado do MSD (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 `msd-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` |
| `phases-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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` |
| `review-reviewer-selection.cjs` | Auxiliares de seleção/normalização de revisor para política de revisor padrão e precedência do `/msd-review` |
| `roadmap-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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) |
| `runtime-slash.cjs` | Formatador de comando slash com reconhecimento de runtime — fonte única de verdade para emitir `/msd-<cmd>` (runtimes baseados em habilidades) e `$msd-<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-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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` |
| `task-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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 `gsd-core/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` |
| `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 `msd-core/bin/lib/` para que o instalador MSD o entregue em `$RUNTIME_DIR` (#448) |
| `update-context.cjs` | Resolvedor de contexto de instalação puro para `/msd-update` — detecção de runtime/escopo/config-dir/versão (LOCAL/GLOBAL/UNKNOWN) portada do bash de update.md; sustenta `msd-tools update-context` (#498) |
| `validate-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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-command-router.cjs` | Adaptador de roteador de subcomando CJS fino para `msd-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` |
@@ -464,23 +464,23 @@ 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-agent-isolation-guard.js` | `PreToolUse` | Bloqueia rigorosamente um dispatch `Agent()` de executor que não tenha o parâmetro de isolamento do harness quando o isolamento de dispatch resolvido do projeto é `harness-worktree` (#3045) |
| `gsd-write-guard.js` | `PreToolUse` | Bloqueia rigorosamente um `Write` de arquivo inteiro que encolhe catastroficamente um artefato curado de `.planning/` (ROADMAP.md, roadmaps de milestone, STATE.md); override via o sentinela de uso único `.planning/.gsd-allow-shrink` (passos de workflow) ou `GSD_ALLOW_PLANNING_SHRINK=1` (interativo) (#2255, correção 3 de #973) |
| `gsd-secret-read-guard.js` | `PreToolUse` | Bloqueia rigorosamente leituras de `.env`, `.env.<suffix>` (exceto templates como `.env.example`) e `.secrets` via Read / Grep / Bash; substitui as regras deny `Read(.env*)` que o instalador escrevia (#4221) |
| `gsd-session-state.sh` | `SessionStart` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `gsd-validate-commit.sh` | `PreToolUse` | 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) |
| `msd-statusline.js` | `statusLine` | Exibe modelo, tarefa, diretório, uso de contexto |
| `msd-context-monitor.js` | `PostToolUse` / `AfterTool` | Injeta avisos de contexto voltados ao agente a 35%/25% de contexto restante |
| `msd-check-update.js` | `SessionStart` | Verificação em segundo plano de novas versões do MSD |
| `msd-check-update-worker.js` | (worker) | Auxiliar de worker em segundo plano para check-update |
| `msd-update-banner.js` | `SessionStart` | Banner opt-in que levanta a disponibilidade de atualização quando a statusline MSD não é usada (PR #2795) |
| `msd-prompt-guard.js` | `PreToolUse` | Varre escritas em `.planning/` em busca de padrões de injeção de prompt (consultivo) |
| `msd-workflow-guard.js` | `PreToolUse` | Detecta edições de arquivo fora do contexto de workflow MSD (consultivo, opt-in) |
| `msd-read-guard.js` | `PreToolUse` | Guarda consultiva que impede Edit/Write em arquivos não lidos |
| `msd-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) |
| `msd-worktree-path-guard.js` | `PreToolUse` | Bloqueia rigorosamente Edit/Write/MultiEdit com caminhos absolutos fora da raiz do worktree (PR #579, #260) |
| `msd-agent-isolation-guard.js` | `PreToolUse` | Bloqueia rigorosamente um dispatch `Agent()` de executor que não tenha o parâmetro de isolamento do harness quando o isolamento de dispatch resolvido do projeto é `harness-worktree` (#3045) |
| `msd-write-guard.js` | `PreToolUse` | Bloqueia rigorosamente um `Write` de arquivo inteiro que encolhe catastroficamente um artefato curado de `.planning/` (ROADMAP.md, roadmaps de milestone, STATE.md); override via o sentinela de uso único `.planning/.msd-allow-shrink` (passos de workflow) ou `MSD_ALLOW_PLANNING_SHRINK=1` (interativo) (#2255, correção 3 de #973) |
| `msd-secret-read-guard.js` | `PreToolUse` | Bloqueia rigorosamente leituras de `.env`, `.env.<suffix>` (exceto templates como `.env.example`) e `.secrets` via Read / Grep / Bash; substitui as regras deny `Read(.env*)` que o instalador escrevia (#4221) |
| `msd-session-state.sh` | `SessionStart` | Rastreamento de estado de sessão para runtimes baseados em shell |
| `msd-validate-commit.sh` | `PreToolUse` | Validação de commit para aplicação de conventional-commit |
| `msd-phase-boundary.sh` | `PostToolUse` | Detecção de limite de fase para transições de workflow |
| `msd-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) |
---

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

@@ -1,4 +1,4 @@
# Documentação do GSD Core
# Documentação do MSD Core
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.
@@ -9,7 +9,7 @@ Versões por idioma: [English](../README.md) · [Português (pt-BR)](README.md)
## Tutorials
- [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
- [Integrando uma base de código existente](tutorials/onboarding-an-existing-codebase.md) — leve o MSD Core a um repositório já existente
---
@@ -21,17 +21,17 @@ Versões por idioma: [English](../README.md) · [Português (pt-BR)](README.md)
- [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
- [Lidar com tarefas rápidas e ágeis](how-to/handle-quick-and-fast-tasks.md) — usar `/msd-quick` e `/msd-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
- [Explorar e esboçar](how-to/spike-and-sketch.md) — usar `/msd-spike` e `/msd-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
- [Conduzir o MSD a partir de uma issue do rastreador](how-to/drive-msd-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 MSD Core
- [Atualizar o MSD](how-to/update-msd.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
---
@@ -40,7 +40,7 @@ Versões por idioma: [English](../README.md) · [Português (pt-BR)](README.md)
- [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
- [Ferramentas CLI](CLI-TOOLS.md) — API programática `msd-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`
@@ -52,14 +52,14 @@ Versões por idioma: [English](../README.md) · [Português (pt-BR)](README.md)
## Explicação
- [Engenharia de contexto](explanation/context-engineering.md) — como a degradação de contexto se forma e como o GSD Core a previne
- [Engenharia de contexto](explanation/context-engineering.md) — como a degradação de contexto se forma e como o MSD 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`
- [Modos de discussão](workflow-discuss-mode.md) — modo de suposições vs. modo de entrevista para `/msd-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
- [Orquestração orientada por issues](issue-driven-orchestration.md) — receita para conduzir o MSD a partir de uma issue do rastreador usando primitivos existentes
---

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

@@ -1,8 +1,8 @@
# Guia do Usuário GSD
# Guia do Usuário MSD
Um guia narrativo complementar ao GSD Core — comece aqui para se orientar e siga os links para a documentação dedicada.
Um guia narrativo complementar ao MSD Core — comece aqui para se orientar e siga os links para a documentação dedicada.
> **A documentação do GSD Core é organizada seguindo o modelo [Diataxis](https://diataxis.fr).**
> **A documentação do MSD Core é organizada seguindo o modelo [Diataxis](https://diataxis.fr).**
> Navegue por objetivo: [Tutoriais](README.md#tutorials) · [Guias práticos](README.md#how-to-guides) · [Referência](README.md#reference) · [Explicação](README.md#explanation) · [Índice da documentação](README.md)
---
@@ -10,7 +10,7 @@ Um guia narrativo complementar ao GSD Core — comece aqui para se orientar e si
## Sumário
- [Formas do slash-command](#formas-do-slash-command)
- [Introdução ao roteamento de namespace](#introdução-ao-roteamento-de-namespace-gsdnamespace-v140)
- [Introdução ao roteamento de namespace](#introdução-ao-roteamento-de-namespace-msdnamespace-v140)
- [Visão geral do ciclo de vida do projeto](#visão-geral-do-ciclo-de-vida-do-projeto)
- [Diagramas de fluxo](#diagramas-de-fluxo)
- [Contrato de design de UI](#contrato-de-design-de-ui)
@@ -24,41 +24,41 @@ Um guia narrativo complementar ao GSD Core — comece aqui para se orientar e si
- [Estrutura de arquivos do projeto](#estrutura-de-arquivos-do-projeto)
- [Relacionados](#relacionados)
Para conduzir o GSD diretamente a partir de uma issue do GitHub / Linear / Jira, consulte o guia
Para conduzir o MSD diretamente a partir de uma issue do GitHub / Linear / Jira, consulte o guia
[Orquestração orientada por issues](issue-driven-orchestration.md) — uma
receita que mapeia issues do rastreador ao ciclo workspace → discuss → plan →
execute → verify → review → ship usando as primitivas GSD existentes.
execute → verify → review → ship usando as primitivas MSD existentes.
---
## Formas do slash-command
O GSD fornece **o mesmo conjunto de habilidades** para todos os runtimes suportados, usando a grafia com hífen para o slash-command:
O MSD fornece **o mesmo conjunto de habilidades** para todos os runtimes suportados, usando a grafia com hífen para o slash-command:
- **Forma com hífen** — `/gsd-command-name` — usada por Claude Code, Copilot, OpenCode, Kilo, Cursor, Windsurf, Augment, Antigravity e Trae.
- **Forma com hífen** — `/msd-command-name` — usada por Claude Code, Copilot, OpenCode, Kilo, Cursor, Windsurf, Augment, Antigravity e Trae.
O instalador grava essa forma no diretório de comandos de cada runtime que você especificar.
## Introdução ao roteamento de namespace (`gsd:<namespace>`, v1.40)
## Introdução ao roteamento de namespace (`msd:<namespace>`, v1.40)
A v1.40 traz seis **meta-habilidades de namespace** como pontos de entrada de primeiro estágio para roteamento hierárquico — elas mantêm baixo o custo de tokens da listagem antecipada de habilidades (~120 tokens para 6 roteadores versus ~2.150 para uma listagem plana de 86 habilidades), enquanto cada sub-habilidade concreta permanece diretamente invocável. O corpo de cada roteador de namespace contém uma tabela de roteamento que mapeia sua intenção à sub-habilidade concreta correta.
| Namespace | Roteador | Encaminha para |
|-----------|--------|-----------|
| Pipeline de fases | `/gsd-workflow` | discuss / plan / execute / verify / phase / progress |
| Ciclo de vida do projeto | `/gsd-project` | milestones, audits, summary |
| Gates de qualidade | `/gsd-quality` | code review, debug, audit, security, eval, ui |
| Inteligência de codebase | `/gsd-context` | map, graphify, docs, learnings |
| Gerenciamento | `/gsd-manage` | config, workspace, workstreams, thread, update, ship, inbox |
| Exploração e captura | `/gsd-ideate` | explore, sketch, spike, spec, capture |
| Pipeline de fases | `/msd-workflow` | discuss / plan / execute / verify / phase / progress |
| Ciclo de vida do projeto | `/msd-project` | milestones, audits, summary |
| Gates de qualidade | `/msd-quality` | code review, debug, audit, security, eval, ui |
| Inteligência de codebase | `/msd-context` | map, graphify, docs, learnings |
| Gerenciamento | `/msd-manage` | config, workspace, workstreams, thread, update, ship, inbox |
| Exploração e captura | `/msd-ideate` | explore, sketch, spike, spec, capture |
Você quase nunca precisa digitar um roteador de namespace diretamente. Seu valor está na camada de roteamento que o modelo usa para descobrir a sub-habilidade correta — eles existem para que o prompt do sistema possa listar 6 entradas em vez de 86. Se você já conhece o comando concreto (ex.: `/gsd-plan-phase`), invoque-o diretamente.
Você quase nunca precisa digitar um roteador de namespace diretamente. Seu valor está na camada de roteamento que o modelo usa para descobrir a sub-habilidade correta — eles existem para que o prompt do sistema possa listar 6 entradas em vez de 86. Se você já conhece o comando concreto (ex.: `/msd-plan-phase`), invoque-o diretamente.
---
## Visão geral do ciclo de vida do projeto
O ciclo central do GSD é: **discuss → plan → execute → verify → ship**, repetido por fase. O guia passo a passo completo — incluindo exemplos de saída, quais arquivos são criados e todas as flags em uso — está no tutorial dedicado.
O ciclo central do MSD é: **discuss → plan → execute → verify → ship**, repetido por fase. O guia passo a passo completo — incluindo exemplos de saída, quais arquivos são criados e todas as flags em uso — está no tutorial dedicado.
Consulte [Seu primeiro projeto](tutorials/your-first-project.md).
@@ -68,12 +68,12 @@ Para integrar uma base de código existente antes de iniciar um novo milestone,
| Flag | Comando | Quando usar |
| ---- | ------- | ----------- |
| `--auto` | `/gsd-new-project` | Pular perguntas interativas, ingerir de um arquivo PRD |
| `--research` | `/gsd-quick` | Adicionar um agente de pesquisa a uma tarefa avulsa |
| `--validate` | `/gsd-quick` | Adicionar verificação de plano e verificação pós-execução |
| `--chain` | `/gsd-discuss-phase` | Encadear automaticamente discuss → plan → execute sem pausas |
| `--skip-research` | `/gsd-plan-phase` | Pular agentes de pesquisa quando o domínio já é familiar |
| `--draft` | `/gsd-ship` | Criar um PR como rascunho em vez de pronto para revisão |
| `--auto` | `/msd-new-project` | Pular perguntas interativas, ingerir de um arquivo PRD |
| `--research` | `/msd-quick` | Adicionar um agente de pesquisa a uma tarefa avulsa |
| `--validate` | `/msd-quick` | Adicionar verificação de plano e verificação pós-execução |
| `--chain` | `/msd-discuss-phase` | Encadear automaticamente discuss → plan → execute sem pausas |
| `--skip-research` | `/msd-plan-phase` | Pular agentes de pesquisa quando o domínio já é familiar |
| `--draft` | `/msd-ship` | Criar um PR como rascunho em vez de pronto para revisão |
Para a referência completa de comandos com todas as flags, consulte [`docs/COMMANDS.md`](COMMANDS.md). Para opções de configuração (perfis de modelo, agentes de workflow, branching git), consulte [`docs/CONFIGURATION.md`](CONFIGURATION.md).
@@ -86,7 +86,7 @@ Para a referência completa de comandos com todas as flags, consulte [`docs/COMM
```text
┌──────────────────────────────────────────────────┐
│ NEW PROJECT │
│ /gsd-new-project │
│ /msd-new-project │
│ Questions -> Research -> Requirements -> Roadmap│
└─────────────────────────┬────────────────────────┘
│
@@ -94,27 +94,27 @@ Para a referência completa de comandos com todas as flags, consulte [`docs/COMM
│ FOR EACH PHASE: │
│ │
│ ┌────────────────────┐ │
│ │ /gsd-discuss-phase │ │ <- Lock in preferences
│ │ /msd-discuss-phase │ │ <- Lock in preferences
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ui-phase │ │ <- Design contract (frontend)
│ │ /msd-ui-phase │ │ <- Design contract (frontend)
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-plan-phase │ │ <- Research + Plan + Verify
│ │ /msd-plan-phase │ │ <- Research + Plan + Verify
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-execute-phase │ │ <- Parallel execution
│ │ /msd-execute-phase │ │ <- Parallel execution
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-verify-work │ │ <- Manual UAT
│ │ /msd-verify-work │ │ <- Manual UAT
│ └──────────┬─────────┘ │
│ │ │
│ ┌──────────▼─────────┐ │
│ │ /gsd-ship │ │ <- Create PR (optional)
│ │ /msd-ship │ │ <- Create PR (optional)
│ └──────────┬─────────┘ │
│ │ │
│ Next Phase?────────────┘
@@ -122,8 +122,8 @@ Para a referência completa de comandos com todas as flags, consulte [`docs/COMM
└─────────────┼──────────────┘
│
┌───────────────▼──────────────┐
│ /gsd-audit-milestone │
│ /gsd-complete-milestone │
│ /msd-audit-milestone │
│ /msd-complete-milestone │
└───────────────┬──────────────┘
│
Another milestone?
@@ -131,14 +131,14 @@ Para a referência completa de comandos com todas as flags, consulte [`docs/COMM
Yes No -> Done!
│
┌───────▼──────────────┐
│ /gsd-new-milestone │
│ /msd-new-milestone │
└──────────────────────┘
```
### Coordenação de agentes de planejamento
```text
/gsd-plan-phase N
/msd-plan-phase N
│
├── Phase Researcher (x4 parallel)
│ ├── Stack researcher
@@ -171,18 +171,18 @@ Para a referência completa de comandos com todas as flags, consulte [`docs/COMM
### Arquitetura de validação (Camada Nyquist)
Durante a pesquisa da fase de planejamento, o GSD mapeia a cobertura de testes automatizados para cada requisito da fase antes que qualquer código seja escrito. O pesquisador detecta sua infraestrutura de testes existente, mapeia cada requisito para um comando de teste específico e identifica qualquer scaffolding de testes que deve ser criado antes do início da implementação (tarefas da Wave 0). O verificador de planos impõe isso como uma 8ª dimensão de verificação: planos em que as tarefas carecem de comandos de verificação automatizados não serão aprovados.
Durante a pesquisa da fase de planejamento, o MSD mapeia a cobertura de testes automatizados para cada requisito da fase antes que qualquer código seja escrito. O pesquisador detecta sua infraestrutura de testes existente, mapeia cada requisito para um comando de teste específico e identifica qualquer scaffolding de testes que deve ser criado antes do início da implementação (tarefas da Wave 0). O verificador de planos impõe isso como uma 8ª dimensão de verificação: planos em que as tarefas carecem de comandos de verificação automatizados não serão aprovados.
**Saída:** `{phase}-VALIDATION.md` — o contrato de feedback para a fase.
**Desativar:** Defina `workflow.nyquist_validation: false` em `/gsd-settings` para fases de prototipagem rápida onde a infraestrutura de testes não é o foco.
**Desativar:** Defina `workflow.nyquist_validation: false` em `/msd-settings` para fases de prototipagem rápida onde a infraestrutura de testes não é o foco.
### Validação retroativa (`/gsd-validate-phase`)
### Validação retroativa (`/msd-validate-phase`)
Para fases executadas antes de a validação Nyquist existir, ou para bases de código existentes com apenas suítes de teste tradicionais, audite retroativamente e preencha as lacunas de cobertura:
```text
/gsd-validate-phase N
/msd-validate-phase N
|
+-- Detect state (VALIDATION.md exists? SUMMARY.md exists?)
|
@@ -204,9 +204,9 @@ O auditor nunca modifica o código de implementação — apenas arquivos de tes
### Modo de discussão por suposições
Por padrão, `/gsd-discuss-phase` faz perguntas abertas sobre suas preferências de implementação. O modo de suposições inverte isso: o GSD lê sua base de código primeiro, levanta suposições estruturadas sobre como construiria a fase e solicita apenas correções.
Por padrão, `/msd-discuss-phase` faz perguntas abertas sobre suas preferências de implementação. O modo de suposições inverte isso: o MSD lê sua base de código primeiro, levanta suposições estruturadas sobre como construiria a fase e solicita apenas correções.
**Ativar:** Defina `workflow.discuss_mode` como `'assumptions'` via `/gsd-settings`.
**Ativar:** Defina `workflow.discuss_mode` como `'assumptions'` via `/msd-settings`.
Consulte [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) para a referência completa do modo discuss.
@@ -214,18 +214,18 @@ Consulte [docs/workflow-discuss-mode.md](workflow-discuss-mode.md) para a refer
A fase de discussão captura decisões de implementação no CONTEXT.md sob um bloco `<decisions>` como marcadores numerados (`- **D-01:** …`). Dois gates garantem que essas decisões sobrevivam até os planos e o código entregue.
**Gate de tradução na fase de planejamento (bloqueante).** Após o planejamento, o GSD se recusa a marcar a fase como planejada até que cada decisão rastreável apareça em pelo menos um `must_haves`, `truths` ou corpo de um plano.
**Gate de tradução na fase de planejamento (bloqueante).** Após o planejamento, o MSD se recusa a marcar a fase como planejada até que cada decisão rastreável apareça em pelo menos um `must_haves`, `truths` ou corpo de um plano.
**Gate de validação na fase de verificação (não bloqueante).** Durante a verificação, o GSD pesquisa planos, SUMMARY.md, arquivos modificados e mensagens de commit recentes para cada decisão rastreável. Ausências são registradas no VERIFICATION.md como uma seção de aviso; o status de verificação permanece inalterado.
**Gate de validação na fase de verificação (não bloqueante).** Durante a verificação, o MSD pesquisa planos, SUMMARY.md, arquivos modificados e mensagens de commit recentes para cada decisão rastreável. Ausências são registradas no VERIFICATION.md como uma seção de aviso; o status de verificação permanece inalterado.
**Excluir uma decisão dos gates.** Mova-a para o cabeçalho `### Claude's Discretion` dentro de `<decisions>`, ou marque-a: `- **D-08 [informational]:** …`, `- **D-09 [folded]:** …`, `- **D-10 [deferred]:** …`.
**Desativar os gates.** Defina `workflow.context_coverage_gate: false` em `.planning/config.json` (ou via `/gsd-settings`). O padrão é `true`.
**Desativar os gates.** Defina `workflow.context_coverage_gate: false` em `.planning/config.json` (ou via `/msd-settings`). O padrão é `true`.
### Coordenação de waves de execução
```text
/gsd-execute-phase N
/msd-execute-phase N
│
├── Analyze plan dependencies
│
@@ -241,14 +241,14 @@ A fase de discussão captura decisões de implementação no CONTEXT.md sob um b
├── Test quality audit (disabled tests, circular patterns, assertion strength)
│
├── PASS -> VERIFICATION.md (success)
└── FAIL -> Issues logged for /gsd-verify-work
└── FAIL -> Issues logged for /msd-verify-work
```
---
## Contrato de design de UI
Frontends gerados por IA são visualmente inconsistentes não porque o Claude Code seja ruim em UI, mas porque não existia um contrato de design antes da execução. `/gsd-ui-phase` bloqueia o contrato de design antes do planejamento; `/gsd-ui-review` audita o resultado após a execução.
Frontends gerados por IA são visualmente inconsistentes não porque o Claude Code seja ruim em UI, mas porque não existia um contrato de design antes da execução. `/msd-ui-phase` bloqueia o contrato de design antes do planejamento; `/msd-ui-review` audita o resultado após a execução.
Para o fluxo completo, configuração, inicialização do shadcn e o gate de segurança do registry, consulte [Projetar uma fase de UI](how-to/design-a-ui-phase.md).
@@ -256,33 +256,33 @@ Para o fluxo completo, configuração, inicialização do shadcn e o gate de seg
| Comando | Descrição |
| -------------------- | ------------------------------------------------------------- |
| `/gsd-ui-phase [N]` | Gerar contrato de design UI-SPEC.md para uma fase de frontend |
| `/gsd-ui-review [N]` | Auditoria visual retroativa em 6 pilares da UI implementada |
| `/msd-ui-phase [N]` | Gerar contrato de design UI-SPEC.md para uma fase de frontend |
| `/msd-ui-review [N]` | Auditoria visual retroativa em 6 pilares da UI implementada |
| Configuração | Padrão | Descrição |
| ------------------------- | ------- | ----------------------------------------------------------------------------- |
| `workflow.ui_phase` | `true` | Gerar contratos de design de UI para fases de frontend |
| `workflow.ui_safety_gate` | `true` | A fase de planejamento solicita executar /gsd-ui-phase para fases de frontend |
| `workflow.ui_safety_gate` | `true` | A fase de planejamento solicita executar /msd-ui-phase para fases de frontend |
---
## Spikes e Esboços
Use `/gsd-spike` para validar a viabilidade técnica antes do planejamento e `/gsd-sketch` para explorar a direção visual antes de projetar. Ambos armazenam artefatos em `.planning/` e se integram ao sistema de habilidades do projeto por meio de seus companions de encerramento.
Use `/msd-spike` para validar a viabilidade técnica antes do planejamento e `/msd-sketch` para explorar a direção visual antes de projetar. Ambos armazenam artefatos em `.planning/` e se integram ao sistema de habilidades do projeto por meio de seus companions de encerramento.
Para o fluxo completo e o diagrama de fluxo, consulte [Spike e esboço](how-to/spike-and-sketch.md).
**Fluxo típico:**
```bash
/gsd-spike "SSE vs WebSocket" # Validate the approach
/gsd-spike --wrap-up # Package learnings
/msd-spike "SSE vs WebSocket" # Validate the approach
/msd-spike --wrap-up # Package learnings
/gsd-sketch "real-time feed UI" # Explore the design
/gsd-sketch --wrap-up # Package decisions
/msd-sketch "real-time feed UI" # Explore the design
/msd-sketch --wrap-up # Package decisions
/gsd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/gsd-plan-phase N # Plan with confidence
/msd-discuss-phase N # Lock in preferences (now informed by spike + sketch)
/msd-plan-phase N # Plan with confidence
```
---
@@ -294,35 +294,35 @@ Para o fluxo completo e o diagrama de fluxo, consulte [Spike e esboço](how-to/s
Ideias que ainda não estão prontas para planejamento ativo vão para o backlog usando a numeração 999.x, mantendo-as fora da sequência de fases ativas.
```bash
/gsd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/gsd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
/msd-capture --backlog "GraphQL API layer" # Creates 999.1-graphql-api-layer/
/msd-capture --backlog "Mobile responsive" # Creates 999.2-mobile-responsive/
```
Os itens de backlog recebem diretórios de fase completos, portanto você pode usar `/gsd-discuss-phase 999.1` para explorar uma ideia mais a fundo ou `/gsd-plan-phase 999.1` quando ela estiver pronta.
Os itens de backlog recebem diretórios de fase completos, portanto você pode usar `/msd-discuss-phase 999.1` para explorar uma ideia mais a fundo ou `/msd-plan-phase 999.1` quando ela estiver pronta.
**Revisar e promover** com `/gsd-review-backlog` — ele exibe todos os itens do backlog e permite promovê-los (mover para a sequência ativa), mantê-los (deixar no backlog) ou removê-los (excluir).
**Revisar e promover** com `/msd-review-backlog` — ele exibe todos os itens do backlog e permite promovê-los (mover para a sequência ativa), mantê-los (deixar no backlog) ou removê-los (excluir).
### Seeds
Seeds são ideias voltadas para o futuro com condições de acionamento. Ao contrário dos itens de backlog, as seeds aparecem automaticamente quando o milestone certo chega.
```bash
/gsd-capture --seed "Add real-time collab when WebSocket infra is in place"
/msd-capture --seed "Add real-time collab when WebSocket infra is in place"
```
`/gsd-new-milestone` verifica todas as seeds e apresenta correspondências. **Armazenamento:** `.planning/seeds/SEED-NNN-slug.md`
`/msd-new-milestone` verifica todas as seeds e apresenta correspondências. **Armazenamento:** `.planning/seeds/SEED-NNN-slug.md`
### Threads de contexto persistentes
Threads são armazenamentos de conhecimento leves entre sessões para trabalhos que abrangem múltiplas sessões mas não pertencem a nenhuma fase específica.
```bash
/gsd-thread # List all threads
/gsd-thread fix-deploy-key-auth # Resume existing thread
/gsd-thread "Investigate TCP timeout" # Create new thread
/msd-thread # List all threads
/msd-thread fix-deploy-key-auth # Resume existing thread
/msd-thread "Investigate TCP timeout" # Create new thread
```
As threads podem ser promovidas a fases (`/gsd-phase`) ou itens de backlog (`/gsd-capture --backlog`) quando amadurecerem. **Armazenamento:** `.planning/threads/{slug}.md`
As threads podem ser promovidas a fases (`/msd-phase`) ou itens de backlog (`/msd-capture --backlog`) quando amadurecerem. **Armazenamento:** `.planning/threads/{slug}.md`
---
@@ -336,19 +336,19 @@ Workstreams e workspaces fornecem isolamento, mas em níveis diferentes.
| Comando | Propósito |
| ---------------------------------- | ------------------------------------------------------------- |
| `/gsd-workstreams create <name>` | Criar um novo workstream com estado de planejamento isolado |
| `/gsd-workstreams switch <name>` | Alternar contexto ativo para um workstream diferente |
| `/gsd-workstreams list` | Exibir todos os workstreams e qual está ativo |
| `/gsd-workstreams complete <name>` | Marcar um workstream como concluído e arquivar seu estado |
| `/msd-workstreams create <name>` | Criar um novo workstream com estado de planejamento isolado |
| `/msd-workstreams switch <name>` | Alternar contexto ativo para um workstream diferente |
| `/msd-workstreams list` | Exibir todos os workstreams e qual está ativo |
| `/msd-workstreams complete <name>` | Marcar um workstream como concluído e arquivar seu estado |
```bash
# Workspace example — feature branch isolation
/gsd-workspace --new --name feature-b --repos .
cd ~/gsd-workspaces/feature-b
/gsd-new-project
/msd-workspace --new --name feature-b --repos .
cd ~/msd-workspaces/feature-b
/msd-new-project
/gsd-workspace --list
/gsd-workspace --remove feature-b
/msd-workspace --list
/msd-workspace --remove feature-b
```
---
@@ -357,7 +357,7 @@ cd ~/gsd-workspaces/feature-b
### Defesa em profundidade (v1.27)
O GSD gera arquivos markdown que se tornam prompts de sistema de LLM. Isso significa que qualquer texto controlado pelo usuário que flua para artefatos de planejamento é um vetor potencial de injeção indireta de prompt. A v1.27 introduziu endurecimento centralizado de segurança:
O MSD gera arquivos markdown que se tornam prompts de sistema de LLM. Isso significa que qualquer texto controlado pelo usuário que flua para artefatos de planejamento é um vetor potencial de injeção indireta de prompt. A v1.27 introduziu endurecimento centralizado de segurança:
**Prevenção de Path Traversal:** Todos os caminhos de arquivo fornecidos pelo usuário (`--text-file`, `--prd`) são validados para resolver dentro do diretório do projeto. A resolução de symlinks macOS `/var` → `/private/var` é tratada.
@@ -365,8 +365,8 @@ O GSD gera arquivos markdown que se tornam prompts de sistema de LLM. Isso signi
**Hooks de runtime:**
- `gsd-prompt-guard.js` — Verifica chamadas Write/Edit para `.planning/` em busca de padrões de injeção (sempre ativo, somente consultivo)
- `gsd-workflow-guard.js` — Avisa sobre edições de arquivos fora do contexto do workflow GSD (opt-in via `hooks.workflow_guard`)
- `msd-prompt-guard.js` — Verifica chamadas Write/Edit para `.planning/` em busca de padrões de injeção (sempre ativo, somente consultivo)
- `msd-workflow-guard.js` — Avisa sobre edições de arquivos fora do contexto do workflow MSD (opt-in via `hooks.workflow_guard`)
**Scanner de CI:** `prompt-injection-scan.security.test.cjs` verifica todos os arquivos de agentes, workflows e comandos em busca de vetores de injeção incorporados.
@@ -396,7 +396,7 @@ Pacotes com `[SLOP]` são removidos do RESEARCH.md inteiramente e nunca chegam a
**Veredictos de legitimidade:**
| Veredicto | Significado | Ação do GSD |
| Veredicto | Significado | Ação do MSD |
|---------|---------|------------|
| `[OK]` | Passa em todas as verificações de legitimidade | Prossegue — nenhum checkpoint adicionado |
| `[SUS]` | Sinais suspeitos | Sinalizado; o planejador adiciona `checkpoint:human-verify` |
@@ -416,17 +416,17 @@ pip install slopcheck
Após executar uma fase, execute uma revisão de código estruturada antes do UAT. Consulte [Configurar revisão cross-AI](how-to/set-up-cross-ai-review.md) para o fluxo completo.
```bash
/gsd-code-review 3 # Review all changed files in phase 3
/gsd-code-review 3 --depth=deep # Deep cross-file review
/gsd-code-review 3 --fix # Fix Critical + Warning findings atomically
/gsd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/gsd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
/msd-code-review 3 # Review all changed files in phase 3
/msd-code-review 3 --depth=deep # Deep cross-file review
/msd-code-review 3 --fix # Fix Critical + Warning findings atomically
/msd-code-review 3 --fix --auto # Fix and re-review until clean (max 3 iterations)
/msd-audit-fix # Audit + classify + fix (medium+ severity, max 5)
```
A etapa de revisão se encaixa após a execução e antes do UAT:
```text
/gsd-execute-phase N -> /gsd-code-review N -> /gsd-code-review N --fix -> /gsd-verify-work N
/msd-execute-phase N -> /msd-code-review N -> /msd-code-review N --fix -> /msd-verify-work N
```
---
@@ -445,26 +445,26 @@ A etapa de revisão se encaixa após a execução e antes do UAT:
```bash
claude --dangerously-skip-permissions
/gsd-new-project # Answer questions, configure, approve roadmap
/msd-new-project # Answer questions, configure, approve roadmap
/clear
/gsd-discuss-phase 1 # Lock in your preferences
/gsd-ui-phase 1 # Design contract (frontend phases)
/gsd-plan-phase 1 # Research + plan + verify
/gsd-execute-phase 1 # Parallel execution
/gsd-verify-work 1 # Manual UAT
/gsd-ship 1 # Create PR from verified work
/gsd-ui-review 1 # Visual audit (frontend phases)
/msd-discuss-phase 1 # Lock in your preferences
/msd-ui-phase 1 # Design contract (frontend phases)
/msd-plan-phase 1 # Research + plan + verify
/msd-execute-phase 1 # Parallel execution
/msd-verify-work 1 # Manual UAT
/msd-ship 1 # Create PR from verified work
/msd-ui-review 1 # Visual audit (frontend phases)
/clear
/gsd-progress --next # Auto-detect and run next step
/msd-progress --next # Auto-detect and run next step
...
/gsd-audit-milestone # Check everything shipped
/gsd-complete-milestone # Archive, tag, done
/gsd-pause-work --report # Generate session summary
/msd-audit-milestone # Check everything shipped
/msd-complete-milestone # Archive, tag, done
/msd-pause-work --report # Generate session summary
```
> [!CAUTION]
> **The permissions flag is optional.** It skips per-file confirmation while
> GSD's sub-agents read and write files. Use it only in low-stakes or
> MSD's sub-agents read and write files. Use it only in low-stakes or
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
> For real work, read the [security model](../explanation/security-model.md) first.
@@ -472,24 +472,24 @@ claude --dangerously-skip-permissions
### Novo projeto a partir de um documento existente
```bash
/gsd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/msd-new-project --auto @prd.md # Auto-runs research/requirements/roadmap from your doc
/clear
/gsd-discuss-phase 1 # Normal flow from here
/msd-discuss-phase 1 # Normal flow from here
```
### Base de código existente
```bash
/gsd-onboard # Safely map, ingest docs, and initialize planning
# Follow printed handoff commands, then rerun /gsd-onboard
/msd-onboard # Safely map, ingest docs, and initialize planning
# Follow printed handoff commands, then rerun /msd-onboard
# (normal phase workflow from here)
```
**Detecção de drift pós-execução (#2003).** Após cada `/gsd-execute-phase`, o GSD verifica se a fase introduziu mudanças estruturais suficientes para tornar `.planning/codebase/STRUCTURE.md` desatualizado. Altere o comportamento com:
**Detecção de drift pós-execução (#2003).** Após cada `/msd-execute-phase`, o MSD verifica se a fase introduziu mudanças estruturais suficientes para tornar `.planning/codebase/STRUCTURE.md` desatualizado. Altere o comportamento com:
```bash
/gsd-settings workflow.drift_action auto-remap # remap automatically
/gsd-settings workflow.drift_threshold 5 # tune sensitivity
/msd-settings workflow.drift_action auto-remap # remap automatically
/msd-settings workflow.drift_threshold 5 # tune sensitivity
```
### Proteção contra drift de plano
@@ -505,40 +505,40 @@ claude --dangerously-skip-permissions
**Comportamento de needs-acknowledgement.** Quando o protetor encontra um símbolo ausente, ele emite um aviso de needs-acknowledgement na saída da revisão do plano em vez de bloquear permanentemente. Você pode reconhecer e prosseguir (o símbolo pode ser intencionalmente novo) ou solicitar uma revisão do plano. O protetor não rejeita planos automaticamente — ele apresenta sinais para decisão humana.
**Funciona sem intel.** Por padrão, o protetor usa `grep`/`ripgrep` para pesquisar arquivos de código-fonte — não requer pré-indexação. Se você executou `/gsd-map-codebase` com `intel.enabled: true`, defina `plan_review.source_grounding_authority: intel` para usar o índice pré-construído `api-map.json` mais rápido.
**Funciona sem intel.** Por padrão, o protetor usa `grep`/`ripgrep` para pesquisar arquivos de código-fonte — não requer pré-indexação. Se você executou `/msd-map-codebase` com `intel.enabled: true`, defina `plan_review.source_grounding_authority: intel` para usar o índice pré-construído `api-map.json` mais rápido.
```bash
# Enable/disable (default: on)
/gsd-settings plan_review.source_grounding true
/gsd-settings plan_review.source_grounding false
/msd-settings plan_review.source_grounding true
/msd-settings plan_review.source_grounding false
# Switch resolver authority
/gsd-settings plan_review.source_grounding_authority grep # live grep (default)
/gsd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
/msd-settings plan_review.source_grounding_authority grep # live grep (default)
/msd-settings plan_review.source_grounding_authority intel # pre-indexed api-map.json
```
Alterne na configuração do projeto (`/gsd-new-project` pergunta durante as preferências de workflow) ou a qualquer momento via `/gsd-settings` (seção Planning → Drift Guard).
Alterne na configuração do projeto (`/msd-new-project` pergunta durante as preferências de workflow) ou a qualquer momento via `/msd-settings` (seção Planning → Drift Guard).
### Correção rápida de bug
```bash
/gsd-quick
/msd-quick
> "Fix the login button not responding on mobile Safari"
```
### Retomando após uma pausa
```bash
/gsd-progress # See where you left off and what's next
/msd-progress # See where you left off and what's next
# or
/gsd-resume-work # Full context restoration from last session
/msd-resume-work # Full context restoration from last session
```
### Preparando para um release
```bash
/gsd-audit-milestone # Check requirements coverage, detect stubs
/gsd-complete-milestone # Archive, tag, done
/msd-audit-milestone # Check requirements coverage, detect stubs
/msd-complete-milestone # Archive, tag, done
```
### Predefinições de velocidade vs qualidade
@@ -549,15 +549,15 @@ Alterne na configuração do projeto (`/gsd-new-project` pergunta durante as pre
| Desenvolvimento normal | `interactive` | `standard` | `balanced` | on | on | on |
| Produção | `interactive` | `fine` | `quality` | on | on | on |
**Pulando a fase discuss no modo autônomo:** Ao executar no modo `yolo`, defina `workflow.skip_discuss: true` via `/gsd-settings`.
**Pulando a fase discuss no modo autônomo:** Ao executar no modo `yolo`, defina `workflow.skip_discuss: true` via `/msd-settings`.
### Mudanças de escopo no meio do milestone
```bash
/gsd-phase # Append a new phase to the roadmap (default mode)
/gsd-phase --insert 3 # Insert urgent work between phases 3 and 4
/gsd-phase --remove 7 # Descope phase 7 and renumber
/gsd-phase --edit 4 # Edit any field of phase 4 in place
/msd-phase # Append a new phase to the roadmap (default mode)
/msd-phase --insert 3 # Insert urgent work between phases 3 and 4
/msd-phase --remove 7 # Descope phase 7 and renumber
/msd-phase --edit 4 # Edit any field of phase 4 in place
```
---
@@ -566,29 +566,29 @@ Alterne na configuração do projeto (`/gsd-new-project` pergunta durante as pre
Para um guia abrangente de solução de problemas, consulte [Recuperar e solucionar problemas](how-to/recover-and-troubleshoot.md). Os problemas mais comuns estão resumidos abaixo.
### CLI programática (`gsd-tools query` vs `gsd-tools.cjs`)
### CLI programática (`msd-tools query` vs `msd-tools.cjs`)
Para automação, prefira **`gsd-tools query`** com um subcomando registrado (consulte [CLI-TOOLS.md — SDK e acesso programático](CLI-TOOLS.md#sdk-and-programmatic-access) e QUERY-HANDLERS.md). O CLI legado `node $HOME/.claude/gsd-core/bin/gsd-tools.cjs` continua sendo suportado.
Para automação, prefira **`msd-tools query`** com um subcomando registrado (consulte [CLI-TOOLS.md — SDK e acesso programático](CLI-TOOLS.md#sdk-and-programmatic-access) e QUERY-HANDLERS.md). O CLI legado `node $HOME/.claude/msd-core/bin/msd-tools.cjs` continua sendo suportado.
### STATE.md fora de sincronia
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate # Detect drift
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify # Preview changes
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync # Reconstruct STATE.md
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate # Detect drift
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify # Preview changes
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync # Reconstruct STATE.md
```
### Um comando parece congelado após "Spawning..."
Os subagentes do GSD rodam em uma janela de contexto separada — seu trabalho fica invisível para a sessão pai enquanto está em andamento. Não interrompa a sessão. Aguarde o resultado; agentes de pesquisa e planejamento rotineiramente levam de 1 a 5 minutos.
Os subagentes do MSD rodam em uma janela de contexto separada — seu trabalho fica invisível para a sessão pai enquanto está em andamento. Não interrompa a sessão. Aguarde o resultado; agentes de pesquisa e planejamento rotineiramente levam de 1 a 5 minutos.
### Degradação de contexto durante sessões longas
Limpe sua janela de contexto entre os principais comandos: `/clear` no Claude Code. O GSD foi projetado em torno de contextos frescos — cada subagente recebe uma janela limpa de 200K. Use `/gsd-resume-work` ou `/gsd-progress` para restaurar o estado após limpar.
Limpe sua janela de contexto entre os principais comandos: `/clear` no Claude Code. O MSD foi projetado em torno de contextos frescos — cada subagente recebe uma janela limpa de 200K. Use `/msd-resume-work` ou `/msd-progress` para restaurar o estado após limpar.
### Planos parecem errados ou desalinhados
Execute `/gsd-discuss-phase [N]` antes do planejamento. A maioria dos problemas de qualidade de plano ocorre porque o Claude faz suposições que o `CONTEXT.md` teria prevenido.
Execute `/msd-discuss-phase [N]` antes do planejamento. A maioria dos problemas de qualidade de plano ocorre porque o Claude faz suposições que o `CONTEXT.md` teria prevenido.
### A execução falha ou produz stubs
@@ -596,11 +596,11 @@ Verifique se o plano não era ambicioso demais. Os planos devem ter no máximo 2
### Perdeu o controle de onde está
Execute `/gsd-progress`. Ele lê todos os arquivos de estado e informa exatamente onde você está e o que fazer a seguir.
Execute `/msd-progress`. Ele lê todos os arquivos de estado e informa exatamente onde você está e o que fazer a seguir.
### Custos de modelo muito altos
Mude para o perfil budget: `/gsd-config --profile budget`. Desative os agentes de pesquisa e verificação de plano via `/gsd-settings` se o domínio for familiar.
Mude para o perfil budget: `/msd-config --profile budget`. Desative os agentes de pesquisa e verificação de plano via `/msd-settings` se o domínio for familiar.
### Ajuste de custo de modelo por fase (`models`) — adicionado na v1.40
@@ -626,7 +626,7 @@ Precisa de uma exceção por agente? Adicione `model_overrides` junto — ele pr
{
"models": { "research": "sonnet" },
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
@@ -656,7 +656,7 @@ Para o mapeamento completo de agente → tier, consulte [Roteamento dinâmico](C
Antes de ajustar `model_profile` ou `models.<phase_type>`, audite quais **servidores MCP** seu harness tem habilitados. Cada servidor MCP habilitado injeta seu esquema de ferramentas em cada turno — servidores pesados podem custar mais de 20k tokens cada.
Esta é uma **configuração do harness**, não do GSD. O toggle fica em `.claude/settings.json`:
Esta é uma **configuração do harness**, não do MSD. O toggle fica em `.claude/settings.json`:
```json
{
@@ -673,13 +673,13 @@ Auditoria rápida antes de uma fase longa:
Cada servidor desabilitado remove seu esquema de cada turno subsequente. Reduzir MCPs **compõe** com o ajuste de `model_profile` — ambas as alavancas são aditivas, e as economias de MCP aparecem imediatamente em cada subagente que o orquestrador gera.
Para a auditoria completa, referência do harness e a nota de composição com `model_profile`, consulte [Custo de esquema de ferramentas MCP](../../gsd-core/references/context-budget.md#mcp-tool-schema-cost-harness-concern) na referência `context-budget.md` incluída.
Para a auditoria completa, referência do harness e a nota de composição com `model_profile`, consulte [Custo de esquema de ferramentas MCP](../../msd-core/references/context-budget.md#mcp-tool-schema-cost-harness-concern) na referência `context-budget.md` incluída.
### Usando runtimes não-Claude (Codex, OpenCode, Antigravity CLI, Kilo)
> **Versão mínima suportada do Codex CLI: `0.130.0`** (issue [#3562](https://github.com/open-gsd/gsd-core/issues/3562)).
Se você instalou o GSD para um runtime não-Claude, o instalador já configurou a resolução de modelo. Nenhuma configuração manual é necessária — `resolve_model_ids: "omit"` é definido automaticamente, o que informa ao GSD para pular a resolução de ID de modelo Anthropic e deixar o runtime escolher seu próprio modelo padrão.
Se você instalou o MSD para um runtime não-Claude, o instalador já configurou a resolução de modelo. Nenhuma configuração manual é necessária — `resolve_model_ids: "omit"` é definido automaticamente, o que informa ao MSD para pular a resolução de ID de modelo Anthropic e deixar o runtime escolher seu próprio modelo padrão.
Para atribuir diferentes modelos em um runtime não-Claude:
@@ -687,9 +687,9 @@ Para atribuir diferentes modelos em um runtime não-Claude:
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3"
}
}
```
@@ -707,9 +707,9 @@ Consulte [Perfis cientes de runtime](CONFIGURATION.md#runtime-aware-profiles-251
### Instalação manual / configuração sem Node.js
Se você não puder executar o instalador do GSD, não poderá usar os arquivos de origem em `agents/` diretamente — eles estão no formato nativo de frontmatter do Claude Code. Para o OpenCode, são necessárias duas transformações:
Se você não puder executar o instalador do MSD, não poderá usar os arquivos de origem em `agents/` diretamente — eles estão no formato nativo de frontmatter do Claude Code. Para o OpenCode, são necessárias duas transformações:
| Campo | Formato fonte GSD | Formato válido para OpenCode | Ação |
| Campo | Formato fonte MSD | Formato válido para OpenCode | Ação |
|---|---|---|---|
| `tools:` | `Read, Bash, Grep` (string com vírgula) | Não é um campo frontmatter | Remover a linha `tools:` inteiramente |
| `color:` | Nome de cor CSS simples | Nome hex ou semântico OpenCode | Converter para hex ou remover |
@@ -717,26 +717,26 @@ Se você não puder executar o instalador do GSD, não poderá usar os arquivos
**Alternativa:** execute o instalador em qualquer máquina com Node.js:
```bash
npx @opengsd/gsd-core@latest --opencode --global
npx @golem15/msd-core@latest --opencode --global
```
### Instalando para o Cline
```bash
npx @opengsd/gsd-core --cline --global # applies to all projects
npx @opengsd/gsd-core --cline --local # this project only
npx @golem15/msd-core --cline --global # applies to all projects
npx @golem15/msd-core --cline --local # this project only
```
### Instalando para o CodeBuddy
```bash
npx @opengsd/gsd-core --codebuddy --global
npx @golem15/msd-core --codebuddy --global
```
### Instalando para o Qwen Code
```bash
npx @opengsd/gsd-core --qwen --global
npx @golem15/msd-core --qwen --global
```
### Instalando para edições de pré-lançamento
@@ -744,7 +744,7 @@ npx @opengsd/gsd-core --qwen --global
Defina a variável de ambiente `*_CONFIG_DIR` do runtime para o diretório de pré-lançamento antes de executar o instalador:
```bash
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --windsurf --global
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @golem15/msd-core@latest --windsurf --global
```
**Referência de variáveis de ambiente para runtimes suportados:**
@@ -767,23 +767,23 @@ WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @opengsd/gsd-core@latest --wind
### Usando o Claude Code com provedores não-Anthropic
Mude para o perfil `inherit`: `/gsd-config --profile inherit`. Isso faz com que todos os agentes usem o modelo da sua sessão atual.
Mude para o perfil `inherit`: `/msd-config --profile inherit`. Isso faz com que todos os agentes usem o modelo da sua sessão atual.
### Trabalhando em um projeto sensível/privado
Defina `commit_docs: false` durante `/gsd-new-project` ou via `/gsd-settings`. Adicione `.planning/` ao seu `.gitignore`.
Defina `commit_docs: false` durante `/msd-new-project` ou via `/msd-settings`. Adicione `.planning/` ao seu `.gitignore`.
### Uma atualização do GSD sobrescreveu minhas alterações locais
### Uma atualização do MSD sobrescreveu minhas alterações locais
Desde a v1.17, o instalador faz backup de arquivos modificados localmente em `gsd-local-patches/`. Execute `/gsd-update --reapply` para mesclar suas alterações de volta.
Desde a v1.17, o instalador faz backup de arquivos modificados localmente em `msd-local-patches/`. Execute `/msd-update --reapply` para mesclar suas alterações de volta.
### Não consigo atualizar via npm
Consulte [docs/manual-update.md](../manual-update.md) para um procedimento de atualização manual passo a passo.
### Diagnósticos de workflow (`/gsd-forensics`)
### Diagnósticos de workflow (`/msd-forensics`)
Quando um workflow falha de forma não óbvia, execute `/gsd-forensics` para gerar um relatório de diagnóstico cobrindo anomalias de histórico git, integridade de artefatos e inconsistências de estado. A saída vai para `.planning/forensics/`.
Quando um workflow falha de forma não óbvia, execute `/msd-forensics` para gerar um relatório de diagnóstico cobrindo anomalias de histórico git, integridade de artefatos e inconsistências de estado. A saída vai para `.planning/forensics/`.
### Subagente executor recebe "Permission denied" em comandos Bash
@@ -812,14 +812,14 @@ Adicione os padrões necessários ao `~/.claude/settings.json`. Padrões princip
### Execução paralela causa erros de bloqueio de build
O GSD trata isso automaticamente desde a v1.26. Se você estiver em uma versão mais antiga, adicione ao `CLAUDE.md` do seu projeto:
O MSD trata isso automaticamente desde a v1.26. Se você estiver em uma versão mais antiga, adicione ao `CLAUDE.md` do seu projeto:
```markdown
## Git Commit Rules for Agents
All subagent/executor commits MUST use `--no-verify`.
```
Para desativar a execução paralela completamente: `/gsd-settings` → defina `parallelization.enabled` como `false`.
Para desativar a execução paralela completamente: `/msd-settings` → defina `parallelization.enabled` como `false`.
---
@@ -827,19 +827,19 @@ Para desativar a execução paralela completamente: `/gsd-settings` → defina `
| Problema | Solução |
| ------------------------------------------- | ----------------------------------------------------------------------------- |
| Contexto perdido / nova sessão | `/gsd-resume-work` ou `/gsd-progress` |
| Contexto perdido / nova sessão | `/msd-resume-work` ou `/msd-progress` |
| Fase deu errado | `git revert` dos commits da fase, depois replanejar |
| Precisa mudar o escopo | `/gsd-phase` (padrão), `/gsd-phase --insert` ou `/gsd-phase --remove` |
| Algo quebrou | `/gsd-debug "description"` (adicione `--diagnose` para análise sem correções) |
| Precisa mudar o escopo | `/msd-phase` (padrão), `/msd-phase --insert` ou `/msd-phase --remove` |
| Algo quebrou | `/msd-debug "description"` (adicione `--diagnose` para análise sem correções) |
| STATE.md fora de sincronia | `state validate` e depois `state sync` |
| Estado do workflow parece corrompido | `/gsd-forensics` |
| Correção rápida e pontual | `/gsd-quick` |
| Plano não corresponde à sua visão | `/gsd-discuss-phase [N]` e depois replanejar |
| Custos altos | `/gsd-config --profile budget` e `/gsd-settings` para desativar agentes |
| Atualização quebrou alterações locais | `/gsd-update --reapply` |
| Quer resumo de sessão para stakeholders | `/gsd-pause-work --report` |
| Não sabe qual é o próximo passo | `/gsd-progress --next` |
| Erros de build em execução paralela | Atualize o GSD ou defina `parallelization.enabled: false` |
| Estado do workflow parece corrompido | `/msd-forensics` |
| Correção rápida e pontual | `/msd-quick` |
| Plano não corresponde à sua visão | `/msd-discuss-phase [N]` e depois replanejar |
| Custos altos | `/msd-config --profile budget` e `/msd-settings` para desativar agentes |
| Atualização quebrou alterações locais | `/msd-update --reapply` |
| Quer resumo de sessão para stakeholders | `/msd-pause-work --report` |
| Não sabe qual é o próximo passo | `/msd-progress --next` |
| Erros de build em execução paralela | Atualize o MSD ou defina `parallelization.enabled: false` |
---
@@ -853,24 +853,24 @@ Para desativar a execução paralela completamente: `/gsd-settings` → defina `
STATE.md # Decisions, blockers, session memory
config.json # Workflow configuration
MILESTONES.md # Completed milestone archive
HANDOFF.json # Structured session handoff (from /gsd-pause-work)
research/ # Domain research from /gsd-new-project
reports/ # Session reports (from /gsd-pause-work --report)
HANDOFF.json # Structured session handoff (from /msd-pause-work)
research/ # Domain research from /msd-new-project
reports/ # Session reports (from /msd-pause-work --report)
todos/
pending/ # Captured ideas awaiting work
completed/ # Completed todos
debug/ # Active debug sessions
resolved/ # Archived debug sessions
spikes/ # Feasibility experiments (from /gsd-spike)
spikes/ # Feasibility experiments (from /msd-spike)
NNN-name/ # Experiment code + README with verdict
MANIFEST.md # Index of all spikes
sketches/ # HTML mockups (from /gsd-sketch)
sketches/ # HTML mockups (from /msd-sketch)
NNN-name/ # index.html (2-3 variants) + README
themes/
default.css # Shared CSS variables for all sketches
MANIFEST.md # Index of all sketches with winners
codebase/ # Brownfield codebase mapping (from /gsd-map-codebase or /gsd-onboard)
onboarding/ # Brownfield onboarding summary (from /gsd-onboard)
codebase/ # Brownfield codebase mapping (from /msd-map-codebase or /msd-onboard)
onboarding/ # Brownfield onboarding summary (from /msd-onboard)
phases/
XX-phase-name/
XX-YY-PLAN.md # Atomic execution plans
@@ -878,9 +878,9 @@ Para desativar a execução paralela completamente: `/gsd-settings` → defina `
CONTEXT.md # Your implementation preferences
RESEARCH.md # Ecosystem research findings
VERIFICATION.md # Post-execution verification results
XX-UI-SPEC.md # UI design contract (from /gsd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /gsd-ui-review)
ui-reviews/ # Screenshots from /gsd-ui-review (gitignored)
XX-UI-SPEC.md # UI design contract (from /msd-ui-phase)
XX-UI-REVIEW.md # Visual audit scores (from /msd-ui-review)
ui-reviews/ # Screenshots from /msd-ui-review (gitignored)
```
---

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

@@ -19,7 +19,7 @@ A barra de status exibe o uso de contexto para o **usuário**, mas o **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`) |
| CRÍTICO | <= 25% | Parar imediatamente, salvar estado (`/msd-pause-work`) |
## Debounce
@@ -31,13 +31,13 @@ Para evitar sobrecarregar o agente com avisos repetidos:
## Arquitetura
```
Hook da Barra de Status (gsd-statusline.js)
Hook da Barra de Status (msd-statusline.js)
| escreve
v
/tmp/claude-ctx-{session_id}.json
^ lê
|
Monitor de Contexto (gsd-context-monitor.js, PostToolUse/AfterTool)
Monitor de Contexto (msd-context-monitor.js, PostToolUse/AfterTool)
| injeta
v
additionalContext -> Agente recebe o aviso
@@ -54,15 +54,15 @@ O arquivo de ponte é um objeto JSON simples:
}
```
## Integração com o GSD
## Integração com o MSD
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.
O comando `/msd-pause-work` do MSD 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).
Ambos os hooks são registrados automaticamente durante a instalação do `npx @golem15/msd-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 Antigravity 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 `&`.
Como referência rápida: o hook da barra de status se registra como `statusLine` em `settings.json`; o monitor de contexto (`msd-context-monitor.js`) se registra como um hook `PostToolUse` (ou `AfterTool` para o Antigravity 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

18
docs/pt-BR/explanation/context-engineering.md
View File

@@ -1,6 +1,6 @@
# Engenharia de contexto
> Por que o GSD Core existe e qual problema ele foi projetado para resolver.
> Por que o MSD Core existe e qual problema ele foi projetado para resolver.
---
@@ -23,15 +23,15 @@ A resposta ingênua é usar `/clear` e recomeçar. Mas isso perde a continuidade
---
## A resposta do GSD Core: subagentes com contexto limpo
## A resposta do MSD 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.
O insight central do MSD 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:
Considere o que isso significa na prática. Quando você executa `/msd-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.
@@ -44,11 +44,11 @@ Cada agente opera com capacidade total, sem o peso do histórico acumulado da su
## 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:
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 MSD 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 `gsd-core/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.
**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 `msd-core/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.
@@ -56,7 +56,7 @@ A combinação é deliberada. O contexto limpo garante que cada agente raciocine
## 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:
A engenharia de contexto exige que o conhecimento sobreviva a reinicializações de contexto. O MSD 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.
@@ -70,11 +70,11 @@ A engenharia de contexto exige que o conhecimento sobreviva a reinicializaçõ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.
**Sobrecarga.** O ciclo de fases introduz atrito real. Executar `/msd-discuss-phase`, `/msd-plan-phase` e `/msd-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).
**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 MSD Core fornece `/msd-quick` e `/msd-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.

40
docs/pt-BR/explanation/multi-agent-orchestration.md
View File

@@ -1,6 +1,6 @@
# Orquestração multi-agente no GSD Core
# Orquestração multi-agente no MSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core foi projetado em torno da
> **Explicação** — Este documento descreve *por que* o MSD 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
@@ -18,7 +18,7 @@ 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
O design multi-agente do MSD 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
@@ -29,17 +29,17 @@ adequado, coleta o resultado e atualiza o estado compartilhado em `.planning/`.
## O padrão orquestrador → agente
Todos os workflows em `gsd-core/workflows/` seguem a mesma estrutura:
Todos os workflows em `msd-core/workflows/` seguem a mesma estrutura:
```text
Orquestrador (arquivo .md de workflow)
│
├── Carregar contexto
│ gsd-tools.cjs init <workflow> <phase>
│ msd-tools.cjs init <workflow> <phase>
│ → JSON: informações do projeto, config, estado, detalhes da fase
│
├── Resolver modelo
│ gsd-tools.cjs resolve-model <agent-name>
│ msd-tools.cjs resolve-model <agent-name>
│ → opus | sonnet | haiku | inherit
│
├── Gerar agente especializado (chamada Task/SubAgent)
@@ -51,7 +51,7 @@ Orquestrador (arquivo .md de workflow)
├── Coletar resultado
│
└── Atualizar estado
gsd-tools.cjs state update / state patch / state advance-plan
msd-tools.cjs state update / state patch / state advance-plan
```
O orquestrador é deliberadamente enxuto. Ele não raciocina sobre o domínio,
@@ -61,19 +61,19 @@ 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
Os agentes do MSD 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 |
| Pesquisadores | `msd-project-researcher`, `msd-phase-researcher`, `msd-ui-researcher`, `msd-advisor-researcher` | 4 em paralelo (stack, funcionalidades, arquitetura, armadilhas) |
| Sintetizadores | `msd-research-synthesizer` | Sequencial, após a conclusão dos pesquisadores |
| Planejadores | `msd-planner`, `msd-roadmapper` | Sequencial |
| Verificadores | `msd-plan-checker`, `msd-integration-checker`, `msd-ui-checker`, `msd-nyquist-auditor` | Sequencial, até 3 iterações de revisão |
| Executores | `msd-executor` | Paralelo dentro de uma onda, sequencial entre ondas |
| Validadores | `msd-verifier` | Sequencial, após a conclusão de todos os executores |
| Mapeadores | `msd-codebase-mapper` | 4 sub-sondas em paralelo |
| Auditores | `msd-ui-auditor`, `msd-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
@@ -87,7 +87,7 @@ Para o catálogo completo de 31 agentes, consulte [Inventário](../INVENTORY.md#
## Execução paralela baseada em ondas
A expressão mais visível do design multi-agente é como o `/gsd-execute-phase`
A expressão mais visível do design multi-agente é como o `/msd-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**:
@@ -173,7 +173,7 @@ 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
de nenhum agente), os workflows do MSD 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.
@@ -186,7 +186,7 @@ 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
trabalhando em um contexto terminaria mais rápido para tarefas simples. O MSD 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.
@@ -199,7 +199,7 @@ 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`
Este é o custo do isolamento. O handler `msd-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.

48
docs/pt-BR/explanation/security-model.md
View File

@@ -1,8 +1,8 @@
# Modelo de segurança do GSD Core
# Modelo de segurança do MSD Core
> **Explicação** — Este documento descreve *por que* o GSD Core possui a
> **Explicação** — Este documento descreve *por que* o MSD 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`
> referência para todos os parâmetros de hook. Para o comando `/msd-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).
@@ -15,13 +15,13 @@
## 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
O MSD 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
O modelo de segurança do MSD 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
@@ -48,21 +48,21 @@ A qualidade insidiosa do slopsquatting é que um nome alucinado que passa no
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
pesquisador → planejador → executor do MSD 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 `gsd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>` para cada um. Os resultados
**Estágio de pesquisa.** Quando `msd-phase-researcher` recomenda pacotes
externos, executa `msd-tools query package-legitimacy check --ecosystem <npm|pypi|crates> <pkgs>` 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
**Estágio de planejamento.** `msd-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
@@ -72,7 +72,7 @@ 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
**Estágio de execução.** Se uma instalação falhar, `msd-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).
@@ -104,7 +104,7 @@ 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
pip falhar no momento da pesquisa), o MSD 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
@@ -122,7 +122,7 @@ checkpoint humano seja mantida independentemente.
### A ameaça
O GSD Core gera arquivos Markdown que se tornam prompts de sistema de LLMs. O
O MSD 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
@@ -133,10 +133,10 @@ 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.
O MSD Core trata a injeção de prompt em três níveis.
**Validação de entrada (`security.cjs`).** O módulo
`gsd-core/bin/lib/security.cjs` é o utilitário central de segurança.
`msd-core/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
@@ -151,7 +151,7 @@ Ele fornece:
- 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
**Hook de runtime: `msd-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
@@ -162,24 +162,24 @@ 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
**Hook de runtime: `msd-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.
MSD está prestes a incorporar ao contexto de um agente.
**Scanner de CI.** `prompt-injection-scan.security.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
código-fonte do MSD — 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
Os dois hooks cobrem superfícies complementares. `msd-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
`msd-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
@@ -189,7 +189,7 @@ pelo usuário). Juntos, eles delimitam o ciclo de vida ingestão → armazenamen
## Camada 3 — Integridade do repositório e das dependências
Acima do comportamento de runtime do GSD, a organização `open-gsd` aplica
Acima do comportamento de runtime do MSD, 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.
@@ -199,7 +199,7 @@ 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.
próprias dependências do MSD.
**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
@@ -259,8 +259,8 @@ 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
- [Comandos](../COMMANDS.md) — inclui `/msd-secure-phase` e
`/msd-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

10
docs/pt-BR/explanation/the-phase-loop.md
View File

@@ -1,12 +1,12 @@
# O loop de fases
> O modelo mental central de como o GSD Core organiza o trabalho.
> O modelo mental central de como o MSD Core organiza o trabalho.
---
## O que é o loop
O GSD Core estrutura todo o trabalho de desenvolvimento como um ciclo que se repete:
O MSD Core estrutura todo o trabalho de desenvolvimento como um ciclo que se repete:
```text
Discuss → (UI design) → Plan → Execute → Verify → Ship
@@ -30,7 +30,7 @@ A etapa Discuss é deliberadamente leve. É uma conversa, não um exercício de
### 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.
Para fases com componente visual, existe uma etapa opcional `/msd-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
@@ -87,7 +87,7 @@ Um bom escopo de fase é aquele em que:
- 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.
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 `/msd-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.
@@ -113,7 +113,7 @@ O loop existe porque cada etapa previne falhas que são genuinamente caras de co
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.
Para trabalhos que ficam abaixo do limite em que o loop é justificado, o MSD Core oferece primitivas mais leves. O loop de fases é uma ferramenta, não a única ferramenta.
---

48
docs/pt-BR/how-to/configure-model-profiles.md
View File

@@ -6,7 +6,7 @@ Escolha a estratégia de nível de modelo adequada para o seu projeto e ajuste a
## Os quatro perfis (mais `adaptive` e `inherit`)
Defina `model_profile` em `.planning/config.json` ou via `/gsd-config --profile <name>`:
Defina `model_profile` em `.planning/config.json` ou via `/msd-config --profile <name>`:
| Perfil | Planejador | Executor | Pesquisadores | Verificador | Usar quando |
|--------|-----------|----------|---------------|-------------|-------------|
@@ -16,15 +16,15 @@ Defina `model_profile` em `.planning/config.json` ou via `/gsd-config --profile
| `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 `gsd-core/bin/shared/model-catalog.json`. Para a tabela completa, consulte [Perfis de Modelo](../CONFIGURATION.md#model-profiles) na referência de configuraçã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 `msd-core/bin/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
/msd-config --profile balanced # Desenvolvimento normal
/msd-config --profile budget # Prototipagem ou fases de alto custo
/msd-config --profile quality # Lançamento em produção
/msd-config --profile inherit # OpenRouter, modelos locais
```
**Ou edite `.planning/config.json` diretamente:**
@@ -45,20 +45,20 @@ Se um único agente precisa de um nível diferente sem alterar o perfil inteiro,
{
"model_profile": "balanced",
"model_overrides": {
"gsd-executor": "opus",
"gsd-codebase-mapper": "haiku"
"msd-executor": "opus",
"msd-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.
`model_overrides` pode ser definido por projeto em `.planning/config.json` ou globalmente em `~/.msd/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.
npx @golem15/msd-core@latest --codex --global # ou --opencode, --kilo, etc.
```
---
@@ -85,11 +85,11 @@ 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`, `gsd-code-reviewer` |
| `discuss` | `gsd-assumptions-analyzer` |
| `planning` | `msd-planner`, `msd-roadmapper`, `msd-pattern-mapper` |
| `research` | `msd-phase-researcher`, `msd-project-researcher`, `msd-research-synthesizer`, `msd-codebase-mapper`, `msd-ui-researcher` |
| `execution` | `msd-executor`, `msd-debugger`, `msd-doc-writer` |
| `verification` | `msd-verifier`, `msd-plan-checker`, `msd-integration-checker`, `msd-nyquist-auditor`, `msd-ui-checker`, `msd-ui-auditor`, `msd-doc-verifier`, `msd-code-reviewer` |
| `discuss` | `msd-assumptions-analyzer` |
| `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.
@@ -103,12 +103,12 @@ O bloco `models` aceita apenas aliases de nível (`opus`, `sonnet`, `haiku`, `in
"research": "sonnet"
},
"model_overrides": {
"gsd-codebase-mapper": "haiku"
"msd-codebase-mapper": "haiku"
}
}
```
Todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `gsd-codebase-mapper`, que está fixado em `haiku`.
Todos os cinco agentes de pesquisa resolvem para `sonnet` *exceto* `msd-codebase-mapper`, que está fixado em `haiku`.
---
@@ -131,7 +131,7 @@ Se você quiser pagar pelos níveis mais baratos por padrão e só escalar quand
}
```
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.
Cada agente possui um nível padrão (`light`, `standard` ou `heavy`). Na primeira tentativa, o MSD 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.
@@ -152,9 +152,9 @@ Cada tentativa usa `tier_models[default_tier]` independentemente do resultado
---
## Usando o GSD em runtimes não-Anthropic
## Usando o MSD em runtimes não-Anthropic
Se você instalou o GSD para Codex, OpenCode, Antigravity 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ê instalou o MSD para Codex, OpenCode, Antigravity CLI ou Kilo, o instalador já definiu `resolve_model_ids: "omit"` na sua configuração. Isso instrui o MSD 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:**
@@ -165,7 +165,7 @@ Se você instalou o GSD para Codex, OpenCode, Antigravity CLI ou Kilo, o instala
}
```
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.
O MSD 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:**
@@ -173,9 +173,9 @@ O GSD resolve cada alias de nível para o modelo nativo do Codex e o esforço de
{
"resolve_model_ids": "omit",
"model_overrides": {
"gsd-planner": "o3",
"gsd-executor": "o4-mini",
"gsd-debugger": "o3"
"msd-planner": "o3",
"msd-executor": "o4-mini",
"msd-debugger": "o3"
}
}
```

54
docs/pt-BR/how-to/debug-a-failed-execution.md
View File

@@ -2,7 +2,7 @@
**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.
**Pré-requisitos:** Você executou `/msd-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.
---
@@ -12,15 +12,15 @@ Antes de tomar qualquer ação de recuperação, determine o que realmente acont
### 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.
Isso é normal, não é um travamento. Os subagentes MSD 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
/msd-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.
O MSD 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
@@ -34,7 +34,7 @@ Planos que commitaram seu trabalho terão uma entrada como `feat(01-02): …`. P
### 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:
O MSD 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.
@@ -44,12 +44,12 @@ O GSD detecta isso na próxima execução e apresenta uma porta de retomada segu
## Diagnosticar a causa raiz
### Execute `/gsd-debug --diagnose`
### Execute `/msd-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"
/msd-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.
@@ -57,36 +57,36 @@ Se a execução produziu saída incorreta, código com stubs ou uma falha de ver
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"
/msd-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.
O MSD 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
/msd-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>
/msd-debug continue <slug>
```
---
## Executar uma análise post-mortem com `/gsd-forensics`
## Executar uma análise post-mortem com `/msd-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"
/msd-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.
O MSD 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.
`/msd-forensics` é somente leitura — ele nunca modifica os arquivos do seu projeto.
**O que ele detecta:**
@@ -103,46 +103,46 @@ O GSD analisa o histórico do git, a completude dos artefatos em `.planning/`, a
Assim que o problema subjacente for resolvido, execute novamente o comando de execução:
```bash
/gsd-execute-phase 1
/msd-execute-phase 1
```
O GSD ignora planos cujo `SUMMARY.md` já existe e despacha executores apenas para os planos restantes.
O MSD 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
/msd-execute-phase 1 --wave 2
```
---
## Reverter com `/gsd-undo`
## Reverter com `/msd-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
/msd-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.
Reverte todos os commits do plano `02` da fase `3`. O MSD exibe uma porta de confirmação antes de gravar qualquer alteração.
### Reverter uma fase inteira
```bash
/gsd-undo --phase 03
/msd-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.
Reverte todos os commits da fase `3`. O MSD 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
/msd-undo --last 5
```
Mostra os cinco commits GSD mais recentes e permite que você selecione quais reverter.
Mostra os cinco commits MSD mais recentes e permite que você selecione quais reverter.
---
@@ -151,7 +151,7 @@ Mostra os cinco commits GSD mais recentes e permite que você selecione quais re
Se você retornou ao projeto após uma reinicialização de contexto ou uma nova sessão:
```bash
/gsd-resume-work
/msd-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.
@@ -159,7 +159,7 @@ Restaura o contexto completo da sua sessão a partir do último handoff, incluin
Como alternativa, para ver sua posição atual e avançar automaticamente para o próximo passo correto:
```bash
/gsd-progress --next
/msd-progress --next
```
---

52
docs/pt-BR/how-to/design-a-ui-phase.md
View File

@@ -2,13 +2,13 @@
**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.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. A fase precisa ter trabalho de frontend ou UI. Executar `/msd-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:
Nem todas as fases precisam de `/msd-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
@@ -20,22 +20,22 @@ 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.
Se não tiver certeza, a trava de segurança irá alertá-lo: quando `workflow.ui_safety_gate` está habilitado (padrão), `/msd-plan-phase` avisa ao detectar trabalho de frontend sem `UI-SPEC.md` e pergunta se deve executar `/msd-ui-phase` primeiro.
---
## Execute o contrato de design de UI
```bash
/gsd-ui-phase 2
/msd-ui-phase 2
```
Se nenhum número de fase for fornecido, o GSD Core usa a fase atual como alvo.
Se nenhum número de fase for fornecido, o MSD 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 sete dimensões. Se problemas forem encontrados, um ciclo de revisão reexecuta o pesquisador (até duas iterações) visando apenas os itens sinalizados.
1. **`msd-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. **`msd-ui-checker`** — valida o `UI-SPEC.md` resultante em sete 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}/`.
@@ -53,7 +53,7 @@ O pesquisador bloqueia decisões em cinco áreas:
| **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 suas sete dimensões — Textos, Visuais, Cores, Tipografia, Espaçamento, Segurança de Registro e Proveniência do Inventário — retornando PASS, FLAG ou BLOCK para cada uma. (A rubrica de 6 pilares com pontuação de 1 a 4 pertence à auditoria retroativa do `/gsd-ui-review`, não a este verificador.)
O verificador valida a especificação em suas sete dimensões — Textos, Visuais, Cores, Tipografia, Espaçamento, Segurança de Registro e Proveniência do Inventário — retornando PASS, FLAG ou BLOCK para cada uma. (A rubrica de 6 pilares com pontuação de 1 a 4 pertence à auditoria retroativa do `/msd-ui-review`, não a este verificador.)
---
@@ -69,7 +69,7 @@ Para projetos React, Next.js e Vite, o pesquisador oferece inicializar o shadcn
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.
A string do preset torna-se um artefato de planejamento de primeira classe do MSD Core, reproduzível entre fases e marcos.
---
@@ -82,13 +82,13 @@ 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.
O verificador sinalizará a especificação como BLOCKED se a segurança do registro não for tratada. Desative a trava via `/msd-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:
Se você já executou `/msd-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
@@ -96,20 +96,20 @@ Se você já executou `/gsd-sketch --wrap-up`, o pesquisador de UI carrega `.cla
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.
Esta é a principal razão para executar `/msd-sketch --wrap-up` antes de `/msd-ui-phase`: transforma a exploração conversacional de design em entrada vinculante para o contrato.
---
## Auditoria visual retroativa com `/gsd-ui-review`
## Auditoria visual retroativa com `/msd-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).
`/msd-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
/msd-ui-review # audit the current phase
/msd-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.
Funciona em qualquer projeto com código frontend — a inicialização de projeto MSD não é necessária.
**O que verifica (6 pilares, pontuação de 1 a 4 cada):**
@@ -120,24 +120,24 @@ Funciona em qualquer projeto com código frontend — a inicialização de proje
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.
**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 `msd-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`.
**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 `/msd-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)
/msd-discuss-phase N ← lock implementation preferences
/msd-ui-phase N ← lock design contract (frontend phases)
/msd-plan-phase N ← research + plan (reads UI-SPEC.md as context)
/msd-execute-phase N ← parallel execution
/msd-verify-work N ← manual UAT
/msd-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.
`/msd-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.
---

32
docs/pt-BR/how-to/discuss-a-phase.md
View File

@@ -2,18 +2,18 @@
**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.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. Caso contrário, execute `/msd-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.
MSD 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
/msd-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.
@@ -21,8 +21,8 @@ Claude identifica áreas cinzentas no escopo da fase, permite que você selecion
**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
node msd-tools.cjs config-set workflow.discuss_mode assumptions
/msd-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.
@@ -30,7 +30,7 @@ Claude lê de 5 a 15 arquivos relevantes da base de código por meio de um subag
Para voltar ao modo anterior:
```bash
node gsd-tools.cjs config-set workflow.discuss_mode discuss
node msd-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.
@@ -42,7 +42,7 @@ Veja [Modos de discussão explicados](../workflow-discuss-mode.md) para uma comp
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
/msd-discuss-phase 2 --all
```
---
@@ -52,7 +52,7 @@ Por padrão, Claude apresenta as áreas cinzentas e pergunta quais você deseja
**Se a fase é bem compreendida e você quer que Claude escolha os padrões recomendados sem fazer perguntas:**
```bash
/gsd-discuss-phase 3 --auto
/msd-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.
@@ -60,7 +60,7 @@ Claude seleciona a resposta recomendada para cada pergunta e registra as escolha
**Se você tem restrições de sessão remota (sem menus TUI):**
```bash
/gsd-discuss-phase 2 --text
/msd-discuss-phase 2 --text
```
Todos os prompts são renderizados como listas numeradas em texto simples em vez de seletores interativos.
@@ -72,7 +72,7 @@ Todos os prompts são renderizados como listas numeradas em texto simples em vez
Se você preferir responder várias perguntas de uma vez em vez de uma por uma:
```bash
/gsd-discuss-phase 2 --batch
/msd-discuss-phase 2 --batch
```
Claude agrupa de 2 a 5 perguntas por turno.
@@ -84,7 +84,7 @@ Claude agrupa de 2 a 5 perguntas por turno.
Se você quiser uma tabela comparativa das opções antes de se comprometer:
```bash
/gsd-discuss-phase 2 --analyze
/msd-discuss-phase 2 --analyze
```
---
@@ -94,7 +94,7 @@ Se você quiser uma tabela comparativa das opções antes de se comprometer:
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
/msd-discuss-phase 1 --power
```
---
@@ -104,7 +104,7 @@ Se você tem um arquivo de respostas preparado e quer enviar todas as decisões
**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
/msd-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.
@@ -132,9 +132,9 @@ Veja [Esquema do CONTEXT.md](../reference/context-md.md) para a referência comp
## 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.
Quando você executar `/msd-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 o CONTEXT.md estiver ausente quando você executar `/msd-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 `/msd-discuss-phase` primeiro.
---
@@ -143,7 +143,7 @@ Quando você executar `/gsd-plan-phase` em seguida, o planejador lê CONTEXT.md
Pule a fase de discussão completamente e vá direto para o planejamento:
```bash
/gsd-plan-phase 1 --prd path/to/prd.md
/msd-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.

68
docs/pt-BR/how-to/drive-gsd-from-a-tracker-issue.md → docs/pt-BR/how-to/drive-msd-from-a-tracker-issue.md
View File

@@ -1,8 +1,8 @@
# Como conduzir o GSD Core a partir de uma issue do rastreador
# Como conduzir o MSD 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.
**Objetivo:** Levar uma única issue bem delimitada do GitHub, Linear ou Jira por todo o pipeline do MSD — desde o workspace isolado até o PR mesclado — usando apenas comandos já existentes no MSD 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.
**Pré-requisitos:** MSD 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).
@@ -16,13 +16,13 @@ Abra sua issue no rastreador e decida como ela se encaixa no `ROADMAP.md`:
- **A issue é um trabalho novo independente** → adicione uma fase:
```bash
/gsd-phase "Descrição correspondente ao título da issue"
/msd-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"
/msd-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.
@@ -34,13 +34,13 @@ Copie a URL da issue do rastreador. Você irá colá-la no `CONTEXT.md` no Passo
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
/msd-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
cd ~/msd-workspaces/my-issue-slug
```
---
@@ -50,15 +50,15 @@ cd ~/gsd-workspaces/my-issue-slug
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
/msd-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.
O MSD 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
/msd-discuss-phase N --auto
```
---
@@ -66,22 +66,22 @@ Se você já sabe todas as respostas e quer avançar rapidamente:
## Passo 4: Planejar a fase
```bash
/gsd-plan-phase N
/msd-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.
O MSD 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
/msd-review --phase N
/msd-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
/msd-plan-review-convergence N
```
---
@@ -91,19 +91,19 @@ Ou execute o loop completo de planejar–revisar–convergir até que não haja
Para execução interativa, fase por fase:
```bash
/gsd-execute-phase N
/msd-execute-phase N
```
Para uma execução sem supervisão por todas as fases restantes:
```bash
/gsd-autonomous
/msd-autonomous
```
Para um painel interativo onde você pode acompanhar o progresso e despachar trabalho entre fases:
```bash
/gsd-manager
/msd-manager
```
As três abordagens atualizam o `STATE.md`, fazem commit de cada tarefa atomicamente e executam o verificador pós-fase.
@@ -113,10 +113,10 @@ As três abordagens atualizam o `STATE.md`, fazem commit de cada tarefa atomicam
## Passo 6: Verificar o trabalho
```bash
/gsd-verify-work N
/msd-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.
O MSD 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 MSD 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.
@@ -127,17 +127,17 @@ Trate `verification_failed` como um bloqueador mesmo quando o código parece cor
Execute uma revisão de código antes de abrir o PR:
```bash
/gsd-code-review N
/gsd-code-review N --fix
/msd-code-review N
/msd-code-review N --fix
```
Em seguida, crie o PR:
```bash
/gsd-ship N
/msd-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.
O MSD 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 `/msd-config`) para que a issue do rastreador seja fechada automaticamente quando o PR for mesclado.
---
@@ -146,12 +146,12 @@ O GSD monta o corpo do PR a partir dos seus artefatos de planejamento: objetivo
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
/msd-capture "Acompanhamento: descrição do trabalho descoberto" # Adicionar como tarefa
/msd-capture --seed "Ideia que vale uma fase futura" # Preservar para o próximo milestone
/msd-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.
O MSD 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.
---
@@ -159,12 +159,12 @@ O GSD não publica no seu rastreador automaticamente. Criar uma issue no rastrea
| 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 |
| A issue é muito pequena (typo, mudança de config) | Pule workspace + discuss + plan; use `/msd-quick` em vez disso |
| A issue tem múltiplas subtarefas independentes | Use `/msd-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 MSD 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 `/msd-phase --insert N` para adicionar subfases, continue |
| Você quer pular a discussão interativa | Use a flag `--auto` com `/msd-discuss-phase`, ou defina `workflow.skip_discuss: true` para automação em todo o projeto |
| Múltiplas issues formam uma release coerente | Execute `/msd-new-milestone` para agrupá-las e `/msd-autonomous` para executar em sequência |
---

24
docs/pt-BR/how-to/execute-a-phase.md
View File

@@ -2,19 +2,19 @@
**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).
**Pré-requisitos:** A fase deve ter pelo menos um arquivo `PLAN.md`. Se o planejamento ainda não foi concluído, execute `/msd-plan-phase N` primeiro — consulte [Planejar uma fase](plan-a-phase.md).
---
## Executar a fase completa
```bash
/gsd-execute-phase 1
/msd-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.
O MSD 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:
Antes de qualquer agente ser despachado, o MSD Core exibe uma tabela de ondas:
```
## Execution Plan
@@ -38,24 +38,24 @@ Para o modelo de coordenação de agentes subjacente, consulte [Orquestração m
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
/msd-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.
O MSD 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.
---
## 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:
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 MSD 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
/msd-execute-phase 1
```
O GSD Core ignorará os planos onde `SUMMARY.md` já existe e retomará a partir do primeiro plano incompleto.
O MSD 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:
**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 MSD 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.
@@ -88,13 +88,13 @@ O histórico git exibirá um commit por tarefa (de cada executor), seguido de co
Para delegar a execução a uma CLI de IA externa (Codex, Antigravity, etc.) configurada em `workflow.cross_ai_command`:
```bash
/gsd-execute-phase 2 --cross-ai
/msd-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
/msd-execute-phase 2 --no-cross-ai
```
---

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

@@ -1,6 +1,6 @@
# 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.
Nem todo trabalho cabe dentro de uma fase. O MSD 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).
@@ -10,30 +10,30 @@ Para contexto sobre quando o pipeline completo de fases vale o custo, consulte [
| 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` |
| Corrigir um bug, adicionar uma funcionalidade pequena ou qualquer tarefa que não possa ser resumida como uma única edição trivial | `/msd-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 | `/msd-fast` |
| A tarefa tem incógnitas, precisa de pesquisa ou vai tocar em mais do que um punhado de arquivos | `/msd-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.
**A regra prática:** se você hesitar por um momento sobre se a tarefa é trivial, use `/msd-quick`. O `/msd-fast` redireciona automaticamente para `/msd-quick` se o escopo parecer não trivial.
---
## `/gsd-quick` — tarefas ad-hoc com garantias GSD
## `/msd-quick` — tarefas ad-hoc com garantias MSD
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).
O `/msd-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
/msd-quick
```
O GSD solicita uma descrição da tarefa, então planeja e executa. Os artefatos ficam em `.planning/quick/`.
O MSD 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"
/msd-quick "Fix the login button not responding on mobile Safari"
```
### Flags
@@ -50,9 +50,9 @@ Adicione flags para incluir mais do pipeline de qualidade quando a tarefa exigir
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
/msd-quick --research --validate # research + plan-checking + verification, no discuss
/msd-quick --discuss # just surface grey areas before planning
/msd-quick --full # the complete quality pipeline
```
### Quando adicionar flags
@@ -65,38 +65,38 @@ As flags se combinam livremente:
### 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
/msd-quick list # show all quick tasks with status
/msd-quick status my-task-slug # show status of a specific task
/msd-quick resume my-task-slug # resume an interrupted task
```
---
## `/gsd-fast` — edições triviais inline
## `/msd-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.
O `/msd-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"
/msd-fast "fix typo in README"
/msd-fast "add .env to .gitignore"
```
Se você omitir a descrição, o GSD vai solicitá-la.
Se você omitir a descrição, o MSD 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ê:
O `/msd-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"
This looks like it needs planning. Use /msd-quick instead:
/msd-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.
Após fazer a alteração, o `/msd-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
## O que o `/msd-quick` faz que o `/msd-fast` não faz
| Capacidade | `/gsd-fast` | `/gsd-quick` |
| Capacidade | `/msd-fast` | `/msd-quick` |
|------------|------------|--------------|
| Planejador subagente | Não | Sim |
| Executor subagente | Não | Sim |
@@ -109,7 +109,7 @@ Após fazer a alteração, o `/gsd-fast` faz commit atomicamente e, se uma tabel
| 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.
A distinção principal é o isolamento de subagentes. O `/msd-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 `/msd-fast` usa apenas a janela de contexto atual e é intencionalmente limitado a alterações triviais o suficiente para não precisar de nada disso.
---

92
docs/pt-BR/how-to/install-on-your-runtime.md
View File

@@ -1,6 +1,6 @@
# Como instalar o GSD Core no seu ambiente de execução
# Como instalar o MSD 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.
Instale o MSD Core (`@golem15/msd-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).
@@ -8,7 +8,7 @@ Instale o GSD Core (`@opengsd/gsd-core`) no ambiente de codificação com IA que
## 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 e escrevendo entradas TOML de agente para o Codex.
O MSD 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 e escrevendo entradas TOML de agente para o Codex.
**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.
@@ -19,7 +19,7 @@ O GSD Core distribui arquivos de agente e comando no formato nativo de frontmatt
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
npx @golem15/msd-core@latest
```
Esse é o único comando necessário para uma instalação nova ou para executar o instalador novamente após trocar de ambiente.
@@ -31,17 +31,17 @@ Esse é o único comando necessário para uma instalação nova ou para executar
### Claude Code
```bash
npx @opengsd/gsd-core@latest --claude --global
npx @golem15/msd-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.
As habilidades são instaladas em `~/.claude/`. Os comandos aparecem como slash commands `/msd-*` na sua próxima sessão do Claude Code. Reinicie o Claude Code para carregá-los.
**Instalação em ambos os escopos `--global` e `--local`.** Essa é uma configuração suportada, mas as próprias regras de resolução de gatilhos do Claude Code — escopo pessoal sobrepõe escopo de projeto, e uma skill sobrepõe um comando de mesmo nome — apontam para a mesma direção: a skill global sempre vence o gatilho `/gsd-<nome>` sobre o comando local. O GSD Core detecta isso e imprime qual escopo está vencendo logo após a instalação (e reporta o mesmo fato pelo `/gsd-health` como o diagnóstico `W028`); é um aviso, não uma falha — a instalação em si continua bem-sucedida. No escopo **global**, a referência da spec de workflow da skill vencedora é resolvida em tempo de execução em relação ao seu diretório de trabalho primeiro, então um projeto com seu próprio `.claude/gsd-core/` ainda obtém suas próprias specs mesmo que a skill global seja o que o Claude Code invoca.
**Instalação em ambos os escopos `--global` e `--local`.** Essa é uma configuração suportada, mas as próprias regras de resolução de gatilhos do Claude Code — escopo pessoal sobrepõe escopo de projeto, e uma skill sobrepõe um comando de mesmo nome — apontam para a mesma direção: a skill global sempre vence o gatilho `/msd-<nome>` sobre o comando local. O MSD Core detecta isso e imprime qual escopo está vencendo logo após a instalação (e reporta o mesmo fato pelo `/msd-health` como o diagnóstico `W028`); é um aviso, não uma falha — a instalação em si continua bem-sucedida. No escopo **global**, a referência da spec de workflow da skill vencedora é resolvida em tempo de execução em relação ao seu diretório de trabalho primeiro, então um projeto com seu próprio `.claude/msd-core/` ainda obtém suas próprias specs mesmo que a skill global seja o que o Claude Code invoca.
**Substituir o diretório de instalação:**
```bash
CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
CLAUDE_CONFIG_DIR=~/.claude-alt npx @golem15/msd-core@latest --claude --global
```
---
@@ -49,7 +49,7 @@ CLAUDE_CONFIG_DIR=~/.claude-alt npx @opengsd/gsd-core@latest --claude --global
### OpenCode
```bash
npx @opengsd/gsd-core@latest --opencode --global
npx @golem15/msd-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.
@@ -57,7 +57,7 @@ As habilidades são instaladas em `~/.config/opencode/` (XDG) ou `~/.opencode/`.
**Substituir o diretório de instalação:**
```bash
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --opencode --global
OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @golem15/msd-core@latest --opencode --global
```
---
@@ -65,7 +65,7 @@ OPENCODE_CONFIG_DIR=~/.config/opencode-alt npx @opengsd/gsd-core@latest --openco
### Kilo
```bash
npx @opengsd/gsd-core@latest --kilo --global
npx @golem15/msd-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.
@@ -73,7 +73,7 @@ As habilidades são instaladas em `~/.config/kilo/` (XDG) ou `~/.kilo/`. Usa o m
**Substituir o diretório de instalação:**
```bash
KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
KILO_CONFIG_DIR=~/.config/kilo-alt npx @golem15/msd-core@latest --kilo --global
```
---
@@ -81,10 +81,10 @@ KILO_CONFIG_DIR=~/.config/kilo-alt npx @opengsd/gsd-core@latest --kilo --global
### Codex
```bash
npx @opengsd/gsd-core@latest --codex --global
npx @golem15/msd-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.
As habilidades são instaladas em `~/.codex/skills/msd-*/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.
@@ -93,15 +93,15 @@ As habilidades são instaladas em `~/.codex/skills/gsd-*/SKILL.md`. Os agentes s
### GitHub Copilot
```bash
npx @opengsd/gsd-core@latest --copilot --global
npx @golem15/msd-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.
As habilidades são instaladas em `~/.copilot/`. O MSD é 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
COPILOT_CONFIG_DIR=~/.copilot-alt npx @golem15/msd-core@latest --copilot --global
```
---
@@ -109,15 +109,15 @@ COPILOT_CONFIG_DIR=~/.copilot-alt npx @opengsd/gsd-core@latest --copilot --globa
### Cursor
```bash
npx @opengsd/gsd-core@latest --cursor --global
npx @golem15/msd-core@latest --cursor --global
```
As habilidades são instaladas em `~/.cursor/`. O GSD instala habilidades, agentes e referências de regras.
As habilidades são instaladas em `~/.cursor/`. O MSD 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
CURSOR_CONFIG_DIR=~/.cursor-alt npx @golem15/msd-core@latest --cursor --global
```
---
@@ -125,29 +125,29 @@ CURSOR_CONFIG_DIR=~/.cursor-alt npx @opengsd/gsd-core@latest --cursor --global
### Windsurf
```bash
npx @opengsd/gsd-core@latest --windsurf --global
npx @golem15/msd-core@latest --windsurf --global
```
As habilidades são instaladas em `~/.codeium/windsurf/`. O GSD instala habilidades, agentes e regras de workspace.
As habilidades são instaladas em `~/.codeium/windsurf/`. O MSD 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
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-alt npx @golem15/msd-core@latest --windsurf --global
```
---
### Cline
O Cline usa uma integração baseada em regras — o GSD é instalado como `.clinerules` em vez de slash commands.
O Cline usa uma integração baseada em regras — o MSD é instalado como `.clinerules` em vez de slash commands.
```bash
# Instalação global (todos os projetos)
npx @opengsd/gsd-core@latest --cline --global
npx @golem15/msd-core@latest --cline --global
# Instalação local (apenas este projeto)
npx @opengsd/gsd-core@latest --cline --local
npx @golem15/msd-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.
@@ -157,10 +157,10 @@ Instalações globais escrevem em `~/.cline/`. Instalações locais escrevem em
### CodeBuddy
```bash
npx @opengsd/gsd-core@latest --codebuddy --global
npx @golem15/msd-core@latest --codebuddy --global
```
As habilidades são instaladas em `~/.codebuddy/skills/gsd-*/SKILL.md`.
As habilidades são instaladas em `~/.codebuddy/skills/msd-*/SKILL.md`.
---
@@ -169,15 +169,15 @@ As habilidades são instaladas em `~/.codebuddy/skills/gsd-*/SKILL.md`.
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
npx @golem15/msd-core@latest --qwen --global
```
As habilidades são instaladas em `~/.qwen/skills/gsd-*/SKILL.md`.
As habilidades são instaladas em `~/.qwen/skills/msd-*/SKILL.md`.
**Substituir o diretório de instalação:**
```bash
QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
QWEN_CONFIG_DIR=~/.qwen-alt npx @golem15/msd-core@latest --qwen --global
```
---
@@ -185,17 +185,17 @@ QWEN_CONFIG_DIR=~/.qwen-alt npx @opengsd/gsd-core@latest --qwen --global
### Augment Code
```bash
npx @opengsd/gsd-core@latest --augment --global
npx @golem15/msd-core@latest --augment --global
```
As habilidades são instaladas em `~/.augment/`. O GSD instala habilidades e agentes. Sem posse de hook ou statusline.
As habilidades são instaladas em `~/.augment/`. O MSD instala habilidades e agentes. Sem posse de hook ou statusline.
---
### Antigravity
```bash
npx @opengsd/gsd-core@latest --antigravity --global
npx @golem15/msd-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.
@@ -203,7 +203,7 @@ O instalador detecta automaticamente o diretório de configuração do Antigravi
**Substituir o diretório de instalação:**
```bash
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --antigravity --global
ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @golem15/msd-core@latest --antigravity --global
```
---
@@ -211,19 +211,19 @@ ANTIGRAVITY_CONFIG_DIR=~/.gemini/antigravity-alt npx @opengsd/gsd-core@latest --
### Trae
```bash
npx @opengsd/gsd-core@latest --trae --global
npx @golem15/msd-core@latest --trae --global
```
As habilidades são instaladas em `~/.trae/`. O GSD instala habilidades, agentes e referências de regras.
As habilidades são instaladas em `~/.trae/`. O MSD 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`:
Todos os exemplos acima usam `--global`, que instala o MSD 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
npx @golem15/msd-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.
@@ -235,10 +235,10 @@ Uma instalação local escreve no diretório `.claude/` na raiz do seu projeto.
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
WINDSURF_CONFIG_DIR=~/.codeium/windsurf-next npx @golem15/msd-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.
Selecione o ambiente estável correspondente no prompt do instalador. O MSD 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.
---
@@ -249,11 +249,11 @@ Se você não pode executar `npx` (por exemplo, em uma máquina Windows sem Node
**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
npx @golem15/msd-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.
**Opção B — Transforme manualmente os arquivos-fonte.** Os arquivos-fonte dos agentes estão em `agents/` no repositório do MSD 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.
---
@@ -262,8 +262,8 @@ npx @opengsd/gsd-core@latest --opencode --global
Reinicie seu ambiente para carregar os novos comandos e agentes. Em seguida, inicie um projeto novo ou faça onboarding de um repositório existente:
```bash
/gsd-new-project # projeto greenfield
/gsd-onboard # base de código existente
/msd-new-project # projeto greenfield
/msd-onboard # base de código existente
```
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.
@@ -273,6 +273,6 @@ Se o comando não for encontrado após o reinício, verifique se o diretório de
## Relacionados
- [Seu primeiro projeto](../tutorials/your-first-project.md)
- [Atualizar o GSD Core](update-gsd.md)
- [Atualizar o MSD Core](update-msd.md)
- [Configuração](../CONFIGURATION.md)
- [Índice da documentação](../README.md)

52
docs/pt-BR/how-to/isolate-work-with-workspaces.md
View File

@@ -1,6 +1,6 @@
# 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.
**Objetivo:** Criar um ambiente MSD 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.
@@ -14,13 +14,13 @@ Um workspace é um ambiente autocontido que combina um ou mais worktrees git (ou
- 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>/`.
Por padrão, os workspaces ficam em `~/msd-workspaces/<nome>/`.
```
~/gsd-workspaces/
~/msd-workspaces/
└── feature-b/
├── WORKSPACE.md ← manifesto
├── .planning/ ← estado GSD totalmente independente
├── .planning/ ← estado MSD totalmente independente
│ ├── PROJECT.md
│ ├── ROADMAP.md
│ └── ...
@@ -35,15 +35,15 @@ Como o `.planning/` do workspace é separado dos repositórios de origem, não h
## Criar um workspace para múltiplos repositórios
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI
/msd-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`.
O MSD cria worktrees de `hr-ui` e `ZeymoAPI` dentro de `~/msd-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 `/msd-new-project`.
Para personalizar o local:
```bash
/gsd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
/msd-workspace --new --name feature-b --repos hr-ui,ZeymoAPI --path /projects/feature-b
```
---
@@ -53,15 +53,15 @@ Para personalizar o local:
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 .
/msd-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`.
O `.` instrui o MSD 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
/msd-workspace --new --name payments-rework --repos . --strategy clone
```
---
@@ -69,7 +69,7 @@ Para forçar um clone completo em vez de um worktree:
## Especificar uma branch explicitamente
```bash
/gsd-workspace --new --name payments-rework --repos . --branch feature/payments-v2
/msd-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>`.
@@ -79,43 +79,43 @@ O flag `--branch` define o nome da branch para todos os repositórios do workspa
## Ignorar perguntas interativas
```bash
/gsd-workspace --new --name payments-rework --repos . --auto
/msd-workspace --new --name payments-rework --repos . --auto
```
O GSD aceita todos os padrões sem solicitar confirmação.
O MSD aceita todos os padrões sem solicitar confirmação.
---
## Inicializar o GSD dentro do workspace
## Inicializar o MSD dentro do workspace
Após criar um workspace, acesse-o e inicialize um projeto GSD:
Após criar um workspace, acesse-o e inicialize um projeto MSD:
```bash
cd ~/gsd-workspaces/feature-b
/gsd-new-project
cd ~/msd-workspaces/feature-b
/msd-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.
O diretório `.planning/` dentro do workspace é a raiz para todos os comandos MSD 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
/msd-workspace --list
```
Exibe todos os workspaces GSD ativos e seus status.
Exibe todos os workspaces MSD ativos e seus status.
---
## Remover um workspace
```bash
/gsd-workspace --remove feature-b
/msd-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.
O MSD 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.
---
@@ -123,15 +123,15 @@ O GSD remove os worktrees git e limpa o diretório do workspace. Isso não exclu
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ê está trabalhando em **múltiplos repositórios** que precisam ser coordenados sob um único projeto MSD (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))
- Você está seguindo um fluxo de trabalho orientado a issues em que cada issue do rastreador é mapeada para um workspace (consulte [Conduzir o MSD a partir de uma issue do rastreador](drive-msd-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ê deseja executar `/msd-plan-phase` ou `/msd-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
---
@@ -139,6 +139,6 @@ Escolha [workstreams](work-in-parallel-with-workstreams.md) quando:
## 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)
- [Conduzir o MSD a partir de uma issue do rastreador](drive-msd-from-a-tracker-issue.md)
- [Comandos](../COMMANDS.md)
- [Índice de documentação](../README.md)

62
docs/pt-BR/how-to/migrate-from-gsd-2.md
View File

@@ -1,22 +1,22 @@
# 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.
**Objetivo:** Atualizar um projeto GSD-2 mais antigo (estrutura de diretório `.gsd/`) para o MSD 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.
**Pré-requisitos:** MSD 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 GSD-2 usava um diretório `.gsd/` como raiz de planejamento. O MSD 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 MSD Core esperam.
| O que existe no GSD-2 | O que `/gsd-import --from-gsd2` produz |
| O que existe no GSD-2 | O que `/msd-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) |
| Arquivos `PLAN.md` de fase | Arquivos `{NN}-{MM}-PLAN.md` do MSD 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.
@@ -27,15 +27,15 @@ A detecção de conflitos é executada antes que qualquer arquivo seja gravado.
### Migrar o diretório atual
```bash
/gsd-import --from-gsd2
/msd-import --from-gsd2
```
O GSD lê `.gsd/` no diretório de trabalho atual e grava os artefatos migrados em `.planning/`.
O MSD 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
/msd-import --from-gsd2 --path ~/projects/old-project
```
Use `--path` quando o projeto GSD-2 não for seu diretório de trabalho atual.
@@ -46,7 +46,7 @@ Use `--path` quando o projeto GSD-2 não for seu diretório de trabalho atual.
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.
Leia o relatório, resolva a contradição (edite o documento de origem ou o artefato de planejamento existente) e execute `/msd-import --from-gsd2` novamente. A migração pode ser executada novamente com segurança até ser concluída sem problemas.
---
@@ -55,30 +55,30 @@ Leia o relatório, resolva a contradição (edite o documento de origem ou o art
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
/msd-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.
O MSD executa a mesma passagem de detecção de conflitos, converte o conteúdo para o formato `PLAN.md` do MSD 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:
Se o seu repositório já contiver ADRs (Architecture Decision Records), PRDs ou documentos de especificação, use `/msd-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
/msd-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.
Se `.planning/` já estiver presente (por exemplo, a partir da migração que você acabou de executar), o MSD 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/
/msd-ingest-docs docs/
/msd-ingest-docs docs/adr/
```
### Usar um manifesto de precedência explícito
@@ -86,7 +86,7 @@ Se `.planning/` já estiver presente (por exemplo, a partir da migração que vo
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
/msd-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.
@@ -94,11 +94,11 @@ O manifesto é um arquivo YAML que lista `{path, type, precedence?}` por documen
### 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)
/msd-ingest-docs --mode merge # Mesclar com o .planning/ existente
/msd-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.
**Saída:** `/msd-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.
---
@@ -107,19 +107,19 @@ O manifesto é um arquivo YAML que lista `{path, type, precedence?}` por documen
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
/msd-health
/msd-health --repair
```
`/gsd-health` verifica a integridade do diretório `.planning/` e relata qualquer desvio. `--repair` corrige automaticamente os problemas recuperáveis.
`/msd-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:
Em seguida, verifique se o MSD Core consegue ler o estado do seu projeto:
```bash
/gsd-progress
/msd-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.
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 MSD Core se aplica.
---
@@ -127,13 +127,13 @@ Se o projeto foi migrado corretamente, você verá o status da fase atual e o pr
| Situação | O que fazer |
|----------|-------------|
| `.gsd/` existe no diretório atual | Execute `/gsd-import --from-gsd2` (sem `--path`) |
| `.gsd/` existe no diretório atual | Execute `/msd-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 |
| Você tem um documento de plano avulso, não um projeto GSD-2 completo | Use `/msd-import --from /path/to/plan.md` |
| Você tem ADRs em `docs/adr/` | Execute `/msd-ingest-docs docs/adr/` após a migração |
| Você tem uma mistura de ADRs, PRDs e especificações | Execute `/msd-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 |
| Você não tem certeza se a migração funcionou | Execute `/msd-health` e `/msd-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 |
---

50
docs/pt-BR/how-to/plan-a-phase.md
View File

@@ -2,23 +2,23 @@
**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.
**Pré-requisitos:** `.planning/ROADMAP.md` deve existir. Um `{fase}-CONTEXT.md` gerado pelo `/msd-discuss-phase` é fortemente recomendado, mas não obrigatório.
---
## Execute o fluxo de planejamento padrão
```bash
/gsd-plan-phase 2
/msd-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.
1. **Pesquisa** — Um subagente `msd-phase-researcher` investiga o domínio e escreve `{fase}-RESEARCH.md`.
2. **Planejamento** — Um subagente `msd-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 `msd-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.
Se nenhum número de fase for fornecido, o MSD Core seleciona a próxima fase não planejada do roadmap.
---
@@ -27,34 +27,34 @@ Se nenhum número de fase for fornecido, o GSD Core seleciona a próxima fase n
**Se o domínio for familiar e não houver necessidade de nova pesquisa:**
```bash
/gsd-plan-phase 3 --skip-research
/msd-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
/msd-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
/msd-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
/msd-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
/msd-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.
Nota: `--research-phase <N>` é uma flag do `/msd-plan-phase`. Não existe um comando standalone de fase de pesquisa — o comando standalone foi removido em favor desta flag.
---
@@ -63,7 +63,7 @@ Nota: `--research-phase <N>` é uma flag do `/gsd-plan-phase`. Não existe um co
**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
/msd-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.
@@ -77,13 +77,13 @@ Na Fase 1 de um novo projeto sem resumos de fases anteriores, `--mvp` também pr
**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
/msd-plan-phase 1 --tdd
```
Combinável com `--mvp`:
```bash
/gsd-plan-phase 1 --mvp --tdd
/msd-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.
@@ -91,17 +91,17 @@ Isso produz fatias verticais onde cada tarefa que adiciona comportamento segue o
O modo TDD também pode ser persistido em config:
```bash
node gsd-tools.cjs config-set workflow.tdd_mode true
node msd-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:**
**Se você executou `/msd-review --phase N` e um `REVIEWS.md` existe:**
```bash
/gsd-plan-phase 3 --reviews
/msd-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`.
@@ -109,7 +109,7 @@ O planejador lê o `REVIEWS.md` e revisa os planos para endereçar o feedback. N
**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
/msd-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.
@@ -121,7 +121,7 @@ O ciclo de convergência executa ciclos de planejar → revisar → replanejar
**Se o `VERIFICATION.md` existir com lacunas não resolvidas e você quiser replanejar apenas para essas lacunas:**
```bash
/gsd-plan-phase 3 --gaps
/msd-plan-phase 3 --gaps
```
A pesquisa é ignorada; o planejador lê as lacunas de verificação diretamente.
@@ -133,13 +133,13 @@ A pesquisa é ignorada; o planejador lê as lacunas de verificação diretamente
**Se `workflow.plan_bounce_script` estiver configurado e você quiser validação externa do plano concluído:**
```bash
/gsd-plan-phase 1 --bounce
/msd-plan-phase 1 --bounce
```
Para pular o bounce mesmo que esteja habilitado em config:
```bash
/gsd-plan-phase 1 --skip-bounce
/msd-plan-phase 1 --skip-bounce
```
---
@@ -147,7 +147,7 @@ Para pular o bounce mesmo que esteja habilitado em config:
## Suprimir confirmações interativas
```bash
/gsd-plan-phase --auto
/msd-plan-phase --auto
```
Ignora todos os prompts. Útil em pipelines automatizados. A pesquisa é ignorada se `research_enabled` for false em config.
@@ -171,7 +171,7 @@ Para a referência completa de campos, consulte o [schema do PLAN.md](../referen
### Dimensões de qualidade do plano
O `gsd-plan-checker` valida os planos em oito dimensões antes de permitir a execução:
O `msd-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
@@ -191,7 +191,7 @@ O ciclo de revisão executa até três vezes. Se os critérios de qualidade não
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
/msd-plan-phase 2 --force
```
Um aviso é emitido na transcrição e em quaisquer documentos de plano confirmados.

116
docs/pt-BR/how-to/recover-and-troubleshoot.md
View File

@@ -2,7 +2,7 @@
**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).
**Pré-requisitos:** MSD Core está instalado. Para problemas específicos de instalação, consulte [Instalar no seu ambiente de execução](install-on-your-runtime.md).
---
@@ -11,7 +11,7 @@
### Se você perdeu o controle de onde está
```bash
/gsd-progress
/msd-progress
```
Lê todos os arquivos de estado e informa exatamente onde você está e o que fazer a seguir.
@@ -19,13 +19,13 @@ Lê todos os arquivos de estado e informa exatamente onde você está e o que fa
Para avançar automaticamente para o próximo passo correto:
```bash
/gsd-progress --next
/msd-progress --next
```
### Se você está iniciando uma nova sessão e precisa restaurar o contexto
```bash
/gsd-resume-work
/msd-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.
@@ -41,21 +41,21 @@ Limpe sua janela de contexto entre comandos principais:
Em seguida, restaure o estado:
```bash
/gsd-resume-work
/msd-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.
O MSD 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
/msd-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
/msd-pause-work --report
```
---
@@ -65,7 +65,7 @@ Cria `.planning/HANDOFF.json` com sua posição atual. Adicione `--report` para
### Se a integridade de `.planning/` está incerta
```bash
/gsd-health
/msd-health
```
Relata o status entre erros, avisos e notas informativas:
@@ -79,7 +79,7 @@ Relata o status entre erros, avisos e notas informativas:
Problemas comuns que podem ser reparados automaticamente (erros E004, E005; avisos W003, W008):
```bash
/gsd-health --repair
/msd-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`.
@@ -89,40 +89,40 @@ Isso recria o `STATE.md` ausente, redefine um `config.json` corrompido para os p
Isso gera o aviso `W002`. Use a CLI de estado para diagnosticar e reparar:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state validate
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state validate
```
Visualize o que uma sincronização mudaria sem gravar:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync --verify
node "$HOME/.claude/msd-core/bin/msd-tools.cjs" state sync --verify
```
Aplique a sincronização:
```bash
node "$HOME/.claude/gsd-core/bin/gsd-tools.cjs" state sync
node "$HOME/.claude/msd-core/bin/msd-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:
`.planning/PROJECT.md` já existe. `/msd-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`.
Em seguida, execute novamente `/msd-new-project`.
### Se a utilização da janela de contexto está alta
```bash
/gsd-health --context
/msd-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.
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 `/msd-resume-work` antes de iniciar o próximo comando principal.
---
@@ -130,7 +130,7 @@ Verifica a proteção de utilização da janela de contexto. Emite aviso em 60%,
### 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:
Os subagentes `msd-executor` do MSD 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:*)",
@@ -148,17 +148,17 @@ Alternativa por projeto: adicione o mesmo bloco em `.claude/settings.local.json`
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
/msd-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:
Isso é causado por múltiplos agentes acionando ferramentas de build simultaneamente. O MSD 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
/msd-settings
```
Defina `parallelization.enabled` como `false`.
@@ -171,7 +171,7 @@ Verifique o log do git antes de concluir que algo quebrou:
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.
Um bug de classificação conhecido do Claude Code pode reportar falha enquanto o trabalho foi concluído com sucesso. Os orquestradores do MSD verificam a saída real, mas se você vir uma discrepância, os commits são a fonte da verdade.
---
@@ -179,31 +179,31 @@ Um bug de classificação conhecido do Claude Code pode reportar falha enquanto
### 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:
Execute `/msd-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
/msd-discuss-phase 1
```
Para ver quais suposições o GSD está fazendo atualmente sem iniciar uma sessão completa:
Para ver quais suposições o MSD está fazendo atualmente sem iniciar uma sessão completa:
```bash
/gsd-discuss-phase 3 --assumptions
/msd-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:
Não execute novamente `/msd-execute-phase`. Use `/msd-quick` para correções direcionadas:
```bash
/gsd-quick "Fix the login button not responding on mobile Safari"
/msd-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.
Ou use `/msd-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.
Aguarde. Os subagentes do MSD 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.
@@ -216,56 +216,56 @@ Se já passou mais de 10 minutos, verifique se a tarefa do agente ainda aparece
### Se o fluxo de trabalho parece corrompido ou o estado está inconsistente
```bash
/gsd-forensics
/msd-forensics
```
Ou com uma descrição:
```bash
/gsd-forensics "Phase 3 execution stalled after wave 1"
/msd-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.
`/msd-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
/msd-undo --phase 03 # Reverte todos os commits da fase 3
/msd-undo --plan 03-02 # Reverte os commits do plano 02 da fase 3
/msd-undo --last 5 # Escolhe interativamente entre os 5 commits MSD mais recentes
```
`/gsd-undo` verifica as fases dependentes antes de reverter e sempre apresenta uma confirmação.
`/msd-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
### Se o MSD 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.
Reinicie seu ambiente de execução. O MSD instala comandos slash no diretório de comandos do seu ambiente de execução (por exemplo, `~/.claude/commands/msd/`). 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
npx @golem15/msd-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:
Desde a v1.17, o instalador faz backup dos arquivos modificados localmente em `msd-local-patches/`. Reaplique suas alterações:
```bash
/gsd-update --reapply
/msd-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.
Se `npx @golem15/msd-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).
Para atualizações de rotina, consulte [Atualizar o MSD](update-msd.md).
---
@@ -276,13 +276,13 @@ Para atualizações de rotina, consulte [Atualizar o GSD](update-gsd.md).
Mude para o perfil de orçamento:
```bash
/gsd-config --profile budget
/msd-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
/msd-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`:
@@ -299,19 +299,19 @@ Audite também quais servidores MCP estão habilitados. Cada servidor MCP habili
| 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) |
| Contexto perdido ou nova sessão | `/msd-resume-work` ou `/msd-progress` |
| Não sabe qual é o próximo passo | `/msd-progress --next` |
| Fase deu errado | `/msd-undo --phase NN`, depois replaneje |
| Algo quebrou | `/msd-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` |
| Integridade de `.planning/` incerta | `/msd-health`, depois `/msd-health --repair` |
| Estado do fluxo de trabalho parece corrompido | `/msd-forensics` |
| Correção direcionada rápida | `/msd-quick` |
| Plano não corresponde à sua visão | `/msd-discuss-phase N` depois replaneje |
| Custos elevados | `/msd-config --profile budget` e `/msd-settings` para desativar agentes |
| Atualização quebrou alterações locais | `/msd-update --reapply` |
| Quer resumo da sessão | `/msd-pause-work --report` |
| Erros de build por execução paralela | Atualize o MSD ou defina `parallelization.enabled: false` |
---

38
docs/pt-BR/how-to/run-phases-autonomously.md
View File

@@ -1,6 +1,6 @@
# 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.
Execute todas as fases restantes — ou um intervalo delimitado delas — sem supervisão, para que o MSD 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).
@@ -10,17 +10,17 @@ Para mais informações sobre o que o loop de fases faz durante uma execução a
- 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`
- Qualquer decisão de design que você se importe já deve estar em `PROJECT.md` ou registrada via um `/msd-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
/msd-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.
O MSD 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.
---
@@ -29,15 +29,15 @@ O GSD lê o `ROADMAP.md`, descobre cada fase incompleta em ordem numérica e exe
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
/msd-autonomous --from 3 # fases 3, 4, 5 … (ignora as fases 1 e 2 já concluídas)
/msd-autonomous --to 5 # fases até e incluindo a 5
/msd-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
Resume with: /msd-autonomous --from 6
```
---
@@ -47,11 +47,11 @@ Resume with: /gsd-autonomous --from 6
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
/msd-autonomous --interactive
```
No modo interativo:
- `/gsd-discuss-phase` é executado inline e aguarda suas respostas
- `/msd-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
@@ -59,7 +59,7 @@ No modo interativo:
## Quais barreiras de segurança ainda se aplicam
O modo autônomo não ignora o pipeline de qualidade do GSD. Cada fase ainda:
O modo autônomo não ignora o pipeline de qualidade do MSD. 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
@@ -74,15 +74,15 @@ A barreira de legitimidade de pacotes também permanece ativa. Se um plano inclu
## Quando não usar o modo autônomo
Não use `/gsd-autonomous` quando:
Não use `/msd-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`.
- **As fases têm decisões de design não resolvidas.** Se você não executou `/msd-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.
- **Você precisa de controle detalhado sobre uma única fase.** Para uma fase, `/msd-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.
- **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 `/msd-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.
@@ -93,13 +93,13 @@ Se uma execução parar no meio do caminho, consulte [Depurar uma execução com
O modo autônomo exibe um banner de progresso antes de cada fase:
```text
GSD ► AUTONOMOUS ▸ Phase 3/7: Auth Middleware [████░░░░] 28%
MSD ► 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
/msd-progress
```
---
@@ -109,10 +109,10 @@ Se você precisar verificar onde a execução está no meio da sessão, abra out
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
/msd-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.
O MSD 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.
---

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

@@ -8,7 +8,7 @@
## Decidir quais revisores usar
O GSD Core pode encaminhar solicitações de revisão para qualquer combinação de: Claude (sessão separada), Codex CLI, CodeRabbit, OpenCode, Qwen Code, Cursor, Antigravity CLI, Ollama, LM Studio e llama.cpp.
O MSD Core pode encaminhar solicitações de revisão para qualquer combinação de: 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.
@@ -26,18 +26,18 @@ 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:
Por padrão, `/msd-review` executa todos os CLIs detectados. Para fixar um subconjunto como padrões do projeto:
```bash
/gsd-config --integrations
/msd-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 `["codex","claude"]`.
Como alternativa, defina diretamente com `gsd-tools`:
Como alternativa, defina diretamente com `msd-tools`:
```bash
gsd config-set review.default_reviewers '["codex","claude"]'
msd config-set review.default_reviewers '["codex","claude"]'
```
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).
@@ -49,17 +49,17 @@ Para o esquema completo de configurações de integração (chaves de API, subst
### Revisão padrão (usa seus padrões configurados ou todos os CLIs detectados)
```bash
/gsd-review --phase 3
/msd-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`.
O MSD 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 --agy
/gsd-review --phase 3 --codex
/gsd-review --phase 3 --cursor
/msd-review --phase 3 --agy
/msd-review --phase 3 --codex
/msd-review --phase 3 --cursor
```
Qualquer flag explícita substitui tanto o padrão `--all` quanto `review.default_reviewers` para aquela execução.
@@ -67,7 +67,7 @@ Qualquer flag explícita substitui tanto o padrão `--all` quanto `review.defaul
### Executar todos os revisores disponíveis em paralelo
```bash
/gsd-review --phase 3 --all
/msd-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).
@@ -77,11 +77,11 @@ Qualquer flag explícita substitui tanto o padrão `--all` quanto `review.defaul
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
/msd-review --phase 3 --ollama
/msd-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.
Configure os endereços de host e a seleção de modelo nas chaves `review.*` via `/msd-config --integrations` se os padrões (`localhost:11434` / `localhost:1234`) não se aplicarem.
---
@@ -100,7 +100,7 @@ O arquivo `{padded_phase}-REVIEWS.md` contém:
Após revisar a saída, replaneje incorporando o feedback:
```bash
/gsd-plan-phase 3 --reviews
/msd-plan-phase 3 --reviews
```
O planejador lê `REVIEWS.md` e ajusta os planos para endereçar as preocupações antes de salvar.
@@ -112,7 +112,7 @@ O planejador lê `REVIEWS.md` e ajusta os planos para endereçar as preocupaçõ
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
/msd-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.
@@ -120,17 +120,17 @@ Isso executa `plan-phase → review → replan → re-review` por até três cic
### Convergência com um revisor específico
```bash
/gsd-plan-review-convergence 3 --codex
/gsd-plan-review-convergence 3 --agy
/msd-plan-review-convergence 3 --codex
/msd-plan-review-convergence 3 --agy
```
### Convergência com todos os revisores e um limite maior de ciclos
```bash
/gsd-plan-review-convergence 3 --all --max-cycles 5
/msd-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.
**Detecção de estagnação:** se a contagem de preocupações ALTAS não estiver diminuindo entre os ciclos, o MSD 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.
---
@@ -143,8 +143,8 @@ Isso executa `plan-phase → review → replan → re-review` por até três cic
| 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 --agy` |
| Você precisa de cobertura máxima antes de um lançamento | `/msd-plan-review-convergence N --all` |
| Você está iterando rapidamente e quer feedback rápido | escolha um CLI: `/msd-review --phase N --agy` |
---

52
docs/pt-BR/how-to/spike-and-sketch.md
View File

@@ -2,7 +2,7 @@
**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.
**Pré-requisitos:** Nenhum. `/msd-spike` e `/msd-sketch` criam seus próprios diretórios de armazenamento e não exigem um projeto MSD inicializado.
---
@@ -10,8 +10,8 @@
| Você quer responder… | Use |
|---|---|
| "Essa abordagem técnica vai funcionar de verdade?" | `/gsd-spike` |
| "Este layout / interação / tratamento visual parece certo?" | `/gsd-sketch` |
| "Essa abordagem técnica vai funcionar de verdade?" | `/msd-spike` |
| "Este layout / interação / tratamento visual parece certo?" | `/msd-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.
@@ -23,21 +23,21 @@ Spikes respondem perguntas binárias de viabilidade com código executável e um
### Coleta interativa (padrão)
```bash
/gsd-spike
/msd-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.
MSD 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"
/msd-spike "can we stream LLM tokens through SSE"
```
### Pular a coleta e executar imediatamente
```bash
/gsd-spike --quick "websocket vs SSE latency"
/msd-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.
@@ -59,10 +59,10 @@ Todos os spikes são indexados em `.planning/spikes/MANIFEST.md`.
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
/msd-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.
Isso grava em `.claude/skills/spike-findings-[project]/`. A skill é descoberta automaticamente e carregada por execuções subsequentes de `/msd-sketch`, `/msd-ui-phase` e `/msd-plan-phase` — você não precisa referenciá-la explicitamente.
---
@@ -71,21 +71,21 @@ Isso grava em `.claude/skills/spike-findings-[project]/`. A skill é descoberta
### Coleta de mood (padrão)
```bash
/gsd-sketch
/msd-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.
MSD 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"
/msd-sketch "dashboard layout"
```
### Pular a coleta de mood e executar imediatamente
```bash
/gsd-sketch --quick "sidebar navigation"
/msd-sketch --quick "sidebar navigation"
```
`--quick` ignora completamente a conversa de coleta e usa o argumento como direção de design.
@@ -93,7 +93,7 @@ GSD abre uma conversa breve para explorar sensação, referências visuais e a a
### Runtimes não-Claude (Codex, Antigravity CLI, etc.)
```bash
/gsd-sketch --text "onboarding flow"
/msd-sketch --text "onboarding flow"
```
`--text` substitui prompts interativos por listas numeradas em texto simples. Use isso quando seu runtime não suporta `AskUserQuestion`.
@@ -115,10 +115,10 @@ Todos os sketches são indexados em `.planning/sketches/MANIFEST.md`.
Após escolher uma variante, capture as decisões visuais em uma skill local do projeto:
```bash
/gsd-sketch --wrap-up
/msd-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.
Isso grava em `.claude/skills/sketch-findings-[project]/`. A skill é carregada automaticamente por `/msd-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.
---
@@ -127,26 +127,26 @@ Isso grava em `.claude/skills/sketch-findings-[project]/`. A skill é carregada
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
/msd-spike "SSE vs WebSocket for real-time feed"
/msd-spike --wrap-up
/gsd-sketch "real-time feed UI"
/gsd-sketch --wrap-up
/msd-sketch "real-time feed UI"
/msd-sketch --wrap-up
/gsd-discuss-phase N
/gsd-plan-phase N
/msd-discuss-phase N
/msd-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`.
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 `/msd-discuss-phase` ou `/msd-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:
Artefatos de spike e sketch não precisam ser referenciados manualmente. MSD 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
1. **`/msd-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. **`/msd-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.

54
docs/pt-BR/how-to/update-gsd.md → docs/pt-BR/how-to/update-msd.md
View File

@@ -1,8 +1,8 @@
# Como atualizar o GSD Core
# Como atualizar o MSD 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.
Atualize uma instalação existente do MSD 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 que você precisa:** O mesmo ambiente de execução para o qual o MSD 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).
---
@@ -11,19 +11,19 @@ Atualize uma instalação existente do GSD Core para a versão mais recente, vis
De dentro do seu ambiente de execução de IA, execute:
```bash
/gsd-update
/msd-update
```
O GSD irá:
O MSD 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`.
2. Verificar no npm a versão mais recente do `@golem15/msd-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>`).
5. Fazer backup de quaisquer arquivos adicionados pelo usuário encontrados dentro de diretórios gerenciados pelo MSD para `msd-user-files-backup/`.
6. Executar o instalador (`npx @golem15/msd-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/`.
8. Informar se arquivos MSD modificados localmente foram copiados para `msd-local-patches/`.
Reinicie seu ambiente de execução após a atualização para carregar os novos comandos e agentes.
@@ -33,22 +33,22 @@ Reinicie seu ambiente de execução após a atualização para carregar os novos
| 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/` |
| `--sync` | Após atualizar, sincroniza habilidades do registro MSD |
| `--reapply` | Após atualizar, mescla arquivos MSD modificados localmente de volta a partir de `msd-local-patches/` |
```bash
/gsd-update --sync # Update and sync skills
/gsd-update --reapply # Update and reapply local patches
/msd-update --sync # Update and sync skills
/msd-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:
`/msd-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
## MSD Update Available
Installed: 1.39.0
Latest: 1.41.0
@@ -70,47 +70,47 @@ Se o changelog não puder ser obtido (sem acesso à rede, falha no npm), a atual
## Recuperando personalizações locais
### Arquivos que você adicionou dentro de diretórios gerenciados pelo GSD
### Arquivos que você adicionou dentro de diretórios gerenciados pelo MSD
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.
Se você colocou arquivos personalizados dentro de diretórios que o MSD gerencia (por exemplo, agentes personalizados com o prefixo `msd-` ou arquivos extras em `commands/msd/`), o instalador os detectará e os copiará para `msd-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 colocados fora de diretórios gerenciados pelo MSD — agentes personalizados sem o prefixo `msd-`, comandos personalizados fora de `commands/msd/`, seus arquivos `CLAUDE.md` e hooks personalizados — nunca são tocados pelo instalador.
### Arquivos GSD que você modificou diretamente
### Arquivos MSD 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:
Se você editou um arquivo instalado pelo MSD (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 `msd-local-patches/` e, em seguida, o substitui pela nova versão. Após a atualização:
```bash
/gsd-update --reapply
/msd-update --reapply
```
Esse comando mescla suas modificações de `gsd-local-patches/` de volta aos arquivos recém-instalados.
Esse comando mescla suas modificações de `msd-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
/msd-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.
É seguro executar `--reapply` de forma independente sem acionar um novo download — se você já estiver na versão mais recente, o MSD 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 `npx @golem15/msd-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.
`/msd-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).
Cada versão do MSD 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).
---

46
docs/pt-BR/how-to/verify-and-ship.md
View File

@@ -9,36 +9,36 @@
## Executar os testes de aceitação do usuário
```bash
/gsd-verify-work 1
/msd-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.
O MSD 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).
Você nunca precisa categorizar a severidade — o MSD 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.
O progresso é gravado em `.planning/phases/01-<name>/01-UAT.md` e sobrevive a um `/clear`. Se uma sessão for interrompida, execute novamente `/msd-verify-work 1` e o MSD 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:
Se algum teste reportar problemas, o MSD 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.
2. **Planeja o fechamento das lacunas** — cria um `msd-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 `msd-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`
`/clear` then `/msd-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.
Execute o comando sugerido para aplicar as correções e, em seguida, execute novamente `/msd-verify-work 1` para confirmar que tudo passa.
---
@@ -47,14 +47,14 @@ Execute o comando sugerido para aplicar as correções e, em seguida, execute no
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
/msd-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:
O MSD 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
/msd-ship 1 # PR pronto para revisão
/msd-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:
@@ -71,19 +71,19 @@ 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:
`/msd-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
/msd-code-review 1 # Revisão padrão
/msd-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
/msd-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 Antigravity, Codex ou outros revisores para revisão de planos mais cedo no ciclo.
@@ -95,11 +95,11 @@ Consulte [Configurar revisão entre IAs](set-up-cross-ai-review.md) para configu
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
/msd-pr-branch # Filtrar contra main
/msd-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.
`/msd-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 `/msd-ship` se a política de revisão da sua equipe exclui ruído de planejamento.
---
@@ -108,11 +108,11 @@ Se o seu branch contiver commits de `.planning/` que você não quer que os revi
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
/msd-audit-milestone # Verificar se todos os requisitos foram entregues
/msd-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.
`/msd-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.
---

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

@@ -2,7 +2,7 @@
**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.
**Pré-requisitos:** Um projeto MSD Core ativo (`.planning/ROADMAP.md` existe). Se não existir, execute `/msd-new-project` primeiro.
---
@@ -28,24 +28,24 @@ Um workstream é um contexto de planejamento isolado dentro de um único reposit
└── 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.
Quando um workstream está ativo, todos os comandos MSD — `/msd-progress`, `/msd-discuss-phase`, `/msd-plan-phase`, `/msd-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
/msd-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.
O MSD 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
/msd-workstreams list
```
Exibe todos os workstreams e qual está atualmente ativo na sua sessão.
@@ -55,26 +55,26 @@ Exibe todos os workstreams e qual está atualmente ativo na sua sessão.
## Alternar para um workstream
```bash
/gsd-workstreams switch backend-api
/msd-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.
A partir deste ponto, todos os comandos de fluxo de trabalho MSD 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
/msd-discuss-phase 1
/msd-plan-phase 1
/msd-execute-phase 1
/msd-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
/msd-workstreams switch frontend-dash
/msd-discuss-phase 1
/msd-plan-phase 1
```
---
@@ -82,7 +82,7 @@ Para trabalhar em outra área, alterne workstreams em um segundo terminal:
## Verificar o progresso em todos os workstreams
```bash
/gsd-workstreams progress
/msd-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.
@@ -90,7 +90,7 @@ Exibe um resumo entre workstreams — status das fases, posição atual e trabal
Para status detalhado de um único workstream:
```bash
/gsd-workstreams status backend-api
/msd-workstreams status backend-api
```
---
@@ -100,10 +100,10 @@ Para status detalhado de um único workstream:
Após uma redefinição de contexto ou uma nova sessão, restaure sua posição:
```bash
/gsd-workstreams resume backend-api
/msd-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`.
Isso ativa o workstream e restaura sua última posição conhecida dentro dele, equivalente a alternar e então executar `/msd-resume-work`.
---
@@ -112,10 +112,10 @@ Isso ativa o workstream e restaura sua última posição conhecida dentro dele,
Quando o trabalho do milestone de um workstream estiver concluído:
```bash
/gsd-workstreams complete backend-api
/msd-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.
O MSD 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.
---
@@ -124,8 +124,8 @@ O GSD marca o workstream como arquivado e o remove da listagem ativa. Os artefat
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
/msd-progress --ws frontend-dash
/msd-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.
@@ -145,7 +145,7 @@ 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
- Você quer executar `/msd-new-project` independentemente em cada workspace com uma raiz `.planning/` completamente separada, não um subdiretório do `.planning/` do repositório principal
---

108
docs/pt-BR/issue-driven-orchestration.md
View File

@@ -1,36 +1,36 @@
# Orquestração Orientada a Issues com o GSD
# Orquestração Orientada a Issues com o MSD
**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.
assistida por IA através dos primitivos existentes do MSD.
## O que é este guia
Uma receita para combinar comandos que o GSD já inclui em um loop
Uma receita para combinar comandos que o MSD 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.
rastreador — cada comando referenciado abaixo já existe no MSD 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
([repositório](https://github.com/openai/symphony)). O MSD 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
nos primitivos que o MSD 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.
contornar os controles de segurança do MSD.
## 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
O MSD tem os blocos de construção para desenvolvimento de IA orientado a issues —
`/msd-workspace --new`, `/msd-manager`, `/msd-autonomous`, `/msd-verify-work`,
`/msd-review`, `/msd-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
nunca recorrem a `/msd-manager` ou `/msd-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
@@ -41,23 +41,23 @@ 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
primitivo do MSD 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 |
| Conceito Symphony | Primitivo MSD |
|---|---|
| `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 |
| Um workspace isolado de agente por tarefa | `/msd-workspace --new --strategy worktree` |
| Despacho e concorrência de agentes | `/msd-manager` (painel interativo), `/msd-autonomous` (sem supervisão) |
| Etapas de discussão e planejamento por fase | `/msd-discuss-phase` → `/msd-plan-phase` → `/msd-execute-phase` |
| Prova de trabalho / evidência de testes | `/msd-verify-work` (UAT.md persistido entre `/clear`) |
| Revisão adversarial | `/msd-review` (revisão por pares entre IAs do plano) |
| Controle humano de merge | `/msd-ship` (cria PR, revisão de código opcional, prepara merge) |
| Captura de trabalho subsequente | `/msd-capture`, `/msd-capture --seed`, `/msd-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
O mapeamento é unidirecional: o MSD é 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).
@@ -72,40 +72,40 @@ colchetes antes de executar.
(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
2. **Mapeie para uma fase do MSD.** 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
`/msd-new-milestone` (para um novo marco de issues relacionadas) ou abra
uma fase via `/msd-phase` / `/msd-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
`/msd-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`
4. **Execute discuss → plan → execute através do MSD.** De dentro do
workspace, execute `/msd-discuss-phase` para esclarecer ambiguidades,
`/msd-plan-phase` para produzir `PLAN.md`, e `/msd-manager`
(painel interativo) ou `/msd-execute-phase` / `/msd-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`
`claude` de fora do MSD — 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
5. **Exija prova de trabalho.** Execute `/msd-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
`/msd-plan-phase --gaps` quando a verificação revela escopo não coberto.
6. **Passe pelos controles de revisão e envio.** Execute `/msd-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
pontos cegos modelo a modelo), depois `/msd-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.
7. **Capture trabalho subsequente explicitamente.** Use `/msd-capture` para
notas inline, `/msd-capture --seed` para ideias que valem uma fase futura,
ou `/msd-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
descoberto requer confirmação explícita do usuário — o MSD não publica em
rastreadores remotos automaticamente.
Quando o PR é mesclado, o loop se fecha. Palavras-chave de fechamento
@@ -117,28 +117,28 @@ rastreador no momento do merge.
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
`/msd-workspace --new`, para que trabalho parcial, planos abandonados e
commits exploratórios nunca toquem o `main`. `msd-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
- **Revisão humana explícita.** `/msd-review` e `/msd-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
fila de merge — não algo que o MSD decide por você.
- **Nenhuma publicação automática.** O MSD 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
- **Verificação antes do envio.** O `UAT.md` do `/msd-verify-work` deve
registrar evidências antes que `/msd-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
diretamente na worktree, pular `/msd-verify-work`, ou criar issues via a API
do rastreador sem confirmação do usuário), as garantias deste guia não se
aplicam.
@@ -148,18 +148,18 @@ Este guia deliberadamente **não** propõe nada do seguinte. Eles estão listado
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
- **Sem venda ou cópia do código Symphony.** O MSD 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.
- **Sem daemon de longa execução.** O MSD 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
humana* — a URL vai para `CONTEXT.md`. O MSD 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
Mesmo ao executar `/msd-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
@@ -171,10 +171,10 @@ código:
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.
- Importar uma issue do GitHub ou Linear para um workspace / fase do MSD.
- 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`.
`/msd-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
@@ -184,8 +184,8 @@ escopo deste guia.
- [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.
- [Índice de documentação](README.md) — sumário completo da documentação do MSD 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/COMMANDS.md](COMMANDS.md) — referência completa dos comandos `/msd-*`.
- [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`.

18
docs/pt-BR/reference/context-md.md
View File

@@ -1,6 +1,6 @@
# 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).
Um `CONTEXT.md` por fase é o mecanismo do MSD Core para capturar decisões de implementação durante `/msd-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).
---
@@ -14,7 +14,7 @@ Toda fase que passou pelo fluxo de trabalho de discussão produz um `CONTEXT.md`
Por exemplo: `.planning/phases/03-post-feed/03-CONTEXT.md`.
O arquivo é produzido por `write_context` em `gsd-core/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.
O arquivo é produzido por `write_context` em `msd-core/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.
---
@@ -39,12 +39,12 @@ O corpo é dividido em blocos nomeados no estilo XML. Os blocos aparecem em uma
| 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` |
| `<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) | `msd-planner`, `msd-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) | `msd-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) | `msd-planner` (decisões bloqueadas devem ser implementadas), `msd-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) | `msd-phase-researcher`, `msd-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) | `msd-planner`, `msd-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) | `msd-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 |
---
@@ -107,7 +107,7 @@ Um CONTEXT.md cujas decisões sobrevivem aos planos é considerado conforme. Um
## 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>`:
Quando `/msd-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>

14
docs/pt-BR/reference/plan-md.md
View File

@@ -1,6 +1,6 @@
# 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).
Um `PLAN.md` por plano é a unidade executável de trabalho do MSD 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).
---
@@ -14,7 +14,7 @@ Os planos ficam dentro de diretórios de fase em:
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.
Os planos são produzidos pelo agente `msd-planner` (disparado por `/msd-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.
---
@@ -66,7 +66,7 @@ must_haves:
| `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`. |
| `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 `msd-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. |
@@ -78,7 +78,7 @@ must_haves:
## 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`.
`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 `msd-verifier`.
### Sub-campos
@@ -122,8 +122,8 @@ Lista os arquivos de workflow que o executor lê antes de começar. Sempre inclu
```xml
<execution_context>
@~/.claude/gsd-core/workflows/execute-plan.md
@~/.claude/gsd-core/templates/summary.md
@~/.claude/msd-core/workflows/execute-plan.md
@~/.claude/msd-core/templates/summary.md
</execution_context>
```
@@ -194,7 +194,7 @@ Planos que contêm qualquer tarefa de checkpoint devem definir `autonomous: fals
## 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):
O agente `msd-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 `msd-planner` para revisão (até 3 iterações):
| Dimensão | O que verifica |
|---|---|

72
docs/pt-BR/reference/planning-artifacts.md
View File

@@ -1,6 +1,6 @@
# 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).
O diretório `.planning/` é a memória compartilhada do MSD 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).
---
@@ -50,32 +50,32 @@ O diretório `.planning/` é a memória compartilhada do GSD Core para um projet
| | |
|---|---|
| **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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado por `/msd-complete-milestone` à medida que as decisões são validadas. |
| **Consumido por** | Todos os fluxos de trabalho de planejamento; `msd-phase-researcher`, `msd-planner` (contexto); `discuss-phase` (decisões anteriores); `msd-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, incluindo handoff do `/gsd-onboard`); 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`. |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado por `/msd-phase --insert` e `/msd-complete-milestone`. |
| **Consumido por** | `/msd-discuss-phase`, `/msd-plan-phase`, `/msd-execute-phase`; todos os comandos de orquestração que precisam de informações de fase; `msd-planner`, `msd-plan-checker`, `msd-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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); requisitos marcados como concluídos por `execute-phase`. |
| **Consumido por** | `msd-planner` (os planos devem contemplar todos os IDs de requisitos da fase); `msd-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, incluindo handoff do `/gsd-onboard`); 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). |
| **Produzido por** | `/msd-new-project` (criação inicial, incluindo handoff do `/msd-onboard`); atualizado continuamente por todos os fluxos de fase, `/msd-pause-work`, `/msd-resume-work`. |
| **Consumido por** | Todos os fluxos de orquestração; `/msd-progress`; execução de tarefas avulsas via `/msd-quick`; `msd-planner` e `msd-phase-researcher` (decisões do projeto). |
Consulte o [esquema de STATE.md](state-md.md) para a referência completa de campos.
@@ -84,8 +84,8 @@ Consulte o [esquema de STATE.md](state-md.md) para a referência completa de cam
| | |
|---|---|
| **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`. |
| **Produzido por** | `/msd-new-project` (criação inicial); `/msd-settings` (edição interativa). |
| **Consumido por** | Todos os fluxos de trabalho e subagentes — lido no momento de inicialização via `msd-tools query config-get`. |
Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
@@ -93,17 +93,17 @@ Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
| | |
|---|---|
| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando GSD recomendado após a configuração inicial. |
| **Produzido por** | `/gsd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/gsd-onboard` ao confirmar o estado de onboarding existente. |
| **Finalidade** | Índice de onboarding brownfield que registra status dos artefatos, se o mapeamento do código-base está completo e o próximo comando MSD recomendado após a configuração inicial. |
| **Produzido por** | `/msd-onboard` depois que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem. |
| **Consumido por** | Humanos revisando a configuração inicial; futuras execuções de `/msd-onboard` ao confirmar o estado de onboarding existente. |
### `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. |
| **Produzido por** | `/msd-complete-milestone`. |
| **Consumido por** | `/msd-audit-milestone`; revisão humana. |
### `DECISIONS-INDEX.md` (opcional)
@@ -118,8 +118,8 @@ Consulte [CONFIGURATION](../CONFIGURATION.md) para o esquema completo.
| | |
|---|---|
| **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`. |
| **Produzido por** | `/msd-pause-work`. |
| **Consumido por** | `/msd-resume-work`. |
---
@@ -132,8 +132,8 @@ Todos os arquivos por fase ficam em `.planning/phases/<NN>-<slug>/`, onde `NN`
| | |
|---|---|
| **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). |
| **Produzido por** | `/msd-discuss-phase` (discussão interativa ou caminhos expressos PRD/ADR). |
| **Consumido por** | `msd-phase-researcher` (o que investigar); `msd-planner` (decisões bloqueadas); `msd-plan-checker` Dimensão 7 (conformidade de contexto). |
Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de campos.
@@ -142,7 +142,7 @@ Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de
| | |
|---|---|
| **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`). |
| **Produzido por** | `/msd-discuss-phase` (etapa `git_commit`). |
| **Consumido por** | Revisão humana; retrospectivas. |
### `<NN>-RESEARCH.md`
@@ -150,32 +150,32 @@ Consulte o [esquema de CONTEXT.md](context-md.md) para a referência completa de
| | |
|---|---|
| **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). |
| **Produzido por** | `/msd-plan-phase` via agente `msd-phase-researcher`. |
| **Consumido por** | `msd-planner` (entradas de planejamento); `msd-plan-checker` Dimensão 7c (conformidade de camada), Dimensão 8 (Nyquist), Dimensão 11 (resolução de pesquisa); `msd-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`. |
| **Produzido por** | `/msd-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** | `msd-plan-checker` Dimensão 8 (gate Check 8e — deve existir antes de os checks Nyquist prosseguirem); `msd-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). |
| **Finalidade** | Mapa de análogos do código-base produzido pelo `msd-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** | `/msd-plan-phase` via agente `msd-pattern-mapper` (opcional; ignorado se `workflow.pattern_mapper: false`). |
| **Consumido por** | `msd-planner` (orientação de padrões); `msd-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). |
| **Produzido por** | `/msd-plan-phase` via agente `msd-planner`. Um arquivo por plano — ex.: `03-02-PLAN.md` é Fase 3, Plano 2. |
| **Consumido por** | `/msd-execute-phase` (agente executor lê o plano e executa as tarefas); `msd-plan-checker` (revisão de qualidade pré-execução); `msd-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.
@@ -185,30 +185,30 @@ Consulte o [esquema de PLAN.md](plan-md.md) para a referência completa de campo
|---|---|
| **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`. |
| **Consumido por** | `/msd-progress` (status da fase); `msd-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. |
| **Produzido por** | `/msd-verify-work` (ou a etapa de verificação dentro de `/msd-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`); `/msd-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). |
| **Produzido por** | `/msd-audit-uat` (sessão UAT interativa). |
| **Consumido por** | `/msd-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`. |
| **Produzido por** | `/msd-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. |
---

42
docs/pt-BR/reference/state-md.md
View File

@@ -1,14 +1,14 @@
# 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).
`STATE.md` é o arquivo de memória viva do projeto do MSD 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:
Todo projeto gerenciado pelo MSD 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`.
- **Frontmatter YAML** — campos legíveis por máquina consumidos pelo hook de linha de status (`parseStateMd`) e pelos comandos `msd-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.
@@ -17,13 +17,13 @@ O arquivo é intencionalmente pequeno (meta: menos de 100 linhas). Ele é um res
## 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.
O frontmatter aparece entre delimitadores `---` no início do arquivo. Todos os campos, exceto `msd_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'
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing
@@ -56,7 +56,7 @@ paused_at: null
| Campo | Tipo | Quando populado | Finalidade |
|---|---|---|---|
| `gsd_state_version` | string (`'1.0'`) | Sempre | Versão do esquema; escrito na primeira chamada `state.*` por `syncStateFrontmatter`. |
| `msd_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). |
@@ -83,7 +83,7 @@ paused_at: null
| Campo | Cardinalidade |
|---|---|
| `gsd_state_version` | one |
| `msd_state_version` | one |
| `milestone` | optional |
| `milestone_name` | optional |
| `current_phase` | optional |
@@ -105,7 +105,7 @@ paused_at: null
### Valores de status
`normalizeStateStatus()` em `gsd-core/bin/lib/state-document.cjs` mapeia o texto bruto do corpo para estes valores canônicos:
`normalizeStateStatus()` em `msd-core/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) |
|---|---|
@@ -121,10 +121,10 @@ Quando um comando do orquestrador está em andamento, a convenção (issue #2833
| Comando | `status` durante a execução |
|---|---|
| `/gsd-discuss-phase` | `discussing` |
| `/gsd-plan-phase` | `planning` |
| `/gsd-execute-phase` | `executing` |
| `/gsd-verify-work` | `verifying` |
| `/msd-discuss-phase` | `discussing` |
| `/msd-plan-phase` | `planning` |
| `/msd-execute-phase` | `executing` |
| `/msd-verify-work` | `verifying` |
<!-- STATE-MD-SCHEMA:START:status-lifecycle — generated by scripts/gen-state-md-docs.cjs from src/state-md-schema.cts; do not edit by hand -->
### Ciclo de vida do status (ADR-2207)
@@ -145,7 +145,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
## 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.
`formatMsdState()` em `hooks/msd-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 |
|---|---|---|
@@ -154,7 +154,7 @@ Phase-completion verbs never write `Milestone complete` (the overloaded bare val
| **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/gsd-statusline.test.cjs`.
**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 `formatMsdState()` e coberta pelo conjunto `"scene priority"` em `tests/msd-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.
@@ -162,7 +162,7 @@ A barra de progresso (`[██░░░░░░░░] 20%`) é anexada ao segm
## 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/gsd-statusline.test.cjs`.
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/msd-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.
@@ -176,7 +176,7 @@ Se uma mudança futura substituir o analisador de regex por uma biblioteca YAML
## Seções do corpo Markdown
O corpo (tudo após o `---` de fechamento) segue o template em `gsd-core/templates/state.md`. As seções padrão são:
O corpo (tudo após o `---` de fechamento) segue o template em `msd-core/templates/state.md`. As seções padrão são:
### Referência do Projeto
@@ -200,7 +200,7 @@ Onde o projeto está agora:
O *histórico* de progresso não pertence aqui. Ele se acumula em [`### Performance Metrics`](#métricas-de-desempenho) logo abaixo, que é a seção projetada para crescer.
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 `gsd-core/bin/lib/state-document.cjs`.
Os campos `Status:` e `Last activity:` nesta seção são atualizados pelos handlers do MSD 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 `msd-core/bin/lib/state-document.cjs`.
### Métricas de Desempenho
@@ -213,11 +213,11 @@ 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`.
**Decisões** — um resumo das decisões recentes que afetam o trabalho atual (o log completo vive em `PROJECT.md`). Adicionado via `msd-tools state add-decision`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/gsd-capture`.
**Todos Pendentes** — contagem e referência a `.planning/todos/pending/`. Capturado via `/msd-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`.
**Bloqueadores/Preocupações** — problemas que afetam trabalhos futuros, prefixados com a fase de origem. Adicionado via `msd-tools state add-blocker`; resolvido via `msd-tools state resolve-blocker`.
### Continuidade de Sessão
@@ -236,7 +236,7 @@ Os campos de ciclo de vida de fase (`active_phase`, `next_action`, `next_phases`
- 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/gsd-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
O conjunto de testes `formatMsdState #2833 backward compatibility` em `tests/msd-statusline.test.cjs` garante essa promessa; qualquer mudança que quebre a renderização legada do `STATE.md` fará o conjunto falhar.
---

4
docs/pt-BR/superpowers/plans/2026-03-23-materialize-new-project-config.md
View File

@@ -7,7 +7,7 @@ Fonte canônica: `docs/superpowers/plans/2026-03-18-materialize-new-project-conf
## Contexto
Este plano formaliza a materialização explícita da configuração do projeto durante `/gsd-new-project`, garantindo que escolhas feitas na inicialização sejam persistidas de forma determinística em `.planning/config.json`.
Este plano formaliza a materialização explícita da configuração do projeto durante `/msd-new-project`, garantindo que escolhas feitas na inicialização sejam persistidas de forma determinística em `.planning/config.json`.
## Objetivos
@@ -37,7 +37,7 @@ Não inclui:
## Critérios de aceitação
- após `/gsd-new-project`, `config.json` reflete as escolhas feitas
- após `/msd-new-project`, `config.json` reflete as escolhas feitas
- rerun não duplica nem corrompe campos
- comandos subsequentes observam os valores persistidos

4
docs/pt-BR/superpowers/specs/2026-03-20-multi-project-workspaces-design.md
View File

@@ -26,14 +26,14 @@ Introduzir workspaces multi-projeto com:
## Modelo conceitual
- **Workspace**: unidade isolada de execução GSD
- **Workspace**: unidade isolada de execução MSD
- **Member repos**: repositórios associados ao workspace
- **Manifest**: arquivo de metadados com estrutura e status
## Fluxo de uso
1. Criar workspace com nome e repositórios alvo
2. Inicializar/retomar fluxo GSD dentro do workspace
2. Inicializar/retomar fluxo MSD dentro do workspace
3. Operar fases normalmente com estado isolado
4. Finalizar e remover quando concluído

64
docs/pt-BR/tutorials/onboarding-an-existing-codebase.md
View File

@@ -1,12 +1,12 @@
# 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.
Neste tutorial você integrará o MSD 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 MSD 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.
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 MSD Core aprende sua base de código antes de planejar qualquer coisa.
---
@@ -18,12 +18,12 @@ Adicionaremos um único endpoint `GET /health` a uma aplicação Express existen
---
## Passo 1 — Instalar o GSD Core
## Passo 1 — Instalar o MSD Core
Na raiz do seu repositório:
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-core@latest
```
Escolha **Claude Code** e **local** quando solicitado. Você verá:
@@ -31,7 +31,7 @@ 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
✓ MSD Core ready — run /msd-new-project to start
```
---
@@ -44,7 +44,7 @@ claude --dangerously-skip-permissions
> [!CAUTION]
> **The permissions flag is optional.** It skips per-file confirmation while
> GSD's sub-agents read and write files. Use it only in low-stakes or
> MSD's sub-agents read and write files. Use it only in low-stakes or
> throwaway contexts. To keep confirmations enabled, start with `claude` instead.
> For real work, read the [security model](../explanation/security-model.md) first.
@@ -53,13 +53,13 @@ claude --dangerously-skip-permissions
## Passo 3 — Iniciar o onboarding brownfield
Antes de criar um projeto, deixe o GSD Core inspecionar o estado do repositório e indicar o próximo comando de nível superior seguro. Este passo evita pular contexto de código ou sobrescrever arquivos de planning existentes.
Antes de criar um projeto, deixe o MSD Core inspecionar o estado do repositório e indicar o próximo comando de nível superior seguro. Este passo evita pular contexto de código ou sobrescrever arquivos de planning existentes.
```text
/gsd-onboard
/msd-onboard
```
Se o onboarding informar que o mapa da base de código está ausente, escolha a opção recomendada e execute o handoff `/gsd-map-codebase` impresso antes de rodar `/gsd-onboard` novamente. `/gsd-onboard --fast` serve para uma primeira passada leve, mas um mapa completo ainda é necessário antes de `/gsd-new-project`. O `/gsd-map-codebase` 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:
Se o onboarding informar que o mapa da base de código está ausente, escolha a opção recomendada e execute o handoff `/msd-map-codebase` impresso antes de rodar `/msd-onboard` novamente. `/msd-onboard --fast` serve para uma primeira passada leve, mas um mapa completo ainda é necessário antes de `/msd-new-project`. O `/msd-map-codebase` 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 |
|--------|------|
@@ -83,9 +83,9 @@ Created .planning/codebase/:
- 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/STACK.md`. Você verá a linguagem, o runtime, as versões do framework e as dependências principais que o MSD 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/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 MSD 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.
@@ -99,15 +99,15 @@ Limpe a janela de sessão:
/clear
```
Agora execute `/gsd-onboard` novamente. Se o GSD Core detectar ADRs, PRDs, specs, RFCs ou requisitos de nível raiz, aceite o handoff recomendado para `/gsd-ingest-docs` primeiro e depois rode `/gsd-onboard` de novo. Quando o contexto estiver pronto, o onboarding imprimirá o handoff de inicialização:
Agora execute `/msd-onboard` novamente. Se o MSD Core detectar ADRs, PRDs, specs, RFCs ou requisitos de nível raiz, aceite o handoff recomendado para `/msd-ingest-docs` primeiro e depois rode `/msd-onboard` de novo. Quando o contexto estiver pronto, o onboarding imprimirá o handoff de inicialização:
```text
/gsd-new-project
/msd-new-project
```
Como o GSD Core encontrou código existente no passo anterior, `/gsd-new-project` sabe que é um projeto brownfield. As perguntas focam no que você está *adicionando*, não em reconstruir o que já existe:
Como o MSD Core encontrou código existente no passo anterior, `/msd-new-project` sabe que é um projeto brownfield. As perguntas focam no que você está *adicionando*, não em reconstruir o que já existe:
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:
O MSD 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
@@ -115,7 +115,7 @@ Add a GET /health endpoint to the Express app. It should return
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.
O MSD 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.
@@ -133,7 +133,7 @@ Proposed Roadmap
Aprove o roteiro.
Execute `/gsd-onboard` mais uma vez depois que a configuração do projeto terminar. Agora que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem, o onboarding cria ou confirma `.planning/onboarding/SUMMARY.md`.
Execute `/msd-onboard` mais uma vez depois que a configuração do projeto terminar. Agora que `PROJECT.md`, `REQUIREMENTS.md`, `ROADMAP.md` e `STATE.md` existem, o onboarding cria ou confirma `.planning/onboarding/SUMMARY.md`.
**O que é criado em `.planning/`:**
@@ -148,7 +148,7 @@ Execute `/gsd-onboard` mais uma vez depois que a configuração do projeto termi
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.
Observe que `.planning/codebase/` já está lá desde o Passo 3. O MSD Core leu esses arquivos ao escrever `PROJECT.md`, por isso conseguiu preencher os requisitos Validated sem que você os descrevesse.
---
@@ -159,10 +159,10 @@ Observe que `.planning/codebase/` já está lá desde o Passo 3. O GSD Core leu
```
```text
/gsd-discuss-phase 1
/msd-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:
Como o MSD 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
@@ -177,7 +177,7 @@ Como o GSD Core leu seu `CONVENTIONS.md` e `ARCHITECTURE.md`, suas perguntas sã
process.uptime() is fine.
```
Quando a discussão encerrar, o GSD Core escreverá:
Quando a discussão encerrar, o MSD Core escreverá:
```text
.planning/phases/01-health-endpoint/CONTEXT.md
@@ -190,7 +190,7 @@ Abra esse arquivo. A seção `## Implementation Decisions` captura suas resposta
## Passo 6 — Planejar a Fase 1
```text
/gsd-plan-phase 1
/msd-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.
@@ -204,7 +204,7 @@ Quatro sub-agentes de pesquisa rodam em paralelo (1–5 minutos). Quando retorna
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.
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 MSD Core observou no mapa da sua base de código. Isso é o mapa da base de código em ação.
---
@@ -213,21 +213,21 @@ Abra `01-01-PLAN.md`. Observe que a tag `<files>` referencia `src/routes/health.
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
/msd-execute-phase 1
/msd-verify-work 1
/msd-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.
Para cada recurso futuro, execute `/msd-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-onboard` sequencia com segurança o setup brownfield sem aninhar comandos interativos ou sobrescrever planning existente.
- 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 `/msd-onboard` sequencia com segurança o setup brownfield sem aninhar comandos interativos ou sobrescrever planning existente.
- Como `/msd-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 `/msd-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 `/msd-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.
---
@@ -235,5 +235,5 @@ Para cada recurso futuro, execute `/gsd-map-codebase` novamente sempre que a est
## 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`
- [Mapear base de código via Comandos](../COMMANDS.md) — todos os flags e subcomandos de `/msd-map-codebase`
- [Índice de documentação](../README.md)

70
docs/pt-BR/tutorials/your-first-project.md
View File

@@ -1,6 +1,6 @@
# 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.
Neste tutorial você instalará o MSD 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.
---
@@ -16,16 +16,16 @@ Um CLI em Node.js que permite adicionar, listar e concluir itens de tarefas arma
- **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.
Nenhuma outra ferramenta é necessária. O próprio MSD Core é instalado no próximo passo.
---
## Passo 1 — Instalar o GSD Core
## Passo 1 — Instalar o MSD Core
Abra um terminal no diretório do seu projeto e execute:
```bash
npx @opengsd/gsd-core@latest
npx @golem15/msd-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.
@@ -35,10 +35,10 @@ 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
✓ MSD Core ready — run /msd-new-project to start
```
Observe que um diretório `.claude/` agora existe no seu projeto. É onde os comandos e agentes do GSD Core residem.
Observe que um diretório `.claude/` agora existe no seu projeto. É onde os comandos e agentes do MSD 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.
@@ -46,7 +46,7 @@ Observe que um diretório `.claude/` agora existe no seu projeto. É onde os com
## 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:
O MSD 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
@@ -61,10 +61,10 @@ Você chegará ao prompt do Claude Code no diretório do seu projeto.
Digite este comando slash no prompt do Claude Code:
```text
/gsd-new-project
/msd-new-project
```
O GSD Core abrirá uma conversa. Ele faz uma pergunta primeiro:
O MSD Core abrirá uma conversa. Ele faz uma pergunta primeiro:
```text
What do you want to build?
@@ -78,13 +78,13 @@ A Node.js CLI tool for managing to-do items. Users run `todo add "buy milk"`,
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.
O MSD 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`.
O MSD 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:
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 MSD Core apresentará um roadmap proposto. Para um projeto de uma única fase, ele terá uma aparência semelhante a:
```text
Proposed Roadmap
@@ -115,7 +115,7 @@ Abra `.planning/ROADMAP.md` agora e leia. Observe que a Fase 1 tem uma Meta, uma
## 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:
O MSD Core é projetado em torno de contextos frescos. Limpe a janela de sessão principal antes de cada fase:
```text
/clear
@@ -124,10 +124,10 @@ O GSD Core é projetado em torno de contextos frescos. Limpe a janela de sessão
Em seguida, inicie a discussão para a Fase 1:
```text
/gsd-discuss-phase 1
/msd-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:
O MSD 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?
@@ -140,7 +140,7 @@ O GSD Core lê a meta da fase e pergunta sobre suas preferências de implementa
Create it silently on first add.
```
Quando a discussão encerra, o GSD Core escreve:
Quando a discussão encerra, o MSD Core escreve:
```text
.planning/phases/01-core-cli/CONTEXT.md
@@ -153,7 +153,7 @@ Abra esse arquivo. Você verá uma seção `## Implementation Decisions` captura
## Passo 5 — Planejar a Fase 1
```text
/gsd-plan-phase 1
/msd-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.
@@ -169,17 +169,17 @@ Quando retornarem, um planejador lê o CONTEXT.md mais os resultados da pesquisa
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.
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 MSD Core executará esse comando após escrever o código.
---
## Passo 6 — Executar a Fase 1
```text
/gsd-execute-phase 1
/msd-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.
O MSD 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:
@@ -215,17 +215,17 @@ 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.
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 MSD Core.
---
## Passo 7 — Verificar o trabalho
```text
/gsd-verify-work 1
/msd-verify-work 1
```
O GSD Core extrai os critérios de sucesso da fase e os percorre um a um:
O MSD 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?
@@ -240,7 +240,7 @@ O GSD Core extrai os critérios de sucesso da fase e os percorre um a um:
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`.
Se alguma verificação falhar, o MSD Core diagnostica a causa raiz e cria um plano de correção. Execute `/msd-execute-phase 1` novamente para aplicá-lo e depois re-execute `/msd-verify-work 1`.
**O que é criado:**
@@ -253,10 +253,10 @@ Se alguma verificação falhar, o GSD Core diagnostica a causa raiz e cria um pl
## Passo 8 — Publicar
```text
/gsd-ship 1
/msd-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.
O MSD 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á:
@@ -272,15 +272,15 @@ 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.
- Como instalar o MSD Core com `npx @golem15/msd-core@latest`.
- Como `/msd-new-project` transforma uma conversa em um roadmap respaldado por artefatos em `.planning/`.
- Como `/msd-discuss-phase` captura decisões de implementação antes de qualquer planejamento acontecer.
- Como `/msd-plan-phase` spawna pesquisadores em paralelo e produz planos de tarefa atômicos.
- Como `/msd-execute-phase` executa esses planos em ondas paralelas e confirma cada tarefa.
- Como `/msd-verify-work` percorre os critérios de sucesso e gera planos de correção quando necessário.
- Como `/msd-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.
Para um projeto de múltiplas fases, repita os Passos 4–8 para cada fase e depois execute `/msd-progress --next` para deixar o MSD Core detectar o próximo passo automaticamente.
---
@@ -288,4 +288,4 @@ Para um projeto de múltiplas fases, repita os Passos 4–8 para cada fase e dep
- [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
- [Integrando uma base de código existente](onboarding-an-existing-codebase.md) — traga o MSD Core para um repositório já existente

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

@@ -1,6 +1,6 @@
# Modo Discuss: Suposições vs Entrevista
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.
A fase de discuss do MSD 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.
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).
@@ -26,10 +26,10 @@ Um fluxo com foco no código-base. O Claude analisa profundamente o código-base
```bash
# Habilitar o modo assumptions
node gsd-tools.cjs config-set workflow.discuss_mode assumptions
node msd-tools.cjs config-set workflow.discuss_mode assumptions
# Voltar ao modo de entrevista
node gsd-tools.cjs config-set workflow.discuss_mode discuss
node msd-tools.cjs config-set workflow.discuss_mode discuss
```
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.
@@ -69,7 +69,7 @@ Os agentes downstream (researcher, planner, checker) consomem esse arquivo de fo
## Relacionados
- [Realizar discuss de uma fase](how-to/discuss-a-phase.md) — passo a passo para executar `/gsd-discuss-phase` em qualquer modo.
- [Realizar discuss de uma fase](how-to/discuss-a-phase.md) — passo a passo para executar `/msd-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.
- [Índice de documentação](README.md) — sumário completo da documentação do MSD Core.