Sobre o projeto

O Diagram & Inventory Rule Engine é um projeto Kiro reutilizável e agnóstico à nuvem que codifica como agentes de IA produzem deterministicamente diagramas de arquitetura e documentos de inventário em cinco perfis de provedor: aws, azure, gcp, oci e um fallback genérico neutro em relação ao fornecedor. Seu valor central é o determinismo: dados os mesmos inputs, qualquer agente em conformidade produz diagramas e documentos de inventário comparáveis que passam no mesmo conjunto de regras de lint. O motor separa um núcleo neutro em relação ao provedor (Linter, Icon Resolver, Inventory Collector, Normalizer, Delta Engine) de perfis por provedor. Terminologia, ícones, cores de marca, convenções de contêiner e verbos de inventário somente leitura vêm todos do perfil selecionado, nunca de lógica central codificada de forma fixa. Adicionar um novo provedor é feito por dados (uma linha de perfil, mapeamento de ícones, verbos e um exemplo golden), não alterando o código central. Desde a versão 1.3.0, o motor suporta duas escalas de diagrama por meio de uma classe de diagrama: um resumo de fluxo (uma visão narrativa de ≤12 nós de como uma requisição se move de ponta a ponta) e um landscape as-built (uma visão completa de inventário em uma única tela, com um limite de nós relaxado, mas regras de layout mais rígidas impostas por geometria). Um sistema grande é entregue como o par sancionado: um resumo de fluxo com link cruzado para um landscape as-built do mesmo sistema. Os ícones são padronizados em pacotes oficiais dos fornecedores e resolvidos por meio de um índice versionado (mappings/icon-index.json) construído no momento da instalação. O conteúdo inclui: - .kiro/steering/ — padrões sempre ativos que governam cada turno do agente: diagram-standards.md (ordem de faixas, limite de 12 nós, citação de nós, rótulos de arestas, célula de título, legenda, matriz PlantUML/Mermaid e o trio de artefatos .drawio / .drawio.png / .diagram.md), inventory-standards.md (verbos somente leitura, regra de zero mutação, layout de pasta de snapshot, campos de manifesto, segurança de segredos), provider-profiles.md (tabela de normalização de terminologia de nove conceitos, convenções de contêiner, paleta de marca, listas de verbos), kb-frontmatter.md (chaves obrigatórias de frontmatter, limites de comprimento de documento e seções), diagram-lint.md (conjunto autoritativo de regras de lint com severidades CRITICAL / ERROR / WARNING) e asset-packs.md (fontes oficiais de pacotes de ícones dos provedores, layouts e ordem de fallback). - .kiro/hooks/ — automação de lint-on-save e validate-on-task - .kiro/agents/ — três agentes personalizados criados para fins específicos (diagram-author, inventory-collector, rule-engine-reviewer) com escopos de ferramentas/permissões de privilégio mínimo - .kiro/skills/rule-engine-artifacts/ — skill de geração de artefatos sob demanda - powers/rule-engine-artifacts/ — a skill mais o MCP AWS-docs empacotados como um Kiro power - .kiro/specs/ — spec do motor mais um template de spec reutilizável - mappings/ — arquivos de mapeamento de ícones/formas por provedor, tabela de papéis de diagrama e índice de ícones versionado - schemas/ — Normalized Resource JSON Schema - examples/ — exemplos golden por provedor: diagrama de fluxo de aplicação mais par com link cruzado de resumo de fluxo HA multi-região + landscape as-built - scripts/ — geradores de diagrama, construtor de conjunto de ícones, buscador de assets, exportador raster - src/rule_engine/ — componentes centrais neutros em relação ao provedor e pontos de entrada de CLI Cada exemplo é entregue como o trio completo de artefatos (fonte .drawio, .drawio.png exportado e companheiro .diagram.md) e segue um padrão de layout: ícones uniformes de 78×78, ordem de faixas fixa, limites externos/internos tracejados na cor de marca do perfil, marcadores de fluxo numerados com uma legenda Flow à direita, bloco Legend padrão e roteamento imposto por geometria. Cada nuvem entrega três diagramas: uma visão de fluxo de aplicação (01) e o par sancionado HA multi-região — um resumo de fluxo (≤12 nós) com link cruzado para um landscape as-built (~34 nós) do mesmo sistema ativo-passivo. O fluxo de aplicação e o resumo exportam em ≤1600px; o landscape exporta em largura ampla (≤3600px). Os ícones são os glifos oficiais do provedor, resolvidos por meio de mappings/icon-index.json. Mecanismos de ícones por nuvem: stencils integrados mxgraph.aws4.* da AWS; formas de imagem por caminho de arquivo azure2 do Azure; ícones oficiais GCP 2025 por caminho de arquivo (produto primeiro, categoria como fallback); stencils incorporados do OCI do pacote oficial do draw.io; formas base em escala de cinza genéricas. Início rápido: instale com pip install -e ., que expõe scripts de console: rule-engine-lint (executa o conjunto de regras de lint sobre diagramas e documentos Markdown), rule-engine-validate-schema (valida recursos normalizados contra o schema), rule-engine-build-icon-sets (busca pacotes oficiais de ícones e constrói o icon-index.json versionado), rule-engine-verify-icon (resolve cada referência de ícone em um .drawio contra a fonte autoritativa), rule-engine-check-rasters (impõe orçamento de PNG exportado ciente da classe), rule-engine-check-snapshot (impõe o formato da pasta Snapshot de inventário), rule-engine-index-assets / rule-engine-check-asset-paths (indexação de assets / guarda de caminhos). Exemplos de invocações de lint: rule-engine-lint --all --fail-on error,critical e rule-engine-lint --file examples/aws/01-aws-agent-platform.drawio --fail-on error,critical. Valide recursos normalizados de exemplo com rule-engine-validate-schema --schema schemas/inventory.schema.json --targets 'examples/**/*.json'. Os seis documentos de steering estão sempre ativos, então assim que o projeto é aberto em um workspace Kiro, cada turno do agente herda automaticamente as regras de diagrama, inventário, perfil, frontmatter, lint e pacote de assets. Além do steering sempre ativo, o workspace entrega configurações Kiro criadas para fins específicos: três agentes personalizados (diagram-author para autoria/regeneração de diagramas e execução do gate; inventory-collector para coleta estritamente somente leitura com contrato de zero mutação codificado como permissões; rule-engine-reviewer para gate de verificação somente leitura), uma skill sob demanda com fluxo de trabalho de geração de artefatos e comandos exatos de gate, e um Kiro power compartilhável empacotando a skill mais o servidor MCP AWS-docs somente leitura. Contribuições são bem-vindas. O projeto inclui um Contributing Guide, Code of Conduct (Contributor Covenant), Security Policy e MIT License. Relatórios de bugs e solicitações de recursos podem ser abertos via GitHub issues, e mudanças enviadas como pull requests usando o template de PR. Os links incluem Installation Guide, Kiro University compliance mapping, Add a New Provider Runbook, Diagram Design Notes, documentação de Architecture e Changelog.