Skills
Todas as skills do OpenSpec: argumentos, o que criam e o que respondem.
As skills vêm em dois conjuntos:
- Núcleo: instalado por padrão, o loop principal de planejamento.
- Opcional: instalado apenas quando você os adiciona, via Perfis.
Toda skill espera um projeto que já usa o OpenSpec. Antes do seu primeiro passo que grava algo, a skill verifica se há uma raiz resolvida. O que acontece quando não há depende de como a skill foi acessada:
- Auto-selecionada: seu agente escolheu a skill por conta própria, sem você nomear o OpenSpec. Ela abandona o OpenSpec e responde sua solicitação normalmente, da mesma forma que faria se o OpenSpec não estivesse instalado.
- Solicitação explícita do OpenSpec: você nomeou o OpenSpec, nomeou a skill ou executou seu comando. Ela para antes de gravar e pergunta como proceder: executar
openspec initaqui, direcionar a um store com--store <id>, ou continuar sem o OpenSpec. Ela aguarda sua resposta.
Comandos são sempre o segundo caso. Um projeto cujo openspec/config.yaml nomeia um store que esta máquina não consegue resolver (não registrado, ou uma linha store: malformada) não é tratado como não inicializado: a skill para e mostra o erro do store com sua correção. Nenhuma skill cria um diretório openspec/ por conta própria em nenhum dos casos. As entradas abaixo descrevem o que cada skill faz uma vez que uma raiz esteja estabelecida.
| Skill | Função | Tipo |
|---|---|---|
| openspec-explore | Pensar em uma ideia antes que se torne uma proposta de mudança | Núcleo |
| openspec-propose | Criar uma proposta de mudança com todos os seus artefatos de planejamento em uma etapa | Núcleo |
| openspec-apply-change | Implementar as tarefas de uma proposta de mudança | Núcleo |
| openspec-update-change | Revisar o plano de uma proposta de mudança | Núcleo |
| openspec-sync-specs | Mesclar as atualizações de spec de uma proposta de mudança em specs/ | Núcleo |
| openspec-archive-change | Mover uma proposta de mudança concluída para o arquivo | Núcleo |
| openspec-new-change | Iniciar uma proposta de mudança como um scaffold vazio | Opcional |
| openspec-continue-change | Criar o próximo artefato de planejamento, um por vez | Opcional |
| openspec-ff-change | Criar uma proposta de mudança com todos os artefatos que a implementação precisa, em uma única passada | Opcional |
| openspec-verify-change | Verificar se a implementação corresponde ao plano | Opcional |
| openspec-bulk-archive-change | Arquivar várias propostas de mudança de uma só vez | Opcional |
| openspec-onboard | Aprender o fluxo de trabalho fazendo uma proposta de mudança real de ponta a ponta | Opcional |
Cada entrada abaixo nomeia a skill que é dona do próximo passo. Quando seu perfil não inclui essa skill, os arquivos instalados nunca a mencionam: a transição se torna o comando openspec equivalente, ou uma solicitação simples a você, e uma linha que existe apenas para apontar para uma skill ausente simplesmente não é gravada. Assim, as skills que você tem sempre transferem para skills que você tem. Qual conjunto você obtém é Perfis.
openspec-explore
Pense em uma ideia antes que ela se torne uma proposta de mudança.
| Contrato | Descrição |
|---|---|
| Argumentos | Um tópico: uma ideia, um problema, uma comparação, ou o nome de uma proposta de mudança existente para explorar em contexto. Sem nada informado, entra no modo exploração. |
| Cria | Nada por padrão. Apenas lê e investiga. Sob solicitação, captura insights: uma nova proposta de mudança em openspec/changes/<name>/, ou atualizações na proposta, design, specs ou tarefas de uma existente. Nunca código. |
| Resposta | Uma conversa aberta sem saída obrigatória. Quando o pensamento se cristaliza, resume o problema, a abordagem, as questões em aberto e os próximos passos, e oferece capturá-los. Você decide. A implementação nunca começa aqui. |
openspec-propose
Crie uma proposta de mudança e gere todos os seus artefatos de planejamento em uma única etapa.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome em kebab-case (add-dark-mode) ou uma descrição simples. Pergunta se você não fornecer nenhum dos dois. |
| Cria | openspec/changes/<name>/ com todos os artefatos que o schema define, em ordem de dependência (orientado a spec: proposta, deltas de spec, design, tarefas). Nunca código. |
| Resposta | Os artefatos criados, prontos para revisão, e o próximo passo. Para por aí; a implementação aguarda openspec-apply-change. |
openspec-apply-change
Implemente as tarefas de uma proposta de mudança, trabalhando pela lista até concluir ou ficar bloqueado.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança (add-auth), opcional. Se o alvo for ambíguo, lista as propostas de mudança ativas e pede que você escolha. |
| Cria | Código: as mudanças mínimas que cada tarefa requer, nos arquivos do seu projeto. Na proposta de mudança, marca cada tarefa concluída (- [ ] para - [x]) no arquivo rastreado identificado por sourcePath e line baseado em um. Um schema pode rastrear tarefas em múltiplos arquivos. |
| Resposta | Progresso por tarefa, depois uma contagem geral (N/M tarefas concluídas). Tudo concluído: sugere openspec-archive-change. Bloqueado por artefatos ausentes: aponta para openspec-continue-change, ou para openspec status e openspec instructions quando essa skill não está instalada (o perfil core não a inclui). Tarefas pouco claras ou erros: pausa e pergunta. |
openspec-update-change
Revise os artefatos de planejamento existentes de uma proposta de mudança e mantenha-os coerentes entre si.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança, opcional, mais a revisão desejada. Sem uma revisão declarada, executa uma revisão de coerência: artefatos verificados entre si quanto a contradições, lacunas e duplicações. |
| Cria | Edita arquivos de artefatos que já existem. Uma exceção: para um artefato escrito como glob, como specs/**/*.md, que já possui pelo menos um arquivo, pode adicionar um arquivo complementar ausente uma vez que você confirme o caminho. Um artefato sem arquivos ainda é tarefa do openspec-continue-change. Sem essa skill (o perfil core não a inclui), aponta para openspec status e openspec instructions. Nunca código. |
| Resposta | Mostra cada revisão proposta e a grava apenas após sua confirmação, um artefato por vez. Termina com o que foi revisado e o próximo passo; a implementação aguarda openspec-apply-change. |
openspec-sync-specs
Mescle as atualizações de spec de uma proposta de mudança em specs/ sem arquivá-la.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança, opcional. Você também pode nomear um subconjunto dos seus deltas de spec, e apenas esses serão sincronizados. |
| Cria | Edita ou cria openspec/specs/<capability-path>/spec.md para cada delta de spec, mesclando requisitos adicionados, modificados, removidos e renomeados na spec principal. Nunca código. |
| Resposta | Um resumo por capacidade dos requisitos adicionados, modificados, removidos ou renomeados, após a validação das specs atualizadas. A proposta de mudança permanece ativa; o arquivamento aguarda openspec-archive-change. |
openspec-archive-change
Mova uma proposta de mudança concluída para o arquivo.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança, opcional. |
| Cria | Move a pasta da proposta de mudança para openspec/changes/archive/YYYY-MM-DD-<name>/ (sem adição de data se o nome já começar com uma). Com sua aprovação, primeiro sincroniza os deltas de spec pendentes. Quando openspec-sync-specs está instalado, executa esse workflow. Caso contrário, mescla os deltas de spec nas specs principais ele mesmo. Nunca código. |
| Resposta | Avisa e pergunta antes de arquivar com artefatos ou tarefas incompletas, e pergunta se deve sincronizar quando existem deltas de spec. Termina com um resumo: nome, schema, local de arquivo, status de sincronização de spec e eventuais avisos. |
openspec-new-change
Inicie uma proposta de mudança como um scaffold vazio.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome em kebab-case (add-user-auth) ou uma descrição simples, mais um nome de schema apenas para um workflow não padrão. Pergunta o que você deseja construir se não fornecer nenhum dos dois. |
| Cria | openspec/changes/<name>/ como um scaffold vazio: nenhum artefato ainda, nunca código. |
| Resposta | O nome e localização do scaffold, a sequência de artefatos do workflow, status (0/N concluídos) e o template do primeiro artefato. A elaboração dos artefatos aguarda openspec-continue-change. |
openspec-continue-change
Crie o próximo artefato de planejamento em uma proposta de mudança, um de cada vez.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança, opcional. Se ainda for ambíguo, pede que você escolha entre os modificados mais recentemente. |
| Cria | O único próximo artefato pronto na sequência do schema, gravado na pasta da proposta de mudança. Um artefato por execução, nunca código. |
| Resposta | O artefato criado, progresso (N de M concluídos) e quais artefatos isso desbloqueou. Quando o planejamento está completo, informa isso; a implementação passa para openspec-apply-change. |
openspec-ff-change
Crie uma proposta de mudança e todos os artefatos de planejamento que a implementação precisa, em uma única passada.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome em kebab-case ou uma descrição simples. Pergunta se você não fornecer nenhum dos dois. Se a proposta de mudança nomeada já existir, sugere continuar em vez de criar outra. |
| Cria | openspec/changes/<name>/ e todos os artefatos de planejamento que a implementação requer, em ordem de dependência (orientado a spec: proposta, specs, design, tarefas), deixando de fora apenas artefatos marcados como ignorados ou condicionais. Nunca código. |
| Resposta | O nome e localização da proposta de mudança, cada artefato criado e qualquer artefato condicional ignorado e o motivo. Para por aí; a implementação aguarda openspec-apply-change. |
openspec-verify-change
Verifique se a implementação corresponde aos artefatos da proposta de mudança.
| Contrato | Descrição |
|---|---|
| Argumentos | Um nome de proposta de mudança, opcional. Quando ambíguo, pergunta, listando propostas de mudança que possuem um artefato de tarefas. |
| Cria | Nada. Lê os artefatos da proposta de mudança e a base de código. A verificação é apenas um relatório. |
| Resposta | Um relatório: um placar para Completude, Corretude e Coerência, depois questões CRÍTICAS, AVISOS e SUGESTÕES com recomendações, e uma avaliação final de prontidão para arquivamento. Não altera nada e não arquiva. |
openspec-bulk-archive-change
Arquive várias propostas de mudança de uma vez.
| Contrato | Descrição |
|---|---|
| Argumentos | Nenhum. Lista as propostas de mudança ativas e pede que você selecione qualquer quantidade, com uma opção para todas. Se nenhuma estiver ativa, informa isso e para. |
| Cria | openspec/changes/archive/YYYY-MM-DD-<name>/ por proposta de mudança arquivada (nomes já datados mantêm seu prefixo). Os deltas de spec de cada uma são sincronizados primeiro via openspec-sync-specs. Nunca código. |
| Resposta | Uma tabela de status por proposta de mudança e uma confirmação para o lote inteiro, depois um resumo dos arquivados, ignorados e com falha, além dos resultados de sincronização de spec. Quando duas propostas de mudança tocam a mesma spec, verifica a base de código e sincroniza os deltas implementados dos mais antigos para os mais recentes. |
openspec-onboard
Aprenda o workflow fazendo uma proposta de mudança real do início ao fim.
| Contrato | Descrição |
|---|---|
| Argumentos | Nenhum. Escaneia sua base de código em busca de tarefas iniciais pequenas e pede que você escolha uma ou descreva a sua própria. |
| Cria | Uma proposta de mudança real para a tarefa escolhida, um artefato por vez, depois código real uma vez que você confirme a implementação. Arquiva a proposta de mudança no final. |
| Resposta | Um tour narrado pelo ciclo completo com pausas para sua contribuição: explorar, criar, construir cada artefato, implementar, arquivar. Termina com um resumo e uma indicação para openspec-propose. Leva cerca de 15 a 20 minutos. |