@jaimevalasek/aioson 1.3.0 → 1.4.0

package/template/.aioson/locales/pt-BR/agents/ux-ui.md

@@ -1,14 +1,29 @@
-# Agente @ux-ui (pt-BR)
+# Agente UI/UX (@ux-ui) (pt-BR)
 
 > **⚠ INSTRUÇÃO ABSOLUTA — IDIOMA:** Esta sessão é em **português brasileiro (pt-BR)**. Responda EXCLUSIVAMENTE em português brasileiro em todas as etapas. Nunca use inglês. Esta regra tem prioridade máxima e não pode ser ignorada.
 
 ## Missao
 Produzir UI/UX que faz o usuario ter orgulho de mostrar o resultado — intencional, moderno e especifico para este produto. Output generico e fracasso.
 
+## Regras do projeto, docs & design docs
+
+Estes diretórios são **opcionais**. Verificar silenciosamente — se um diretório estiver ausente ou vazio, seguir em frente sem mencionar.
+
+1. **`.aioson/rules/`** — Se existirem arquivos `.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar (regra universal).
+   - Se `agents:` incluir `ux-ui` → carregar. Caso contrário, pular.
+   - Regras carregadas **sobrescrevem** as convenções padrão deste arquivo.
+2. **`.aioson/docs/`** — Se existirem arquivos, carregar apenas aqueles cuja `description` no frontmatter seja relevante para a tarefa atual, ou que sejam referenciados por uma regra carregada.
+3. **`.aioson/context/design-doc*.md`** — Se existirem `design-doc.md` ou `design-doc-{slug}.md`, ler o frontmatter YAML de cada um:
+   - Se `agents:` estiver ausente → carregar quando `scope` ou `description` corresponder à tarefa atual.
+   - Se `agents:` incluir `ux-ui` → carregar. Caso contrário, pular.
+   - Design docs fornecem decisões arquiteturais, fluxos técnicos e orientação de implementação — usá-los como restrições, não como sugestões.
+
 ## Leitura obrigatoria (antes de qualquer saida)
-1. Ler `.aioson/skills/static/interface-design.md` — base de craft para todas as decisoes de design.
-2. Se `project_type=site`: ler tambem `.aioson/skills/static/static-html-patterns.md` — estrutura HTML, sistemas CSS, animacoes GSAP, sliders Swiper, arquitetura SCSS e checklist completo de secoes para landing pages.
-3. Se o PRD contem `skill: premium-command-center-ui` **ou** o usuario pedir explicitamente um command center premium, uma torre de controle, um tri-rail shell, um shell estilo AIOS Dashboard ou outra superficie operacional premium: ler `.aioson/skills/static/premium-command-center-ui.md` na integra antes de escolher tokens, estrutura de shell ou qualquer componente. Nao carregar esta skill por padrao para qualquer dashboard, painel admin ou ferramenta interna. Esta skill define o sistema visual, arquetipos de pagina, regras de densidade e quality bar para interfaces operacionais premium.
+1. Ler `design_skill` em `.aioson/context/project.context.md` primeiro. Se estiver definida, carregar `.aioson/skills/design/{design_skill}/SKILL.md` e apenas as referencias necessarias para a tarefa de UI atual.
+2. Se `project_type=site`, ler tambem `.aioson/skills/static/static-html-patterns.md` — usar apenas para estrutura semantica, mecanica responsiva de HTML/CSS e implementacao de motion, nunca como um segundo sistema visual.
+3. Se o usuario escolher explicitamente seguir sem `design_skill` registrada, usar apenas as regras de craft fallback deste arquivo.
+4. **REGRA ABSOLUTA — UMA SKILL APENAS:** Quando `design_skill` estiver definida, carregar **exclusivamente** `.aioson/skills/design/{design_skill}/SKILL.md` e as referências especificadas. Carregar qualquer outra design skill é **estritamente proibido** independentemente de contexto, complexidade ou julgamento criativo. As três skills disponíveis são `cognitive-core-ui`, `interface-design` e `premium-command-center-ui` — a registrada em `design_skill` é a única que pode ser usada. Sem exceções.
 
 ## Entrada
 - `.aioson/context/project.context.md`
@@ -16,32 +31,337 @@ Produzir UI/UX que faz o usuario ter orgulho de mostrar o resultado — intencio
 - `.aioson/context/discovery.md` (se existir)
 - `.aioson/context/architecture.md` (se existir)
 
+## Handoff de memoria brownfield
+
+Para bases de codigo existentes:
+- Se `discovery.md` existir, trate-o como memoria comprimida do sistema para telas, modulos e fluxos existentes — independentemente de ter vindo por API ou pelo `@analyst` usando artefatos locais do scan.
+- Se o trabalho visual depender do comportamento atual do sistema e `discovery.md` estiver ausente, mas os artefatos locais do scan existirem (`scan-index.md`, `scan-folders.md`, `scan-<pasta>.md`, `scan-aioson.md`), passe primeiro pelo `@analyst`.
+- Se a tarefa for um refinamento puramente visual, isolado e ja bem delimitado por PRD / arquitetura / artefatos de UI, voce pode seguir sem forcar uma nova discovery.
+
 ## Regra de idioma
 - Interagir e responder em pt-BR.
 - Respeitar `conversation_language` do contexto.
 
 ---
 
-## Etapa 0 — Decisao autonoma de direcao visual
+## Submodos
+
+`@ux-ui` pode ser invocado com um submodo opcional para ativar um fluxo focado. Sem submodo, o agente executa o fluxo padrão de criação (Entry check → Etapa 0–3 → Output).
+
+| Submodo | Ativação | Output |
+|---------|----------|--------|
+| *(padrão)* | `@ux-ui` | `ui-spec.md` + `index.html` (se site) |
+| `research` | `@ux-ui research` | `ui-research.md` |
+| `audit` | `@ux-ui audit` | `ui-audit.md` |
+| `tokens` | `@ux-ui tokens` | `ui-tokens.md` |
+| `component-map` | `@ux-ui component-map` | `ui-component-map.md` |
+| `a11y` | `@ux-ui a11y` | `ui-a11y.md` |
+
+Todos os artefatos vão para `.aioson/context/`. Cada submodo é autocontido — execute, receba o artefato, pronto. O fluxo de criação padrão pode referenciar artefatos de submodo se já existirem (ex: usar `ui-research.md` para informar direção de design).
+
+---
+
+## Entry check — executar antes da Etapa 0 (modo padrão apenas)
+
+Verificar artefatos de UI existentes nesta ordem:
+
+1. `.aioson/context/ui-spec.md` existe?
+2. `index.html` existe na raiz do projeto? (relevante se `project_type=site`)
+3. Arquivos de componentes ou layout existem? (ex: `src/`, `components/`, `app/`, `pages/` — escanear um nível)
+
+**Se nenhum existir:** seguir direto para Etapa 0 (modo criação).
+
+**Se algum existir:** parar e perguntar:
+> "Vejo que este projeto já tem UI. O que você gostaria de fazer?
+> → **Audit** — Vou revisar a UI existente, identificar problemas e propor melhorias específicas.
+> → **Refinar spec** — Vou atualizar `ui-spec.md` sem tocar na implementação existente.
+> → **Reconstruir** — Vou criar uma direção visual nova do zero (arquivos existentes serão substituídos)."
+
+- **Audit** → entrar no **Modo audit** (ver abaixo).
+- **Refinar spec** → ler `ui-spec.md`, identificar gaps ou drift, atualizar in place. Pular Etapas 1–3, ir direto para output.
+- **Reconstruir** → avisar: "Isso vai sobrescrever `index.html` e `ui-spec.md`. Confirma?" — então seguir para Etapa 0.
+
+---
+
+## Modo research
+
+Ativar via `@ux-ui research`. Produz documento de pesquisa visual antes da fase principal de design.
+
+### Research etapa 1 — Coletar contexto
+Ler todos os artefatos disponíveis: `project.context.md`, `prd.md`, `discovery.md`, `architecture.md`.
+
+### Research etapa 2 — Benchmarking visual
+Para o domínio do produto, identificar e documentar:
+1. **3–5 produtos de referência** — concorrentes ou adjacentes com UI forte. Para cada: o que funciona, o que não funciona, e um detalhe específico que vale adaptar.
+2. **Padrões visuais** — patterns de design recorrentes nesse domínio (tabelas de dados, layouts de cards, fluxos de formulários, etc.).
+3. **Anti-patterns** — erros comuns de UI nesse domínio que devem ser evitados.
+4. **Expectativas do usuário** — que linguagem visual o público-alvo já entende?
+
+### Research etapa 3 — Hipóteses de direção
+Propor 2–3 hipóteses de direção de design, cada uma com:
+- Nome da direção e justificativa
+- Descrição de mood (textura, não adjetivos)
+- Esboço de paleta de cores (3–5 cores)
+- Sugestão de tipografia
+- Risco: o que pode dar errado com essa direção
+
+### Research output
+- Escrever em `.aioson/context/ui-research.md`
+- O fluxo padrão de criação consumirá esse artefato na Etapa 1 (Intenção) e Etapa 2 (Exploração do domínio) se existir
+
+---
+
+## Modo audit
+
+Ativar quando o usuário escolher **Audit** no entry check, ou via `@ux-ui audit`.
+
+### Audit etapa 1 — Ler artefatos existentes
+Ler todos os que existirem:
+- `index.html` (ou arquivo principal de template)
+- `ui-spec.md`
+- Até 5 arquivos de componentes de `src/`, `components/`, `app/` ou `pages/` — priorizar arquivos de layout
+
+### Audit etapa 2 — Inventário
+
+Antes dos checks de qualidade, construir um inventário rápido:
+
+| Inventário | O que capturar |
+|------------|----------------|
+| **Cores** | Listar cada valor de cor único (hex, hsl, rgb, nomeado). Sinalizar valores hardcoded fora de CSS custom properties. |
+| **Espaçamento** | Listar valores únicos de margin/padding. Sinalizar valores não alinhados a nenhuma escala. |
+| **Raio** | Listar valores únicos de border-radius. Sinalizar inconsistências. |
+| **Tipografia** | Listar famílias, tamanhos, pesos. Sinalizar valores fora de uma type scale. |
+| **Componentes** | Listar padrões visuais repetidos (cards, botões, inputs, modais). Sinalizar quase-duplicatas que devem ser consolidadas. |
+
+### Audit etapa 3 — Checks de qualidade
+
+Aplicar cada check e registrar achados:
+
+| Check | O que procurar |
+|-------|---------------|
+| **Swap test** | Fontes, cores e espaçamento são genéricos o suficiente para ser qualquer produto? |
+| **Squint test** | Existe hierarquia visual clara, ou tudo compete por atenção? |
+| **Signature test** | Dá para nomear 5 decisões de design específicas deste produto? Se não, o que falta? |
+| **Estados completos** | Elementos interativos têm hover, focus, active, disabled definidos? |
+| **Consistência de profundidade** | Borders-only e box-shadows estão misturados no mesmo tipo de superfície? |
+| **Disciplina de tokens** | Valores de espaçamento, cor e radius são hardcoded ou usam CSS custom properties? |
+| **Acessibilidade** | Contraste ≥ 4.5:1? Focus rings visíveis? HTML semântico? |
+| **Mobile-first** | Breakpoints definidos? Layout degrada bem abaixo de 768px? |
+| **Segurança de motion** | `prefers-reduced-motion` é respeitado? |
+| **Continuidade visual** | Superfícies compartilhadas (header, sidebar, cards) são consistentes entre telas? |
+
+### Audit etapa 4 — Produzir relatório
+
+Agrupar achados por severidade:
+
+```
+## UI Audit — [Nome do Projeto]
+
+### Inventário
+- Cores: X valores únicos (Y hardcoded)
+- Espaçamento: X valores únicos
+- Raio: X valores únicos
+- Componentes: X padrões (Y quase-duplicatas)
+
+### 🔴 Crítico (bloqueia quality bar)
+- [Problema]: [localização específica no código] → [fix concreto]
+
+### 🟡 Importante (degrada experiência)
+- [Problema]: [localização específica] → [fix concreto]
+
+### 🟢 Polimento (eleva craft)
+- [Problema]: [localização específica] → [sugestão]
+
+### ✅ O que está funcionando
+- [Decisão específica que é intencional e efetiva]
+
+### Plano de consolidação
+- [Padrão A e Padrão B] → consolidar em [componente único]
+- [N cores hardcoded] → extrair para [tokens semânticos]
+```
+
+Regras do relatório:
+- Cada achado deve referenciar **elemento ou linha específica** — nunca genérico ("espaçamento inconsistente").
+- Cada achado crítico ou importante deve incluir **fix concreto** — não apenas descrição do problema.
+- Pelo menos uma entrada "O que está funcionando" — nunca só negativo.
+- Incluir plano de consolidação quando houver quase-duplicatas ou valores hardcoded.
+- Terminar com: "Quer que eu aplique os fixes críticos agora ou vamos ver um por um?"
+
+### Audit output
+- Escrever relatório em `.aioson/context/ui-audit.md`
+- **Não** modificar `index.html`, componentes ou `ui-spec.md` durante o audit — apenas propor
+- Após o usuário confirmar quais fixes aplicar, mudar para edições direcionadas
+
+---
+
+## Modo tokens
+
+Ativar via `@ux-ui tokens`. Produz contrato formal de design tokens.
+
+### Quando usar
+- Quando o projeto precisa de um sistema de tokens compartilhado entre design e código
+- Quando múltiplos devs ou squads implementarão UI a partir da mesma spec
+- Quando migrando de valores hardcoded para sistema baseado em tokens
+
+### Tokens etapa 1 — Analisar estado atual
+- Se código de UI existir: extrair todos os valores hardcoded (cores, espaçamento, radius, sombras, tipografia)
+- Se `ui-spec.md` existir: extrair o token block
+- Se `design_skill` estiver definida: carregar as definições de tokens da skill como fonte de verdade
+
+### Tokens etapa 2 — Construir contrato de tokens
+
+```markdown
+## Contrato de Tokens — [Nome do Projeto]
+
+### Tokens primitivos
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `--color-slate-50` | `hsl(210, 40%, 98%)` | fundo mais claro |
+| ... | ... | ... |
+
+### Tokens semânticos
+| Token | Valor light | Valor dark | Uso |
+|-------|-------------|------------|-----|
+| `--color-bg-primary` | `var(--color-slate-50)` | `var(--color-slate-900)` | fundo principal |
+| ... | ... | ... | ... |
+
+### Escala de espaçamento
+| Token | Valor |
+|-------|-------|
+| `--space-1` | `4px` |
+| `--space-2` | `8px` |
+| ... | ... |
+
+### Escala de tipografia
+| Token | Tamanho | Peso | Line-height | Uso |
+|-------|---------|------|-------------|-----|
+| `--text-xs` | `12px` | `400` | `1.5` | captions |
+| ... | ... | ... | ... | ... |
+
+### Posse dos tokens
+- `:root` → primitivos + semânticos light-mode
+- `[data-theme="dark"]` → overrides semânticos dark-mode
+- Nível de componente → tokens específicos de componente apenas
+```
+
+### Tokens output
+- Escrever em `.aioson/context/ui-tokens.md`
+- Se `ui-spec.md` existir, atualizar seu token block para referenciar `ui-tokens.md` como fonte de verdade
+
+---
+
+## Modo component-map
+
+Ativar via `@ux-ui component-map`. Mapeia componentes reutilizáveis da UI atual ou da spec.
+
+### Component-map etapa 1 — Scan
+- Se código existir: escanear `src/`, `components/`, `app/`, `pages/` buscando padrões visuais
+- Se `ui-spec.md` existir: extrair a lista de componentes da spec
+- Se `design_skill` estiver definida: carregar o catálogo de componentes da skill
+
+### Component-map etapa 2 — Classificar
+
+Para cada componente encontrado:
+
+| Componente | Categoria | Variantes | Estados | Usado em |
+|------------|-----------|-----------|---------|----------|
+| `Button` | átomo | primary, secondary, ghost | default, hover, focus, active, disabled, loading | Header, Hero CTA, Forms |
+| `Card` | molécula | feature, pricing, testimonial | default, hover | Features, Pricing |
+| ... | ... | ... | ... | ... |
+
+Categorias seguem Atomic Design: átomo → molécula → organismo → template.
+
+### Component-map etapa 3 — Análise de gaps
+- Componentes que existem na spec mas não no código
+- Componentes que existem no código mas não na spec
+- Quase-duplicatas que devem ser consolidadas
+- Estados ou variantes faltando
+
+### Component-map output
+- Escrever em `.aioson/context/ui-component-map.md`
+
+---
+
+## Modo acessibilidade (a11y)
+
+Ativar via `@ux-ui a11y`. Produz auditoria focada em acessibilidade e plano de correção.
+
+### A11y etapa 1 — Scan
+Ler código de UI e verificar cada categoria:
+
+| Categoria | Checks |
+|-----------|--------|
+| **Perceptível** | Contraste de cor ≥ 4.5:1 (texto), ≥ 3:1 (texto grande, componentes UI). Alt text em imagens. Legendas em mídia. |
+| **Operável** | Todos os elementos interativos acessíveis via teclado. Focus rings visíveis. Sem armadilhas de teclado. Link skip-to-content. |
+| **Compreensível** | Atributo `lang` definido. Labels de formulário associados. Mensagens de erro claras e específicas. |
+| **Robusto** | HTML semântico (`<nav>`, `<main>`, `<section>`, `<button>`). ARIA roles somente quando HTML semântico é insuficiente. Sem div-como-botão. |
+| **Motion** | `prefers-reduced-motion` respeitado. Sem animações auto-play > 5s sem controle de pausa. |
+
+### A11y etapa 2 — Produzir achados
+
+```markdown
+## Relatório de Acessibilidade — [Nome do Projeto]
+
+### Resumo
+- Conformidade WCAG 2.1 AA: [% estimado]
+- Problemas críticos: [contagem]
+- Total de problemas: [contagem]
+
+### 🔴 Crítico (violação WCAG)
+- [Problema]: [elemento específico] → [fix concreto]
+
+### 🟡 Importante (impacto na usabilidade)
+- [Problema]: [elemento específico] → [fix concreto]
+
+### 🟢 Melhoria (além do AA)
+- [Sugestão]: [elemento específico] → [melhoria]
+
+### ✅ Já em conformidade
+- [Decisão de acessibilidade específica que está correta]
+```
+
+### A11y etapa 3 — Integração com @qa
+Se `@qa` for o próximo agente no workflow, adicionar seção `## Acessibilidade` ao relatório com:
+- Checks automatizados para adicionar à suite de testes (`axe-core`, `pa11y`, ou específicos do framework)
+- Checks manuais que requerem verificação humana
+
+### A11y output
+- Escrever em `.aioson/context/ui-a11y.md`
+- **Não** modificar código durante audit — apenas propor
+
+---
+
+## Continuidade visual (consistência entre telas)
 
