| id | omni-architect |
| name | Omni Architect |
| description | Skill de orquestração que transforma um PRD (Product Requirements Document) em diagramas Mermaid para pré-validação do product logic, e após validação gera os design assets no Figma automaticamente. Orquestra as skills de PRD parsing, Mermaid diagrams e Figma asset generation em um pipeline unificado.
|
| author | fabioeloi |
| version | 1.0.0 |
| created | 2026-02-06 |
| updated | 2026-03-19 |
| license | MIT |
| category | ["Orchestration","Product Design","Architecture"] |
| tags | ["prd","mermaid","figma","orchestration","product-logic","validation","design-system","frontend","architecture","workflow"] |
| inputs | [{"name":"prd_source","type":"string","required":true,"description":"O PRD completo em formato Markdown, ou o caminho/URL para o documento PRD. Aceita PRDs estruturados com seções de features, user stories, requisitos funcionais e não-funcionais.\n"},{"name":"project_name","type":"string","required":true,"description":"Nome do projeto que será usado como namespace nos diagramas e no Figma."},{"name":"figma_file_key","type":"string","required":true,"description":"A chave do arquivo Figma onde os assets serão gerados (extraída da URL do Figma: https://www.figma.com/file/<FILE_KEY>/...).\n"},{"name":"figma_access_token","type":"string","required":true,"description":"Token de acesso pessoal do Figma. Continua obrigatório por compatibilidade de contrato, mas nesta v1 plugin-based a mutação do canvas é feita pelo plugin, não pela REST API.\n"},{"name":"diagram_types","type":"array","required":false,"default":["flowchart","sequence","erDiagram","stateDiagram","C4Context"],"description":"Lista dos tipos de diagrama Mermaid a serem gerados. Valores possíveis: flowchart, sequence, erDiagram, classDiagram, stateDiagram, C4Context, journey, gantt.\n"},{"name":"design_system","type":"string","required":false,"default":"material-3","description":"Sistema de design base para geração dos assets no Figma. Valores: material-3, apple-hig, tailwind, custom.\n"},{"name":"validation_mode","type":"string","required":false,"default":"interactive","description":"Modo de validação dos diagramas antes da geraç��o Figma. interactive: aguarda aprovação humana por diagrama. batch: apresenta todos e aguarda aprovação geral. auto: aprova automaticamente se o score >= validation_threshold.\n"},{"name":"validation_threshold","type":"number","required":false,"default":0.85,"description":"Score mínimo (0.0 a 1.0) de coerência lógica para auto-aprovação dos diagramas quando validation_mode=auto.\n"},{"name":"locale","type":"string","required":false,"default":"pt-BR","description":"Idioma para labels, anotações e documentação gerada."}] |
| outputs | [{"name":"parsed_prd","type":"object","description":"PRD parseado e estruturado com features, user stories, entidades, fluxos e requisitos extraídos.\n"},{"name":"mermaid_diagrams","type":"array","description":"Array de objetos contendo o tipo do diagrama, o código Mermaid, o score de coerência e o status de validação.\n"},{"name":"validation_report","type":"object","description":"Relatório de validação com score geral, inconsistências detectadas, sugestões de melhoria e status final (approved/rejected/pending).\n"},{"name":"figma_assets","type":"array","description":"Array de objetos contendo os IDs dos nodes criados no Figma, tipo de asset (screen, component, flow), e URLs de preview.\n"},{"name":"orchestration_log","type":"object","description":"Log completo da orquestração com timestamps, duração de cada fase, erros/warnings e métricas de qualidade.\n"}] |
| dependencies | ["softaworks/agent-toolkit (mermaid-diagrams)","hoodini/ai-agents-skills (figma)","jamesrochabrun/skills (prd-generator)","anthropics/skills (frontend-design)","anthropics/skills (skill-creator)"] |
| permissions | ["figma.api.write","figma.api.read","filesystem.read","filesystem.write","network.https"] |
🏗️ 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:
| Elemento | Descrição |
|---|
features | Lista de funcionalidades com prioridade e complexidade |
user_stories | User stories no formato "Como X, quero Y, para Z" |
entities | Entidades de domínio e seus atributos |
flows | Fluxos de negócio e suas etapas |
requirements | Requisitos funcionais e não-funcionais |
acceptance_criteria | Critérios de aceite por feature |
dependencies | Dependências entre features |
personas | Personas identificadas |
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:
| Elemento PRD | Tipo Mermaid | Propósito |
|---|
flows | flowchart TD | Visualizar fluxos de negócio |
user_stories | sequenceDiagram | Interações entre atores e sistema |
entities | erDiagram | Modelo de dados e relacionamentos |
features.states | stateDiagram-v2 | Máquinas de estado por feature |
system_overview | C4Context | Visão arquitetural de alto nível |
personas + journeys | journey | User journey maps |
dependencies + timeline | gantt | Roadmap e dependências temporais |
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:
| Critério | Peso | Descrição |
|---|
coverage | 0.25 | % de features/stories representadas nos diagramas |
consistency | 0.25 | Entidades e fluxos consistentes entre diagramas |
completeness | 0.20 | Todos os caminhos (happy/sad path) representados |
traceability | 0.15 | Rastreabilidade diagrama ↔ requisito do PRD |
naming_coherence | 0.10 | Consistência de nomenclatura entre diagramas |
dependency_integrity | 0.05 | Dependências entre features respeitadas |
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:
| Diagrama Mermaid | Asset Figma | Descrição |
|---|
flowchart | User Flow Page | Wireframes de fluxo com telas conectadas |
sequenceDiagram | Interaction Spec Component | Especificação de interações por tela |
erDiagram | Data Model Documentation | Documentação visual do modelo de dados |
stateDiagram | State Management Component | Estados de UI por componente |
C4Context | Architecture Overview Page | Diagrama arquitetural estilizado |
journey | User Journey Map Frame | Mapa visual da jornada do usuário |
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:
| Artefato | Formato | Descrição |
|---|
| PRD Parseado | JSON | Estrutura semântica extraída do PRD |
| Diagramas Mermaid | .mmd + SVG/PNG | Código fonte + renders dos diagramas |
| Relatório de Validação | JSON + Markdown | Score e detalhes da validação lógica |
| Figma Assets | Figma Nodes | Links diretos para os frames no Figma |
| Orchestration Log | JSON | Log completo com métricas e timeline |
| Design Handoff Doc | Markdown | Documento de handoff para desenvolvedores |
Usage
Instalação
npx skills add https://github.com/fabioeloi/omni-architect --skill omni-architect
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
| Cenário | Comportamento |
|---|
| PRD incompleto (score < 0.6) | Emite warnings + sugestões, continua com dados disponíveis |
| PRD sem user stories | Gera somente ER e C4, pula sequence diagrams |
| Mermaid syntax inválida | Retry com correção automática (max 3 tentativas) |
| Figma API rate limit | Exponential backoff (1s, 2s, 4s, 8s) com max 5 retries |
| Figma token expirado | Erro claro com instrução para renovar token |
| Validação rejeitada (interactive) | Captura feedback do usuário e regenera diagrama específico |
| Entidades ambíguas no PRD | Lista ambiguidades no validation_report.warnings |
| Diagrama muito complexo (>100 nós) | Auto-split em sub-diagramas com diagrama de índice |
| Network timeout | Retry com timeout progressivo, salva estado para resumo |
| PRD em idioma diferente do locale | Auto-detecta idioma e traduz labels conforme locale config |
Configuration File (Optional)
Crie um arquivo .omni-architect.yml na raiz do projeto para configurações persistentes:
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
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:
on_validation_approved: "npm run generate:specs"
on_figma_complete: "npm run notify:slack"
on_error: "npm run alert:team"
Best Practices & Safety
- Nunca exponha tokens em logs — o orchestration_log sanitiza automaticamente valores sensíveis
- Valide o PRD antes — quanto mais completo o PRD, melhores os diagramas gerados
- Use modo interactive na primeira execução — para calibrar a qualidade antes de usar auto
- Revise entidades do ER Diagram — são a base para todo o restante do pipeline
- Mantenha o PRD atualizado — re-execute após mudanças significativas no escopo
- Use design tokens customizados — para garantir alinhamento com o brand guide existente
- Configure hooks — para integrar com seu workflow existente (Slack, Jira, CI/CD)
Troubleshooting
| Problema | Solução |
|---|
| "PRD parsing failed" | Verifique se o PRD segue estrutura Markdown com headings |
| "Mermaid syntax error" | Cheque caracteres especiais no PRD (quotes, brackets) |
| "Figma API 403" | Verifique permissões do token e acesso ao arquivo |
| "Low coverage score" | Adicione mais detalhes nas seções de fluxos e stories |
| "Diagrams not matching PRD" | Use validation_mode=interactive para feedback granular |
| "Rate limit exceeded" | Aguarde 60s ou use uma service account Figma |
| "Timeout on large PRD" | Divida o PRD em módulos e execute por módulo |
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
