robsonprod/portfolio

Implementa tarefas de uma mudança (change) do OpenSpec.

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, depois passe --store <id> nos comandos que leem ou escrevem specs e changes (new change, status, instructions, list, show, validate, archive, doctor, context, schemas, view). Uma vez selecionada, trate --store <id> como fixo para o resto do fluxo de trabalho. Cada exemplo sem escopo desses comandos abaixo é uma abreviação: antes de executá-lo, adicione a flag. Por exemplo, execute openspec status --change "<nome>" --json --store "<id>", não a forma sem escopo mostrada abaixo. Outros comandos não aceitam a flag. As dicas impressas pelos comandos já carregam a flag; mantenha-a em acompanhamentos. Sem uma store, os comandos atuam na raiz openspec/ local mais próxima.

Verificação do projeto: Estas etapas esperam um projeto que já usa OpenSpec. Antes da primeira etapa que escreve algo (new change, archive, sync specs ou criação de um arquivo de artefato), confirme que o projeto tem uma raiz: execute openspec list --json (com --store <id> quando uma store estiver selecionada, pois a store é então a raiz) e leia root. Um objeto root significa que o projeto está configurado. "root": null significa que não está - não há um diretório openspec/ aqui, e uma escrita como openspec new change criaria um como efeito colateral. O comando também sai com código não zero, que é essa resposta em vez de uma CLI quebrada, então leia o JSON em vez de tentar novamente ou contornar o problema.

Um caso de "root": null não é sobre configuração: quando uma mensagem de erro status começa com Declared in ou Invalid store declaration in e nomeia o openspec/config.yaml (ou config.yml) deste projeto, o projeto usa OpenSpec através de uma store que ele declara, a qual esta máquina não consegue resolver (a store não está registrada, ou a linha store: está malformada). Não trate como não inicializado e pule as ramificações abaixo: pare antes de escrever e mostre ao usuário a message e o fix desse erro.

Caso contrário, sem raiz, o que acontece a seguir depende de como este fluxo de trabalho foi alcançado:

• Selecionado automaticamente: você escolheu este fluxo de trabalho por conta própria, sem o usuário nomear OpenSpec, nomear este skill ou executar seu comando de barra. Pare de usar OpenSpec e responda à solicitação normalmente, como faria sem OpenSpec instalado. Não peça para configurar nada e não mencione a configuração do OpenSpec.
• Solicitação explícita do OpenSpec: o usuário nomeou OpenSpec, nomeou este skill ou executou seu comando de barra. Pare antes de escrever e pergunte como proceder: configurar este projeto (openspec init), direcionar uma store que já possuem (--store <id>) ou continuar sem o OpenSpec para esta solicitação. Aguarde a resposta.

Em ambas as ramificações, nunca crie a raiz como efeito colateral: não execute openspec init até que o usuário peça, não crie manualmente arquivos openspec/ e não deixe um comando criá-la.

Entrada: Opcionalmente, especifique um nome de change (ex.: /opsx:apply add-auth). Se omitido, verifique se pode ser inferido do contexto da conversa. Se vago ou ambíguo, você DEVE solicitar as mudanças disponíveis.

Passos

1. Selecione a change

   Se um nome for fornecido, use-o. Caso contrário:

   • Inferir do contexto da conversa se o usuário mencionou uma change
   • Auto-selecionar se apenas uma change ativa existir
   • Se ambíguo, execute openspec list --json para obter as changes disponíveis e peça ao usuário para selecionar uma

   Sempre anuncie: "Usando change: " e como sobrescrever (ex.: /opsx:apply <outro>).

2. Verifique o status para entender o esquema

   openspec status --change "<nome>" --json
   

   Analise o JSON para entender:

   • schemaName: O fluxo de trabalho sendo usado (ex.: "spec-driven")
   • planningHome, changeRoot e actionContext: escopo de planejamento e restrições de edição
   • Qual artefato contém as tarefas (tipicamente "tasks" para spec-driven, verifique o status para outros)