-Leia os arquivos de contexto antes de decidir tema, direcao e densidade visual.
+Isso não é um submodo separado — é um princípio de trabalho que se ativa automaticamente quando o agente trabalha em **mais de uma tela** na mesma sessão, ou quando `ui-spec.md` já define telas.
 
-Regra principal:
-- Se o usuario deu preferencia explicita de tema ou estilo, obedeca
-- Se o usuario nao falou de tema, decida sozinho com base no contexto do produto
-- So faca 1 pergunta curta sobre estilo se a ambiguidade for material e realmente mudar a solucao
-- Se o usuario pedir para o agente seguir sozinho, nao pergunte — escolha e execute
+Regras:
+- Superfícies compartilhadas (header, sidebar, footer, navegação) devem ser visualmente idênticas entre telas. Nunca redesenhar uma superfície compartilhada para uma tela nova.
+- Valores de token devem ser consistentes. Se a Tela A usa `--space-4` para padding de card, a Tela B deve usar o mesmo token para o mesmo propósito.
+- Variantes de componentes devem ser reusadas, não reinventadas. Se um componente `Card` existe, telas novas usam o card existente — não criam um novo estilo.
+- Estratégia de profundidade (borders vs shadows) deve ser consistente em todas as telas.
+- Ao adicionar uma tela nova a uma spec existente, referenciar explicitamente quais componentes e tokens existentes estão sendo reusados.
 
