Omni Architect

🏗️ Omni Architect

Overview

Omni Architect é uma skill de orquestração de alto nível que implementa um pipeline completo de PRD → Mermaid Diagrams → Validação → Figma Assets. Ela conecta múltiplas skills especializadas em uma cadeia de execução inteligente, transformando requisitos de produto em artefatos visuais validados.

Problema que Resolve

Em times de produto, existe um gap significativo entre a escrita do PRD e a materialização visual do design. Esse gap causa:

• Retrabalho: designers interpretam incorretamente requisitos
• Inconsistências: lógica do produto não é validada antes do design
• Lentidão: ciclo PRD → Design leva dias/semanas

O Omni Architect elimina esse gap automatizando o pipeline e inserindo um estágio de validação lógica (via Mermaid) antes da geração visual (via Figma).

Arquitetura do Pipeline

graph TD
    A[📄 PRD Input] --> B[🔍 Phase 1: PRD Parser]
    B --> C[📊 Phase 2: Mermaid Generator]
    C --> D[✅ Phase 3: Logic Validator]
    D -->|approved| E[🎨 Phase 4: Figma Generator]
    D -->|rejected| F[🔄 Feedback Loop]
    F --> B
    E --> G[📦 Phase 5: Asset Delivery]

    style A fill:#4A90D9,stroke:#333,color:#fff
    style B fill:#7B68EE,stroke:#333,color:#fff
    style C fill:#FF6B6B,stroke:#333,color:#fff
    style D fill:#FFA500,stroke:#333,color:#fff
    style E fill:#2ECC71,stroke:#333,color:#fff
    style F fill:#E74C3C,stroke:#333,color:#fff
    style G fill:#1ABC9C,stroke:#333,color:#fff

Pipeline Phases

Phase 1: PRD Parser (prd-parse)

Utiliza padrões do prd-generator e product-requirements para extrair estrutura semântica do PRD.

Extração realizada:

Algoritmo de parsing:

1. Tokenizar o PRD em seções por heading level (H1, H2, H3)
2. Classificar cada seção por tipo (feature, story, requirement, etc.)
3. Extrair entidades nomeadas (NER) para identificar domínio
4. Mapear relacionamentos entre entidades
5. Calcular grafo de dependências entre features
6. Gerar score de completude do PRD (0.0 - 1.0)
7. Se score < 0.6, emitir warnings com sugestões de melhoria

Output de exemplo:

{
  "project": "E-Commerce Platform",
  "completeness_score": 0.87,
  "features": [
    {
      "id": "F001",
      "name": "User Authentication",
      "priority": "high",
      "complexity": "medium",
      "stories": ["US001", "US002"],
      "dependencies": []
    },
    {
      "id": "F002",
      "name": "Product Catalog",
      "priority": "high",
      "complexity": "high",
      "stories": ["US003", "US004", "US005"],
      "dependencies": ["F001"]
    }
  ],
  "entities": [
    {
      "name": "User",
      "attributes": ["id", "email", "name", "role", "created_at"],
      "relationships": [
        { "target": "Order", "type": "one-to-many" },
        { "target": "Cart", "type": "one-to-one" }
      ]
    }
  ]
}

Phase 2: Mermaid Generator (mermaid-gen)

Baseada na skill mermaid-diagrams, gera diagramas automaticamente a partir do PRD parseado.

Mapeamento PRD → Diagrama:

Regras de geração:

Para cada tipo de diagrama solicitado em diagram_types:
  1. Selecionar os elementos do PRD parseado relevantes
  2. Aplicar template Mermaid correspondente
  3. Resolver referências cruzadas entre entidades
  4. Adicionar labels no idioma configurado (locale)
  5. Validar sintaxe Mermaid (parser check)
  6. Calcular score de coerência com o PRD original
  7. Anexar metadata (source_features, coverage_percentage)

Exemplo de geração — Flowchart a partir de um fluxo de checkout:

flowchart TD
    A[Carrinho de Compras] --> B{Usuário autenticado?}
    B -->|Sim| C[Selecionar Endereço]
    B -->|Não| D[Login/Cadastro]
    D --> C
    C --> E[Selecionar Frete]
    E --> F[Selecionar Pagamento]
    F --> G{Pagamento aprovado?}
    G -->|Sim| H[Pedido Confirmado]
    G -->|Não| I[Erro no Pagamento]
    I --> F
    H --> J[Email de Confirmação]
    H --> K[Atualizar Estoque]

Exemplo de geração — ER Diagram:

