aiox-core 5.0.2 → 5.0.3

package/pro/squads/design/workflows/self-healing-workflow.yaml

@@ -0,0 +1,237 @@
+# Self-Healing Workflow for Design System
+
+# Heuristic: #16 - Self-healing obrigatório
+# Princípio: Não reinventar - plugar ferramentas validadas (Vercel 87%, CodeRabbit, etc)
+
+name: self-healing-design-system
+version: "1.0.0"
+description: |
+  Workflow de auto-correção para design system.
+  Usa ferramentas existentes (Vercel, CodeRabbit, GitHub Actions) para detectar e corrigir problemas automaticamente.
+
+triggers:
+  - on_push:
+      paths:
+        - "workspace/ui/**"
+        - "workspace/system/**"
+        - "workspace/domains/design-system/**"
+  - on_pr:
+      paths:
+        - "**/*.tsx"
+        - "**/*.css"
+  - scheduled:
+      cron: "0 6 * * 1"  # Segundas às 6h
+
+# =============================================================================
+# DETECTION LAYER
+# =============================================================================
+detection:
+  # 1. Lint (ESLint + Prettier)
+  lint:
+    tool: "eslint"
+    config: ".eslintrc.js"
+    auto_fix: true
+    severity_threshold: "warning"
+
+  # 2. Type Check (TypeScript)
+  typecheck:
+    tool: "typescript"
+    config: "tsconfig.json"
+    strict: true
+
+  # 3. A11y (axe-core)
+  accessibility:
+    tool: "axe-core"
+    rules:
+      - "wcag2aa"
+      - "best-practice"
+    severity_threshold: "serious"
+
+  # 4. Token Drift
+  token_drift:
+    tool: "custom"
+    script: "scripts/detect-token-drift.cjs"
+    checks:
+      - hardcoded_colors: true
+      - hardcoded_spacing: true
+      - missing_css_vars: true
+
+  # 5. Registry Sync
+  registry_sync:
+    tool: "custom"
+    script: "scripts/validate-registry-sync.cjs"
+    checks:
+      - component_count_match: true
+      - metadata_completeness: true
+
+# =============================================================================
+# AUTO-FIX LAYER
+# =============================================================================
+auto_fix:
+  # Fixes que podem rodar sem aprovação humana
+  automatic:
+    - type: "lint"
+      action: "eslint --fix"
+      commit_message: "fix(ds): auto-fix lint issues"
+
+    - type: "formatting"
+      action: "prettier --write"
+      commit_message: "style(ds): auto-format code"
+
+    - type: "imports"
+      action: "eslint --fix --rule 'import/order: error'"
+      commit_message: "fix(ds): organize imports"
+
+  # Fixes que requerem aprovação
+  requires_approval:
+    - type: "token_replacement"
+      description: "Substituir hardcoded values por tokens"
+      action: "scripts/replace-hardcoded-tokens.cjs"
+      approval_channel: "#design-system"
+
+    - type: "a11y_fix"
+      description: "Adicionar atributos de acessibilidade"
+      action: "scripts/add-a11y-attributes.cjs"
+      approval_channel: "#design-system"
+
+    - type: "component_migration"
+      description: "Migrar componente para novo padrão"
+      action: "scripts/migrate-component.cjs"
+      approval_channel: "#design-system"
+
+# =============================================================================
+# EXTERNAL TOOLS INTEGRATION
+# =============================================================================
+integrations:
+  # Vercel (87% auto-fix rate)
+  vercel:
+    enabled: true
+    features:
+      - preview_deployments: true
+      - build_error_detection: true
+      - performance_monitoring: true
+    auto_actions:
+      - on_build_fail: "notify_slack"
+      - on_perf_regression: "create_issue"
+
+  # CodeRabbit
+  coderabbit:
+    enabled: true
+    features:
+      - pr_review: true
+      - security_scan: true
+      - pattern_detection: true
+    config:
+      focus:
+        - "design_system_patterns"
+        - "accessibility"
+        - "token_usage"
+
+  # GitHub Actions
+  github_actions:
+    enabled: true
+    workflows:
+      - "design-ci.yml"
+      - "copy-lint.yml"
+    auto_actions:
+      - on_check_fail: "add_comment"
+      - on_fix_available: "create_suggestion"
+
+  # Sentry (Observability)
+  sentry:
+    enabled: true
+    features:
+      - error_tracking: true
+      - performance_monitoring: true
+    alerts:
+      - on_spike: "notify_slack"
+      - on_new_error: "create_issue"
+
+# =============================================================================
+# NOTIFICATION LAYER
+# =============================================================================
+notifications:
+  channels:
+    slack:
+      webhook: "${SLACK_WEBHOOK_URL}"
+      channel: "#design-system"
+
+    github:
+      issues: true
+      prs: true
+      comments: true
+
+  templates:
+    auto_fix_applied:
+      title: "🔧 Auto-fix applied"
+      body: |
+        **Type:** {fix_type}
+        **Files:** {files_changed}
+        **Commit:** {commit_sha}
+
+    fix_requires_approval:
+      title: "⚠️ Fix requires approval"
+      body: |
+        **Type:** {fix_type}
+        **Description:** {description}
+        **Impact:** {files_affected} files
+        **Action:** Review and approve in PR #{pr_number}
+
+    detection_report:
+      title: "📊 Weekly Design System Health"
+      body: |
+        **Period:** {start_date} - {end_date}
+
+        **Issues Detected:** {total_issues}
+        **Auto-fixed:** {auto_fixed} ({auto_fix_rate}%)
+        **Pending Review:** {pending_review}
+
+        **Top Issues:**
+        {top_issues_list}
+
+# =============================================================================
+# METRICS
+# =============================================================================
+metrics:
+  track:
+    - auto_fix_rate
+    - detection_accuracy
+    - mean_time_to_fix
+    - issues_by_type
+    - issues_by_component
+
+  targets:
+    auto_fix_rate: 80%
+    mean_time_to_fix: "< 24h"
+    detection_accuracy: 95%
+
+# =============================================================================
+# ROLLBACK
+# =============================================================================
+rollback:
+  enabled: true
+  triggers:
+    - build_failure_after_fix
+    - test_failure_after_fix
+    - manual_request
+
+  actions:
+    - revert_commit
+    - notify_team
+    - create_incident
+
+# =============================================================================
+# QUALITY GATES
+# =============================================================================
+quality_gates:
+  pre_merge:
+    - lint_pass: required
+    - typecheck_pass: required
+    - a11y_pass: required
+    - token_drift_check: required
+    - registry_sync: required
+
+  post_deploy:
+    - lighthouse_score: ">= 90"
+    - core_web_vitals: "pass"
+    - error_rate: "< 0.1%"

