williamsnieves/landing-factory

Implementar tarefas a partir de uma alteração 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 e, em seguida, passe --store <id> nos comandos que leem ou escrevem specs e alterações (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 não qualificado desses comandos abaixo é uma abreviação: antes de executá-lo, acrescente a flag. Por exemplo, execute openspec status --change "<nome>" --json --store "<id>", não a forma não qualificada mostrada abaixo. Outros comandos não aceitam a flag. As dicas impressas pelos comandos já carregam a flag; mantenha-a nas ações de acompanhamento. 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 o criaria 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 contorná-lo.

Um "root": null não é sobre configuração: quando uma mensagem de erro de 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 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 fix desse erro.

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

• Auto-selecionado: 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 o OpenSpec e responda à solicitação normalmente, como faria sem o 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 ele já possui (--store <id>), ou continuar sem 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 solicite, não crie arquivos openspec/ manualmente e não deixe um comando criá-la.

Entrada: Opcionalmente, especifique um nome de alteração (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 alterações disponíveis.

Passos

1. Selecionar a alteração

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

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

   Sempre anuncie: "Usando alteração: " e como substituir (ex.: /opsx:apply <outra>).

2. Verificar 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. Obter instruções de aplicação

   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
   • context opcional: entrada de instrução do projeto atual necessária da raiz selecionada
   • operationGuidance opcional: orientação consultiva atual para aplicação
   • missingArtifacts (quando presente): IDs de artefato necessários sem saída

   Lidar com estados:

   • Se state: "blocked": mostre a mensagem e pause a implementação.
     • Se missingArtifacts não estiver vazio: sugira completar os artefatos faltantes. 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 bloqueado.
   • Se state: "all_done": relate que todas as tarefas rastreadas estão concluídas 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 conselho adicional opcional. Leia e considere cada entrada, e siga entradas que são aplicáveis e compatíveis com o fluxo de trabalho incorporado.

   Mantenha ambos os campos separados do estado retornado pela CLI, artefatos faltantes, tarefas, progresso, contextFiles e a instruction incorporada. Eles não são evidência de conclusão de tarefa, não substituem a instrução incorporada e não permitem contornar um estado bloqueado. Se o contexto conflitar com a instrução incorporada, 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 conflitar 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 executáveis.

4. Ler arquivos de contexto

   Leia cada caminho de arquivo listado em contextFiles da saída das instruções de aplicação. Os arquivos dependem do esquema sendo usado:

   • spec-driven: proposal, specs, design, tasks
   • Outros esquemas: siga os contextFiles da saída da CLI

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

5. Mostrar progresso atual

   Exibir:

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

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

   Para cada tarefa pendente:

   • Mostrar em qual tarefa está sendo trabalhada
   • Fazer as alterações de código necessárias
   • Manter as alterações mínimas e focadas
   • Antes de editar, confirmar que a caixa de seleção no sourcePath e line retornados ainda corresponde à descrição da tarefa; se não corresponder, reexecute as instruções de aplicação e use o local atualizado
   • Marcar a tarefa como concluída em seu sourcePath e line retornados: - [ ] → - [x]
   • Reexecutar as instruções de aplicação e confirmar que a tarefa agora está concluída e o progresso mudou
   • Continuar para a próxima tarefa

   Pausar se:

   • Tarefa não estiver clara → pedir esclarecimento
   • Implementação revelar um problema de design → sugerir atualização dos artefatos
   • Uma tarefa precisar de trabalho além do que a especificação e as tarefas descrevem, ou você for tentado a eliminar, reduzir, adiar ou aceitar exceções ao comportamento especificado para encaixar → trazer à tona o escopo adicional e perguntar; não absorvê-lo silenciosamente
   • Erro ou bloqueador encontrado → relatar e aguardar orientação
   • Usuário interromper

7. Ao concluir ou pausar, mostrar status

   Exibir:

   • Tarefas concluídas nesta sessão
   • Progresso geral: "N/M tarefas concluídas"
   • Se tudo concluído: relatar que as tarefas rastreadas estão concluídas e sugerir revisão ou verificação conforme apropriado antes de arquivar
   • Se pausado: explicar o porquê e aguardar orientação

Saída Durante a Implementação

## Implementando: <nome-da-alteração> (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 Ao Concluir

## Implementação Concluída

**Alteração:** <nome-da-alteração>
**Esquema:** <nome-do-esquema>
**Progresso:** 7/7 tarefas concluídas ✓

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

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

Saída Ao Pausar (Problema Encontrado)

## Implementação Pausada

**Alteração:** <nome-da-alteração>
**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?

Diretrizes de Segurança

• Continue passando pelas tarefas até concluir ou bloquear
• Sempre leia os arquivos de contexto antes de começar (da saída das instruções de aplicação)
• Se a tarefa for ambígua, pause e pergunte antes de implementar
• Se a implementação revelar problemas, pause e sugira atualizações nos artefatos
• 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, traga à tona o escopo adicional e pause - nunca elimine, 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ída ou adiada
• 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 de Fluxo de Trabalho Fluido

Este skill suporta o modelo de "ações em uma alteração":

• 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 artefatos: Se a implementação revelar problemas de design, sugira atualizar os artefatos - não bloqueado por fase, trabalhe fluidamente