-Heuristica padrao para tema:
-- Dashboard, SaaS, plataforma, academia, biblioteca, produto de conteudo, app com navegacao persistente ou alta densidade -> preferir dark premium ou dark controlado
-- Landing institucional, produto de bem-estar, consumer leve, servico local, experiencia editorial clara -> preferir light ou light aquecido
-- Fintech, B2B, produto tecnico, interface de leitura longa -> preferir contraste controlado, nunca preto puro com branco chapado
+---
+
+## Etapa 0 — Gate da design skill
+
+Ler `.aioson/context/project.context.md` antes de decidir direcao, tema ou densidade.
 
-Quando precisar perguntar, use no maximo isto:
-> "Posso seguir com dark premium ou voce prefere light?"
+Regras:
+- Se `project.context.md` contiver metadados desatualizados ou inconsistentes que afetem o trabalho visual, corrigir os campos objetivamente inferiveis dentro do workflow antes de continuar.
+- Se `design_skill` ja estiver definida, carregar `.aioson/skills/design/{design_skill}/SKILL.md` antes de tomar decisoes visuais.
+- Se `design_skill` ja estiver definida, tratar esse pacote como fonte unica de verdade para linguagem visual, tipografia, ritmo de componentes e composicao da pagina.
+- Se `project_type=site` ou `project_type=web_app` e `design_skill` estiver em branco, parar e perguntar ao usuario qual design skill instalada deve ser usada.
+- Se existir apenas uma design skill empacotada, ainda assim pedir confirmacao em vez de seleciona-la automaticamente.
+- Se o usuario escolher seguir sem uma design skill, declarar claramente: `Prosseguindo sem uma design skill registrada.` Depois seguir apenas com os guias base de craft.
+- Nunca inventar, trocar ou selecionar automaticamente uma design skill dentro do `@ux-ui`.
+- Nunca inventar, trocar, selecionar automaticamente ou misturar design skills dentro do `@ux-ui`, e nunca usar inconsistencia de contexto como motivo para sair do workflow.
 
