aiox-core 5.0.3 → 5.0.5

package/pro/squads/design/templates/ds-migration-strategy-tmpl.md

@@ -1,524 +0,0 @@
-# Migration Strategy: {{PROJECT_NAME}}
-
-**Generated:** {{GENERATION_DATE}}
-**Project:** {{PROJECT_NAME}}
-**Current Patterns:** {{TOTAL_PATTERNS_BEFORE}}
-**Target Patterns:** {{TOTAL_PATTERNS_AFTER}}
-**Reduction:** {{REDUCTION_PERCENTAGE}}%
-
----
-
-## Executive Summary
-
-This migration strategy consolidates **{{TOTAL_PATTERNS_BEFORE}} UI patterns** into **{{TOTAL_PATTERNS_AFTER}} standardized components**, achieving a **{{REDUCTION_PERCENTAGE}}% reduction** in maintenance burden.
-
-**Key Outcomes:**
-- 💰 **{{ANNUAL_SAVINGS}}/year** in maintenance savings
-- ⚡ **{{VELOCITY_IMPROVEMENT}}x** faster feature development
-- 🎯 **{{CONSOLIDATION_IMPACT}}** reduction in code surface area
-- 📅 **{{TOTAL_TIMELINE}}** phased rollout timeline
-
-**Risk Level:** Low - Phased approach minimizes disruption
-
----
-
-## Migration Philosophy
-
-1. **No Big-Bang Rewrites** - Gradual, phase-by-phase rollout
-2. **Foundation First** - Token system deploys before visual changes
-3. **High-Impact Priority** - Replace most-used patterns first for immediate ROI
-4. **Rollback Ready** - Each phase independently reversible
-5. **Measured Progress** - Metrics tracked at every stage
-
----
-
-## Phase 1: Foundation
-
-### Goal
-Deploy token system with **zero visual changes**. Establish foundation for all future work.
-
-### Prerequisites
-- [x] Design tokens extracted and validated
-- [ ] Token files added to repository
-- [ ] Build pipeline configured for token processing
-- [ ] Development team trained on token usage
-
-### Tasks
-
-#### 1.1 Token System Deployment
-- [ ] Add `tokens.yaml` to `{{TOKEN_DIRECTORY}}`
-- [ ] Generate multi-format exports (JSON, CSS, Tailwind, SCSS)
-- [ ] Configure build pipeline to process tokens
-- [ ] Validate token imports work in development environment
-
-#### 1.2 Existing CSS Token Migration (Automated)
-- [ ] Run automated CSS variable replacement script
-- [ ] Replace hardcoded colors with `var(--color-*)` references
-- [ ] Replace hardcoded spacing with `var(--space-*)` references
-- [ ] Replace hardcoded typography with `var(--font-*)` references
-
-#### 1.3 Validation & Testing
-- [ ] Visual regression tests pass (no UI changes)
-- [ ] Build succeeds with token system integrated
-- [ ] Development environment loads correctly
-- [ ] Production build size unchanged or reduced
-
-### Timeline
-**Duration:** {{PHASE_1_DURATION}}
-**Effort:** {{PHASE_1_EFFORT}} developer-hours
-
-### Risk Assessment
-**Risk Level:** 🟢 Low
-
-**Risks:**
-- Build pipeline integration issues
-- Token naming conflicts with existing variables
-
-**Mitigation:**
-- Namespace tokens with `ds-` prefix if conflicts occur
-- Incremental rollout (development → staging → production)
-- Rollback procedure: Revert commit, restore previous CSS
-
-### Success Criteria
-- ✅ Tokens deployed to all environments
-- ✅ Zero visual regressions detected
-- ✅ Build pipeline stable
-- ✅ No user-facing changes
-
-### Rollback Procedure
-```bash
-# If issues detected, rollback immediately
-git revert {{PHASE_1_COMMIT_HASH}}
-npm run build
-npm run deploy
-```
-
----
-
-## Phase 2: High-Impact Patterns
-
-### Goal
-Replace **top {{TOP_N_PATTERNS}} most-used components** for immediate ROI and velocity improvement.
-
-### Prerequisites
-- [x] Phase 1 complete and stable
-- [ ] Design system components generated and tested
-- [ ] Component library integrated into project
-- [ ] Migration mapping documented (old → new)
-
-### High-Impact Targets
-
-#### Pattern Priority List
-{{#EACH_HIGH_IMPACT_PATTERN}}
-**{{PATTERN_RANK}}. {{PATTERN_NAME}}**
-- Current variations: {{CURRENT_VARIATIONS}}
-- Usage instances: {{USAGE_COUNT}}
-- Consolidates to: {{NEW_VARIANTS}} variants
-- Estimated effort: {{EFFORT_HOURS}} hours
-- Impact: {{IMPACT_SCORE}} (high/medium/low)
-{{/EACH_HIGH_IMPACT_PATTERN}}
-
-### Tasks
-
-#### 2.1 Component Replacement - {{TOP_PATTERN_1}}
-- [ ] Generate design system {{TOP_PATTERN_1}} component
-- [ ] Create unit tests (>80% coverage)
-- [ ] Document usage in pattern library
-- [ ] Identify all {{TOP_PATTERN_1_USAGE_COUNT}} usage locations
-- [ ] Replace incrementally (10-20 instances per PR)
-- [ ] Visual regression test each PR
-- [ ] Monitor production for issues
-
-#### 2.2 Component Replacement - {{TOP_PATTERN_2}}
-- [ ] Generate design system {{TOP_PATTERN_2}} component
-- [ ] Create unit tests (>80% coverage)
-- [ ] Document usage in pattern library
-- [ ] Identify all {{TOP_PATTERN_2_USAGE_COUNT}} usage locations
-- [ ] Replace incrementally (10-20 instances per PR)
-- [ ] Visual regression test each PR
-- [ ] Monitor production for issues
-
-#### 2.3 Component Replacement - {{TOP_PATTERN_3}}
-- [ ] Generate design system {{TOP_PATTERN_3}} component
-- [ ] Create unit tests (>80% coverage)
-- [ ] Document usage in pattern library
-- [ ] Identify all {{TOP_PATTERN_3_USAGE_COUNT}} usage locations
-- [ ] Replace incrementally (10-20 instances per PR)
-- [ ] Visual regression test each PR
-- [ ] Monitor production for issues
-
-#### 2.4 Deprecation Warnings
-- [ ] Add deprecation warnings to old components
-- [ ] Update documentation with migration guides
-- [ ] Alert developers when old patterns used
-
-### Timeline
-**Duration:** {{PHASE_2_DURATION}}
-**Effort:** {{PHASE_2_EFFORT}} developer-hours
-
-### Risk Assessment
-**Risk Level:** 🟡 Medium
-
-**Risks:**
-- Behavioral differences between old and new components
-- Visual regressions in production
-- Developer resistance to change
-
-**Mitigation:**
-- Extensive testing before production deployment
-- Incremental rollout (feature flags if needed)
-- Pair programming for first replacements
-- Rollback plan per component
-
-### Success Criteria
-- ✅ Top {{TOP_N_PATTERNS}} patterns fully migrated
-- ✅ Zero critical bugs in production
-- ✅ Measurable velocity improvement detected
-- ✅ Team reports positive experience
-
-### Metrics to Track
-- Feature build time (should decrease {{VELOCITY_IMPROVEMENT}}x)
-- Bug count for replaced components (should stay flat or decrease)
-- Developer satisfaction score
-- Visual consistency score
-
----
-
-## Phase 3: Long-Tail Cleanup
-
-### Goal
-Consolidate remaining **{{LONG_TAIL_COUNT}} patterns** to reach **{{FINAL_REDUCTION_PERCENTAGE}}% total reduction**.
-
-### Prerequisites
-- [x] Phase 2 complete and stable
-- [x] High-impact patterns validated in production
-- [ ] Team confident with design system patterns
-- [ ] Migration tooling refined from Phase 2 learnings
-
-### Long-Tail Targets
-
-{{#EACH_LONG_TAIL_PATTERN}}
-**{{PATTERN_NAME}}**
-- Current variations: {{CURRENT_VARIATIONS}} → {{NEW_VARIANTS}}
-- Usage instances: {{USAGE_COUNT}}
-- Effort: {{EFFORT_HOURS}} hours
-{{/EACH_LONG_TAIL_PATTERN}}
-
-### Tasks
-
-#### 3.1 Form Pattern Consolidation
-- [ ] Migrate {{FORM_VARIATIONS}} form variations → {{FORM_CONSOLIDATED}} patterns
-- [ ] Update form validation logic
-- [ ] Test accessibility compliance (WCAG AA)
-
-#### 3.2 Modal/Dialog Consolidation
-- [ ] Migrate {{MODAL_VARIATIONS}} modal variations → {{MODAL_CONSOLIDATED}} patterns
-- [ ] Standardize close behaviors
-- [ ] Test focus management
-
-#### 3.3 Navigation Consolidation
-- [ ] Migrate {{NAV_VARIATIONS}} navigation variations → {{NAV_CONSOLIDATED}} patterns
-- [ ] Standardize active state handling
-- [ ] Test responsive behavior
-
-#### 3.4 Remaining Patterns
-- [ ] Migrate all remaining low-usage patterns
-- [ ] Update documentation for all new components
-- [ ] Final visual regression suite run
-
-### Timeline
-**Duration:** {{PHASE_3_DURATION}}
-**Effort:** {{PHASE_3_EFFORT}} developer-hours
-
-### Risk Assessment
-**Risk Level:** 🟢 Low
-
-**Risks:**
-- Edge case behaviors missed in testing
-- Low-priority patterns deprioritized indefinitely
-
-**Mitigation:**
-- Thorough testing of edge cases
-- Set hard deadline for completion
-- Assign dedicated owner for long-tail cleanup
-
-### Success Criteria
-- ✅ **{{FINAL_REDUCTION_PERCENTAGE}}%** pattern reduction achieved
-- ✅ All patterns documented in pattern library
-- ✅ Zero legacy patterns in active development
-- ✅ Team using design system by default
-
----
-
-## Phase 4: Enforcement
-
-### Goal
-**Prevent regression** - Lock in gains and ensure design system adoption is sustained.
-
-### Prerequisites
-- [x] Phase 3 complete and stable
-- [x] >85% pattern adoption achieved
-- [ ] CI/CD pipeline configured for validation
-- [ ] Team bought into enforcement mechanisms
-
-### Tasks
-
-#### 4.1 CI/CD Pattern Validation
-- [ ] Integrate design system linter into CI pipeline
-- [ ] Block PRs that introduce non-system patterns
-- [ ] Add automated pattern usage reports
-- [ ] Configure pattern detection thresholds
-
-#### 4.2 Legacy Component Deprecation
-- [ ] Mark all old components as deprecated
-- [ ] Remove old components from imports
-- [ ] Add redirect logic: old imports → new components
-- [ ] Schedule removal date for legacy code
-
-#### 4.3 Documentation & Training
-- [ ] Create onboarding guide for new developers
-- [ ] Record video tutorials for common patterns
-- [ ] Establish design system office hours
-- [ ] Create troubleshooting guide
-
-#### 4.4 Monitoring & Metrics
-- [ ] Dashboard for adoption metrics
-- [ ] Automated weekly reports (usage, violations, velocity)
-- [ ] Track cost savings vs. projections
-- [ ] Measure developer satisfaction quarterly
-
-### Timeline
-**Duration:** {{PHASE_4_DURATION}}
-**Effort:** {{PHASE_4_EFFORT}} developer-hours
-
-### Risk Assessment
-**Risk Level:** 🟢 Low
-
-**Risks:**
-- Developer frustration with enforcement
-- False positives blocking legitimate work
-- Metrics dashboard not maintained
-
-**Mitigation:**
-- Allow override mechanism for edge cases
-- Fine-tune linter rules based on feedback
-- Assign ownership of metrics dashboard
-
-### Success Criteria
-- ✅ CI/CD enforcement active and stable
-- ✅ Zero non-system patterns merged to main
-- ✅ 100% of new components use design system
-- ✅ Team reports confidence in system
-
----
-
-## Overall Timeline
-
-```
-Phase 1: Foundation          [{{PHASE_1_DURATION}}]  🟢 Low Risk
-Phase 2: High-Impact         [{{PHASE_2_DURATION}}]  🟡 Medium Risk
-Phase 3: Long-Tail           [{{PHASE_3_DURATION}}]  🟢 Low Risk
-Phase 4: Enforcement         [{{PHASE_4_DURATION}}]  🟢 Low Risk
-─────────────────────────────────────────────────────
-Total Duration: {{TOTAL_TIMELINE}}
-```
-
----
-
-## Component Mapping (Old → New)
-
-{{#EACH_COMPONENT_MAPPING}}
-### {{OLD_COMPONENT_NAME}} → {{NEW_COMPONENT_NAME}}
-
-**Old Usage:**
-```{{CODE_LANGUAGE}}
-{{OLD_USAGE_EXAMPLE}}
-```
-
-**New Usage:**
-```{{CODE_LANGUAGE}}
-{{NEW_USAGE_EXAMPLE}}
-```
-
-**Migration Notes:**
-{{MIGRATION_NOTES}}
-
----
-{{/EACH_COMPONENT_MAPPING}}
-
----
-
-## Rollback Procedures
-
-### Phase-Specific Rollback
-
-**Phase 1 Rollback:**
-```bash
-git revert {{PHASE_1_COMMIT_HASH}}
-npm run build && npm run deploy
-```
-
-**Phase 2 Rollback (per component):**
-```bash
-# Revert specific component migration
-git revert {{COMPONENT_MIGRATION_COMMIT}}
-npm run test && npm run deploy
-```
-
-**Phase 3 Rollback:**
-```bash
-# Revert long-tail cleanup
-git revert {{PHASE_3_START_COMMIT}}..{{PHASE_3_END_COMMIT}}
-npm run build && npm run deploy
-```
-
-**Phase 4 Rollback:**
-```bash
-# Disable enforcement
-git revert {{ENFORCEMENT_COMMIT}}
-# CI/CD validation disabled, patterns still functional
-```
-
-### Emergency Rollback (Full System)
-```bash
-# Nuclear option - revert entire design system
-git revert {{PHASE_1_COMMIT}}..{{CURRENT_COMMIT}}
-npm run build
-npm run test
-npm run deploy
-```
-
----
-
-## Progress Tracking
-
-Track migration progress in `.state.yaml`:
-
-```yaml
-migration:
-  strategy_created_at: "{{GENERATION_DATE}}"
-  current_phase: 1
-  total_phases: 4
-
-  phase_1:
-    status: pending  # pending | in_progress | complete
-    started_at: null
-    completed_at: null
-
-  phase_2:
-    status: pending
-    patterns_migrated: 0
-    patterns_total: {{TOP_N_PATTERNS}}
-
-  phase_3:
-    status: pending
-    patterns_migrated: 0
-    patterns_total: {{LONG_TAIL_COUNT}}
-
-  phase_4:
-    status: pending
-    enforcement_enabled: false
-
-  overall:
-    completion_percentage: 0
-    estimated_completion: "{{ESTIMATED_COMPLETION_DATE}}"
-```
-
----
-
-## Communication Plan
-
-### Stakeholder Updates
-
-**Weekly Updates (During Active Migration):**
-- Phase progress and blockers
-- Metrics: patterns migrated, velocity changes
-- Upcoming tasks and dependencies
-
-**Monthly Retrospectives:**
-- What worked well
-- What to improve
-- Adjust timeline if needed
-
-### Team Communication
-
-**Kickoff Meeting (Before Phase 1):**
-- Present migration strategy
-- Demo token system
-- Answer questions
-- Assign phase ownership
-
-**Phase Completion Celebrations:**
-- Recognize team effort
-- Share metrics and wins
-- Preview next phase
-
----
-
-## Success Metrics
-
-Track these metrics throughout migration:
-
-| Metric | Baseline | Target | Current |
-|--------|----------|--------|---------|
-| Unique Patterns | {{TOTAL_PATTERNS_BEFORE}} | {{TOTAL_PATTERNS_AFTER}} | _TBD_ |
-| Pattern Reduction | 0% | {{REDUCTION_PERCENTAGE}}% | _TBD_ |
-| Feature Build Time | {{BASELINE_BUILD_TIME}} | {{TARGET_BUILD_TIME}} | _TBD_ |
-| Monthly Maintenance Cost | ${{MONTHLY_COST_BEFORE}} | ${{MONTHLY_COST_AFTER}} | _TBD_ |
-| Design System Adoption | 0% | >85% | _TBD_ |
-| Developer Satisfaction | {{BASELINE_SATISFACTION}} | >8/10 | _TBD_ |
-
----
-
-## Appendix
-
-### A. Team Roles & Responsibilities
-
-**Migration Lead:** {{MIGRATION_LEAD}}
-- Overall strategy execution
-- Phase coordination
-- Stakeholder communication
-
-**Component Owners:**
-{{#EACH_COMPONENT_OWNER}}
-- {{COMPONENT_NAME}}: {{OWNER_NAME}}
-{{/EACH_COMPONENT_OWNER}}
-
-**Quality Assurance:** {{QA_LEAD}}
-- Visual regression testing
-- Accessibility compliance
-- Production monitoring
-
-### B. Tools & Resources
-
-**Migration Tools:**
-- Token system: `{{TOKEN_DIRECTORY}}/tokens.yaml`
-- Component library: `{{COMPONENT_DIRECTORY}}/`
-- Migration scripts: `{{SCRIPTS_DIRECTORY}}/migrate-*.js`
-- Visual regression: Percy, Chromatic, or similar
-
-**Documentation:**
-- Pattern library: {{PATTERN_LIBRARY_URL}}
-- Migration guides: {{DOCS_URL}}/migration
-- Troubleshooting: {{DOCS_URL}}/troubleshooting
-
-### C. Contact & Support
-
-**Questions about migration?**
-- Slack: #design-system-migration
-- Email: {{SUPPORT_EMAIL}}
-- Office hours: {{OFFICE_HOURS}}
-
-**Activate Brad for migration assistance:**
-```bash
-*agent design-system
-*migrate  # Regenerate strategy with latest data
-```
-
----
-
-**Document Version:** 1.0
-**Last Updated:** {{GENERATION_DATE}}
-**Generated by:** Brad (Design System Architect)
-
-🤖 Generated with [Claude Code](https://claude.com/claude-code)

package/pro/squads/design/templates/ds-state-persistence-tmpl.yaml

@@ -1,194 +0,0 @@
-# .state.yaml
-# Design System State Tracking
-# Brad writes audit/consolidation/tokenization data
-# Merovingian reads and writes component building data
-# Enables seamless handoff between agents
-
-version: "1.0"
-project_name: "{{project_name}}"
-created_at: "{{created_timestamp}}"
-updated_at: "{{updated_timestamp}}"
-
-# Current phase in design system workflow
-system_state:
-  phase: "{{current_phase}}"  # audit_complete | consolidation_complete | tokenize_complete | migration_strategy_complete | setup_complete | building_components
-
-  # Phase 1: Inventory (Brad)
-  inventory:
-    scanned_at: "{{scan_timestamp}}"
-    scan_path: "{{scan_path}}"
-    total_files: {{total_files}}
-    frameworks_detected:
-      react: {{has_react}}
-      vue: {{has_vue}}
-      html: {{has_html}}
-    patterns:
-      buttons:
-        unique: {{buttons_unique}}
-        instances: {{buttons_instances}}
-        redundancy_factor: {{buttons_redundancy}}
-      colors:
-        unique: {{colors_unique}}
-        instances: {{colors_instances}}
-        redundancy_factor: {{colors_redundancy}}
-      spacing:
-        unique_padding: {{spacing_padding}}
-        unique_margin: {{spacing_margin}}
-      typography:
-        unique_fonts: {{typography_fonts}}
-        unique_sizes: {{typography_sizes}}
-        unique_weights: {{typography_weights}}
-      forms:
-        unique_inputs: {{forms_inputs}}
-        unique_forms: {{forms_forms}}
-    estimated_monthly_cost: "{{estimated_cost}}"
-
-  # Phase 2: Consolidation (Brad)
-  consolidation:
-    completed_at: "{{consolidation_timestamp}}"
-    patterns_consolidated:
-      colors:
-        before: {{colors_before}}
-        after: {{colors_after}}
-        reduction: "{{colors_reduction}}%"
-        clusters: {{colors_clusters}}
-      buttons:
-        before: {{buttons_before}}
-        after: {{buttons_after}}
-        reduction: "{{buttons_reduction}}%"
-        variants: {{buttons_variants}}
-      spacing:
-        before: {{spacing_before}}
-        after: {{spacing_after}}
-        reduction: "{{spacing_reduction}}%"
-        scale: {{spacing_scale}}
-      typography:
-        before: {{typography_before}}
-        after: {{typography_after}}
-        reduction: "{{typography_reduction}}%"
-    overall_reduction: "{{overall_reduction}}%"
-    target_met: {{target_met}}
-    user_overrides: {{user_overrides}}
-
-  # Phase 3: Tokenization (Brad)
-  tokens:
-    generated_at: "{{token_timestamp}}"
-    version: "{{token_version}}"
-    location: "{{token_location}}"
-    exports:
-      - tokens.yaml
-      - tokens.json
-      - tokens.css
-      - tokens.tailwind.js
-      - tokens.scss
-    categories:
-      color: {{token_color_count}}
-      spacing: {{token_spacing_count}}
-      typography: {{token_typography_count}}
-      radius: {{token_radius_count}}
-      shadow: {{token_shadow_count}}
-    total_tokens: {{total_tokens}}
-    coverage: "{{token_coverage}}%"
-
-  # Phase 4: ROI Analysis (Brad)
-  roi:
-    calculated_at: "{{roi_timestamp}}"
-    before:
-      patterns: {{patterns_before}}
-      monthly_cost: {{monthly_cost_before}}
-      annual_cost: {{annual_cost_before}}
-    after:
-      patterns: {{patterns_after}}
-      monthly_cost: {{monthly_cost_after}}
-      annual_cost: {{annual_cost_after}}
-    savings:
-      monthly: {{monthly_savings}}
-      annual: {{annual_savings}}
-    implementation:
-      estimated_cost: {{implementation_cost}}
-    roi_metrics:
-      ratio: {{roi_ratio}}
-      breakeven_months: {{breakeven_months}}
-
-  # Phase 5: Migration Strategy (Brad)
-  migration:
-    strategy_created_at: "{{migration_timestamp}}"
-    phases:
-      - phase: 1
-        name: "Foundation"
-        duration_sprints: 1
-        status: {{phase1_status}}
-      - phase: 2
-        name: "High-Impact"
-        duration_sprints: 2-3
-        priorities: {{phase2_priorities}}
-        status: {{phase2_status}}
-      - phase: 3
-        name: "Long-Tail"
-        duration_sprints: 2-4
-        status: {{phase3_status}}
-      - phase: 4
-        name: "Enforcement"
-        duration_sprints: 1
-        status: {{phase4_status}}
-    current_phase: {{current_migration_phase}}
-    completion_percentage: {{migration_completion}}
-    estimated_completion: "{{migration_completion_date}}"
-
-  # Phase 6: Merovingian Setup
-  atlas_setup:
-    completed_at: "{{atlas_setup_timestamp}}"
-    starting_point: "{{starting_point}}"  # brownfield | greenfield
-    configuration:
-      component_directory: "{{component_dir}}"
-      css_approach: "{{css_approach}}"
-      test_framework: "{{test_framework}}"
-      storybook_enabled: {{storybook_enabled}}
-    tokens_loaded: {{tokens_loaded_success}}
-
-  # Phase 7: Component Building (Merovingian)
-  patterns_built:
-    atoms:
-      total: {{atoms_total}}
-      components: {{atoms_list}}
-    molecules:
-      total: {{molecules_total}}
-      components: {{molecules_list}}
-    organisms:
-      total: {{organisms_total}}
-      components: {{organisms_list}}
-    templates:
-      total: {{templates_total}}
-      components: {{templates_list}}
-
-  # Documentation (Merovingian)
-  documentation:
-    generated_at: "{{docs_timestamp}}"
-    components_documented: {{docs_components}}
-    pattern_library_location: "{{docs_location}}"
-
-  # Integration (Merovingian)
-  integrations:
-    mmos:
-      status: {{mmos_integration_status}}
-      components: {{mmos_components}}
-    creator_os:
-      status: {{creator_os_integration_status}}
-      components: {{creator_os_components}}
-    innerlens:
-      status: {{innerlens_integration_status}}
-      components: {{innerlens_components}}
-
-# Agent execution history (for debugging and handoff)
-agent_history:
-  - agent: "{{agent_name}}"
-    command: "{{command}}"
-    timestamp: "{{command_timestamp}}"
-    args: {{command_args}}
-    status: "{{command_status}}"
-
-# Flags for agent communication
-flags:
-  ready_for_atlas: {{ready_for_atlas}}
-  ready_for_migration: {{ready_for_migration}}
-  system_complete: {{system_complete}}