Migração para o OPSX

Este guia ajuda você a fazer a transição do fluxo de trabalho legado do OpenSpec para o OPSX. A migração foi projetada para ser tranquila — seu trabalho existente é preservado e o novo sistema oferece mais flexibilidade.

O que está mudando?

O OPSX substitui o antigo fluxo de trabalho bloqueado por fases por uma abordagem fluida e baseada em ações. Aqui está a mudança principal:

Aspecto	Legado	OPSX
Comandos	`/openspec:proposal`, `/openspec:apply`, `/openspec:archive`	Padrão: `/opsx:propose`, `/opsx:explore`, `/opsx:apply`, `/opsx:update`, `/opsx:sync`, `/opsx:archive` (comandos de fluxo de trabalho expandidos opcionais)
Fluxo de trabalho	Criar todos os artefatos de uma vez	Criar incrementalmente ou tudo de uma vez — você escolhe
Voltar atrás	Portões de fase desconfortáveis	Natural — atualize qualquer artefato a qualquer momento
Personalização	Estrutura fixa	Orientado por esquema, totalmente personalizável
Configuração	`CLAUDE.md` com marcadores + `project.md`	Configuração limpa em `openspec/config.yaml`

A mudança de filosofia: O trabalho não é linear. O OPSX para de fingir que é.

Antes de Começar

Seu Trabalho Existente Está Seguro

O processo de migração foi projetado com preservação em mente:

Alterações ativas em openspec/changes/ — Completamente preservadas. Você pode continuar com os comandos OPSX.
Alterações arquivadas — Intocadas. Seu histórico permanece intacto.
Especificações principais em openspec/specs/ — Intocadas. Estas são sua fonte de verdade.
Seu conteúdo em CLAUDE.md, AGENTS.md, etc. — Preservado. Apenas os blocos de marcadores do OpenSpec são removidos; tudo o que você escreveu permanece.

O Que Será Removido

Apenas arquivos gerenciados pelo OpenSpec que estão sendo substituídos:

O Que	Por Que
Diretórios/arquivos de comandos slash legados	Substituídos pelo novo sistema de skills
`openspec/AGENTS.md`	Gatilho de fluxo de trabalho obsoleto
Marcadores do OpenSpec em `CLAUDE.md`, `AGENTS.md`, etc.	Não são mais necessários

Localizações de comandos legados por ferramenta (exemplos — sua ferramenta pode variar):

Claude Code: .claude/commands/openspec/
Cursor: .cursor/commands/openspec-*.md
Devin Desktop, anteriormente Windsurf: .windsurf/workflows/openspec-*.md
Cline: .clinerules/workflows/openspec-*.md
Roo: .roo/commands/openspec-*.md
GitHub Copilot: .github/prompts/openspec-*.prompt.md (apenas extensões de IDE; não suportado no Copilot CLI)
Codex: O OpenSpec agora usa o caminho canônico .agents/skills/openspec-*. Arquivos SKILL.md gerenciados pelo OpenSpec sob o antigo caminho .codex/skills são reconciliados apenas após a existência de substitutos; arquivos personalizados e cópias divergentes permanecem no lugar. Se uma árvore .agents sem marcação já contém skills do OpenSpec, o OpenSpec preserva sua renderização existente do Codex ($openspec-*) ou genérica (/openspec-*) em vez de supor a partir do diretório legado. Selecione codex explicitamente com openspec init para alternar a propriedade. A limpeza de prompts legados ainda visa apenas os nomes de arquivos permitidos pelo OpenSpec em $CODEX_HOME/prompts ou ~/.codex/prompts.
E outros (Augment, Continue, Amazon Q, etc.)

A migração detecta quais ferramentas você tem configuradas e limpa seus arquivos legados.

A lista de remoções pode parecer longa, mas todos estes são arquivos que o OpenSpec originalmente criou. Seu próprio conteúdo nunca é excluído.

O Que Requer Sua Atenção

Um arquivo requer migração manual:

openspec/project.md — Este arquivo não é excluído automaticamente porque pode conter contexto de projeto que você escreveu. Você precisará:

Revisar seu conteúdo
Mover o contexto útil para openspec/config.yaml (veja as orientações abaixo)
Excluir o arquivo quando estiver pronto

Por que fizemos esta mudança:

O antigo project.md era passivo — agentes poderiam lê-lo, poderiam não ler, poderiam esquecer o que leram. Descobrimos que a confiabilidade era inconsistente.

O novo contexto em config.yaml é ativamente injetado em cada solicitação de planejamento do OpenSpec. Isso significa que suas convenções de projeto, stack tecnológica e regras estão sempre presentes quando a IA cria artefatos. Maior confiabilidade.

