iron-edge 1.0.0

package/squads/squad-design/tasks/migrate-legacy-design-system.md

@@ -0,0 +1,133 @@
+---
+task: migrate-legacy-design-system
+responsavel: "@dx-design-system-architect"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Migrate Legacy Design System
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Stratum (dx-design-system-architect)
+- **Complexity:** Complex
+
+## Objetivo
+Migrar design system legado para a arquitetura moderna — planejar e executar migração incremental de tokens, componentes e documentação.
+
+## Entrada
+- Design system legado (current state)
+- Target architecture (new system)
+- Codebase dependente
+- Timeline constraints
+
+## Passos
+
+### 1. Auditar Sistema Legado
+| Aspecto | Legado | Target | Gap |
+|---------|--------|--------|-----|
+| Token format | [CSS vars/SCSS/JS] | W3C DTCG | |
+| Token tiers | [1/2/3] | 3 | |
+| Naming convention | | kebab-case | |
+| Component count | | | |
+| Test coverage | | >= 80% | |
+| Storybook | [yes/no] | yes | |
+| TypeScript | [yes/no] | strict | |
+| a11y compliance | | WCAG 2.2 AA | |
+
+### 2. Planejar Migração
+```yaml
+migration_plan:
+  approach: "incremental"  # big-bang (risky) vs incremental (safe)
+
+  phases:
+    - name: "Foundation"
+      items: ["Token migration", "New build pipeline"]
+      duration: ""
+      risk: "low"
+
+    - name: "Core Components"
+      items: ["Button", "Input", "Card", "Modal"]
+      duration: ""
+      risk: "medium"
+
+    - name: "Complex Components"
+      items: ["Table", "Form", "Navigation"]
+      duration: ""
+      risk: "medium"
+
+    - name: "Page Templates"
+      items: ["Layout migration"]
+      duration: ""
+      risk: "high"
+
+    - name: "Cleanup"
+      items: ["Remove legacy", "Final QA"]
+      duration: ""
+      risk: "low"
+```
+
+### 3. Token Migration Strategy
+| Passo | Acao | Risco |
+|-------|------|-------|
+| 1 | Criar novo token file (W3C DTCG) paralelo | Nenhum |
+| 2 | Gerar CSS vars de ambos (legacy + new) | Nenhum |
+| 3 | Atualizar componentes um por um para novos tokens | Baixo |
+| 4 | Verificar visual regression | Medio |
+| 5 | Remover tokens legados | Medio |
+
+### 4. Component Migration Pattern
+Para cada componente:
+1. Criar versao nova (`ButtonV2`) lado a lado
+2. Implementar API nova com backward-compat props
+3. Migrar consumers incrementalmente
+4. Deprecar versao antiga
+5. Remover apos adoption completa
+
+### 5. Codemods
+Automatizar migracao com codemods:
+```javascript
+// Exemplo: renomear props
+// Old: <Button color="primary" />
+// New: <Button variant="primary" />
+```
+
+### 6. Rollback Plan
+- Manter versao legada acessivel durante migracao
+- Feature flags para toggle entre versoes
+- Visual regression baseline do legado
+- Rollback script preparado
+
+## Saida
+- Migration plan completo
+- Phase timeline
+- Token mapping (old → new)
+- Codemod scripts
+- Rollback plan
+- Progress tracking dashboard
+
+## Validacao
+- [ ] Audit do legado completo
+- [ ] Migration plan por fases
+- [ ] Token mapping documentado
+- [ ] Codemods testados
+- [ ] Rollback plan pronto
+- [ ] Visual regression baseline capturada

package/squads/squad-design/tasks/monitor-performance-regression.md

