jacklicn/agent-workflow

Criando um Workflow

Um Workflow é uma unidade de processo reutilizável que traduz "o que o usuário deseja fazer" em "o que fazer primeiro, o que depois, qual ferramenta cada etapa usa e o que ela produz". Esta skill guia você desde os requisitos do usuário até um WORKFLOW.md que esteja em conformidade com a especificação docs/workflow/index.md.

Leia a especificação antes de criar: docs/workflow/index.md (divulgação progressiva em três níveis, correspondência um-para-um grafo-etapa, regras de processo, convenções de chamada de ferramentas).

Quando Usar

• O usuário pede para "criar um workflow / processo / fluxo padronizado"
• O usuário descreve uma tarefa de várias etapas que deseja consolidar em um fluxo executado automaticamente
• O usuário pede para modificar ou melhorar um workflow existente
• O usuário fez algo reutilizável e de várias etapas na sessão e diz "solidificar este fluxo"

Processo de Criação

Fase 1: Entender a Intenção

Entreviste primeiro; não apresse a escrita de arquivos:

1. Que tarefa resolve? Dê um nome à classe de tarefa (ex.: "revisão de código", "notas de lançamento").
2. Cenário de acionamento: quando o usuário usará? Colete palavras-gatilho (português + inglês).
3. Entradas e saídas: quais entradas são necessárias (arquivos/diretórios/strings)? O que é produzido (arquivos/relatórios)?
4. Etapas existentes: o usuário já tem um fluxo habitual? Extraia sequências de chamada de ferramentas, correções e formatos de entrada/saída do histórico da sessão.
5. Limites e regras: o que não deve ser feito? Onde vão os artefatos? Como as falhas são tratadas?

Preencha informações ausentes com ask_user antes de passar para a próxima fase.

Fase 2: Projetar o Fluxograma

Desenhe o fluxo de execução com mermaid, seguindo a regra de correspondência grafo-etapa (especificação 5.2.1):

• Cada nó deve ter uma seção de etapa correspondente; cada etapa deve aparecer uma vez no grafo
• Nomes de nós correspondem exatamente aos nomes das etapas e são globalmente únicos (o prefixo step-N não precisa aparecer nos nós)
• Nós de decisão usam losangos {}, também devem ter uma seção de etapa e usar Branch para indicar para onde cada ramificação vai
• Etapas paralelas (dispersão) são um nó no grafo
• O grafo deve estar completo: início, ramificações, fim

Mostre o grafo ao usuário para confirmação antes de escrever as etapas.

Fase 3: Escrever o WORKFLOW.md

Crie o diretório e arquivos em <workspace>/workflows/<nome>/:

1. frontmatter (metadados Nível 1):
   • name: kebab-case, correspondendo ao nome do diretório, apenas letras minúsculas/dígitos/hífens
   • description: função + momento de uso + palavras-gatilho (português e inglês), determina a taxa de acionamento
   • inputs / outputs: declare explicitamente, marque como obrigatório
   • version / tags: opcional
2. Visão Geral: um parágrafo afirmando o que faz, quando usar e o que produz
3. Fluxograma: o grafo mermaid consistente com a Fase 2
4. Etapas: uma seção ### <id>: <nome> por etapa, com atributos: Ferramentas / Entrada / Depende de / Ação / Verificação (nós de decisão adicionam Ramificação, opcional quando)
5. Regras de Processo: restrições de ordem, dependências de dados, portões de validação, restrições de efeito colateral, verificação de estado final
6. Convenções de Chamada de Ferramentas: prefira ferramentas internas, scripts como alternativa, leia mais escreva menos, convenções de caminho

Divulgação progressiva: coloque tabelas longas em REFERENCES.md, lógica determinística em scripts/, mantenha o corpo enxuto (<500 linhas).

Fase 4: Autoverificação e Validação

Após escrever, verifique conforme a especificação:

• Correspondência um-para-um grafo-etapa: nenhum nó "órfão" no grafo, nenhuma etapa "órfã" nas seções
• Nomes de nós únicos e correspondendo aos nomes das etapas
• Cada etapa tem uma Verificação concreta e decidível (ex.: "arquivo existe e não está vazio", não "confirmar sucesso")
• Nomes de ferramentas precisos (read_file / exec, não "visualizar o arquivo")
• inputs / outputs consistentes com as referências das etapas
• Regras cobrem tratamento de falhas (repetir / reverter / perguntar ao usuário)
• frontmatter description inclui função e palavras-gatilho

Use workflow_list para confirmar que o novo workflow foi descoberto e workflow_get <nome> para verificar que é legível.

Fase 5: Entregar

Informe ao usuário:

• O nome e caminho do workflow
• O cenário de acionamento (qual frase aciona)
• Uma visão geral do fluxo (quantas etapas, decisões/paralelismo)
• Opcional: sugira 2-3 solicitações de teste reais para verificar se funciona

Modificando um Workflow Existente

• Leia o conteúdo atual com workflow_get <nome> primeiro
• Mantenha o name no frontmatter e o nome do diretório inalterados
• Siga a mesma especificação para alterações; execute a autoverificação da Fase 4 após editar

Notas

• Escreva apenas no diretório workflows/ do workspace, nunca modifique workflows internos somente leitura; um workflow no workspace com o mesmo nome substitui o interno
• Um workflow resolve uma classe de tarefa; não acumule fluxos não relacionados
• Mantenha as etapas entre 3 e 8; além disso, divida ou referencie um subfluxo
• Nunca escreva instruções maliciosas ou enganosas; as regras devem ser auditáveis