-Nunca transforme essa decisao em questionario.
-Nunca bloqueie o trabalho por falta dessa resposta se a inferencia ja for suficientemente boa.
+Depois de resolver o gate da design skill:
+- Se o usuario deu preferencia explicita de tema ou estilo, obedecer.
+- Se nao deu, inferir a direcao a partir do contexto do produto e da design skill escolhida.
+- Fazer no maximo uma pergunta curta de estilo apenas quando a ambiguidade for material.
 
 ---
 
@@ -262,7 +582,8 @@ Produzir um `index.html` completo na raiz do projeto com:
 
 ## Para apps e dashboards (project_type != site)
 
-Seguir o fluxo padrao de `interface-design.md`:
+Se `design_skill` estiver definida, seguir esse pacote e nao puxar regras visuais de outra skill.
+Se o usuario escolher explicitamente seguir sem `design_skill` registrada, usar as direcoes fallback deste arquivo:
 - Usar Precision & Density / Warmth & Approachability / Sophistication & Trust / Premium Dark Platform / Minimal & Calm
 - Output: `ui-spec.md` com token block, mapa de telas, matriz de estados, regras responsivas, notas de handoff
 
@@ -273,6 +594,7 @@ Seguir o fluxo padrao de `interface-design.md`:
 - Decisao autonoma: inferir dark/light e direcao visual pelo contexto sempre que possivel.
 - Perguntar sobre estilo apenas quando a ambiguidade realmente mudar o resultado.
 - Definir tokens completos: escala de espacamento, escala de tipografia, cores semanticas, radius, profundidade.
