create-genia-os 2.4.0 → 3.0.0

package/template/.aiox-core/development/tasks/run-design-system-pipeline.md

@@ -0,0 +1,640 @@
+# Run Design System Pipeline
+
+> Task ID: run-design-system-pipeline
+> Agent: @ux-design-expert (Brad - Design System Architect)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+
+- Executa pipeline completo automaticamente
+- Minimal user interaction
+- **Best for:** Pipelines de CI/CD, releases automatizados
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+
+- Checkpoint entre cada step
+- Mostra resultados e pede confirmação
+- **Best for:** Primeira execução, validação manual
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+
+- Analisa projeto antes de executar
+- Identifica potenciais problemas
+- **Best for:** Projetos complexos, primeira migração
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOX Task Format V1.0)
+
+```yaml
+task: run-design-system-pipeline
+responsável: Brad (Design System Architect)
+responsavel_type: Agente
+atomic_layer: Pipeline
+
+inputs:
+  - name: project_path
+    type: string
+    required: false
+    default: "."
+    prompt: "Project directory path"
+
+  - name: mode
+    type: string
+    required: false
+    default: "interactive"
+    prompt: "Execution mode (yolo|interactive|preflight)"
+
+  - name: skip_steps
+    type: array
+    required: false
+    default: []
+    prompt: "Steps to skip (build|document|a11y|roi)"
+
+  - name: output_dir
+    type: string
+    required: false
+    default: "outputs/design-system/"
+    prompt: "Output directory for artifacts"
+
+outputs:
+  - name: pipeline_report
+    type: object
+    destination: file_system
+    persisted: true
+
+  - name: build_artifacts
+    type: object
+    destination: file_system
+    persisted: true
+
+  - name: documentation
+    type: object
+    destination: file_system
+    persisted: true
+
+  - name: a11y_report
+    type: object
+    destination: file_system
+    persisted: true
+
+  - name: roi_metrics
+    type: object
+    destination: file_system
+    persisted: true
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Design System project exists with components
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check for design-system/ or components/ui/ directory
+    error_message: "Pre-condition failed: No Design System found in project"
+
+  - [ ] Package.json exists with required dependencies
+    tipo: pre-condition
+    blocker: false
+    validação: |
+      Check for React, TypeScript, Tailwind dependencies
+    error_message: "Warning: Some dependencies may be missing"
+
+  - [ ] Build tools configured (vite, webpack, or similar)
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check for build configuration files
+    error_message: "Pre-condition failed: No build configuration found"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] All pipeline steps completed without critical errors
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify each step exit code = 0 or has acceptable warnings
+    error_message: "Post-condition failed: Pipeline had critical errors"
+
+  - [ ] Output artifacts generated in expected locations
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Check outputs/design-system/ contains expected files
+    error_message: "Post-condition failed: Missing output artifacts"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Build step: Components compiled successfully
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] Document step: Pattern Library documentation generated
+    tipo: acceptance-criterion
+    blocker: false
+
+  - [ ] A11y step: WCAG AA audit completed (warnings OK, errors block)
+    tipo: acceptance-criterion
+    blocker: true
+
+  - [ ] ROI step: Metrics calculated and report generated
+    tipo: acceptance-criterion
+    blocker: false
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** build-component
+  - **Purpose:** Build individual components
+  - **Source:** .aiox-core/development/tasks/build-component.md
+
+- **Tool:** generate-documentation
+  - **Purpose:** Generate Pattern Library docs
+  - **Source:** .aiox-core/development/tasks/generate-documentation.md
+
+- **Tool:** accessibility-audit
+  - **Purpose:** Run WCAG compliance checks
+  - **Source:** External: axe-core, pa11y, or similar
+
+- **Tool:** calculate-roi
+  - **Purpose:** Calculate ROI metrics
+  - **Source:** .aiox-core/development/tasks/calculate-roi.md
+
+---
+
+## Error Handling
+
+**Strategy:** continue-on-warning
+
+**Common Errors:**
+
+1. **Error:** Build Failure
+   - **Cause:** TypeScript errors, missing dependencies, invalid imports
+   - **Resolution:** Fix errors and re-run build step only
+   - **Recovery:** Show error details, suggest fixes, offer to skip to next step
+
+2. **Error:** Documentation Generation Failed
+   - **Cause:** Missing component metadata, invalid JSDoc
+   - **Resolution:** Add missing metadata, fix JSDoc syntax
+   - **Recovery:** Continue pipeline, flag for manual documentation
+
+3. **Error:** Accessibility Violations (Critical)
+   - **Cause:** WCAG AA violations in components
+   - **Resolution:** Fix accessibility issues before proceeding
+   - **Recovery:** Generate remediation report, block pipeline if critical
+
+4. **Error:** ROI Calculation Failed
+   - **Cause:** Missing baseline metrics, no consolidation data
+   - **Resolution:** Run consolidation first or provide manual inputs
+   - **Recovery:** Skip ROI, complete pipeline with partial results
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-15 min (full pipeline)
+cost_estimated: $0.01-0.05
+token_usage: ~5,000-15,000 tokens
+
+step_breakdown:
+  build: 1-3 min
+  document: 2-5 min
+  a11y: 1-3 min
+  roi: 1-2 min
+```
+
+**Optimization Notes:**
+
+- Run a11y checks in parallel with documentation generation
+- Cache build artifacts between runs
+- Skip unchanged components in incremental mode
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - build-component.md
+  - generate-documentation.md
+  - calculate-roi.md
+tags:
+  - pipeline
+  - automation
+  - design-system
+  - quality
+  - ci-cd
+updated_at: 2025-01-30
+```
+
+---
+
+## Description
+
+Pipeline automatizado pós-migração para Design System. Executa sequencialmente: build de componentes atômicos → geração de documentação do Pattern Library → auditoria de acessibilidade WCAG AA → cálculo de ROI e savings.
+
+Ideal para integração em CI/CD ou validação antes de releases.
+
+## Prerequisites
+
+- Design System configurado no projeto
+- Componentes existentes para build
+- Node.js 18+ instalado
+- Dependências do projeto instaladas (npm install)
+
+## Workflow
+
+### Pipeline Sequence
+
+```text
+┌──────┬───────────────────┬───────────────────────────────────────┐
+│ Step │       ID          │                 Ação                  │
+├──────┼───────────────────┼───────────────────────────────────────┤
+│ 1    │ build             │ Build de componentes atômicos         │
+├──────┼───────────────────┼───────────────────────────────────────┤
+│ 2    │ document          │ Gerar documentação do Pattern Library │
+├──────┼───────────────────┼───────────────────────────────────────┤
+│ 3    │ a11y              │ Auditoria de acessibilidade (WCAG AA) │
+├──────┼───────────────────┼───────────────────────────────────────┤
+│ 4    │ roi               │ Cálculo de ROI e savings              │
+└──────┴───────────────────┴───────────────────────────────────────┘
+```
+
+### Step 1: Build Components
+
+```yaml
+step: build
+agent: @ux-design-expert
+action: Build de componentes atômicos
+```
+
+**Execução:**
+
+1. Identificar todos os componentes no Design System
+2. Compilar tokens de design (cores, tipografia, espaçamentos)
+3. Build de componentes atômicos (atoms → molecules → organisms)
+4. Validar estrutura de arquivos e nomenclatura
+5. Verificar TypeScript strict mode compliance
+6. Gerar bundle de componentes
+
+**Outputs:**
+
+- `build_report.json` - Relatório de build
+- `compiled_tokens/` - Tokens compilados
+- `dist/` - Bundle de componentes
+
+**Validation:**
+
+- [ ] Build completo sem erros TypeScript
+- [ ] Todos os tokens compilados
+- [ ] Componentes exportados corretamente
+
+### Step 2: Generate Documentation
+
+```yaml
+step: document
+agent: @ux-design-expert
+action: Gerar documentação do Pattern Library
+requires: build
+```
+
+**Execução:**
+
+1. Extrair metadata dos componentes (props, variants, types)
+2. Gerar documentação de cada componente
+3. Criar guia de estilo visual
+4. Gerar código de exemplo para cada variante
+5. Atualizar changelog de componentes
+6. Build do Storybook (se configurado)
+
+**Outputs:**
+
+- `docs/pattern-library/` - Documentação completa
+- `docs/api-reference/` - Referência de API
+- `docs/style-guide.md` - Guia de estilo
+- `storybook-static/` - Storybook build (se habilitado)
+
+**Validation:**
+
+- [ ] Todos os componentes documentados
+- [ ] Exemplos de código funcionais
+- [ ] Guia de estilo atualizado
+
+### Step 3: Accessibility Audit
+
+```yaml
+step: a11y
+agent: @ux-design-expert
+action: Auditoria de acessibilidade (WCAG AA)
+requires: document
+```
+
+**Execução:**
+
+1. Executar axe-core em todos os componentes
+2. Verificar contraste de cores (4.5:1 texto, 3:1 UI)
+3. Validar navegação por teclado
+4. Checar atributos ARIA e roles
+5. Verificar focus states e indicadores visuais
+6. Testar com múltiplos tamanhos de fonte
+
+**WCAG 2.1 AA Checklist:**
+
+- [ ] 1.4.3 Contrast (Minimum) - 4.5:1 for text
+- [ ] 1.4.11 Non-text Contrast - 3:1 for UI
+- [ ] 2.1.1 Keyboard - All functionality keyboard accessible
+- [ ] 2.4.7 Focus Visible - Focus indicator visible
+- [ ] 4.1.2 Name, Role, Value - ARIA attributes correct
+
+**Outputs:**
+
+- `a11y/audit-report.json` - Relatório completo
+- `a11y/violations.md` - Lista de violações
+- `a11y/remediation-plan.md` - Plano de correção
+
+**Validation:**
+
+- [ ] Zero violações críticas (Level A)
+- [ ] Violações AA documentadas com plano de correção
+- [ ] Navegação por teclado funcional
+
+### Step 4: Calculate ROI
+
+```yaml
+step: roi
+agent: @ux-design-expert
+action: Cálculo de ROI e savings
+requires: a11y
+```
+
+**Execução:**
+
+1. Coletar métricas de componentes (quantidade, reuso)
+2. Calcular tempo economizado em desenvolvimento
+3. Estimar redução de inconsistências visuais
+4. Projetar velocidade de entrega de features
+5. Calcular custo de manutenção reduzido
+6. Gerar dashboard de métricas
+
+**Métricas Calculadas:**
+
+- Horas dev economizadas/mês
+- % de reuso de componentes
+- Tempo médio para nova feature
+- Redução de bugs visuais
+- ROI ratio e breakeven point
+
+**Outputs:**
+
+- `roi/roi-analysis.md` - Análise completa
+- `roi/executive-summary.md` - Resumo executivo
+- `roi/metrics-dashboard.json` - Dados para dashboard
+
+**Validation:**
+
+- [ ] Métricas de reuso calculadas
+- [ ] ROI ratio positivo
+- [ ] Executive summary gerado
+
+---
+
+## Output
+
+### Final Pipeline Report
+
+```yaml
+# pipeline-report.yaml
+pipeline:
+  id: design-system-build-quality
+  executed_at: '2025-01-30T14:00:00Z'
+  mode: interactive
+  duration: '8m 32s'
+
+steps:
+  build:
+    status: success
+    duration: '2m 15s'
+    components_built: 24
+    tokens_compiled: 156
+    errors: 0
+    warnings: 2
+
+  document:
+    status: success
+    duration: '3m 45s'
+    pages_generated: 28
+    examples_created: 72
+    storybook: enabled
+
+  a11y:
+    status: success
+    duration: '1m 22s'
+    components_audited: 24
+    violations_critical: 0
+    violations_serious: 3
+    violations_minor: 8
+    wcag_level: 'AA (with warnings)'
+
+  roi:
+    status: success
+    duration: '1m 10s'
+    monthly_savings: '$12,400'
+    reuse_rate: '78%'
+    roi_ratio: '8.2x'
+
+summary:
+  total_duration: '8m 32s'
+  overall_status: success
+  quality_score: 94/100
+  next_steps:
+    - 'Fix 3 serious a11y violations'
+    - 'Review ROI with stakeholders'
+    - 'Schedule production release'
+```
+
+---
+
+## Success Criteria
+
+- [ ] Pipeline executa todos os 4 steps sem erros críticos
+- [ ] Build gera bundle de componentes válido
+- [ ] Documentação cobre 100% dos componentes
+- [ ] Zero violações críticas de acessibilidade (WCAG A)
+- [ ] ROI report gerado com métricas válidas
+- [ ] Pipeline report salvo em outputs/
+
+---
+
+## Examples
+
+### Example 1: Execução Completa (YOLO Mode)
+
+```bash
+*run-design-system-pipeline --mode=yolo
+```
+
+Output:
+
+```
+🚀 Brad: Iniciando Design System Pipeline (YOLO mode)...
+
+[1/4] 🏗️ BUILD
+  ✓ Compilando tokens... 156 tokens
+  ✓ Building componentes... 24 components
+  ✓ Bundle gerado: dist/design-system.js (142kb)
+  ⏱️ 2m 15s
+
+[2/4] 📚 DOCUMENT
+  ✓ Gerando Pattern Library... 28 páginas
+  ✓ API Reference... 24 componentes
+  ✓ Storybook build... 72 stories
+  ⏱️ 3m 45s
+
+[3/4] ♿ A11Y AUDIT
+  ✓ Executando axe-core... 24 componentes
+  ✓ Contraste de cores... PASS
+  ✓ Navegação keyboard... PASS
+  ⚠️ 3 violações serious (ver remediation-plan.md)
+  ⏱️ 1m 22s
+
+[4/4] 💰 ROI
+  ✓ Calculando métricas...
+  ✓ Monthly savings: $12,400
+  ✓ ROI ratio: 8.2x
+  ✓ Breakeven: 1.2 months
+  ⏱️ 1m 10s
+
+═══════════════════════════════════════════
+✅ PIPELINE COMPLETO
+═══════════════════════════════════════════
+📊 Quality Score: 94/100
+⏱️ Total: 8m 32s
+📁 Outputs: outputs/design-system/
+
+Brad says: "Pipeline limpo. Ship it! 🚢"
+```
+
+### Example 2: Execução Interativa
+
+```bash
+*run-design-system-pipeline
+```
+
+Output:
+
+```
+🚀 Brad: Iniciando Design System Pipeline (Interactive mode)...
+
+[1/4] 🏗️ BUILD
+  Componentes encontrados: 24
+  Tokens encontrados: 156
+
+  Continuar com build? (Y/n): Y
+
+  ✓ Build completo!
+
+  Resultado:
+  - Components: 24/24 ✓
+  - Tokens: 156/156 ✓
+  - Warnings: 2 (non-blocking)
+
+  Prosseguir para documentação? (Y/n): Y
+
+[2/4] 📚 DOCUMENT
+  ...
+```
+
+### Example 3: Skip Steps
+
+```bash
+*run-design-system-pipeline --skip=document,roi
+```
+
+Executa apenas: build → a11y
+
+---
+
+## Integration
+
+### CI/CD Integration
+
+```yaml
+# .github/workflows/design-system.yml
+name: Design System Quality
+on:
+  push:
+    paths:
+      - 'src/components/**'
+      - 'design-system/**'
+
+jobs:
+  quality-pipeline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run Design System Pipeline
+        run: npx aiox-core task run-design-system-pipeline --mode=yolo
+```
+
+### NPM Script
+
+```json
+{
+  "scripts": {
+    "ds:pipeline": "npx aiox-core task run-design-system-pipeline",
+    "ds:pipeline:ci": "npx aiox-core task run-design-system-pipeline --mode=yolo"
+  }
+}
+```
+
+---
+
+## Notes
+
+- Pipeline é idempotente - pode ser executado múltiplas vezes
+- Resultados são incrementais quando possível
+- Modo YOLO ideal para CI/CD
+- Modo Interactive ideal para desenvolvimento local
+- A11y violations serious não bloqueiam, mas devem ser corrigidas antes do release
+- ROI é opcional mas recomendado para justificar investimento