Como Funcionam os Comandos

A única coisa que você precisa saber: o OpenSpec tem dois tipos de comandos, e eles rodam em dois lugares diferentes.

• Os comandos openspec ... rodam no seu terminal. (Exemplo: openspec init.)
• Os comandos /opsx:... rodam no chat do seu assistente de IA. (Exemplo: /opsx:propose.)

Se você digitar /opsx:propose no terminal e nada acontecer, esta página é o motivo. Você está falando com a metade errada do OpenSpec. Comandos de barra não são comandos de terminal. São instruções que você dá ao seu assistente de codificação de IA, na mesma caixa de chat onde você normalmente digitaria "adicione um formulário de login".

Essa distinção é o obstáculo mais comum para novos usuários, então vamos deixá-la bem clara.

As duas metades

OpenSpec é um projeto que usa dois chapéus.

A CLI (metade do terminal). Um programa chamado openspec que você instala e executa no seu shell. Ele configura seu projeto, lista e valida alterações, mostra um painel e arquiva trabalhos concluídos. Você digita isso no iTerm, no terminal do VS Code, no PowerShell, em qualquer lugar onde executaria git ou npm.

openspec init        # set up OpenSpec in this project
openspec list        # see active changes
openspec view        # open the interactive dashboard

Os comandos de barra (metade do chat). Comandos curtos como /opsx:propose e /opsx:apply que você digita no seu assistente de IA. Eles dizem à IA para seguir o fluxo de trabalho do OpenSpec: redigir uma proposta, escrever especificações, construir a partir da lista de tarefas, arquivar quando terminar. Você digita isso no Claude Code, Cursor, Devin Desktop, Copilot ou em qualquer assistente que use.

/opsx:propose add-dark-mode    (typed in your AI chat)
/opsx:apply                    (typed in your AI chat)
/opsx:archive                  (typed in your AI chat)

Aqui está o modelo mental em uma imagem:

        YOUR TERMINAL                         YOUR AI ASSISTANT'S CHAT
   ┌──────────────────────┐               ┌──────────────────────────────┐
   │  $ openspec init     │   installs    │  /opsx:propose add-dark-mode  │
   │  $ openspec list     │  ──────────►  │  /opsx:apply                  │
   │  $ openspec view     │   commands    │  /opsx:archive                │
   └──────────────────────┘    & skills   └──────────────────────────────┘
        run openspec here                       run /opsx:* here

Observe a seta. Executar openspec init no seu terminal é o que instala os comandos de barra na sua ferramenta de IA. A metade do terminal configura a metade do chat. Depois disso, a condução do dia a dia acontece principalmente no chat.

"Como faço para iniciar o modo interativo?"

Não há um modo interativo separado para iniciar. Essa pergunta aparece muito, então merece uma resposta clara.

Você não entra em um modo especial do OpenSpec. Você apenas abre seu assistente de codificação de IA como sempre faz e digita um comando de barra no chat. O comando de barra é como você "entra" no OpenSpec. Seu assistente o reconhece, carrega a habilidade correspondente do OpenSpec e começa a seguir o fluxo de trabalho.

Portanto, as instruções reais são:

1. Abra seu assistente de codificação de IA (Claude Code, Cursor, Devin Desktop, etc.) no seu projeto.
2. Digite /opsx:propose no chat dele, no mesmo lugar onde você digita qualquer outra solicitação.
3. Observe o autocompletar: se o OpenSpec estiver instalado, você verá /opsx:propose, /opsx:apply e outros aparecerem enquanto você digita a barra.

É isso. Nenhum modo para alternar, nenhum daemon para iniciar, nenhuma janela separada.

Uma coisa que é genuinamente interativa vive no terminal: openspec view. Ele abre um painel para navegar por suas especificações e alterações. Mas isso é um visualizador, não é a ferramenta com a qual você propõe e constrói. A construção acontece por meio de comandos de barra no chat.

Por que essa divisão existe

Vale a pena entender, porque explica por que o OpenSpec funciona com mais de 30 ferramentas de IA diferentes.

A CLI é o motor. Ela conhece as regras: como é uma pasta de alteração, quais artefatos dependem de quais, como mesclar uma especificação delta na sua fonte da verdade. É a mesma em todos os lugares.

Os comandos de barra são o volante, e cada ferramenta de IA tem um ligeiramente diferente. O Claude Code os chama de comandos. Cursor e Devin Desktop têm seus próprios formatos. Algumas ferramentas os chamam de habilidades. Quando você executa openspec init, o OpenSpec gera o tipo certo de arquivo para cada ferramenta selecionada, então a mesma intenção /opsx:propose funciona independentemente de qual assistente você prefere.

A força desse design: você aprende o fluxo de trabalho uma vez e o leva entre ferramentas. A compensação: a sintaxe exata de um comando pode diferir ligeiramente entre ferramentas, o que é a próxima seção.

Sintaxe de comandos de barra por ferramenta

A intenção é idêntica em todos os lugares. A grafia segue o arquivo que sua ferramenta carrega.

Arquivo de comando da sua ferramenta	Como você digita	Ferramentas de exemplo
.../commands/opsx/<id>.*	/opsx:propose	Claude Code, Gemini CLI, Crush
.../opsx-<id>.*	/opsx-propose	Cursor, GitHub Copilot (IDE), Devin Desktop, Trae, Oh My Pi
.amazonq/prompts/opsx-<id>.md	@opsx-propose	Amazon Q Developer
nenhum — apenas habilidades	/openspec-propose	CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent, .agents compartilhado
nenhum — Kimi Code	/skill:openspec-propose	Kimi Code
nenhum — CLI do Codex	$openspec-propose	Codex