3. Obtenha as instruções de apply

   openspec instructions apply --change "<nome>" --json
   

   Isso retorna:

   • contextFiles: ID do artefato -> array de caminhos de arquivo concretos (varia por esquema - pode ser proposal/specs/design/tasks ou spec/tests/implementation/docs)
   • Progresso (total, completo, restante)
   • Lista de tarefas com status, caminho de origem e linha de origem
   • Instrução dinâmica baseada no estado atual
   • Opcional context: entrada de instrução de projeto atual exigida da raiz selecionada
   • Opcional operationGuidance: orientação consultiva atual para apply
   • missingArtifacts (quando presente): IDs de artefatos obrigatórios sem saída

   Lide com estados:

   • Se state: "blocked": mostre a mensagem e pause a implementação.
     • Se missingArtifacts não estiver vazio: sugira completar os artefatos ausentes. Execute openspec status --change "<nome>" --json, selecione o próximo artefato ready (não skipped ou blocked) e use openspec instructions "<artifact-id>" --change "<nome>" --json para suas regras e modelo. Mantenha o --store <id> selecionado em ambos os comandos.
     • Caso contrário, siga a instrução da CLI para criar ou reparar o arquivo de rastreamento configurado pelo esquema a partir de artefatos de planejamento existentes. Não assuma que outro artefato está pronto ou inicie a implementação enquanto estiver bloqueado.
   • Se state: "all_done": relate que todas as tarefas rastreadas estão completas e sugira revisão ou verificação conforme apropriado antes de arquivar
   • Caso contrário: prossiga para a implementação

   Trate context como uma entrada obrigatória no nível do prompt. Leia e considere, e aplique fatos, convenções e restrições relevantes do projeto durante a implementação. Trate operationGuidance como aconselhamento adicional opcional. Leia e considere cada entrada, e siga entradas que sejam aplicáveis e compatíveis com o fluxo de trabalho integrado.

   Mantenha ambos os campos separados do estado retornado pela CLI, artefatos ausentes, tarefas, progresso, contextFiles e a instruction integrada. Eles não são evidência de conclusão de tarefa, não substituem a instrução integrada e não permitem contornar um estado bloqueado. Se o contexto entrar em conflito com a instrução integrada, uma escolha explícita do usuário ou um valor controlado pela CLI, relate o conflito e preserve o valor controlador. Se a orientação for inaplicável ou entrar em conflito com essas entradas controladoras, não a siga e explique o porquê. Estes são contratos de comportamento no nível do prompt, não verificações aplicáveis.

4. Leia os arquivos de contexto

   Leia cada caminho de arquivo listado em contextFiles do resultado das instruções de apply. Os arquivos dependem do esquema sendo usado:

   • spec-driven: proposta, especificações, design, tarefas
   • Outros esquemas: siga os contextFiles da saída da CLI

   Não copie context ou operationGuidance literalmente em arquivos de implementação ou artefatos de planejamento, a menos que o usuário separadamente solicite esse conteúdo.

5. Mostre o progresso atual

   Exiba:

   • Esquema sendo usado
   • Progresso: "N/M tarefas completas"
   • Visão geral das tarefas restantes
   • Instrução dinâmica da CLI

6. Implemente tarefas (loop até concluir ou bloquear)

   Para cada tarefa pendente:

   • Mostre em qual tarefa está trabalhando
   • Faça as alterações de código necessárias
   • Mantenha as alterações mínimas e focadas
   • Antes de editar, confirme que a caixa de seleção no sourcePath e line retornados ainda corresponde à descrição da tarefa; se não, reexecute as instruções de apply e use a localização atualizada
   • Marque a tarefa como completa em seu sourcePath e line retornados: - [ ] → - [x]
   • Reexecute as instruções de apply e confirme que aquela tarefa agora está concluída e o progresso mudou
   • Continue para a próxima tarefa

   Pause se:

   • A tarefa não estiver clara → peça esclarecimento
   • A implementação revelar um problema de design → sugira atualizar artefatos
   • Uma tarefa precisar de trabalho além do que a especificação e as tarefas descrevem, ou você for tentado a remover, restringir, adiar ou aceitar exceções ao comportamento especificado para fazê-lo caber → exiba o escopo adicional e pergunte; não o absorva silenciosamente
   • Erro ou bloqueador for encontrado → relate e aguarde orientação
   • O usuário interromper