A compensação:

Como o contexto é injetado em cada solicitação, você quererá ser conciso. Foque no que realmente importa:

Stack tecnológica e convenções principais
Restrições não óbvias que a IA precisa conhecer
Regras que frequentemente eram ignoradas antes

Não se preocupe em acertar de primeira. Ainda estamos aprendendo o que funciona melhor aqui, e estaremos melhorando como a injeção de contexto funciona conforme experimentamos.

Executando a Migração

Tanto openspec init quanto openspec update detectam arquivos legados e o guiam pelo mesmo processo de limpeza. Use o que se adequar à sua situação:

Instalações novas usam o perfil core por padrão (propose, explore, apply, update, sync, archive).
Instalações migradas preservam seus fluxos de trabalho anteriormente instalados escrevendo um perfil custom quando necessário.

Usando `openspec init`

Execute isto se você deseja adicionar novas ferramentas ou reconfigurar quais ferramentas estão configuradas:

bash

openspec init

O comando init detecta arquivos legados e o guia pela limpeza:

Upgrading to the new OpenSpec

OpenSpec now uses agent skills, the emerging standard across coding
agents. This simplifies your setup while keeping everything working
as before.

Files to remove
No user content to preserve:
  • .claude/commands/openspec/
  • openspec/AGENTS.md

Files to update
OpenSpec markers will be removed, your content preserved:
  • CLAUDE.md
  • AGENTS.md

Needs your attention
  • openspec/project.md
    We won't delete this file. It may contain useful project context.

    The new openspec/config.yaml has a "context:" section for planning
    context. This is included in every OpenSpec request and works more
    reliably than the old project.md approach.

    Review project.md, move any useful content to config.yaml's context
    section, then delete the file when ready.

? Upgrade and clean up legacy files? (Y/n)

O que acontece quando você diz sim:

Diretórios de comandos slash legados são removidos
Marcadores do OpenSpec são removidos de CLAUDE.md, AGENTS.md, etc. (seu conteúdo permanece)
openspec/AGENTS.md é excluído
Novas skills são instaladas em .claude/skills/
openspec/config.yaml é criado com um esquema padrão

Usando `openspec update`

Execute isto se você apenas deseja migrar e atualizar suas ferramentas existentes para a versão mais recente:

bash

openspec update

O comando update também detecta e limpa artefatos legados, e então atualiza skills/comandos gerados para corresponder ao seu perfil e configurações de entrega atuais.

Ambientes Não-Interativos / CI

Para migrações por script:

bash

openspec init --force --tools claude

A flag --force ignora prompts e aceita a limpeza automaticamente.

Isso inclui a limpeza de arquivos de prompt do Codex gerenciados pelo OpenSpec no diretório global de prompts do Codex. A limpeza visa apenas os nomes de arquivos legados permitidos pelo OpenSpec, remove-os apenas após a existência de skills substitutas em .agents/skills/openspec-*, e preserva todos os outros arquivos.

Migrando project.md para config.yaml

O antigo openspec/project.md era um arquivo markdown livre para contexto de projeto. O novo openspec/config.yaml é estruturado e — criticamente — injetado em cada solicitação de planejamento para que suas convenções estejam sempre presentes quando a IA trabalha.

Antes (project.md)

markdown

# Project Context

This is a TypeScript monorepo using React and Node.js.
We use Jest for testing and follow strict ESLint rules.
Our API is RESTful and documented in docs/api.md.

## Conventions

- All public APIs must maintain backwards compatibility
- New features should include tests
- Use Given/When/Then format for specifications

Depois (config.yaml)

yaml

schema: spec-driven

context: |
  Tech stack: TypeScript, React, Node.js
  Testing: Jest with React Testing Library
  API: RESTful, documented in docs/api.md
  We maintain backwards compatibility for all public APIs

rules:
  proposal:
    - Include rollback plan for risky changes
  specs:
    - Use Given/When/Then format for scenarios
    - Reference existing patterns before inventing new ones
  design:
    - Include sequence diagrams for complex flows

Diferenças Principais

project.md	config.yaml
Markdown livre	YAML estruturado
Um bloco de texto	Contexto separado e regras por artefato
Desconhecido quando é usado	Contexto aparece em TODOS os artefatos; regras aparecem apenas nos artefatos correspondentes
Sem seleção de esquema	Campo `schema:` explícito define o fluxo de trabalho padrão

O Que Manter, O Que Descartar

Ao migrar, seja seletivo. Pergunte-se: "A IA precisa disto para cada solicitação de planejamento?"

