OpenSpec

Instalação ​

Pré-requisitos ​

  • Node.js 20.19.0 ou superior — Verifique sua versão: node --version

Instale com seu assistente de IA ​

Prefere não fazer isso manualmente? Cole o prompt abaixo em qualquer assistente de codificação que possa executar comandos de shell — Claude Code, Codex, Cursor, Gemini CLI, Copilot e o restante das ferramentas suportadas. Ele instala a CLI, inicializa este projeto e informa o que realmente aconteceu.

As etapas manuais abaixo são a fonte da verdade — o prompt apenas as executa para você. Se seu assistente parar e devolver algo, isso é proposital: ele pergunta antes de qualquer ação privilegiada e nunca edita seus arquivos de inicialização do shell. Termine essas partes você mesmo com Gerenciadores de Pacotes e Solução de Problemas.

text
Instale o OpenSpec neste projeto e configure-o para mim. Siga estas etapas em
ordem e pare onde uma etapa mandar parar.

1. RUNTIME. Execute `node --version`. O OpenSpec precisa do Node.js 20.19.0 ou
   superior. Se o Node estiver ausente ou for mais antigo, diga isso e pare —
   não instale o Node, mude de versão ou reconfigure meu gerenciador de versão
   por mim.

2. INSTALL. Use o gerenciador de pacotes que já está no meu PATH, preferindo npm:
     npm install -g @fission-ai/openspec@latest
     pnpm add -g @fission-ai/openspec@latest
     bun add -g @fission-ai/openspec@latest
     yarn global add @fission-ai/openspec@latest   (somente Yarn 1.x)
   Não escolha com base no lockfile deste projeto — uma instalação global não
   tem nada a ver com a forma como as dependências deste repositório são
   instaladas. Se nenhum desses quatro estiver disponível, pare e me avise —
   não improvise uma instalação. (Se eu estiver usando Nix, aponte-me para a
   seção Nix da documentação de instalação do OpenSpec.)
   Mostre-me o comando exato e deixe-me confirmar antes de executá-lo; isso
   instala software fora do projeto, e posso querer que um gerenciador de
   pacotes diferente seja o responsável.
   Pare e me pergunte novamente se a instalação precisar de sudo ou direitos de
   administrador, falhar com erro de permissão ou informar que o diretório bin
   global está ausente ou não configurado. Nunca edite meus arquivos de
   inicialização do shell (.bashrc, .zshrc, .profile, fish, perfil do
   PowerShell) e nunca execute um comando de configuração que os edite para mim
   — mostre-me a alteração e deixe-me fazê-la.

3. PATH. Execute `openspec --version`. Se o comando não for encontrado, pode
   ser apenas que esteja faltando neste shell: diga-me onde o gerenciador de
   pacotes o instalou e como adicionar esse diretório ao PATH para o meu shell
   e sistema operacional, então pare até eu confirmar. Se ele imprimir uma
   versão mais antiga do que a que a instalação acabou de relatar, uma cópia
   anterior está o ocultando no PATH — diga-me ambas as versões em vez de
   continuar. Se eu usar um gerenciador de versões, diga isso em vez de editar
   o PATH ao redor dele: com nvm ou fnm, a CLI está vinculada à versão do Node
   que estava ativa quando você a instalou, e com asdf ou volta, um shim pode
   precisar ser regenerado.

4. INITIALIZE. Pergunte-me qual ferramenta ou ferramentas de codificação de IA
   eu uso e mapeie cada uma para um id de `openspec init --help` (Copilot é
   `github-copilot`, Zoo Code é `roocode`). `--tools` aceita uma lista separada
   por vírgulas, então nomeie todas. `openspec init --tools <ids>` exclui
   automaticamente sobras de versões anteriores do OpenSpec, sem perguntar —
   incluindo arquivos de prompt `opsx-*.md` no meu diretório inicial (o Codex
   os mantém em ~/.codex/prompts). Antes de executá-lo, procure por eles:
   pastas `.../commands/openspec/`, blocos de marcação do OpenSpec em arquivos
   como CLAUDE.md ou AGENTS.md, e prompts `opsx-*.md` no diretório inicial.
   Liste o que encontrar e aguarde meu sinal; se não encontrar nada, diga isso
   e continue sem perguntar. Uma pasta `openspec/` existente não é um problema
   — o init a atualiza e deixa minhas especificações e alterações em paz.
   Confirme também que estou na pasta certa: o init cria `openspec/` onde quer
   que seja executado, inclusive dentro de um pacote monorepo.
   Então execute: openspec init --tools <ids>

5. REPORT. Não presuma o que deve existir — diga-me o que o init realmente
   imprimiu: quantas skills e/ou comandos ele criou e onde, a linha do arquivo
   de configuração, qualquer nota "Setup required" e o que reiniciar ou
   recarregar. Algumas ferramentas são apenas de skills e corretamente criam
   zero arquivos de comando, então comandos ausentes não são uma falha por si
   só. Se o init disse que nada foi gerado, repasse a correção que ele sugeriu
   em vez de tentar novamente. Termine dizendo-me como invocar o OpenSpec na
   minha ferramenta e use a grafia exata dos arquivos que o init criou, e não
   da linha de resumo: a pontuação varia por ferramenta (/opsx:propose em
   algumas, /opsx-propose em outras, @opsx-propose no Amazon Q), e ferramentas
   que recebem skills em vez de comandos são invocadas pelo nome da skill
   (/openspec-propose, ou $openspec-propose no Codex, ou /skill:openspec-propose
   no Kimi Code).

