golem15/msd-core
4
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9faacc0c153a88f939ef07ced74d56dc468f0708
msd-core/docs/pt-BR/how-to/install-on-your-runtime.md
Tom Boucher ffd5370464 fix(#2903): use the command form that actually works in reader-facing docs (#3047) 
* fix(#2903): use the command form that actually works in reader-facing docs

Docs told readers to type the colon form, which no runtime registers -- 18 of
19 runtimes use slash-hyphen and the 19th uses shell-var -- so anyone copying an
example got an unrecognized command. Swept 178 occurrences across 53 files,
locale mirrors included so they do not re-diverge from English.

The colon form is a source-authoring token, not a user-facing one: install-time
converters key on it to produce the hyphen form runtimes actually register. So
the sweep is scoped, and three things are deliberately left alone:

- ADRs, which are a historical record; editing their prose falsifies what was
  written at the time.
- The legacy release-notes archive, pending a maintainer decision on whether it
  follows the same historical carve-out. Excluding it keeps a later reversal
  additive rather than a revert.
- Source artifacts under commands, workflows and agents, where the colon form is
  load-bearing. Rewriting those would break the installed-skill guarantee across
  every runtime -- the single largest hazard here.

The plugin namespace form is a real, separate token and survives untouched.

Adds a lint enforcing exactly that boundary, since the correct form genuinely
differs by directory and nothing previously caught the drift.

Also fixes a hardcoded colon form in the capability-matrix generator. The sweep
alone would have left the generated matrix disagreeing with the template that
produces it, so the fix is at the source and the output regenerated.

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

* fix(#2903): stop the sweep misquoting source frontmatter

Adversarial review caught three lines where the sweep rewrote a citation of the
literal YAML name: key from a source command file. That key genuinely is the
colon form -- this change's own carve-out logic says source-authoring tokens keep
it -- so the docs ended up misquoting the real files. One of the three is an
acceptance-checklist assertion, which the sweep turned into a false statement.

Restored the three citations to match their sources verbatim, surgically: where a
line carried both a name: citation and a real reader-facing slash command, only
the citation reverted and the command stayed corrected.

The guard needed the same distinction, or it would have flagged the restoration
and reddened the build: a gsd:<cmd> token preceded by name: is a citation of a
source token and is now permitted. The exemption is deliberately narrow -- a bare
gsd:<cmd> anywhere else still fails -- with a test pinning that narrowness.

Also makes the detection case-insensitive. Review found /GSD:next slipped through
silently; no such casing exists in the tree today, so this closes a latent gap
rather than fixing a live one.

Swept the whole tree for further corrupted citations: none beyond the three.

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

* fix(#2903): retire the stale-next invariant and sweep next like every other command

Maintainer decision on a genuine conflict between two contracts.

Invariant #3054 banned the literal /gsd-next from user-facing docs because it
named a retired workflow-advance command. But commands/gsd/next.md is a live
command -- the state-aware smart-entry launcher -- and this issue requires docs
to use the hyphen form every runtime actually registers. Both could not hold for
this one command, so docs had been sidestepping the ban by keeping the colon
form, which is exactly the defect this issue exists to remove.

FEATURES.md already recorded the reassignment: the hyphen form "is not the
retired workflow-advance command; it is reserved for the state-aware smart-entry
launcher. Workflow advancement remains under /gsd-progress --next." With that
reassignment the invariant's premise is obsolete and the guard now contradicts
the documented command form, so it is retired with a comment recording why
rather than deleted silently.

next is now swept like every other command, and the earlier exemption added to
the new guard is removed so nothing is special-cased.

Four citations of the literal name: frontmatter key stay in colon form, because
the source file really does carry name: gsd:next and a doc quoting it must
reproduce it verbatim. Two of those lines were reworded to say which side is the
frontmatter key and which is the slash command, since they previously conflated
the two.

Verified the retired scan would now genuinely fail against this tree -- the
conflict was real and resolved, not dodged.

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

* chore(#2903): backfill changeset pr number

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

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 13:23:44 -04:00

293 lines
9.7 KiB
Markdown
Raw Blame History

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