Boas candidatas para context:

Stack tecnológica (linguagens, frameworks, bancos de dados)
Padrões arquiteturais principais (monorepo, microsserviços, etc.)
Restrições não óbvias ("não podemos usar a biblioteca X porque...")
Convenções críticas que frequentemente são ignoradas

Mover para rules: em vez disso

Formatação específica de artefato ("use Given/When/Then em specs")
Critérios de revisão ("propostas devem incluir planos de rollback")
Estas aparecem apenas para o artefato correspondente, mantendo outras solicitações mais leves

Deixar de fora completamente

Boas práticas gerais que a IA já conhece
Explicações verbosas que poderiam ser resumidas
Contexto histórico que não afeta o trabalho atual

Etapas de Migração

Criar config.yaml (se ainda não criado pelo init):
yaml
```
schema: spec-driven
```

Adicionar seu contexto (seja conciso — isto vai em cada solicitação):

yaml

context: |
  Seu contexto de projeto vai aqui.
  Foque no que a IA genuinamente precisa saber.

Adicionar regras por artefato (opcional):

yaml

rules:
  proposal:
    - Sua orientação específica para propostas
  specs:
    - Suas regras de escrita de especificações

Excluir project.md depois de mover tudo o que for útil.

Não pense demais. Comece com o essencial e itere. Se você notar que a IA está perdendo algo importante, adicione. Se o contexto parecer inchado, reduza. Este é um documento vivo.

Precisa de Ajuda? Use Este Prompt

Se você não tem certeza de como destilar seu project.md, pergunte ao seu assistente de IA:

I'm migrating from OpenSpec's old project.md to the new config.yaml format.

Here's my current project.md:
[paste your project.md content]

Please help me create a config.yaml with:
1. A concise `context:` section (this gets injected into every planning request, so keep it tight—focus on tech stack, key constraints, and conventions that often get ignored)
2. `rules:` for specific artifacts if any content is artifact-specific (e.g., "use Given/When/Then" belongs in specs rules, not global context)

Leave out anything generic that AI models already know. Be ruthless about brevity.

A IA ajudará você a identificar o que é essencial versus o que pode ser reduzido.

Os Novos Comandos

A disponibilidade de comandos depende do perfil:

Padrão (perfil core):

Comando	Propósito
`/opsx:propose`	Criar uma alteração e gerar artefatos de planejamento em uma etapa
`/opsx:explore`	Pensar ideias sem estrutura
`/opsx:apply`	Implementar tarefas do tasks.md
`/opsx:update`	Revisar artefatos de planejamento de uma alteração e mantê-los coerentes
`/opsx:sync`	Mesclar especificações delta nas especificações principais
`/opsx:archive`	Finalizar e arquivar a alteração

Fluxo de trabalho expandido (seleção personalizada):

Comando	Propósito
`/opsx:new`	Iniciar um novo esqueleto de alteração
`/opsx:continue`	Criar o próximo artefato (um de cada vez)
`/opsx:ff`	Avanço rápido — criar artefatos de planejamento de uma vez
`/opsx:verify`	Validar que a implementação corresponde às especificações
`/opsx:bulk-archive`	Arquivar múltiplas alterações de uma vez
`/opsx:onboard`	Fluxo de trabalho de onboarding guiado de ponta a ponta

Ative os comandos expandidos com openspec config profile, e então execute openspec update.

Mapeamento de Comandos Legados

Legado	Equivalente OPSX
`/openspec:proposal`	`/opsx:propose` (padrão) ou `/opsx:new` seguido de `/opsx:ff` (expandido)
`/openspec:apply`	`/opsx:apply`
`/openspec:archive`	`/opsx:archive`

Novas Capacidades

Estas capacidades fazem parte do conjunto de comandos do fluxo de trabalho expandido.

Criação granular de artefatos:

/opsx:continue

Cria um artefato de cada vez com base em dependências. Use isto quando você quiser revisar cada etapa.

Modo de exploração:

/opsx:explore

Pense ideias com um parceiro antes de se comprometer com uma alteração.

Compreendendo a Nova Arquitetura

De Fases Bloqueadas a Fluxo Contínuo

O fluxo de trabalho legado forçava uma progressão linear:

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│   PLANNING   │ ───► │ IMPLEMENTING │ ───► │   ARCHIVING  │
│    PHASE     │      │    PHASE     │      │    PHASE     │
└──────────────┘      └──────────────┘      └──────────────┘

Se você está na implementação e percebe que o design está errado?
Passe. As portas de fase não permitem voltar facilmente.