Nada no prompt é específico de fornecedor: são instruções simples mais os mesmos comandos documentados nesta página. Funciona em macOS, Linux e Windows, e deliberadamente para em vez de improvisar quando uma etapa precisa da sua permissão. Seu assistente precisa ser capaz de executar comandos de shell — algumas integrações de IDE não conseguem.

Gerenciadores de Pacotes ​

npm ​

bash
npm install -g @fission-ai/openspec@latest

pnpm ​

bash
pnpm add -g @fission-ai/openspec@latest

yarn ​

bash
yarn global add @fission-ai/openspec@latest

Yarn 2 e posteriores (Berry) removeram o comando global. Nessas versões, instale o OpenSpec com npm, pnpm ou bun — uma CLI global não precisa compartilhar o gerenciador de pacotes do seu projeto.

deno ​

O Deno às vezes tem problemas para interpretar a tag @latest, mas podemos especificar uma versão ao instalar inicialmente. Se isso acontecer, você pode tentar trocar a tag @latest pela versão, algo como @^1.3.1

bash
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@latest
# ou
deno install --global \
  --allow-read --allow-write --allow-env --allow-sys=cpus,homedir --allow-net=edge.openspec.dev \
  npm:@fission-ai/openspec@^1.3.1

Nota: Se seus subcomandos iniciarem ferramentas externas, como edição de configuração, feedback ou abertura de workspace, você pode precisar de um --allow-run=<programa> com escopo.

bun ​

O Bun pode instalar o OpenSpec globalmente, mas o OpenSpec atualmente roda no Node.js. Você ainda precisa do Node.js 20.19.0 ou superior disponível no PATH.

bash
bun add -g @fission-ai/openspec@latest

Nix ​

Execute o OpenSpec diretamente sem instalação:

bash
nix run github:Fission-AI/OpenSpec -- init

Ou instale no seu perfil:

bash
nix profile install github:Fission-AI/OpenSpec

Ou adicione ao seu ambiente de desenvolvimento no flake.nix:

nix
{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    openspec.url = "github:Fission-AI/OpenSpec";
  };

  outputs = { nixpkgs, openspec, ... }: {
    devShells.x86_64-linux.default = nixpkgs.legacyPackages.x86_64-linux.mkShell {
      buildInputs = [ openspec.packages.x86_64-linux.default ];
    };
  };
}

Verificar Instalação ​

bash
openspec --version

Atualização ​

Atualize o pacote e, em seguida, reescreva os arquivos gerados de cada projeto:

bash
npm install -g @fission-ai/openspec@latest   # ou equivalente pnpm/yarn/bun
openspec update                              # execute dentro de cada projeto

openspec update regenera os arquivos de skill e comando para as ferramentas que você configurou, para que seus comandos de barra fiquem atualizados com a versão instalada. Ele também verifica se uma versão mais nova da CLI foi publicada e oferece a atualização, já que atualizar é o que torna novos fluxos de trabalho disponíveis em primeiro lugar — consulte Referência da CLI.

Desinstalação ​

Não existe comando openspec uninstall, porque o OpenSpec é apenas um pacote global mais alguns arquivos no seu projeto. Removê-lo são algumas etapas manuais, e nada aqui toca seu código-fonte.

1. Remova o pacote global:

bash
npm uninstall -g @fission-ai/openspec   # ou: pnpm rm -g / yarn global remove / bun rm -g

2. Remova o OpenSpec de um projeto (opcional). Exclua o diretório openspec/ se você não quiser mais suas especificações e alterações:

bash
rm -rf openspec/

Pense antes de fazer isso: openspec/specs/ e openspec/changes/archive/ são seu registro de como o sistema se comporta e por que mudou. Se você pode querer esse histórico, mantenha a pasta (ou mantenha-a no git) mesmo após desinstalar.

3. Remova os arquivos gerados de ferramentas de IA (opcional). O OpenSpec grava arquivos de skill e comando em diretórios por ferramenta, como .claude/skills/openspec-*/, .cursor/commands/opsx-*, e assim por diante. Exclua as skills openspec-* e os comandos opsx-* para as ferramentas que você configurou. Os caminhos exatos por ferramenta estão listados em Ferramentas Suportadas.

Se você também tiver blocos de marcação do OpenSpec em arquivos como CLAUDE.md ou AGENTS.md, remova esses blocos manualmente; seu próprio conteúdo nesses arquivos é seu para manter.

Próximos Passos ​

Após instalar, inicialize o OpenSpec no seu projeto:

bash
cd seu-projeto
openspec init

Consulte Começando para um guia completo.