Revise os artefatos de planejamento existentes de um change e mantenha-os coerentes. Nunca edite código.
Seleção de store: Se o usuário nomear uma store (uma store é um repositório OpenSpec independente registrado nesta máquina) ou o trabalho estiver em uma, execute openspec store list --json para descobrir os IDs de store registrados e, em seguida, passe --store <id> nos comandos que leem ou escrevem specs e changes (new change, status, instructions, list, show, validate, archive, doctor, context). Outros comandos não aceitam a flag. Dicas impressas pelos comandos já trazem a flag; mantenha-a nos acompanhamentos. Sem uma store, os comandos atuam na raiz local openspec/ mais próxima.
Entrada: Opcionalmente, especifique um nome de change. Se omitido, verifique se pode ser inferido a partir do contexto da conversa. Se vago ou ambíguo, você DEVE perguntar pelos changes disponíveis.
Passos
-
Se nenhum nome de change for fornecido, pergunte pela seleção
Execute
openspec list --jsonpara obter os changes disponíveis ordenados pelo mais recentemente modificado. Em seguida, use a ferramenta AskUserQuestion para permitir que o usuário selecione qual change atualizar.Apresente os 3-4 changes mais recentemente modificados como opções, mostrando:
- Nome do change
- Schema (do campo
schemase presente, senão "spec-driven") - Status (ex.: "0/5 tarefas", "completo", "sem tarefas")
- Há quanto tempo foi modificado (do campo
lastModified)
Marque o change mais recentemente modificado como "(Recomendado)", já que é provavelmente o que o usuário deseja atualizar.
IMPORTANTE: NÃO adivinhe ou selecione automaticamente um change. Sempre deixe o usuário escolher.
-
Obtenha os artefatos do change
openspec status --change "<nome>" --jsonAnalise o JSON para entender o estado atual. A resposta inclui:
schemaName: O schema de workflow sendo usado (ex.: "spec-driven")artifacts: Array de artefatos com seu status ("done", "ready", "blocked")isComplete: Booleano indicando se todos os artefatos estão completosplanningHome,changeRoot,artifactPathseactionContext: contexto de caminho e escopo. Use estes em vez de assumir caminhos locais do repositório.
Os IDs e caminhos dos artefatos vêm do schema ativo — não os assuma e não crie ramificações com base em nomes de artefatos hardcoded. Schemas personalizados devem funcionar sem alterações.
Os arquivos a editar são
artifactPaths.<id>.existingOutputPaths— os arquivos concretos que existem em disco, já expandidos para artefatos glob (ex.:specs/**/*.md). NÃO escreva emresolvedOutputPath: para um artefato glob ele ainda é o padrão glob, não um arquivo real. -
Entenda a solicitação
- Se o usuário pediu uma revisão específica ("o design agora usa X"), essa é a edição inicial.
- Se ele apenas disse "atualizar" / "tornar isso coerente", trate como uma revisão de coerência: leia os artefatos existentes e verifique-os entre si em busca de contradições, lacunas e duplicações.
-
Leia e reconcilie
- Leia o(s) artefato(s) que a solicitação toca e os outros artefatos existentes do change.
- Aplique a edição solicitada. Em seguida, verifique cada outro artefato existente em relação a ela — em QUALQUER direção: uma edição em um artefato posterior pode exigir a revisão de um anterior, e não apenas o contrário. A ordem de construção é uma ordem de leitura útil, não uma restrição sobre quais artefatos podem ser revisados.
- Anote tudo que agora está inconsistente, ausente ou contraditório.
- Revise apenas arquivos que já existem (
existingOutputPaths). NÃO crie artefatos que ainda não existem e NÃO invente novos arquivos em um artefato glob — anote-os e aponte o usuário para/opsx:continuepara criá-los. - Se o change já estiver coerente, diga isso e não faça edições.
-
Confirme e aplique, um artefato de cada vez
- Mostre cada revisão proposta e o motivo. Escreva apenas após a confirmação do usuário.
- Se o usuário rejeitar uma revisão, não a escreva — deixe aquele artefato inalterado.
- Quando uma reescrita substancial for necessária, obtenha primeiro as regras e o template daquele artefato:
openspec instructions <artifact-id> --change "<nome>" --json
-
Aponte para o próximo passo (orientação apenas — NUNCA aja sobre ele)
- Artefatos ainda ausentes -> sugira
/opsx:continuepara criá-los. - Change já implementado (tarefas marcadas / já aplicado) -> o código pode não corresponder mais ao plano revisado; sugira
/opsx:applypara levar a diferença ao código. - Tudo feito e implementado -> sugira
/opsx:archive.
- Artefatos ainda ausentes -> sugira
Saída
Após cada invocação, mostre:
- Quais artefatos foram revisados (e quais revisões propostas foram rejeitadas)
- Qualquer coisa adiada para
/opsx:continue(artefatos ou arquivos ainda não criados) - Onde o change se encontra e o próximo comando recomendado
Guardrails
- Apenas artefatos de planejamento — NUNCA edite código de implementação. Se o plano revisado implicar alterações de código, pare e aponte para
/opsx:apply. - Use os IDs e caminhos de artefatos relatados por
openspec status; nunca crie ramificações com base em nomes de artefatos hardcoded. - Edite apenas os arquivos concretos em
existingOutputPaths; nunca escreva em umresolvedOutputPathglob. - Não avance a fronteira de construção: nenhum novo artefato, nenhum novo arquivo em artefatos glob — essa é a função de
/opsx:continue. - Confirme cada edição com o usuário antes de escrever.
- Se a solicitação mudar a intenção do change em vez de refiná-la, recomende começar do zero com
/opsx:new(a heurística "Atualizar vs. Começar do Zero").