O OPSX usa ações, não fases:

         ┌───────────────────────────────────────────────┐
         │           ACTIONS (not phases)                │
         │                                               │
         │     new ◄──► continue ◄──► apply ◄──► archive │
         │      │          │           │             │   │
         │      └──────────┴───────────┴─────────────┘   │
         │                    any order                  │
         └───────────────────────────────────────────────┘

Grafo de Dependências

Os artefatos formam um grafo direcionado. As dependências são habilitadores, não bloqueios:

                        proposal
                       (root node)
                            │
              ┌─────────────┴─────────────┐
              │                           │
              ▼                           ▼
           specs                       design
        (requires:                  (requires:
         proposal)                   proposal)
              │                           │
              └─────────────┬─────────────┘
                            │
                            ▼
                         tasks
                     (requires:
                     specs, design)

Quando você executa /opsx:continue, ele verifica o que está pronto e oferece o próximo artefato. Você também pode criar múltiplos artefatos prontos em qualquer ordem.

Skills vs Comandos

O sistema legado usava arquivos de comandos específicos por ferramenta:

.claude/commands/openspec/
├── proposal.md
├── apply.md
└── archive.md

O OPSX usa o padrão emergente de skills:

.claude/skills/
├── openspec-explore/SKILL.md
├── openspec-new-change/SKILL.md
├── openspec-continue-change/SKILL.md
├── openspec-apply-change/SKILL.md
└── ...

Skills são reconhecidas por múltiplas ferramentas de codificação com IA e fornecem metadados mais ricos.

O Codex é exclusivamente baseado em skills no OPSX. O OpenSpec não gera mais arquivos de prompt personalizado para o Codex; use os diretórios gerados .agents/skills/openspec-* em vez disso.

Continuando Alterações Existentes

Suas alterações em andamento funcionam perfeitamente com os comandos do OPSX.

Tem uma alteração ativa do fluxo de trabalho legado?

/opsx:apply add-my-feature

O OPSX lê os artefatos existentes e continua de onde você parou.

Quer adicionar mais artefatos a uma alteração existente?

/opsx:continue add-my-feature

Mostra o que está pronto para criar com base no que já existe.

Precisa ver o status?

bash

openspec status --change add-my-feature

O Novo Sistema de Configuração

Estrutura do config.yaml

yaml

# Obrigatório: Schema padrão para novas alterações
schema: spec-driven

# Opcional: Contexto do projeto (máx. 50KB)
# Injetado em TODAS as instruções de artefatos
context: |
  Background do seu projeto, stack tecnológica,
  convenções e restrições.

# Opcional: Regras por artefato
# Injetado apenas nos artefatos correspondentes
rules:
  proposal:
    - Include rollback plan
  specs:
    - Use Given/When/Then format
  design:
    - Document fallback strategies
  tasks:
    - Break into 2-hour maximum chunks

Resolução de Schema

Ao determinar qual schema usar, o OPSX verifica na seguinte ordem:

Flag de CLI: --schema <name> (maior prioridade)
Metadados da alteração: .openspec.yaml no diretório da alteração
Configuração do projeto: openspec/config.yaml
Padrão: spec-driven

Schemas Disponíveis

Schema	Artefatos	Ideal Para
`spec-driven`	proposal → specs → design → tasks	A maioria dos projetos

Liste todos os schemas disponíveis:

bash

openspec schemas

Schemas Personalizados

Crie seu próprio fluxo de trabalho:

bash

openspec schema init my-workflow

Ou faça um fork de um existente:

bash

openspec schema fork spec-driven my-workflow

Veja Customização para mais detalhes.

Solução de Problemas

"Legacy files detected in non-interactive mode"

Você está executando em um ambiente de CI ou não interativo. Use:

bash

openspec init --force

Comandos não aparecem após a migração

Reinicie seu IDE. Skills são detectadas na inicialização.

"Unknown artifact ID in rules"

Verifique se as chaves do seu rules: correspondem aos IDs de artefatos do seu schema:

spec-driven: proposal, specs, design, tasks

Execute este comando para ver os IDs de artefatos válidos:

bash

openspec schemas --json

Configuração não está sendo aplicada

Certifique-se de que o arquivo está em openspec/config.yaml (não .yml)
Valide a sintaxe do YAML
Alterações na configuração têm efeito imediato — não é necessário reiniciar

project.md não migrado

O sistema preserva intencionalmente o project.md porque ele pode conter conteúdo personalizado. Revise-o manualmente, mova as partes úteis para config.yaml e, em seguida, exclua-o.

Quer ver o que seria limpo?