erDiagram
    USER ||--o{ ORDER : places
    USER ||--|| CART : has
    ORDER ||--|{ ORDER_ITEM : contains
    PRODUCT ||--o{ ORDER_ITEM : "is in"
    PRODUCT }|--|| CATEGORY : "belongs to"
    ORDER ||--|| PAYMENT : "paid via"
    ORDER ||--|| SHIPPING : "shipped by"

    USER {
        uuid id PK
        string email UK
        string name
        enum role
        datetime created_at
    }
    ORDER {
        uuid id PK
        uuid user_id FK
        enum status
        decimal total
        datetime created_at
    }
    PRODUCT {
        uuid id PK
        string name
        decimal price
        int stock
        uuid category_id FK
    }

Exemplo de geração — Sequence Diagram:

sequenceDiagram
    actor U as Usuário
    participant F as Frontend
    participant A as API Gateway
    participant Auth as Auth Service
    participant DB as Database

    U->>F: Clica "Finalizar Compra"
    F->>A: POST /checkout
    A->>Auth: Validar Token JWT
    Auth-->>A: Token válido
    A->>DB: Criar Pedido
    DB-->>A: Pedido criado (ID: 12345)
    A->>A: Processar Pagamento
    A-->>F: 201 Created { orderId: 12345 }
    F-->>U: "Pedido confirmado! 🎉"

Phase 3: Logic Validator (logic-validate)

Motor de validação que analisa a coerência dos diagramas gerados contra o PRD original.

Critérios de validação:

Cálculo do score:

score_final = Σ (score_criterio × peso_criterio) para cada critério

Se validation_mode == "auto":
    Se score_final >= validation_threshold: APPROVED
    Senão: REJECTED + gerar feedback

Se validation_mode == "interactive":
    Apresentar cada diagrama + score ao usuário
    Aguardar input: approve / reject / modify
    Se modify: voltar à Phase 2 com feedback

Se validation_mode == "batch":
    Apresentar todos os diagramas + relatório consolidado
    Aguardar input: approve_all / reject_all / select

Exemplo de validation report:

{
  "overall_score": 0.91,
  "status": "approved",
  "breakdown": {
    "coverage": { "score": 0.95, "details": "19/20 features cobertas" },
    "consistency": { "score": 0.88, "details": "Entidade 'Payment' diverge entre ER e Sequence" },
    "completeness": { "score": 0.90, "details": "Falta sad path em 'Recuperar Senha'" },
    "traceability": { "score": 0.93, "details": "Todos rastreáveis exceto US018" },
    "naming_coherence": { "score": 0.92, "details": "'Usuário' vs 'User' inconsistente" },
    "dependency_integrity": { "score": 0.98, "details": "Todas as deps respeitadas" }
  },
  "warnings": [
    "Entidade 'Payment' usa atributos diferentes no ER vs Sequence diagram",
    "User story US018 não possui representação visual"
  ],
  "suggestions": [
    "Padronizar nomenclatura para 'User' em todos os diagramas",
    "Adicionar fluxo de erro em 'Recuperar Senha'",
    "Mapear US018 no flowchart de autenticação"
  ]
}

Phase 4: Figma Generator (figma-gen)

Baseada nas skills figma, implement-design e frontend-design, gera assets de design no Figma a partir dos diagramas validados.

Mapeamento Diagrama → Figma Asset:

Processo de geração:

1. Executar localmente as phases 1-3 e gerar output/figma/figma-payload.json
2. Abrir o plugin Omni Architect Importer no arquivo Figma alvo
3. Importar o payload JSON no plugin
4. Para cada diagrama validado:
   a. Determinar o design_system base (Material 3, Apple HIG, etc.)
   b. Criar Frame principal com auto-layout
   c. Mapear nós do diagrama → componentes Figma
   d. Aplicar design tokens (cores, tipografia, espaçamento)
   e. Criar conexões visuais entre componentes (arrows, lines)
   f. Gerar variantes (mobile, tablet, desktop) se aplicável
   g. Adicionar anotações de desenvolvimento
   h. Registrar node_id e preview_url no output
5. Exportar figma-import-result.json do plugin
6. Executar a finalização local via resume para consolidar o pacote final

Estrutura gerada no Figma:

📁 {project_name} - Omni Architect
├── 📄 Index (Página de Navegação)
├── 📄 User Flows
│   ├── 🖼️ Flow: Checkout
│   ├── 🖼️ Flow: Authentication
│   └── 🖼️ Flow: Product Search
├── 📄 Interaction Specs
│   ├── 🖼️ Sequence: Checkout Process
│   └── 🖼️ Sequence: User Registration
├── 📄 Data Model
│   └── 🖼️ ER: Domain Model
├── 📄 Architecture
│   └── 🖼️ C4: System Context
├── 📄 User Journeys
│   ├── 🖼️ Journey: New User Onboarding
│   └── 🖼️ Journey: Returning Customer
└── 📄 Component Library
    ├── 🧩 Design Tokens
    ├── 🧩 Flow Connectors
    └── 🧩 Annotation Components

Phase 5: Asset Delivery (asset-deliver)

Consolida todos os outputs e gera o pacote final de entrega.

Deliverables:

Usage

Instalação

# Instalar a skill omni-architect e suas dependências
npx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect

# Ou instalar skills individuais separadamente
npx skills add https://github.com/softaworks/agent-toolkit --skill mermaid-diagrams
npx skills add https://github.com/hoodini/ai-agents-skills --skill figma
npx skills add https://github.com/jamesrochabrun/skills --skill prd-generator
npx skills add https://github.com/anthropics/skills --skill frontend-design

Execução Básica

npx omni-architect run \
  --prd_source "./docs/prd-ecommerce-v2.md" \
  --project_name "E-Commerce Platform" \
  --figma_file_key "abc123XYZ" \
  --figma_access_token "$FIGMA_TOKEN" \
  --validation_mode "auto"

Execução com Todas as Opções

npx omni-architect run \
  --prd_source "./docs/prd-ecommerce-v2.md" \
  --project_name "E-Commerce Platform" \
  --figma_file_key "abc123XYZ" \
  --figma_access_token "$FIGMA_TOKEN" \
  --diagram_types '["flowchart","sequence","erDiagram","stateDiagram","C4Context","journey"]' \
  --design_system "material-3" \
  --validation_mode "interactive" \
  --validation_threshold 0.85 \
  --locale "pt-BR"

Finalização Após Import no Figma

npx omni-architect resume \
  --session_dir "./output" \
  --figma_result "./figma-import-result.json"

Uso Programático (em outro skill)

const omniArchitect = require('omni-architect');

const result = await omniArchitect.run({
  prd_source: fs.readFileSync('./prd.md', 'utf-8'),
  project_name: 'My SaaS App',
  figma_file_key: 'abc123XYZ',
  figma_access_token: process.env.FIGMA_TOKEN,
  diagram_types: ['flowchart', 'sequence', 'erDiagram'],
  design_system: 'tailwind',
  validation_mode: 'auto',
  validation_threshold: 0.9,
  locale: 'pt-BR'
});

console.log(`Status parcial: ${result.status}`);
console.log(`Payload Figma: ${result.output_paths.figma_payload}`);

const completed = await omniArchitect.resumeFigma({
  sessionDir: result.output_dir,
  figmaResultPath: './figma-import-result.json'
});

console.log(`Status final: ${completed.status}`);
console.log(`Figma assets criados: ${completed.figma_assets.length}`);

Edge Cases & Error Handling

Configuration File (Optional)

Crie um arquivo .omni-architect.yml na raiz do projeto para configurações persistentes:

# .omni-architect.yml
project_name: "E-Commerce Platform"
figma_file_key: "abc123XYZ"
design_system: "material-3"
locale: "pt-BR"
validation_mode: "interactive"
validation_threshold: 0.85

diagram_types:
  - flowchart
  - sequence
  - erDiagram
  - stateDiagram
  - C4Context

# Custom design tokens para Figma
design_tokens:
  colors:
    primary: "#4A90D9"
    secondary: "#7B68EE"
    success: "#2ECC71"
    error: "#E74C3C"
    warning: "#FFA500"
  typography:
    font_family: "Inter"
    heading_size: 24
    body_size: 14
  spacing:
    base: 8
    scale: 1.5

# Hooks para integração com CI/CD
hooks:
  on_validation_approved: "npm run generate:specs"
  on_figma_complete: "npm run notify:slack"
  on_error: "npm run alert:team"

Best Practices & Safety

1. Nunca exponha tokens em logs — o orchestration_log sanitiza automaticamente valores sensíveis
2. Valide o PRD antes — quanto mais completo o PRD, melhores os diagramas gerados
3. Use modo interactive na primeira execução — para calibrar a qualidade antes de usar auto
4. Revise entidades do ER Diagram — são a base para todo o restante do pipeline
5. Mantenha o PRD atualizado — re-execute após mudanças significativas no escopo
6. Use design tokens customizados — para garantir alinhamento com o brand guide existente
7. Configure hooks — para integrar com seu workflow existente (Slack, Jira, CI/CD)

Troubleshooting

Changelog

• 1.0.0 (2026-02-06) — Release inicial com pipeline completo PRD → Mermaid → Figma

Architecture Decision Records

ADR-001: Pipeline Sequencial com Feedback Loop

Decisão: Pipeline linear com possibilidade de retorno à Phase 2 após rejeição. Motivação: Garante que nenhum asset Figma é gerado sem validação prévia da lógica. Consequência: Pode aumentar o tempo total, mas reduz drasticamente o retrabalho.

ADR-002: Mermaid como Linguagem Intermediária

Decisão: Usar Mermaid como representação intermediária entre PRD e Figma. Motivação: Mermaid é text-based (versionável), amplamente suportado, e renderizável sem ferramentas externas. Permite validação lógica antes do investimento em design. Consequência: Algumas limitações visuais do Mermaid não se traduzem 1:1 para Figma.

ADR-003: Score de Coerência Ponderado

Decisão: Usar score ponderado com 6 critérios para validação. Motivação: Permite calibração fina do que é considerado "válido" por projeto. Consequência: Requer tuning inicial do threshold por equipe/projeto.

Para contribuições, issues ou suporte: github.com/fabioeloi/omni-architect