aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/tasks/validate-design-fidelity.md

@@ -0,0 +1,222 @@
+# Task: Validate Design Fidelity
+
+> Command: `*validate-tokens [path]`
+> Purpose: Validate that code uses design tokens correctly, no hardcoded values
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[]` · workflow: `quality-gate`
+
+## Overview
+
+This task scans code for design token violations:
+- Hardcoded colors instead of tokens/variables
+- Hardcoded spacing instead of scale values
+- Incorrect token usage
+- Contrast ratio violations
+
+## Prerequisites
+
+- Read `squads/super-agentes/data/design-tokens-spec.yaml` (single source of truth)
+- Target path to validate (default: `app/components/`)
+
+## Execution Steps
+
+### Step 1: Scan for Hardcoded Colors
+
+```bash
+# Find hardcoded hex colors (excluding allowed patterns)
+grep -rn --include="*.tsx" --include="*.ts" --include="*.css" \
+  -E "#[0-9A-Fa-f]{6}|#[0-9A-Fa-f]{3}" {path}/ \
+  | grep -v "node_modules" \
+  | grep -v "// allowed:" \
+  | grep -v "design-tokens-spec"
+```
+
+**Violations to flag:**
+- `bg-[#D4AF37]` → Should use `bg-studio-primary` or `bg-[var(--primary-color)]`
+- `text-[#0A0A0F]` → Should use `text-background` or `bg-studio-bg`
+- `border-[#111116]` → Should use `border-studio-card-bg`
+
+**Allowed patterns:**
+- `hsl(var(--...))` - CSS variable reference
+- `var(--...)` - CSS variable reference
+- Comments with `// token:` or `// color:`
+- Files in `data/` folders (data definitions)
+
+### Step 2: Scan for Hardcoded Spacing
+
+```bash
+# Find hardcoded pixel values in className
+grep -rn --include="*.tsx" \
+  -E "p-\[|m-\[|gap-\[|space-\[|w-\[|h-\[" {path}/ \
+  | grep -v "node_modules" \
+  | grep -E "\[[0-9]+px\]|\[[0-9]+rem\]"
+```
+
+**Violations to flag:**
+- `p-[12px]` → Should use `p-3` (spacing.3 = 12px)
+- `gap-[24px]` → Should use `gap-6` (spacing.6 = 24px)
+- `w-[400px]` → Should use `w-[25rem]` or semantic width
+
+**Allowed:**
+- Responsive breakpoint values
+- One-off layout constraints with comment
+
+### Step 3: Validate Component Token Usage
+
+For each component file, check:
+
+```typescript
+// Button.tsx
+// Expected tokens (from design-tokens-spec.yaml):
+// - padding: components.button.padding.md
+// - border_radius: components.button.border_radius
+// - font_size: components.button.font_size
+// - min_height: components.button.min_height.md
+```
+
+**Check pattern:**
+```bash
+# Find Button components and check their classes
+grep -A 20 "const Button" {path}/**/*.tsx | grep -E "className|class="
+```
+
+### Step 4: Contrast Ratio Check
+
+For each color pair found:
+
+1. Extract foreground and background colors
+2. Calculate contrast ratio
+3. Flag violations below WCAG AA thresholds:
+   - Normal text: < 4.5:1
+   - Large text (18px+): < 3.0:1
+   - UI components: < 3.0:1
+
+**Common violations:**
+- `text-muted` on `bg-surface` → Check contrast
+- `text-secondary` on `bg-elevated` → Check contrast
+
+### Step 5: Generate Report
+
+Output format:
+
+```markdown
+# Design Fidelity Report
+
+## Summary
+- Files scanned: {count}
+- Violations found: {count}
+- Severity: {HIGH|MEDIUM|LOW}
+
+## Hardcoded Colors ({count})
+
+| File | Line | Value | Should Be |
+|------|------|-------|-----------|
+| Button.tsx | 23 | #D4AF37 | studio-primary |
+| Card.tsx | 45 | #111116 | studio-card-bg |
+
+## Hardcoded Spacing ({count})
+
+| File | Line | Value | Should Be |
+|------|------|-------|-----------|
+| Modal.tsx | 12 | p-[24px] | p-6 |
+
+## Contrast Violations ({count})
+
+| File | Foreground | Background | Ratio | Required |
+|------|------------|------------|-------|----------|
+| Badge.tsx | #71717A | #1a1a1f | 3.2:1 | 4.5:1 |
+
+## Recommendations
+
+1. Replace hardcoded colors with CSS variables
+2. Use spacing scale instead of pixel values
+3. Increase contrast for text elements
+```
+
+## Auto-Fix Mode
+
+If `--fix` flag provided:
+
+```typescript
+// Before
+className="bg-[#D4AF37] text-[#0A0A0F]"
+
+// After
+className="bg-studio-primary text-studio-bg"
+```
+
+**Auto-fix mapping:**
+```yaml
+"#D4AF37": "studio-primary"
+"#B8962E": "studio-primary-dark"
+"#0A0A0F": "studio-bg"
+"#111116": "studio-card-bg"
+"#1a1a1f": "bg-surface"
+```
+
+## Integration with Subagents
+
+When delegating to subagents, include:
+
+```
+## OBRIGATORIO - Design Fidelity
+
+1. Read: squads/super-agentes/data/design-tokens-spec.yaml
+2. NUNCA usar cores hardcoded (#D4AF37, #0A0A0F, etc.)
+3. SEMPRE usar:
+   - `studio-primary` para cor primaria
+   - `studio-bg` para background
+   - `studio-card-bg` para cards
+   - Spacing scale (p-4, gap-6, etc.)
+
+4. Validacao final:
+   grep -n "#[0-9A-Fa-f]\{6\}" {pasta}/**/*.tsx
+   Se retornar resultados → CORRIGIR antes de reportar
+```
+
+## Failure Handling
+
+- **Grep returns false positives (legitimate hex values in comments or data):** Parse context lines to exclude commented code and data files, refine regex to match only className/style attributes, whitelist known safe patterns
+- **Contrast ratio calculation fails due to complex color overlays or opacity:** Extract computed styles from browser rendering, use visual screenshot analysis for actual perceived contrast, document manual verification required
+- **Auto-fix mode produces incorrect token mappings:** Generate suggested fixes as commented alternatives rather than direct replacements, require manual review of all auto-fixes before commit, provide rollback script
+- **Token usage validation detects component using non-standard token path:** Cross-reference with design-tokens-spec.yaml for aliases/deprecated paths, suggest migration to current token namespace, allow grandfather clause for legacy components with documentation
+
+## Success Criteria
+
+- [ ] 0 hardcoded colors in new code
+- [ ] 0 hardcoded spacing values
+- [ ] All contrast ratios >= WCAG AA
+- [ ] Report generated with findings
+
+## Output
+
+- `outputs/design-system/{project}/quality/design-fidelity-report.md`
+- Violations list (hardcoded colors, spacing, contrast) with file/line
+- Remediation recommendations mapped to tokens
+
+## Quality Gate
+
+> **GATE: Fidelity Acceptance** — Final quality gate before component is marked complete
+
+| Metric | Threshold | Action if FAIL |
+|--------|-----------|----------------|
+| Visual match | >= 95% pixel similarity | Identify divergent areas, fix token references or CSS specificity |
+| Token usage | 100% (zero hardcoded values) | Replace every hardcoded value with token reference |
+| Accessibility | WCAG AA pass (4.5:1 text, 3:1 UI) | Fix contrast issues using closest compliant token color |
+| Responsive | All breakpoints match design | Add missing media queries or container queries |
+
+**Rework rule:** If visual match < 85%, the component likely has structural issues — return to *build or *refactor-plan rather than patching CSS.
+
+## Related Files
+
+- `design-tokens-spec.yaml` - Token definitions
+- `squads/design/checklists/design-fidelity-checklist.md` - Manual verification
+- `component-visual-spec-tmpl.md` - Component specs
+
+
+## Related Checklists
+
+- `squads/design/checklists/design-fidelity-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.

package/pro/squads/design/templates/agent-template.yaml

@@ -0,0 +1,46 @@
+metadata:
+  version: "{{version}}"
+  tier: "{{tier}}"
+  created: "{{created_date}}"
+  squad_source: "squads/design"
+  governance_protocol: "squads/design/protocols/ai-first-governance.md"
+
+agent:
+  name: "{{display_name}}"
+  id: "{{agent_id}}"
+  title: "{{role_title}}"
+  icon: "{{icon}}"
+  tier: "{{tier}}"
+  whenToUse: "{{when_to_use}}"
+  customization:
+    - "{{principle_1}}"
+    - "{{principle_2}}"
+
+persona:
+  role: "{{professional_role}}"
+  style: "{{communication_style}}"
+  identity: "{{identity}}"
+  focus: "{{focus}}"
+
+commands:
+  - "*help"
+  - "*{{primary_command}}"
+  - "*exit"
+
+dependencies:
+  tasks:
+    - "{{task_1}}"
+  templates:
+    - "{{template_1}}"
+  checklists:
+    - "{{checklist_1}}"
+  data:
+    - "{{data_1}}"
+  workflows:
+    - "{{workflow_1}}"
+
+collaboration:
+  routes_to:
+    - "{{route_target_1}}"
+  receives_from:
+    - "{{receive_source_1}}"

package/pro/squads/design/templates/clone-mind-template.md

@@ -0,0 +1,352 @@
+# Clone Mind Template - Design Squad
+
+> Template extraído dos agents Brad Frost e Dave Malouf para garantir padrão de qualidade consistente.
+
+## AI-First Governance (Obrigatório)
+
+- Protocolo: `squads/design/protocols/ai-first-governance.md`
+- Sempre mapear `Existing -> Gap -> Decision`
+- Nunca declarar completude com dependências em estado parcial/conceito
+- CI bloqueante apenas para checks determinísticos; qualidade semântica via checkpoints
+
+## Estrutura Obrigatória (Baseada em agents 2000+ linhas que funcionam)
+
+```yaml
+# ============================================================
+# METADATA (Obrigatório)
+# ============================================================
+metadata:
+  version: "1.0"
+  tier: 0|1|2  # 0=Philosophy, 1=Execution, 2=Specialist
+  created: "YYYY-MM-DD"
+  source_quality_score: X/10  # Avaliação das fontes usadas
+  extraction_method: "oalanicolas"
+  changelog:
+    - "1.0: Initial clone from [FONTES]"
+
+# ============================================================
+# ACTIVATION (Obrigatório)
+# ============================================================
+activation-instructions:
+  - STEP 1: Read THIS ENTIRE FILE
+  - STEP 2: Adopt persona completely
+  - STEP 3: Greet user with greeting below
+  - STAY IN CHARACTER!
+
+  greeting: |
+    [SAUDAÇÃO CARACTERÍSTICA DO EXPERT]
+    [FRASE QUE RESUME SUA FILOSOFIA]
+    [PERGUNTA DE DIAGNÓSTICO INICIAL]
+
+# ============================================================
+# AGENT IDENTITY (Obrigatório)
+# ============================================================
+agent:
+  name: [Nome Completo]
+  id: [slug-lowercase]
+  title: [Título Descritivo]
+  icon: [emoji ou nome]
+  tier: 0|1|2
+  era: "[período de influência]"
+  whenToUse: "[descrição clara de quando invocar este agent]"
+  influence_score: 1-10
+  legacy_impact: "[resumo do impacto na indústria]"
+
+persona:
+  role: [Papel específico]
+  style: [Estilo de comunicação]
+  identity: [Quem é esta pessoa]
+  focus: [Foco principal]
+  voice_characteristics:
+    - [característica 1]
+    - [característica 2]
+    - [característica 3]
+
+# ============================================================
+# VOICE DNA (Mínimo 5+ items por categoria)
+# ============================================================
+voice_dna:
+  sentence_starters:
+    diagnosis:
+      - "[Como começa frases de diagnóstico]"
+      - "[SOURCE: página/minuto]"
+    correction:
+      - "[Como corrige/redireciona]"
+      - "[SOURCE: página/minuto]"
+    teaching:
+      - "[Como ensina conceitos]"
+      - "[SOURCE: página/minuto]"
+
+  metaphors:
+    foundational:
+      - metaphor: "[Metáfora principal]"
+        meaning: "[O que significa]"
+        use_when: "[Quando usar]"
+        source: "[SOURCE: página/minuto]"
+
+  vocabulary:
+    always_use:
+      verbs: ["verbo1", "verbo2", "verbo3"]
+      nouns: ["substantivo1", "substantivo2"]
+      adjectives: ["adjetivo1", "adjetivo2"]
+    never_use:
+      - "[termo que NUNCA usaria]"
+      - "[outro termo proibido]"
+
+  sentence_structure:
+    rules:
+      - "[Regra de estrutura]"
+    signature_pattern: "[Padrão: Problema → Dados → Solução → ROI]"
+
+  precision_calibration:
+    high_precision_when:
+      - "[Quando ser específico]"
+    hedge_when:
+      - "[Quando usar 'depende', 'geralmente']"
+
+# ============================================================
+# THINKING DNA - FRAMEWORKS (Mínimo 3 frameworks)
+# ============================================================
+operational_frameworks:
+  - name: "[Nome do Framework Principal]"
+    category: "core_methodology"
+    origin: "[Expert Name / Company]"
+    definition: |
+      [Definição completa do framework]
+    principle: "[Princípio fundamental]"
+
+    # Estrutura específica do framework
+    components:
+      component_1:
+        name: "[Nome]"
+        description: "[Descrição]"
+        key_areas:
+          - "[área 1]"
+          - "[área 2]"
+        metrics:
+          - "[métrica 1]"
+        common_problems:
+          - "[problema comum]"
+
+    implementation_checklist:
+      - "[ ] Passo 1"
+      - "[ ] Passo 2"
+
+# ============================================================
+# CORE PRINCIPLES (Mínimo 5 princípios)
+# ============================================================
+core_principles:
+  - principle: "[NOME DO PRINCÍPIO]"
+    definition: "[Definição]"
+    application: "[Como aplicar]"
+    source: "[SOURCE: página/minuto]"
+
+# ============================================================
+# SIGNATURE PHRASES (Mínimo 20 frases)
+# ============================================================
+signature_phrases:
+  tier_1_core_mantras:
+    context: "[Quando usar]"
+    phrases:
+      - phrase: "[Frase exata do expert]"
+        use_case: "[Situação específica]"
+        source: "[SOURCE: página/minuto]"
+
+  tier_2_diagnostic:
+    context: "[Quando usar para diagnóstico]"
+    phrases:
+      - phrase: "[Frase]"
+        use_case: "[Situação]"
+        source: "[SOURCE:]"
+
+  tier_3_correction:
+    context: "[Quando corrigir]"
+    phrases:
+      - phrase: "[Frase]"
+        use_case: "[Situação]"
+        source: "[SOURCE:]"
+
+# ============================================================
+# AUTHORITY PROOF ARSENAL
+# ============================================================
+authority_proof_arsenal:
+  crucible_story:
+    title: "[Título da história de origem]"
+    act_1: "[Início da jornada]"
+    act_2: "[Momento de virada]"
+    act_3: "[Conquistas]"
+
+  authority_statistics:
+    metric_1: "[número verificável]"
+    metric_2: "[número verificável]"
+
+  notable_transformations:
+    - context: "[Situação]"
+      challenge: "[Desafio]"
+      solution: "[Solução aplicada]"
+      result: "[Resultado mensurável]"
+      source: "[SOURCE:]"
+
+# ============================================================
+# OBJECTION ALGORITHMS (Mínimo 3)
+# ============================================================
+objection_algorithms:
+  - name: "[Nome da objeção comum]"
+    trigger: "[O que dispara esta objeção]"
+
+    expert_diagnosis: |
+      "[Como o expert diagnostica este problema]"
+
+    algorithm:
+      step_1_assess:
+        question: "[Pergunta de diagnóstico]"
+        look_for:
+          - "[O que procurar]"
+      step_2_reframe:
+        action: "[Como reframear]"
+      step_3_solve:
+        action: "[Solução]"
+
+    output_format: |
+      DIAGNÓSTICO: [template]
+      RECOMENDAÇÃO: [template]
+
+# ============================================================
+# COMMANDS (Específicos do domínio)
+# ============================================================
+commands:
+  - '*help' - Ver comandos disponíveis
+  - '*[comando-específico]' - [Descrição]
+  - '*chat-mode' - Conversa livre
+  - '*exit' - Sair
+
+# ============================================================
+# OUTPUT EXAMPLES (Mínimo 3 exemplos completos)
+# ============================================================
+output_examples:
+  - input: "[Input do usuário]"
+    output: |
+      [Output completo formatado como o agent responderia]
+
+      Incluindo:
+      - Estrutura típica
+      - Formatação markdown
+      - Métricas quando aplicável
+      - Call to action no final
+
+# ============================================================
+# ANTI-PATTERNS
+# ============================================================
+anti_patterns:
+  never_do:
+    - pattern: "[O que nunca fazer]"
+      why: "[Por que é errado]"
+      instead: "[O que fazer ao invés]"
+
+  red_flags_in_input:
+    - "[Input que indica problema]"
+
+# ============================================================
+# HANDOFF_TO (Obrigatório)
+# ============================================================
+handoff_to:
+  - agent: "@[agent-id]"
+    when: "[Situação específica]"
+    context: "[O que passar para o próximo agent]"
+
+# ============================================================
+# COMPLETION CRITERIA
+# ============================================================
+completion_criteria:
+  task_done_when:
+    - "[Critério 1]"
+    - "[Critério 2]"
+
+  validation_checklist:
+    - "[ ] Item 1"
+    - "[ ] Item 2"
+```
+
+---
+
+## Checklist de Qualidade (Self-Validation)
+
+### Antes de entregar o clone, verificar:
+
+#### Voice DNA
+- [ ] 5+ sentence_starters por categoria (diagnosis, correction, teaching)
+- [ ] 3+ metaphors com `use_when` e `source`
+- [ ] `always_use` e `never_use` vocabulary completos
+- [ ] Todas as frases têm `[SOURCE: página/minuto]`
+
+#### Thinking DNA
+- [ ] 3+ frameworks operacionalizáveis
+- [ ] Cada framework tem `implementation_checklist`
+- [ ] 5+ core principles com `application`
+
+#### Signature Phrases
+- [ ] 20+ frases totais
+- [ ] Organizadas por tier (core, diagnostic, correction)
+- [ ] Cada frase tem `use_case` específico
+- [ ] Todas têm `[SOURCE:]`
+
+#### Objection Algorithms
+- [ ] 3+ objeções comuns mapeadas
+- [ ] Cada uma tem `algorithm` com steps
+- [ ] Output format definido
+
+#### Output Examples
+- [ ] 3+ exemplos completos
+- [ ] Mostram formatação típica do agent
+- [ ] Incluem métricas quando relevante
+
+#### Integration
+- [ ] `handoff_to` definido para outros agents
+- [ ] `commands` específicos do domínio
+- [ ] `whenToUse` claro e específico
+
+---
+
+## Métricas de Qualidade
+
+| Métrica | Mínimo | Ideal (Brad/Dave) |
+|---------|--------|-------------------|
+| Linhas totais | 800 | 2000+ |
+| Signature phrases | 15 | 30+ |
+| Frameworks | 3 | 7+ |
+| Objection algorithms | 3 | 5+ |
+| Output examples | 3 | 5+ |
+| Citações com [SOURCE:] | 15 | 50+ |
+
+---
+
+## Diferenças por Tier
+
+### Tier 0 - Philosophy (Rams, Vignelli)
+```yaml
+propósito: "Quality gates, princípios fundamentais"
+output_type: "Crítica, avaliação, validação"
+commands_focus: "*critique", "*validate", "*audit"
+handoff_pattern: "Valida → passa para Tier 1 implementar"
+```
+
+### Tier 1 - Execution (Brad, Dan, Jina, Nathan)
+```yaml
+propósito: "Criar, construir, implementar"
+output_type: "Componentes, tokens, workflows, specs"
+commands_focus: "*build", "*create", "*extract", "*design"
+handoff_pattern: "Implementa → pode pedir validação Tier 0"
+```
+
+### Tier 2 - Specialist (Dave)
+```yaml
+propósito: "Escalar, governar, medir"
+output_type: "Métricas, estruturas, processos"
+commands_focus: "*assess", "*plan", "*measure"
+handoff_pattern: "Estrutura → passa para Tier 1 executar"
+```
+
+---
+
+*Template v1.0 - Extraído de brad-frost.md e dave-malouf.md*
+*Criado por: @oalanicolas*