+- Declarar explicitamente a posse dos tokens: quais ficam em `:root`, quais ficam em `[data-theme]` e onde o `font-family` e realmente aplicado.
 - Profundidade: comprometer com UMA abordagem — nao misturar borders-only com sombras na mesma superficie.
 - Acessibilidade primeiro: navegacao por teclado, focus rings visiveis, HTML semantico, contraste minimo 4.5:1.
 - Estados completos: default, hover, focus, active, disabled, loading, empty, error, success.
@@ -296,15 +618,28 @@ Seguir o fluxo padrao de `interface-design.md`:
 **Para project_type=site:**
 - `index.html` (raiz do projeto) — HTML completo e funcional com CSS inline e conteudo real
 - `.aioson/context/ui-spec.md` — tokens de design, decisoes e notas de handoff para @dev
+- `.aioson/context/project.context.md` — atualizar `design_skill` se a escolha for confirmada nesta sessao
 
 **Para project_type != site:**
-- `.aioson/context/ui-spec.md` — token block, mapa de telas, matriz de estados de componentes, regras responsivas, notas de handoff
+- `.aioson/context/ui-spec.md` — token block, posse dos tokens (`:root` vs container de tema), mapa de telas, matriz de estados de componentes, regras responsivas, notas de handoff
+- `.aioson/context/project.context.md` — atualizar `design_skill` se a escolha for confirmada nesta sessao
+
+**Outputs dos submodos:**
+- `@ux-ui research` → `.aioson/context/ui-research.md` — benchmarking visual, hipóteses de direção
+- `@ux-ui audit` → `.aioson/context/ui-audit.md` — inventário, achados por severidade, plano de consolidação
+- `@ux-ui tokens` → `.aioson/context/ui-tokens.md` — contrato formal de tokens (primitivos, semânticos, escalas, posse)
+- `@ux-ui component-map` → `.aioson/context/ui-component-map.md` — inventário de componentes, classificação, análise de gaps
+- `@ux-ui a11y` → `.aioson/context/ui-a11y.md` — auditoria WCAG, achados por severidade, notas de integração com @qa
+
+**Regras de audit e submodos:**
+- Não modificar arquivos de UI existentes até o usuário confirmar quais fixes aplicar
 
 **Enriquecimento do PRD (sempre, se prd.md ou prd-{slug}.md existir):**
 Apos gerar o `ui-spec.md`, enriquecer a secao `## Identidade visual` no PRD existente. Adicionar ou expandir:
 - direcao estetica confirmada
 - direcao de design escolhida (ex: Premium Dark Platform, Precision & Density)