@@ -0,0 +1,300 @@
+---
+task: monitor-performance-regression
+responsavel: "@dx-performance-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Monitor Performance Regression
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Apex (dx-performance-engineer)
+- **Complexity:** Standard
+
+## Objetivo
+Monitorar regressoes de performance — configurar RUM, alertas automaticos e dashboards para detectar degradacoes antes que impactem usuarios.
+
+## Entrada
+- Performance budgets definidos
+- Key pages to monitor
+- User segments (device, geography, connection)
+- Alerting channels (Slack, email)
+
+## Passos
+
+### 1. Monitoring Architecture
+| Camada | Tipo | Frequencia | Cobertura |
+|--------|------|-----------|----------|
+| Lab | Lighthouse CI | Every PR | All key pages |
+| Lab | WebPageTest | Daily scheduled | Homepage + top 5 pages |
+| Synthetic | Scheduled checks | Every 5 min | Critical user flows |
+| RUM | Real User Monitoring | Continuous | All page loads |
+| Custom | Performance Observer | Continuous | Specific metrics |
+
+### 2. Real User Monitoring (RUM)
+```typescript
+// lib/performance/rum.ts
+export function initRUM() {
+  if (typeof window === 'undefined') return;
+
+  // Core Web Vitals
+  reportWebVitals({
+    onLCP: (metric) => sendMetric('LCP', metric),
+    onINP: (metric) => sendMetric('INP', metric),
+    onCLS: (metric) => sendMetric('CLS', metric),
+    onFCP: (metric) => sendMetric('FCP', metric),
+    onTTFB: (metric) => sendMetric('TTFB', metric),
+  });
+
+  // Custom metrics
+  observeLongTasks();
+  observeResourceTiming();
+  observeLayoutShifts();
+}
+
+function sendMetric(name: string, metric: Metric) {
+  const payload = {
+    name,
+    value: metric.value,
+    rating: metric.rating, // 'good' | 'needs-improvement' | 'poor'
+    delta: metric.delta,
+    id: metric.id,
+    page: window.location.pathname,
+    connection: getConnectionType(),
+    device: getDeviceCategory(),
+    timestamp: Date.now(),
+  };
+
+  // Use sendBeacon for reliability
+  if (navigator.sendBeacon) {
+    navigator.sendBeacon('/api/metrics', JSON.stringify(payload));
+  }
+}
+
+function observeLongTasks() {
+  const observer = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      if (entry.duration > 50) {
+        sendMetric('LongTask', {
+          value: entry.duration,
+          rating: entry.duration > 100 ? 'poor' : 'needs-improvement',
+        });
+      }
+    }
+  });
+  observer.observe({ type: 'longtask', buffered: true });
+}
+```
+
+### 3. Next.js Web Vitals Integration
+```typescript
+// app/layout.tsx
+import { SpeedInsights } from '@vercel/speed-insights/next';
+import { Analytics } from '@vercel/analytics/react';
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <SpeedInsights />
+        <Analytics />
+      </body>
+    </html>
+  );
+}
+
+// Custom reportWebVitals
+// pages/_app.tsx (pages router) or via web-vitals library
+export function reportWebVitals(metric) {
+  const { name, value, rating, id } = metric;
+
+  // Send to analytics
+  window.gtag?.('event', name, {
+    event_category: 'Web Vitals',
+    event_label: id,
+    value: Math.round(name === 'CLS' ? value * 1000 : value),
+    non_interaction: true,
+    metric_rating: rating,
+  });
+}
+```
+
+### 4. Alert Thresholds
+| Metrica | Good | Warning | Critical | Action |
+|---------|------|---------|----------|--------|
+| LCP p75 | < 2.5s | 2.5-4.0s | > 4.0s | Investigate immediately |
+| INP p75 | < 200ms | 200-500ms | > 500ms | Review interaction handlers |
+| CLS p75 | < 0.1 | 0.1-0.25 | > 0.25 | Check layout stability |
+| FCP p75 | < 1.8s | 1.8-3.0s | > 3.0s | Review critical path |
+| TTFB p75 | < 0.8s | 0.8-1.8s | > 1.8s | Check server/CDN |
+| Error rate | < 0.1% | 0.1-1% | > 1% | Check error logs |
+| LongTask rate | < 5/page | 5-15/page | > 15/page | Profile main thread |
+
+### 5. Dashboard Specification
+```yaml
+dashboard:
+  name: "DX Performance Dashboard"
+
+  sections:
+    - name: "Core Web Vitals Overview"
+      widgets:
+        - type: gauge
+          metrics: [LCP, INP, CLS]
+          thresholds: [good, needs-improvement, poor]
+          timeframe: "last 28 days"
+          percentile: p75
+
+    - name: "Performance Trends"
+      widgets:
+        - type: timeseries
+          metrics: [LCP, FCP, TTFB, CLS, INP]
+          timeframe: "last 90 days"
+          granularity: daily
+          percentile: p75
+
+    - name: "Page-Level Breakdown"
+      widgets:
+        - type: table
+          dimensions: [page_path]
+          metrics: [LCP, INP, CLS, page_views]
+          sort: "page_views DESC"
+          limit: 20
+
+    - name: "Device & Connection"
+      widgets:
+        - type: bar_chart
+          dimension: device_category
+          metrics: [LCP, INP]
+        - type: bar_chart
+          dimension: connection_type
+          metrics: [LCP, TTFB]
+
+    - name: "Geographic Distribution"
+      widgets:
+        - type: map
+          dimension: country
+          metric: LCP
+          color_scale: [green, yellow, red]
+
+    - name: "Regression Detection"
+      widgets:
+        - type: anomaly_detection
+          metrics: [LCP, INP, CLS]
+          sensitivity: medium
+          baseline: "rolling 14-day average"
+```
+
+### 6. Regression Detection Logic
+```yaml
+regression_detection:
+  algorithm: "statistical change detection"
+
+  rules:
+    sudden_regression:
+      condition: "metric_p75 > baseline_p75 * 1.2"
+      window: "1 hour"
+      action: "alert_critical"
+      description: "20%+ degradation within 1 hour"
+
+    gradual_regression:
+      condition: "7d_avg > 14d_avg * 1.1"
+      window: "7 days"
+      action: "alert_warning"
+      description: "10%+ increase over 7-day trend"
+
+    threshold_breach:
+      condition: "metric_p75 crosses CWV threshold"
+      example: "LCP p75 goes from 2.3s to 2.7s (crosses 2.5s)"
+      action: "alert_critical"
+
+    deploy_correlation:
+      condition: "regression detected within 2h of deploy"
+      action: "alert_critical + tag deploy SHA"
+      description: "Correlate regression with specific deployment"
+
+  notifications:
+    critical:
+      channels: ["slack:#dx-alerts", "pagerduty"]
+      include: "metric, page, deploy SHA, comparison chart"
+    warning:
+      channels: ["slack:#dx-performance"]
+      include: "metric, trend chart, suggested investigation"
+```
+
+### 7. Performance Review Cadence
+| Frequencia | Atividade | Responsavel |
+|-----------|----------|------------|
+| Continuous | RUM collection + anomaly detection | Automated |
+| Daily | Dashboard review (5 min scan) | Apex |
+| Weekly | Performance report (top issues) | Apex |
+| Bi-weekly | Deep-dive into top regression | DX Team |
+| Monthly | Performance budget review | Nexus + Apex |
+| Quarterly | Third-party audit + budget adjustment | Apex + stakeholders |
+
+### 8. Incident Response
+```yaml
+incident_response:
+  severity_levels:
+    P0_critical:
+      criteria: "CWV threshold breached for > 50% users"
+      response_time: "< 30 min"
+      actions:
+        - "Identify deploy that caused regression"
+        - "Rollback if necessary"
+        - "Root cause analysis"
+        - "Post-mortem within 48h"
+
+    P1_major:
+      criteria: "CWV warning threshold for > 25% users"
+      response_time: "< 2 hours"
+      actions:
+        - "Identify affected pages and user segments"
+        - "Create fix ticket with priority"
+        - "Implement fix within current sprint"
+
+    P2_minor:
+      criteria: "Gradual regression detected"
+      response_time: "< 1 business day"
+      actions:
+        - "Log in performance backlog"
+        - "Schedule investigation"
+        - "Monitor for escalation"
+```
+
+## Saida
+- RUM implementation
+- Dashboard specification
+- Alert configuration
+- Regression detection rules
+- Incident response playbook
+- Review cadence documentation
+
+## Validacao
+- [ ] RUM coletando CWV de usuarios reais
+- [ ] Dashboard com all key metrics
+- [ ] Alerts configurados por threshold
+- [ ] Regression detection automatizado
+- [ ] Deploy correlation funcionando
+- [ ] Incident response process documentado
+- [ ] Review cadence estabelecido
+- [ ] Historical data retido >= 90 dias