package/pro/squads/design/workflows/storybook-brownfield-migration.yaml

@@ -0,0 +1,400 @@
+# WF-SB-BF: Storybook Brownfield Migration Pipeline
+# Duration: 1-3 sessions (depends on component count)
+# Best for: Existing codebases with 20-200+ components needing Storybook documentation
+# Key Agents: @storybook-expert, @brad-frost (atomic classification)
+
+workflow:
+  id: wf-storybook-brownfield-migration
+  name: "Storybook Brownfield Migration Pipeline"
+  version: "1.0"
+  orchestrator: "@storybook-expert"
+  duration: "1-3 sessions"
+  description: |
+    End-to-end pipeline for migrating brownfield codebases into Storybook.
+    Takes ANY existing React/Next.js project and produces:
+    - Complete component inventory with atomic classification
+    - Dependency graph showing component relationships
+    - Phased migration plan (atoms → molecules → organisms → templates → pages)
+    - Story files for EVERY component
+    - Mock decorators for context-dependent components
+    - Adaptation report documenting all changes
+
+    Supports same-project (add stories) and cross-project (copy + add stories) modes.
+
+  best_for:
+    - "Existing project with 20-200+ undocumented components"
+    - "Migrating components from one project to another"
+    - "Design system adoption in legacy codebases"
+    - "Component library documentation from scratch"
+    - "Atomization of monolithic UI code"
+
+  decision_matrix_fit:
+    awareness: "Migration"
+    sophistication: "Advanced"
+    primary_output: "Complete Storybook with brownfield component stories"
+
+  migration_modes:
+    same_project:
+      description: "Add stories co-located with existing components"
+      when: "Project already has Storybook or components stay in place"
+      output: "*.stories.tsx next to each component"
+    cross_project:
+      description: "Copy components to target project, adapt imports, add stories"
+      when: "Building a separate design system package"
+      output: "Components + stories in target project"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# PHASE 1: SCAN (Component Inventory & Classification)
+# ═══════════════════════════════════════════════════════════════════════════════
+phases:
+  - id: PHASE-1
+    name: "Scan & Classify Components"
+    tier: 0
+    description: |
+      Walk the source codebase and produce a complete component inventory.
+      Classify each component by atomic level (atom/molecule/organism/template/page),
+      map dependencies between components, and generate a phased migration plan
+      ordered by dependency tree.
+
+    tasks:
+      - task_file: sb-brownfield-scan.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Inventory all components, classify, build dependency graph"
+        output: "component-inventory.json, migration-plan.md, dependency-graph.json"
+
+    checkpoint:
+      criteria:
+        - "All component files scanned and classified"
+        - "Dependency graph has no unresolved references"
+        - "Migration plan has at least 2 phases"
+        - "Atomic distribution covers atom through organism minimum"
+      human_review: true
+      message: |
+        Scan complete. Review the migration plan before proceeding.
+        - Total components: {total_components}
+        - Atoms: {atoms} | Molecules: {molecules} | Organisms: {organisms}
+        - Already have stories: {with_stories}
+        - Need stories: {migration_gap}
+        Approve to proceed with migration, or adjust plan.
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 2: PREPARE (Storybook Environment)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-2
+    name: "Prepare Storybook Environment"
+    tier: 0
+    description: |
+      Ensure target project has Storybook installed and configured.
+      If not present, run sb-install and sb-configure. If present,
+      verify stories glob covers brownfield component locations.
+
+    tasks:
+      - task_file: sb-install.md
+        agent: "@storybook-expert"
+        required: false
+        description: "Install Storybook if not present (skip if exists)"
+        output: "installed_packages"
+        notes: |
+          CONDITIONAL: Only execute if target project has no Storybook.
+          Check for .storybook/ directory and storybook in devDependencies.
+
+      - task_file: sb-configure.md
+        agent: "@storybook-expert"
+        required: false
+        description: "Configure Storybook if not configured (skip if exists)"
+        output: ".storybook/main.ts, .storybook/preview.ts"
+        notes: |
+          CONDITIONAL: Only execute if .storybook/main.ts doesn't exist.
+          If exists, verify stories glob covers component paths.
+
+    checkpoint:
+      criteria:
+        - "Storybook is installed and configured"
+        - "Stories glob covers all component locations from scan"
+        - "Storybook dev server starts without errors"
+      human_review: false
+      message: "Storybook environment ready. Starting migration."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 3: MIGRATE ATOMS (Foundation Components)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-3
+    name: "Migrate Atoms & Primitives"
+    tier: 1
+    description: |
+      Migrate all atom-level components first. These have zero internal
+      dependencies and form the foundation for all other components.
+      Typically: buttons, badges, avatars, inputs, labels, separators, icons.
+
+    tasks:
+      - task_file: sb-brownfield-migrate.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Generate stories for all atom components"
+        output: "story_files (atoms)"
+        notes: |
+          Execute with: phase_filter="1" (atoms phase from migration plan)
+          These components should need NO mocks or decorators.
+          Strategy: args-driven stories with Default + Variants + Gallery.
+
+    checkpoint:
+      criteria:
+        - "All atom components have stories"
+        - "npm run typecheck passes"
+        - "All atoms render in Storybook without errors"
+      human_review: false
+      message: "Atoms migrated. Foundation complete."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 4: MIGRATE MOLECULES (Composite Components)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-4
+    name: "Migrate Molecules"
+    tier: 1
+    description: |
+      Migrate molecule-level components. These compose 2-3 atoms into
+      reusable patterns. May need render functions to show composition.
+      Typically: InputWithLabel, CardHeader, NavItem, SearchBar.
+
+    tasks:
+      - task_file: sb-brownfield-migrate.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Generate stories for all molecule components"
+        output: "story_files (molecules)"
+        notes: |
+          Execute with: phase_filter matching molecule phases from migration plan.
+          Strategy: render function stories showing composition.
+
+    checkpoint:
+      criteria:
+        - "All molecule components have stories"
+        - "npm run typecheck passes"
+        - "Molecules render correctly (atoms are available)"
+      human_review: false
+      message: "Molecules migrated."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 5: MIGRATE ORGANISMS (Feature Components)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-5
+    name: "Migrate Organisms & Features"
+    tier: 2
+    description: |
+      Migrate organism-level components. These are section-level components
+      with business logic, context dependencies, and multiple internal deps.
+      This phase typically requires the most adaptations (mock providers,
+      stub data, decorator wrappers).
+
+      Includes: AgentCard, KanbanColumn, ChatContainer, Sidebar, etc.
+
+    tasks:
+      - task_file: sb-brownfield-migrate.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Generate stories for organisms with necessary mocks"
+        output: "story_files (organisms), mock_files"
+        notes: |
+          Execute with: phase_filter matching organism phases.
+          Strategy: render function + decorators for context.
+          Create mock providers in .storybook/mocks/ as needed.
+          Document every adaptation in the report.
+
+    checkpoint:
+      criteria:
+        - "All organism components have stories"
+        - "Mock decorators created for context-dependent components"
+        - "npm run typecheck passes"
+        - "All adaptations documented in report"
+      human_review: true
+      message: |
+        Organisms migrated. This phase had the most adaptations.
+        Review mock files and adaptations before proceeding to templates/pages.
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 6: MIGRATE TEMPLATES & PAGES (Layout & Full Pages)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-6
+    name: "Migrate Templates & Pages"
+    tier: 2
+    description: |
+      Migrate template and page-level components. These are full layouts
+      and pages that compose organisms. Need layout: "fullscreen" parameter
+      and comprehensive mock data.
+
+    tasks:
+      - task_file: sb-brownfield-migrate.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Generate stories for templates and pages"
+        output: "story_files (templates, pages)"
+        notes: |
+          Execute with: phase_filter matching template/page phases.
+          Use parameters: { layout: "fullscreen" } for layout components.
+          May need mock routing, mock API responses, mock global state.
+
+    checkpoint:
+      criteria:
+        - "All template and page components have stories"
+        - "Layout stories use fullscreen layout"
+        - "npm run typecheck passes"
+      human_review: false
+      message: "Templates and pages migrated. Running final verification."
+
+  # ═══════════════════════════════════════════════════════════════════════════════
+  # PHASE 7: VERIFY (Final Quality Gate)
+  # ═══════════════════════════════════════════════════════════════════════════════
+  - id: PHASE-7
+    name: "Verify Complete Migration"
+    tier: 2
+    description: |
+      Final verification of the complete brownfield migration.
+      Runs typecheck, lint, build, story coverage check, and
+      generates the final adaptation report.
+
+    tasks:
+      - task_file: sb-verify.md
+        agent: "@storybook-expert"
+        required: true
+        description: "Run all verification checks"
+        output: "verification_report"
+
+    checkpoint:
+      criteria:
+        - "TypeScript: zero errors"
+        - "Lint: zero errors"
+        - "Build: succeeds"
+        - "Coverage: 100% of planned components"
+        - "Adaptation report complete"
+      human_review: true
+      message: "Migration complete. Review final report."
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# ERROR HANDLING
+# ═══════════════════════════════════════════════════════════════════════════════
+error_handling:
+  on_phase_failure:
+    - log_error: true
+    - notify_stakeholders: false
+    - create_remediation_task: false
+    - halt_workflow: true
+
+  on_checkpoint_failure:
+    - log_failure_reason: true
+    - return_to_previous_phase: false
+    - max_retries: 3
+
+  phase_specific:
+    PHASE-5_organisms:
+      description: "Organisms phase most likely to fail due to context deps"
+      on_failure: "Create mock for failing component, document in report, continue"
+      max_component_retries: 2
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# COMPLETION SIGNALS
+# ═══════════════════════════════════════════════════════════════════════════════
+completion_signal: "<promise>COMPLETE</promise>"
+checkpoint_signal: "<promise>CHECKPOINT:PHASE-X</promise>"
+blocked_signal: "<promise>BLOCKED:T-X.Y</promise>"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# OUTPUT ARTIFACTS
+# ═══════════════════════════════════════════════════════════════════════════════
+outputs:
+  scan_results:
+    - "outputs/design-system/{project}/brownfield/component-inventory.json"
+    - "outputs/design-system/{project}/brownfield/dependency-graph.json"
+    - "outputs/design-system/{project}/brownfield/migration-plan.md"
+  stories:
+    - "src/components/**/*.stories.tsx (one per component)"
+  mocks:
+    - ".storybook/mocks/*.tsx (provider mocks)"
+    - ".storybook/decorators/*.tsx (story decorators)"
+  reports:
+    - "outputs/design-system/{project}/brownfield/adaptation-report.md"
+    - "Verification report (typecheck, lint, build, coverage)"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# AGENT ASSIGNMENTS BY PHASE
+# ═══════════════════════════════════════════════════════════════════════════════
+agents_by_phase:
+  PHASE-1:
+    primary:
+      - "@storybook-expert"
+    secondary:
+      - "@brad-frost"
+  PHASE-2:
+    primary:
+      - "@storybook-expert"
+  PHASE-3:
+    primary:
+      - "@storybook-expert"
+  PHASE-4:
+    primary:
+      - "@storybook-expert"
+  PHASE-5:
+    primary:
+      - "@storybook-expert"
+    secondary:
+      - "@brad-frost"
+  PHASE-6:
+    primary:
+      - "@storybook-expert"
+  PHASE-7:
+    primary:
+      - "@storybook-expert"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# QUALITY CHECKLIST
+# ═══════════════════════════════════════════════════════════════════════════════
+quality_checklist:
+  scan:
+    - "[ ] All component files discovered"
+    - "[ ] Atomic classification applied to every component"
+    - "[ ] Dependency graph is complete and acyclic"
+    - "[ ] Migration plan phases ordered by dependency"
+
+  atoms:
+    - "[ ] All atoms have stories"
+    - "[ ] Stories are args-driven (no unnecessary render functions)"
+    - "[ ] Gallery stories for multi-variant atoms"
+
+  molecules:
+    - "[ ] All molecules have stories"
+    - "[ ] Composition patterns shown in render functions"
+
+  organisms:
+    - "[ ] All organisms have stories"
+    - "[ ] Context dependencies mocked"
+    - "[ ] Adaptations documented"
+
+  templates_pages:
+    - "[ ] All templates/pages have stories"
+    - "[ ] Layout stories use fullscreen"
+    - "[ ] Mock data is representative"
+
+  verification:
+    - "[ ] npm run typecheck — zero errors"
+    - "[ ] npm run lint — zero errors"
+    - "[ ] npm run build-storybook — succeeds"
+    - "[ ] Coverage: 100% of planned components"
+    - "[ ] Adaptation report complete"
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# METADATA
+# ═══════════════════════════════════════════════════════════════════════════════
+metadata:
+  version: "1.0"
+  framework: "AIOS Design Squad"
+  created: "2026-02-25"
+  primary_use_case: "Brownfield component migration to Storybook"
+  key_difference: |
+    Unlike storybook-full-setup (greenfield), this workflow handles
+    EXISTING codebases with scattered, undocumented components.
+    Key capabilities:
+    - Component discovery and atomic classification
+    - Dependency-aware migration ordering
+    - Context isolation (mock providers, stub data)
+    - Same-project and cross-project modes
+    - Adaptation tracking and reporting