-- referencia de skill (`skill: premium-command-center-ui`) se aplicada
+- referencia da design skill (`skill: cognitive-ui` ou outra design skill instalada) se aplicada
+- nota `pending-selection` se o usuario tiver adiado explicitamente a escolha da design skill
 - declaracao do quality bar
 
 Se o PRD ainda nao contiver `## Identidade visual` e a direcao de design ja estiver clara, criar primeiro essa secao e depois enriquecer.
@@ -318,5 +653,9 @@ Nao sobrescrever Visao, Problema, Usuarios, Escopo MVP, Fluxos de usuario, Metri
 - Usar `conversation_language` do contexto para toda interacao e output.
 - Nao redesenhar regras de negocio definidas em discovery/architecture.
 - Output generico e fracasso. Se outro AI produziria o mesmo resultado do mesmo prompt — revisar.
+- Nao selecionar automaticamente uma `design_skill` para `site` ou `web_app` quando o campo estiver em branco.
 - Nao abrir questionarios de estilo quando o contexto ja permite inferencia suficiente.
 - Somente copy real — sem "Lorem ipsum", sem "[Seu titulo aqui]", sem texto placeholder no output final.
+- Sempre executar o entry check antes da Etapa 0 — nunca assumir modo criação quando artefatos de UI já podem existir.
+- Em modo audit, nunca modificar arquivos de UI existentes antes do usuário confirmar quais fixes aplicar.
+- Se o CLI `aioson` não estiver disponível, escrever devlog ao final da sessão seguindo a seção "Devlog" em `.aioson/config.md`.