7. Na conclusão ou pausa, mostre o status

   Exiba:

   • Tarefas concluídas nesta sessão
   • Progresso geral: "N/M tarefas completas"
   • Se tudo concluído: relate que as tarefas rastreadas estão completas e sugira revisão ou verificação conforme apropriado antes de arquivar
   • Se pausado: explique o motivo e aguarde orientação

Saída Durante a Implementação

## Implementando: <nome-da-change> (esquema: <nome-do-esquema>)

Trabalhando na tarefa 3/7: <descrição da tarefa>
[...implementação acontecendo...]
✓ Tarefa concluída

Trabalhando na tarefa 4/7: <descrição da tarefa>
[...implementação acontecendo...]
✓ Tarefa concluída

Saída na Conclusão

## Implementação Completa

**Change:** <nome-da-change>
**Esquema:** <nome-do-esquema>
**Progresso:** 7/7 tarefas concluídas ✓

### Concluídas Nesta Sessão
- [x] Tarefa 1
- [x] Tarefa 2
...

Todas as tarefas rastreadas estão concluídas. Revise ou verifique a change conforme apropriado
antes de arquivar. Você pode arquivar esta change com `/opsx:archive`.

Saída na Pausa (Problema Encontrado)

## Implementação Pausada

**Change:** <nome-da-change>
**Esquema:** <nome-do-esquema>
**Progresso:** 4/7 tarefas concluídas

### Problema Encontrado
<descrição do problema>

**Opções:**
1. <opção 1>
2. <opção 2>
3. Outra abordagem

O que você gostaria de fazer?

Guardrails

• Continue pelas tarefas até concluir ou bloquear
• Sempre leia os arquivos de contexto antes de começar (da saída das instruções de apply)
• Se a tarefa for ambígua, pause e pergunte antes de implementar
• Se a implementação revelar problemas, pause e sugira atualizações de artefato
• Mantenha as alterações de código mínimas e focadas em cada tarefa
• Atualize a caixa de seleção da tarefa imediatamente após concluir cada tarefa
• Pause em erros, bloqueadores ou requisitos pouco claros - não adivinhe
• Quando uma tarefa precisar de trabalho além do que a especificação descreve, exiba o escopo adicional e pause - nunca remova, adie ou simplifique silenciosamente o comportamento especificado
• Só marque uma tarefa como - [x] quando seu comportamento especificado estiver totalmente implementado, não quando estiver parcialmente concluído ou adiado
• Use contextFiles da saída da CLI, não assuma nomes de arquivo específicos
• Use o sourcePath e line de cada tarefa para atualizar sua caixa de seleção exata
• Não use contexto ou orientação de operação como prova de que uma tarefa está concluída
• Aplique o contexto relevante do projeto; relate conflitos com entradas controladoras do fluxo de trabalho
• Considere cada entrada de orientação; explique qualquer conselho inaplicável ou conflitante
• Não copie contexto de tempo de execução ou orientação de operação em arquivos de implementação ou artefatos de planejamento
• Preserve o comportamento controlado pela CLI de bloqueado/pronto/tudo-concluído e os critérios de conclusão

Integração com Fluxo de Trabalho Fluido

Este skill suporta o modelo "ações em uma change":

• Pode ser invocado a qualquer momento: Antes de todos os artefatos estarem prontos (se as tarefas existirem), após implementação parcial, intercalado com outras ações
• Permite atualizações de artefato: Se a implementação revelar problemas de design, sugira atualizar artefatos - sem bloqueio de fase, trabalhe fluidamente