architawr/claude-bpmn-skill

O que claude-bpmn-skill faz?

Plugin do Claude Code (Agent Skill) para BPMN 2.0 - ler, explicar, criar e editar diagramas de processo .bpmn com layout limpo gerado automaticamente, validação e análise de fluxo de controle (deadlocks, tokens travados). Funciona com Camunda Modeler e bpmn.io.

Funcionalidades

• Leitura e explicação: Analisa arquivos .bpmn e traduz o diagrama em linguagem natural, explicando os elementos do processo.
• Criação e edição: Gera ou modifica modelos BPMN 2.0 a partir de descrições textuais, mantendo a estrutura semântica correta.
• Layout automático: Aplica um layout limpo e legível automaticamente, usando ferramentas como bpmn-auto-layout ou camunda-modeler com plugins.
• Validação e linting: Detecta deadlocks, tokens travados, elementos não conectados e outras violações de fluxo de controle usando bpmnlint ou o bpmn-linter escrito em Java.
• Suporte a plataformas: Integra-se com Camunda Modeler (via arquivos .bpmn) e bpmn.io (via visualização em navegador).

Pré-requisitos

• Claude Code (ou Cursor) instalado em seu ambiente.
• Node.js e npm para execução de ferramentas de linting.
• Java Runtime (JRE) para executar o bpmn-linter (opcional, mas recomendado).
• Um diretório de projeto contendo arquivos .bpmn ou permissão para criá-los.

Como usar

1. Instalação do Skill

Adicione este skill ao seu agente Claude Code:

claude add skill architawr/claude-bpmn-skill

2. Comandos principais

• Ler e explicar um diagrama:

  Explique o arquivo process.bpmn localizado em ./modelos
  

• Criar um novo processo:

  Crie um fluxo de aprovação de pedido de compra no arquivo aprovar.bpmn. Inclua gateways exclusivos para valores acima de 1000 e tarefas de usuário para gestores.
  

• Validar e corrigir:

  Valide o arquivo processo.bpmn e corrija quaisquer deadlocks encontrados.
  

3. Ferramentas de linha de comando

Para validação local, use os seguintes comandos:

npx bpmnlint ./caminho/para/diagrama.bpmn

Ou, para usar o bpmn-linter em Java:

java -jar bpmn-linter.jar ./caminho/para/diagrama.bpmn

4. Exemplo de uso com Camunda Modeler

1. Abra o Camunda Modeler.
2. Crie um novo diagrama BPMN.
3. Salve como diagrama.bpmn.
4. No Claude Code, peça para "Melhorar o layout e validar o diagrama.bpmn".

Estrutura de arquivos esperada

projeto/
├── modelos/
│   ├── processo1.bpmn
│   └── processo2.bpmn
├── bpmnlintrc.json          # Configuração opcional do bpmnlint
└── .bpmn-linter.properties   # Configuração opcional do bpmn-linter

Integração com bpmn.io

Para visualizar diagramas em um navegador, use o bpmn.io. Carregue o arquivo .bpmn gerado ou editado.

Diagnóstico de problemas comuns

• Deadlock: Ocorre quando um fluxo chega a um gateway que não pode prosseguir. O linter detecta esses casos.
• Token travado: Acontece quando um elemento não tem saída. O linter aponta o elemento problemático.
• Elementos não conectados: Gatilho para validação, o layout automático tenta corrigir.

Contribuição

Contribuições são bem-vindas! Siga o guia de contribuição.

Licença

MIT

Referências

• bpmn.io
• Camunda Modeler
• bpmnlint
• bpmn-linter (Java)