package/template/.aioson/rules/squad/README.md

@@ -0,0 +1,50 @@
+# Squad Creation Rules
+
+Rules in this directory are automatically loaded by the `@squad` agent during squad creation.
+
+## How it works
+
+1. Create a `.md` file in this directory
+2. Add YAML frontmatter with `name`, `description`, and optional `applies_to` / `domains` fields
+3. The `@squad` agent reads matching rules before creating any squad
+
+## Frontmatter format
+
+```yaml
+---
+name: my-rule-name
+description: One-line description of what this rule enforces
+applies_to: [content]          # optional: content, software, research, mixed
+domains: [youtube, instagram]  # optional: restrict to specific domains
+priority: 10                   # optional: higher = loaded first
+version: 1.0.0
+---
+```
+
+## Field reference
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | yes | Unique identifier for the rule |
+| `description` | yes | What the rule enforces |
+| `applies_to` | no | Squad modes this rule applies to. If absent, applies to all. |
+| `domains` | no | Specific domains. If absent, applies to all domains within `applies_to`. |
+| `priority` | no | Loading order (higher first). Default: 0 |
+| `version` | no | Semantic version for tracking changes |
+
+## Example
+
+```markdown
+---
+name: content-review-policy
+description: All content squads must include a review step in their workflow
+applies_to: [content]
+priority: 5
+version: 1.0.0
+---
+
+# Content Review Policy
+
+Every content squad MUST include at least one review step in its workflow.
+The review step MUST be assigned to a different executor than the one who produced the content.
+```

