Entrada do Usuário
$ARGUMENTS
Você DEVE considerar a entrada do usuário antes de prosseguir (se não estiver vazia).
Verificações Pré-Execução
Verificar hooks de extensão (antes da convergência):
-
Verifique se
.specify/extensions.ymlexiste na raiz do projeto. -
Se existir, leia-o e procure por entradas na chave
hooks.before_converge. -
Se o YAML não puder ser analisado ou for inválido, não ignore silenciosamente: avise o usuário que
.specify/extensions.ymlnão pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados ali, depois continue normalmente. -
Filtre os hooks onde
enabledestá explicitamente comofalse. Trate hooks sem um campoenabledcomo habilitados por padrão. -
Para cada hook restante, não tente interpretar ou avaliar expressões
conditiondos hooks:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável. - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor.
- Se o hook não tiver um campo
-
Ao construir invocações de comando a partir de nomes de comando de hooks, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. -
Para cada hook executável, produza a seguinte saída com base em sua flag
optional:-
Hook opcional (
optional: true):## Hooks de Extensão **Pré-Hook Opcional**: {extension} Comando: `/{command}` Descrição: {description} Prompt: {prompt} Para executar: `/{command}` -
Hook obrigatório (
optional: false):## Hooks de Extensão **Pré-Hook Automático**: {extension} Executando: `/{command}` EXECUTE_COMMAND: {command} Aguarde o resultado do comando do hook antes de prosseguir para o Objetivo.Após emitir o bloco acima, você DEVE de fato invocar o hook e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando neste agente/sessão (a invocação pode diferir do ID literal
{command}mostrado acima; por exemplo, um agente em modo de habilidades executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o hook.
-
-
Se nenhum hook estiver registrado ou
.specify/extensions.ymlnão existir, ignore silenciosamente.
Objetivo
Eliminar a lacuna entre o que a especificação, plano e tarefas de uma funcionalidade exigem e o que a base de código atualmente implementa. Leia spec.md, plan.md e tasks.md como a única fonte de intenção (com a constituição como restrições governantes), avalie o estado atual do código, determine quais requisitos, critérios de aceitação, decisões de plano e tarefas existentes estão não atendidos, incompletos ou apenas parcialmente satisfeitos, e anexe cada parte do trabalho restante como uma nova tarefa rastreável no final de tasks.md para que /speckit-implement possa concluí-la. Este comando DEVE ser executado somente após /speckit-implement ter sido executado no tasks.md atual, e após /speckit-tasks ter produzido um tasks.md completo.
Isso não é uma ferramenta de diff e não rastreia alterações. Ela avalia o estado atual do código em relação aos artefatos da funcionalidade — sem git, sem comparação de branches, sem histórico.
Restrições Operacionais
SOMENTE ANEXAR, NUNCA REESCREVER: A única gravação do comando é anexar uma nova seção ## Phase N: Convergence ao tasks.md. O comando NÃO DEVE:
- modificar
spec.mdouplan.mdde forma alguma; - reescrever, renumerar, reordenar ou excluir qualquer tarefa existente (incluindo tarefas de uma fase de Convergência anterior);
- modificar, criar ou excluir qualquer código de aplicação — completar as tarefas anexadas é trabalho do
/speckit-implement.
Quando a base de código já satisfizer tudo, o comando DEVE deixar tasks.md byte por byte inalterado (nenhum cabeçalho de Convergência vazio) e relatar um resultado limpo.
Autoridade da Constituição: A constituição do projeto (.specify/memory/constitution.md) é innegociável. Código que viola um princípio MUST é a descoberta de maior gravidade e produz uma tarefa de remediação correspondente. Se a constituição for um modelo não preenchido, pule as verificações da constituição de forma elegante, sem falhar.
Etapas de Execução
1. Inicializar o Contexto de Convergência
Execute .specify/scripts/bash/check-prerequisites.sh --json --require-spec --require-tasks --include-tasks uma vez da raiz do repositório e analise o JSON para obter FEATURE_DIR e AVAILABLE_DOCS. Derive caminhos absolutos:
- SPEC = FEATURE_DIR/spec.md
- PLAN = FEATURE_DIR/plan.md
- TASKS = FEATURE_DIR/tasks.md
- CONSTITUTION =
.specify/memory/constitution.md(se presente)
Se spec.md, plan.md ou tasks.md estiver faltando, PARE com uma mensagem clara e acionável nomeando o comando pré-requisito a ser executado (/speckit-specify para especificação faltante, /speckit-plan para plano faltante, /speckit-tasks para tarefas faltantes). Não produza saída parcial.
Para aspas simples em argumentos como "I'm Groot", use sintaxe de escape: por exemplo, 'I'\''m Groot' (ou aspas duplas se possível: "I'm Groot").
2. Carregar Artefatos (Divulgação Progressiva)
Carregue apenas o contexto mínimo necessário de cada artefato:
De spec.md:
- Requisitos Funcionais (FR-###)
- Critérios de Sucesso (SC-###) — inclua apenas itens que exigem trabalho construtível; exclua métricas de resultado pós-lançamento e KPIs de negócio
- Histórias de Usuário e seus Cenários de Aceitação
- Casos de Borda (se presentes)
De plan.md:
- Escolhas de arquitetura/stack e decisões técnicas
- Referências ao Modelo de Dados
- Fases e pontos de contato nomeados (arquivos/componentes que o plano diz que serão criados ou editados)
- Restrições técnicas
De tasks.md:
- IDs de Tarefas (para calcular o próximo ID e o próximo número de fase)
- Descrições, agrupamento de fases e caminhos de arquivos referenciados
Da constituição (se não for um modelo não preenchido):
- Nomes de princípios e declarações normativas MUST/SHOULD
3. Construir o Inventário de Intenções
Crie um modelo interno (não ecoe artefatos brutos):
- Inventário de requisitos: uma chave estável por FR-### / SC-### / cenário de aceitação de história de usuário (por exemplo,
US1/AC2), mais as decisões de plano e princípios constitucionais que impõem obrigações construtíveis. - Mapa de escopo de código: a partir dos caminhos de arquivo nomeados em
plan.mdetasks.md, mais uma pesquisa por palavra-chave para os conceitos que cada requisito descreve, derive o conjunto de arquivos fonte e componentes no escopo para avaliação. Limite a avaliação a estes — não infira escopo além do que os artefatos definem.
4. Avaliar a Base de Código e Classificar Descobertas
Inclua cada tarefa existente no inventário de intenções, independentemente do estado da caixa de seleção ou da fase de Convergência: alegações de conclusão não são evidência. Verifique o comportamento atual em relação à especificação, plano, tarefas e constituição; para cadeias de tarefas corretivas, avalie o comportamento resultante, não detalhes de implementação substituídos. Verifique tanto obrigações não atendidas quanto implementação que contradiz, excede ou está fora da intenção declarada.
Para cada item no inventário de intenções, inspecione o código atual no escopo e produza uma Finding somente onde houver uma lacuna. Classifique cada descoberta por tipo de lacuna:
missing: o trabalho necessário está ausente do código completamente.partial: o trabalho existe mas ainda não satisfaz completamente o requisito / critério de aceitação / decisão de plano.contradicts: o código faz algo que conflita com a intenção declarada ou um princípio MUST da constituição.unrequested: o código contém trabalho não solicitado pela especificação, plano ou tarefas (apresentado para conscientização — convergir não exclui código, apenas anexa uma tarefa para revisar/justificar ou remover).
Cada Finding registra: um id estável, a source-ref à qual remete, o gap-type, uma severidade e uma descrição curta legível com a evidência (o arquivo/área observado).
Casos de borda:
- Pouco ou nenhum código ainda: trate todo o escopo especificado como trabalho
missingrestante, em vez de falhar. - Nada resta: produza zero descobertas e siga o ramo convergido na Etapa 7.
5. Atribuir Severidade
- CRITICAL: viola um princípio MUST da constituição, ou uma lacuna
missing/contradictsque bloqueia a funcionalidade básica de uma história de usuário P1. - HIGH: uma lacuna
missingoupartialem um requisito funcional principal ou critério de aceitação. - MEDIUM: uma lacuna
partialem um requisito secundário, ou uma adiçãounrequestedcom justificativa pouco clara. - LOW: lacunas parciais menores, polimento ou adições
unrequestedde baixo risco.
6. Apresentar o Resumo das Descobertas na Sessão
Antes de anexar qualquer coisa, produza um resumo compacto, graduado por severidade (ainda sem gravações de arquivo):
Descobertas de Convergência
| ID | Tipo de Lacuna | Severidade | Fonte | Evidência | Trabalho Restante |
|---|---|---|---|---|---|
| F1 | missing | HIGH | FR-008 | Exemplo: nenhuma proteção append-only detectada em caminho/para/modulo.py ao escrever tasks.md | Adicionar aplicação de append-only |
Métricas de resumo:
- Requisitos / critérios de aceitação verificados
- Decisões de plano verificadas
- Princípios constitucionais verificados (ou "ignorado — modelo")
- Descobertas por tipo de lacuna (missing / partial / contradicts / unrequested)
- Descobertas por severidade
7. Anexar Tarefas de Convergência (ou relatar convergido)
Se houver uma ou mais descobertas acionáveis (resultado tasks_appended):
Anexe ao final de tasks.md, conforme o contrato de anexação:
-
Escaneie todos os IDs de tarefas existentes; seja
Mo máximo. Determine o próximo número de faseN(fase existente mais alta + 1). -
Escreva um único cabeçalho de nova seção
## Phase N: Convergence. -
Emita um item de lista de verificação por descoberta acionável, ordenado por CRITICAL/HIGH primeiro, atribuindo IDs preenchidos com zero
T{M+1:03d}, T{M+2:03d}, …:- [ ] T042 <descrição imperativa> por <source-ref> (<gap-type>)<source-ref>rastreia a tarefa até sua origem: por exemplo,FR-003,SC-002,US1/AC2,plan: decisão de armazenamento,Constitution II.<gap-type>é um demissing,partial,contradicts,unrequested.Tarefas de violação da constituição DEVEM ser emitidas primeiro e descritas como
CRITICAL. -
Nunca reutilize ou renumerie IDs existentes. Se uma fase de Convergência anterior existir, adicione uma nova, numerada separadamente, abaixo dela — não toque na antiga.
Se não houver descobertas acionáveis (resultado converged):
- Não modifique
tasks.mdde forma alguma — nenhum cabeçalho de fase vazio. - Relate: "✅ Convergido — a implementação satisfaz a especificação, o plano e as tarefas."
- Inclua as contagens de resumo do que foi verificado.
8. Fornecer Próximas Ações (Handoff)
- Em
tasks_appended: informe quantas tarefas foram anexadas e sob qual fase, e recomende executar/speckit-implementpara completá-las; observe que uma execução de convergência subsequente encontrará menos ou nenhum item restante. - Em
converged: recomende prosseguir para revisão / abrir um PR. Nenhuma passada de implementação adicional é necessária para o escopo especificado desta funcionalidade.
9. Verificar hooks de extensão
Após produzir o resultado, verifique se .specify/extensions.yml existe na raiz do projeto.
-
Se existir, leia-o e procure por entradas na chave
hooks.after_converge. -
Se o YAML não puder ser analisado ou for inválido, não ignore silenciosamente: avise o usuário que
.specify/extensions.ymlnão pôde ser lido (inclua o erro do parser) e que nenhum hook foi verificado, incluindo quaisquer hooks obrigatórios (optional: false) registrados ali, depois continue normalmente. -
Filtre os hooks onde
enabledestá explicitamente comofalse. Trate hooks sem um campoenabledcomo habilitados por padrão. -
Para cada hook restante, não tente interpretar ou avaliar expressões
conditiondos hooks:- Se o hook não tiver um campo
condition, ou ele for nulo/vazio, trate o hook como executável. - Se o hook definir uma
conditionnão vazia, pule o hook e deixe a avaliação da condição para a implementação do HookExecutor.
- Se o hook não tiver um campo
-
Relate o resultado da convergência (
convergedoutasks_appended) na sessão antes de listar quaisquer hooks, para que os usuários possam decidir se devem executar comandos de acompanhamento opcionais. -
Ao construir invocações de comando a partir de nomes de comando de hooks, substitua pontos (
.) por hífens (-). Por exemplo,speckit.git.commit→/speckit-git-commit. -
Para cada hook executável, produza a seguinte saída com base em sua flag
optional:-
Hook opcional (
optional: true):## Hooks de Extensão **Hook Opcional**: {extension} Comando: `/{command}` Descrição: {description} Prompt: {prompt} Para executar: `/{command}` -
Hook obrigatório (
optional: false):## Hooks de Extensão **Hook Automático**: {extension} Executando: `/{command}` EXECUTE_COMMAND: {command}Após emitir o bloco acima, você DEVE de fato invocar o hook e aguardar sua conclusão antes de continuar. Execute-o da mesma forma que você executaria o comando neste agente/sessão (a invocação pode diferir do ID literal
{command}mostrado acima; por exemplo, um agente em modo de habilidades executa como/skill:speckit-...ou$speckit-...). Apenas emitir o bloco não executa o hook.
-
-
Se nenhum hook estiver registrado ou
.specify/extensions.ymlnão existir, ignore silenciosamente.