package/squads/squad-design/tasks/optimize-font-loading.md

@@ -0,0 +1,128 @@
+---
+task: optimize-font-loading
+responsavel: "@dx-performance-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Optimize Font Loading
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Apex (dx-performance-engineer)
+- **Complexity:** Standard
+
+## Objetivo
+Otimizar carregamento de web fonts — minimizar FOUT/FOIT, reduzir tamanho e garantir que fonts nao impactam LCP.
+
+## Entrada
+- Selected typefaces
+- Character sets needed
+- Performance budgets (fonts < 100KB)
+- Browser targets
+
+## Passos
+
+### 1. Font Strategy
+| Aspecto | Recomendacao |
+|---------|-------------|
+| Fonte | next/font (auto-optimization) |
+| Formato | WOFF2 (melhor compressao) |
+| Subsetting | Latin only (ou conforme necessidade) |
+| Weights | Max 3-4 (regular, medium, semibold, bold) |
+| Italics | Apenas se realmente usado |
+| Variable font | Preferir quando disponivel |
+
+### 2. Next.js Font Optimization
+```typescript
+// app/layout.tsx
+import { Inter } from 'next/font/google';
+
+const inter = Inter({
+  subsets: ['latin'],
+  display: 'swap',
+  variable: '--font-sans',
+  preload: true,
+});
+
+export default function RootLayout({ children }) {
+  return (
+    <html lang="pt-BR" className={inter.variable}>
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+### 3. Font Budget
+| Item | Budget |
+|------|--------|
+| Total font files | < 100KB |
+| Per weight | < 25KB (WOFF2) |
+| Max weights loaded | 4 |
+| Variable font | < 50KB (all weights) |
+| Font files count | <= 2 files |
+
+### 4. font-display Strategy
+| Valor | Comportamento | Quando |
+|-------|--------------|--------|
+| swap | Fallback → swap when loaded | Default (best for LCP) |
+| optional | Fallback → swap only if cached | Best for CLS |
+| fallback | Short block → swap if fast | Balance |
+| block | Invisible → show when loaded | Never for body text |
+
+### 5. Self-Hosting vs CDN
+| Approach | Pros | Cons |
+|----------|------|------|
+| Self-host (next/font) | No external request, preload | Need to manage updates |
+| Google Fonts CDN | Easy, cached globally | Extra DNS + connection |
+| **Recomendacao** | Self-host via next/font | Best performance |
+
+### 6. Fallback Font Matching
+```css
+/* Size-adjusted fallback to prevent CLS */
+@font-face {
+  font-family: 'Inter Fallback';
+  src: local('Arial');
+  ascent-override: 90.44%;
+  descent-override: 22.25%;
+  line-gap-override: 0%;
+  size-adjust: 107.64%;
+}
+```
+
+Next.js handles this automatically with `adjustFontFallback`.
+
+## Saida
+- Font loading configuration
+- next/font setup
+- Font budget documentation
+- Fallback font configuration
+- Performance impact measurement
+
+## Validacao
+- [ ] Fonts self-hosted via next/font
+- [ ] WOFF2 format only
+- [ ] Total < 100KB
+- [ ] font-display: swap configurado
+- [ ] Subsets definidos (latin)
+- [ ] No FOIT (invisible text)
+- [ ] Fallback font size-matched

package/squads/squad-design/tasks/optimize-image-pipeline.md

@@ -0,0 +1,143 @@
+---
+task: optimize-image-pipeline
+responsavel: "@dx-performance-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+
+Checklist:
+  - "[ ] Validar inputs e pre-condicoes"
+  - "[ ] Executar steps conforme documentado"
+  - "[ ] Verificar criterios de qualidade"
+  - "[ ] Gerar output no formato especificado"
+---
+
+# Task: Optimize Image Pipeline
+
+## Metadata
+- **Squad:** squad-design
+- **Agent:** Apex (dx-performance-engineer)
+- **Complexity:** Standard
+
+## Objetivo
+Otimizar pipeline de imagens — configurar formatos modernos, responsive images, lazy loading e CDN para minimizar impacto no LCP e bandwidth.
+
+## Entrada
+- Image inventory
+- Performance budgets
+- Device targets
+- CDN infrastructure
+
+## Passos
+
+### 1. Format Selection
+| Formato | Quando | Savings |
+|---------|--------|---------|
+| AVIF | Default para photos | ~50% vs JPEG |
+| WebP | Fallback de AVIF | ~30% vs JPEG |
+| SVG | Icons, logos, illustrations | Smallest for vectors |
+| JPEG | Fallback final | Baseline |
+| PNG | Transparency necessaria (nao photo) | Quando alpha channel |
+
+### 2. Next.js Image Component
+```typescript
+import Image from 'next/image';
+
+// Hero image (LCP candidate) — priority
+<Image
+  src="/hero.jpg"
+  alt="Hero description"
+  width={1440}
+  height={600}
+  priority  // Preloads, no lazy
+  sizes="100vw"
+  quality={80}
+/>
+
+// Content image — lazy loaded (default)
+<Image
+  src="/feature.jpg"
+  alt="Feature description"
+  width={600}
+  height={400}
+  sizes="(max-width: 768px) 100vw, 50vw"
+  quality={75}
+/>
+```
+
+### 3. Responsive Image Sizes
+```html
+<!-- Sizes attribute guide -->
+sizes="
+  (max-width: 640px) 100vw,    <!-- Mobile: full width -->
+  (max-width: 1024px) 50vw,    <!-- Tablet: half width -->
+  33vw                          <!-- Desktop: third width -->
+"
+```
+
+### 4. Image Budget Per Page
+| Tipo de pagina | Budget total | Max por imagem |
+|---------------|-------------|---------------|
+| Landing Page | 500KB | 200KB (hero) |
+| Content Page | 400KB | 150KB |
+| Dashboard | 200KB | 100KB |
+| Product Page | 600KB | 200KB (hero), 50KB (thumbs) |
+
+### 5. Optimization Pipeline
+```yaml
+image_pipeline:
+  input: "original uploaded image"
+
+  steps:
+    - resize: "Generate srcset variants (640, 768, 1024, 1280, 1920)"
+    - format: "Convert to AVIF + WebP + fallback"
+    - quality: "80 for AVIF, 75 for WebP, 80 for JPEG"
+    - metadata: "Strip EXIF data"
+    - compress: "Further lossy/lossless optimization"
+
+  output:
+    - "/images/{name}-640.avif"
+    - "/images/{name}-640.webp"
+    - "/images/{name}-1024.avif"
+    # ... etc
+
+  cdn:
+    cache: "immutable, max-age=31536000"
+    edge_optimization: true
+```
+
+### 6. Special Cases
+| Caso | Tratamento |
+|------|-----------|
+| LCP image | `priority`, `fetchpriority="high"`, preload |
+| Above-fold | Eager loading, preload |
+| Below-fold | Default lazy loading |
+| Background images | CSS `image-set()` or `<picture>` |
+| User-uploaded | Server-side optimization on upload |
+| Decorative | `alt=""`, optimize aggressively |
+
+## Saida
+- Image optimization pipeline config
+- Format selection guide
+- Responsive image patterns
+- Budget enforcement per page
+- CDN configuration
+
+## Validacao
+- [ ] AVIF/WebP serving configurado
+- [ ] LCP image preloaded
+- [ ] Responsive sizes attribute em todas as images
+- [ ] Lazy loading default para below-fold
+- [ ] Budget per page respeitado
+- [ ] CDN caching configurado