package/template/.aioson/schemas/genome-meta.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://aiosforge.dev/schemas/genome-meta.schema.json",
   "title": "AIOSON Genome Metadata",
-  "description": "Schema dos metadados operacionais do Genoma 2.0 e 3.0",
+  "description": "Schema dos metadados operacionais do Genome 2.0 e 3.0",
   "type": "object",
   "required": ["schemaVersion", "version", "format", "slug", "domain", "type", "language", "depth", "evidenceMode", "sourceCount", "counts", "origin", "compat", "bindings", "createdAt", "updatedAt"],
   "properties": {

package/template/.aioson/schemas/genome.schema.json

@@ -2,7 +2,7 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://aiosforge.dev/schemas/genome.schema.json",
   "title": "AIOSON Genome",
-  "description": "Schema do objeto normalizado do Genoma 2.0 e 3.0",
+  "description": "Schema do objeto normalizado do Genome 2.0 e 3.0",
   "type": "object",
   "required": ["slug", "domain", "type", "language", "depth", "version", "format", "evidenceMode", "sections"],
   "properties": {

package/template/.aioson/schemas/squad-blueprint.schema.json

@@ -159,6 +159,17 @@
       "type": "array",
       "items": { "type": "string" }
     },
+    "investigation": {
+      "type": "object",
+      "description": "Referência à investigação de domínio do @orache",
+      "properties": {
+        "slug": { "type": "string" },
+        "path": { "type": "string" },
+        "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+        "dimensionsCovered": { "type": "integer", "minimum": 0, "maximum": 7 },
+        "date": { "type": "string", "format": "date" }
+      }
+    },
     "confidence": {
       "type": "number",
       "minimum": 0,