Execute o init e recuse o prompt de limpeza — você verá o resumo completo de detecção sem que nenhuma alteração seja feita.

Referência Rápida

Arquivos Após a Migração

project/
├── openspec/
│   ├── specs/                    # Inalterado
│   ├── changes/                  # Inalterado
│   │   └── archive/              # Inalterado
│   └── config.yaml               # NOVO: Configuração do projeto
├── .claude/
│   └── skills/                   # NOVO: Skills do OPSX
│       ├── openspec-propose/     # perfil core padrão
│       ├── openspec-explore/
│       ├── openspec-apply-change/
│       ├── openspec-update-change/
│       ├── openspec-sync-specs/
│       ├── openspec-archive-change/
│       └── ...                   # perfil expandido adiciona new/continue/ff/etc.
├── CLAUDE.md                     # Marcadores do OpenSpec removidos, seu conteúdo preservado
└── AGENTS.md                     # Marcadores do OpenSpec removidos, seu conteúdo preservado

O Que Foi Removido

.claude/commands/openspec/ — substituído por .claude/skills/
openspec/AGENTS.md — obsoleto
openspec/project.md — migre para config.yaml e, em seguida, exclua
Blocos de marcadores do OpenSpec em CLAUDE.md, AGENTS.md, etc.

Guia Rápido de Comandos

text

/opsx:propose      Inicie rapidamente (perfil core padrão)
/opsx:apply        Implemente tarefas
/opsx:archive      Finalize e arquive

# Fluxo de trabalho expandido (se habilitado):
/opsx:new          Crie a estrutura de uma alteração
/opsx:continue     Crie o próximo artefato
/opsx:ff           Crie artefatos de planejamento

Obtenção de Ajuda

Discord: discord.gg/YctCnvvshC
GitHub Issues: github.com/Fission-AI/OpenSpec/issues
Documentação: docs/opsx.md para a referência completa do OPSX

Migração para o OPSX ​

O que está mudando? ​

Antes de Começar ​

Seu Trabalho Existente Está Seguro ​

O Que Será Removido ​

O Que Requer Sua Atenção ​

Executando a Migração ​

Usando openspec init ​

Usando openspec update ​

Ambientes Não-Interativos / CI ​

Migrando project.md para config.yaml ​

Antes (project.md) ​

Depois (config.yaml) ​

Diferenças Principais ​

O Que Manter, O Que Descartar ​

Etapas de Migração ​

Precisa de Ajuda? Use Este Prompt ​

Os Novos Comandos ​

Mapeamento de Comandos Legados ​

Novas Capacidades ​

Compreendendo a Nova Arquitetura ​

De Fases Bloqueadas a Fluxo Contínuo ​

Grafo de Dependências ​

Skills vs Comandos ​

Continuando Alterações Existentes ​

O Novo Sistema de Configuração ​

Estrutura do config.yaml ​

Resolução de Schema ​

Schemas Disponíveis ​

Schemas Personalizados ​

Solução de Problemas ​

"Legacy files detected in non-interactive mode" ​

Comandos não aparecem após a migração ​

"Unknown artifact ID in rules" ​

Configuração não está sendo aplicada ​

project.md não migrado ​

Quer ver o que seria limpo? ​

Referência Rápida ​

Arquivos Após a Migração ​

O Que Foi Removido ​

Guia Rápido de Comandos ​

Obtenção de Ajuda ​

Migração para o OPSX

O que está mudando?

Antes de Começar

Seu Trabalho Existente Está Seguro

O Que Será Removido

O Que Requer Sua Atenção

Executando a Migração

Usando `openspec init`

Usando `openspec update`

Ambientes Não-Interativos / CI

Migrando project.md para config.yaml

Antes (project.md)

Depois (config.yaml)

Diferenças Principais

O Que Manter, O Que Descartar

Etapas de Migração

Precisa de Ajuda? Use Este Prompt

Os Novos Comandos

Mapeamento de Comandos Legados

Novas Capacidades

Compreendendo a Nova Arquitetura

De Fases Bloqueadas a Fluxo Contínuo

Grafo de Dependências

Skills vs Comandos

Continuando Alterações Existentes

O Novo Sistema de Configuração

Estrutura do config.yaml

Resolução de Schema

Schemas Disponíveis

Schemas Personalizados

Solução de Problemas

"Legacy files detected in non-interactive mode"

Comandos não aparecem após a migração

"Unknown artifact ID in rules"

Configuração não está sendo aplicada

project.md não migrado

Quer ver o que seria limpo?

Referência Rápida

Arquivos Após a Migração

O Que Foi Removido

Guia Rápido de Comandos

Obtenção de Ajuda