Devin é a única ferramenta que abrange duas linhas. O Devin Desktop lê .devin/workflows/, então /opsx-propose funciona lá; o Devin Local não, então nesse agente use a habilidade /openspec-propose em vez disso. As habilidades que o OpenSpec escreve em .devin/skills/ funcionam em ambos, por isso referenciam umas às outras pelo nome da habilidade.

Cada ferramenta está listada em Como Invocar — essa tabela é a autoritativa. Duas linhas não são comandos de barra: o Amazon Q carrega seus arquivos em uma biblioteca de prompts invocada com @, e as últimas três linhas usam o nome da habilidade, que não é o id do comando (/opsx:apply é a habilidade openspec-apply-change).

Em caso de dúvida, leia a linha "Introdução" que openspec init imprimiu: ela já usa o formato que suas ferramentas registraram. Digitar uma barra e observar o autocompletar também funciona, para as ferramentas que exibem comandos de barra.

Como os comandos chegaram lá: habilidades e comandos

Quando você executa openspec init (ou openspec update), o OpenSpec grava pequenos arquivos no seu projeto para que sua ferramenta de IA possa encontrar o fluxo de trabalho. Dependendo da sua ferramenta e configurações, esses arquivos são habilidades, comandos ou ambos.

• Habilidades ficam em lugares como .claude/skills/openspec-*/SKILL.md. Elas são o padrão emergente entre ferramentas: uma pasta de instruções que seu assistente detecta automaticamente.
• Comandos ficam em lugares como .cursor/commands/opsx-<id>.md ou .claude/commands/opsx/<id>.md — o layout é da ferramenta, e ela decide como você digita o comando. Eles são os arquivos de comando de barra mais antigos, específicos de cada ferramenta. O Codex não recebe arquivos de comando gerados; use .agents/skills/openspec-*.

Você não precisa se preocupar com qual a sua ferramenta usa. Você apenas digita o comando de barra e funciona. Mas saber que esses arquivos existem ajuda quando algo dá errado: se seus comandos desaparecem, geralmente significa que esses arquivos estão ausentes ou desatualizados, e openspec update os regenera.

Consulte Ferramentas Suportadas para os caminhos exatos por ferramenta, e Guia de Migração para saber como as habilidades substituíram a abordagem antiga baseada apenas em comandos.

Confirmando que está instalado

Verificações rápidas, da mais rápida primeiro:

1. Digite uma barra no seu chat de IA. Comece a digitar /opsx e observe as sugestões de autocompletar. Se elas aparecerem, você está pronto. Em uma ferramenta apenas de habilidades (Codex, Kimi Code, CodeArts, ForgeCode, Hermes, Mistral Vibe, Zed Agent ou o alvo compartilhado .agents) /opsx nunca completa mesmo em uma instalação saudável — tente o nome da habilidade da tabela acima.
2. Procure pelos arquivos. Para o Claude Code, verifique se .claude/skills/ contém pastas openspec-*. Outras ferramentas usam seus próprios diretórios (Ferramentas Suportadas os lista).
3. Execute a configuração novamente. A partir da raiz do seu projeto, execute openspec update. Isso regenera os arquivos de habilidade e comando para as ferramentas que você configurou.
4. Reinicie seu assistente. Muitas ferramentas verificam habilidades e comandos na inicialização, então uma nova janela pode ser o passo que falta.

Quais comandos eu tenho, afinal?

Por padrão, o OpenSpec instala o conjunto principal de comandos de barra:

• /opsx:explore: pense em uma ideia com a IA antes de se comprometer com uma alteração (ótimo primeiro passo quando você não tem certeza)
• /opsx:propose: crie uma alteração e redija todos os seus artefatos de planejamento em uma única etapa
• /opsx:apply: construa a alteração trabalhando na sua lista de tarefas
• /opsx:update: revise os artefatos de planejamento de uma alteração e mantenha-os coerentes
• /opsx:sync: mescle as atualizações de especificação de uma alteração nas suas especificações principais (geralmente automático)
• /opsx:archive: finalize uma alteração e arquive-a

Um bom ritmo padrão: explore quando você está decidindo o que fazer, depois propose, apply, archive. O guia Explore Primeiro explica por que esse passo inicial compensa.

Há também um conjunto expandido para pessoas que querem mais controle (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify, /opsx:bulk-archive, /opsx:onboard). Você o ativa com openspec config profile e depois o aplica com openspec update.

Novo nisso tudo? O /opsx:onboard (no conjunto expandido) guia você por uma alteração completa no seu próprio código, narrando cada passo. É a introdução mais amigável possível.

Para detalhes sobre o que cada comando faz, consulte Comandos. Para saber quando usar cada um, consulte Fluxos de Trabalho.

Uma primeira execução limpa

Juntando tudo, aqui está a sequência completa com cada etapa rotulada por onde ela acontece.

TERMINAL   $ npm install -g @fission-ai/openspec@latest
TERMINAL   $ cd your-project
TERMINAL   $ openspec init
              (installs slash commands into your AI tool)

AI CHAT      /opsx:explore
              (optional: think the idea through with the AI first)

AI CHAT      /opsx:propose add-dark-mode
              (AI drafts proposal, specs, design, tasks)

AI CHAT      /opsx:apply
              (AI builds it, checking off tasks)

AI CHAT      /opsx:archive
              (change is merged into your specs and filed away)

Duas etapas no terminal para configurar. Depois, você vive no chat. Esse é o ritmo.

Relacionados

• Introdução: o passo a passo completo da primeira alteração
• Comandos: todos os comandos de barra em detalhes
• CLI: todos os comandos de terminal em detalhes
• Ferramentas Suportadas: sintaxe e locais de arquivos por ferramenta
• FAQ: mais respostas rápidas
• Solução de Problemas: correções quando os comandos não aparecem