aios-core 2.1.5 → 2.2.0

package/.aios-core/development/tasks/generate-migration-strategy.md

@@ -1,522 +1,522 @@
-# Generate Phased Migration Strategy
-
-> Task ID: brad-generate-migration-strategy
-> Agent: Brad (Design System Architect)
-> Version: 1.0.0
-
-## Execution Modes
-
-**Choose your execution mode:**
-
-### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-- Autonomous decision making with logging
-- Minimal user interaction
-- **Best for:** Simple, deterministic tasks
-
-### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-- Explicit decision checkpoints
-- Educational explanations
-- **Best for:** Learning, complex decisions
-
-### 3. Pre-Flight Planning - Comprehensive Upfront Planning
-- Task analysis phase (identify all ambiguities)
-- Zero ambiguity execution
-- **Best for:** Ambiguous requirements, critical work
-
-**Parameter:** `mode` (optional, default: `interactive`)
-
----
-
-## Task Definition (AIOS Task Format V1.0)
-
-```yaml
-task: generateMigrationStrategy()
-responsável: Dara (Sage)
-responsavel_type: Agente
-atomic_layer: Strategy
-
-**Entrada:**
-- campo: name
-  tipo: string
-  origem: User Input
-  obrigatório: true
-  validação: Must be non-empty, lowercase, kebab-case
-
-- campo: options
-  tipo: object
-  origem: User Input
-  obrigatório: false
-  validação: Valid JSON object with allowed keys
-
-- campo: force
-  tipo: boolean
-  origem: User Input
-  obrigatório: false
-  validação: Default: false
-
-**Saída:**
-- campo: created_file
-  tipo: string
-  destino: File system
-  persistido: true
-
-- campo: validation_report
-  tipo: object
-  destino: Memory
-  persistido: false
-
-- campo: success
-  tipo: boolean
-  destino: Return value
-  persistido: false
-```
-
----
-
-## Pre-Conditions
-
-**Purpose:** Validate prerequisites BEFORE task execution (blocking)
-
-**Checklist:**
-
-```yaml
-pre-conditions:
-  - [ ] Target does not already exist; required inputs provided; permissions granted
-    tipo: pre-condition
-    blocker: true
-    validação: |
-      Check target does not already exist; required inputs provided; permissions granted
-    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
-```
-
----
-
-## Post-Conditions
-
-**Purpose:** Validate execution success AFTER task completes
-
-**Checklist:**
-
-```yaml
-post-conditions:
-  - [ ] Resource created successfully; validation passed; no errors logged
-    tipo: post-condition
-    blocker: true
-    validação: |
-      Verify resource created successfully; validation passed; no errors logged
-    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
-```
-
----
-
-## Acceptance Criteria
-
-**Purpose:** Definitive pass/fail criteria for task completion
-
-**Checklist:**
-
-```yaml
-acceptance-criteria:
-  - [ ] Resource exists and is valid; no duplicate resources created
-    tipo: acceptance-criterion
-    blocker: true
-    validação: |
-      Assert resource exists and is valid; no duplicate resources created
-    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
-```
-
----
-
-## Tools
-
-**External/shared resources used by this task:**
-
-- **Tool:** component-generator
-  - **Purpose:** Generate new components from templates
-  - **Source:** .aios-core/scripts/component-generator.js
-
-- **Tool:** file-system
-  - **Purpose:** File creation and validation
-  - **Source:** Node.js fs module
-
----
-
-## Scripts
-
-**Agent-specific code for this task:**
-
-- **Script:** create-component.js
-  - **Purpose:** Component creation workflow
-  - **Language:** JavaScript
-  - **Location:** .aios-core/scripts/create-component.js
-
----
-
-## Error Handling
-
-**Strategy:** retry
-
-**Common Errors:**
-
-1. **Error:** Resource Already Exists
-   - **Cause:** Target file/resource already exists in system
-   - **Resolution:** Use force flag or choose different name
-   - **Recovery:** Prompt user for alternative name or force overwrite
-
-2. **Error:** Invalid Input
-   - **Cause:** Input name contains invalid characters or format
-   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
-   - **Recovery:** Sanitize input or reject with clear error message
-
-3. **Error:** Permission Denied
-   - **Cause:** Insufficient permissions to create resource
-   - **Resolution:** Check file system permissions, run with elevated privileges if needed
-   - **Recovery:** Log error, notify user, suggest permission fix
-
----
-
-## Performance
-
-**Expected Metrics:**
-
-```yaml
-duration_expected: 5-20 min (estimated)
-cost_estimated: $0.003-0.015
-token_usage: ~2,000-8,000 tokens
-```
-
-**Optimization Notes:**
-- Iterative analysis with depth limits; cache intermediate results; batch similar operations
-
----
-
-## Metadata
-
-```yaml
-story: N/A
-version: 1.0.0
-dependencies:
-  - N/A
-tags:
-  - automation
-  - workflow
-updated_at: 2025-11-17
-```
-
----
-
-
-## Description
-
-Create realistic 4-phase migration plan to gradually adopt design system without blocking sprints. Prioritizes high-impact patterns first, includes rollback procedures, tracks progress.
-
-## Prerequisites
-
-- Tokenization completed (*tokenize command run successfully)
-- .state.yaml contains consolidation and token data
-- Token files exist (tokens.yaml, exports)
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to customize migration strategy.
-
-1. **Assess Team Context**
-   - Ask about team size and velocity
-   - Current sprint length
-   - Risk tolerance (conservative vs aggressive rollout)
-   - Availability for migration work
-
-2. **Review Pattern Priority**
-   - Show most-used patterns (highest impact first)
-   - Confirm prioritization strategy
-   - Identify any must-have-first patterns
-
-3. **Define Phase Timeline**
-   - Estimate effort per phase
-   - Map to sprint schedule
-   - Set milestone dates
-   - Confirm realistic timeline
-
-### Steps
-
-1. **Load Token and Consolidation Data**
-   - Read .state.yaml for consolidation metrics
-   - Load token locations
-   - Identify pattern counts and reduction percentages
-   - Validation: Tokenization phase completed
-
-2. **Analyze Pattern Impact**
-   - Calculate usage frequency for each pattern type
-   - Identify highest-impact patterns (most instances)
-   - Estimate migration effort per pattern
-   - Prioritize by impact/effort ratio
-   - Validation: Priority list created
-
-3. **Design Phase 1: Foundation**
-   - Goal: Deploy token system with zero visual changes
-   - Tasks: Add token files, configure build, update CSS to use tokens
-   - Risk: Low (no component changes)
-   - Duration: 1 sprint
-   - Validation: Phase plan defined
-
-4. **Design Phase 2: High-Impact Patterns**
-   - Goal: Replace most-used components for immediate ROI
-   - Identify top 3 patterns (buttons, inputs, cards typically)
-   - Calculate instances to migrate
-   - Estimate effort and ROI
-   - Risk: Medium
-   - Duration: 2-3 sprints
-   - Validation: High-impact patterns identified
-
-5. **Design Phase 3: Long-Tail Cleanup**
-   - Goal: Consolidate remaining patterns
-   - List remaining components
-   - Group by complexity
-   - Estimate effort
-   - Risk: Low (proven system exists)
-   - Duration: 2-4 sprints
-   - Validation: Cleanup plan created
-
-6. **Design Phase 4: Enforcement**
-   - Goal: Prevent regression
-   - Add CI/CD pattern validation
-   - Deprecate old components
-   - Monitor adoption metrics
-   - Risk: Low
-   - Duration: 1 sprint
-   - Validation: Enforcement strategy defined
-
-7. **Create Component Mapping**
-   - Generate old component → new component mapping
-   - Document prop changes
-   - Create migration snippets (find/replace patterns)
-   - Validation: Complete mapping for all components
-
-8. **Define Rollback Procedures**
-   - Document rollback steps for each phase
-   - Identify rollback trigger conditions
-   - Ensure backups exist
-   - Validation: Rollback plan documented
-
-9. **Generate Migration Documentation**
-   - Create migration-strategy.md (executive summary)
-   - Create phase-specific guides (phase-1.md, phase-2.md, etc)
-   - Generate component mapping file
-   - Include code examples
-   - Validation: Complete migration docs created
-
-10. **Calculate ROI Timeline**
-    - Estimate when ROI breakeven occurs
-    - Project cumulative savings by phase
-    - Show investment vs savings curve
-    - Validation: ROI projection created
-
-11. **Update State File**
-    - Add migration section to .state.yaml
-    - Record phase count, timeline, priorities
-    - Update phase to "migration_strategy_complete"
-    - Set ready_for_atlas flag
-    - Validation: State updated for Atlas handoff
-
-## Output
-
-- **migration-strategy.md**: Executive summary with 4-phase plan
-- **phase-1-foundation.md**: Detailed Phase 1 tasks
-- **phase-2-high-impact.md**: Detailed Phase 2 tasks
-- **phase-3-long-tail.md**: Detailed Phase 3 tasks
-- **phase-4-enforcement.md**: Detailed Phase 4 tasks
-- **component-mapping.json**: Old → new component map
-- **migration-progress.yaml**: Progress tracking template
-- **.state.yaml**: Updated with migration plan
-
-### Output Format
-
-```markdown
-# Migration Strategy
-
-## Executive Summary
-
-**Target**: Adopt design system with >80% pattern reduction
-**Timeline**: 6-8 sprints (12-16 weeks)
-**Risk Level**: Medium (phased approach reduces risk)
-**ROI Breakeven**: Phase 2 completion (~6 weeks)
-
-## Phase 1: Foundation (1 sprint)
-
-**Goal**: Deploy tokens, zero visual changes
-
-**Tasks**:
-- [ ] Add token files to project (tokens.yaml, exports)
-- [ ] Configure build pipeline to process tokens
-- [ ] Update existing CSS to use CSS custom properties
-- [ ] No component changes yet
-
-**Success Criteria**: Tokens deployed, no visual regressions
-
-**Rollback**: Remove token files, revert CSS
-
-## Phase 2: High-Impact Patterns (2-3 sprints)
-
-**Goal**: Replace most-used components for immediate ROI
-
-**Priorities**:
-1. Button (327 instances → 3 variants) - 93% reduction
-2. Input (189 instances → 5 variants) - 87% reduction
-3. Card (145 instances → 2 variants) - 85% reduction
-
-**Success Criteria**: Top 3 patterns migrated, measurable velocity improvement
-
-**Rollback**: Component-level rollback, old components still available
-
-## Phase 3: Long-Tail Cleanup (2-4 sprints)
-
-**Goal**: Consolidate remaining patterns
-
-**Tasks**:
-- [ ] Forms (23 variations → 5)
-- [ ] Modals (12 variations → 2)
-- [ ] Navigation (8 variations → 3)
-
-**Success Criteria**: >85% overall pattern consolidation achieved
-
-## Phase 4: Enforcement (1 sprint)
-
-**Goal**: Prevent regression
-
-**Tasks**:
-- [ ] Add CI/CD pattern validation
-- [ ] Deprecate old components
-- [ ] Block non-system patterns
-- [ ] Monitor adoption metrics
-
-**Success Criteria**: System enforced, adoption sustained
-```
-
-## Critical References
-
-**ALWAYS include these in migration strategy docs:**
-
-- **Migration Validation Checklist** (`migration-validation-checklist.md`)
-  - Run AFTER every migration script execution
-  - Detects corrupted classes, build failures, visual regressions
-  - 5-10 min validation saves hours of debugging
-  - **Non-negotiable** - must be followed before committing
-
-- **Migration Pitfalls** (`migration-pitfalls.md`)
-  - Common mistakes and how to avoid them
-  - Anti-patterns from real incidents
-  - Detection patterns for corruption
-  - Prevention strategies
-
-**In every phase guide, include:**
-```markdown
-## Validation
-
-After executing migration scripts:
-1. Run migration-validation-checklist.md (ALL steps)
-2. Review migration-pitfalls.md for common issues
-3. Do NOT commit until validation passes
-
-See: expansion-packs/super-agentes/checklists/migration-validation-checklist.md
-```
-
-## Success Criteria
-
-- [ ] 4 distinct phases defined with clear goals
-- [ ] Phase 1 has zero visual changes (safe foundation)
-- [ ] Phase 2 prioritizes highest-impact patterns
-- [ ] Each phase has success criteria and rollback plan
-- [ ] Timeline is realistic for team size/velocity
-- [ ] Component mapping covers all patterns
-- [ ] ROI breakeven projected accurately
-
-## Error Handling
-
-- **No tokenization data**: Exit with message to run *tokenize first
-- **Cannot estimate timeline**: Use defaults, warn user to adjust
-- **Insufficient pattern data**: Recommend re-running audit
-- **Team context missing**: Use conservative defaults
-
-## Security Considerations
-
-- Migration scripts run with user permissions only
-- Validate component mapping to prevent injection
-- Backup files before any automated changes
-- Rollback procedures tested before execution
-
-## Examples
-
-### Example 1: Migration Strategy Generation
-
-```bash
-*migrate
-```
-
-Output:
-```
-🔍 Brad: Generating phased migration strategy...
-
-📊 Pattern Analysis:
-  - Buttons: 327 instances (highest priority)
-  - Inputs: 189 instances
-  - Colors: 1247 usages
-
-🗓️ MIGRATION PLAN (4 phases, 6-8 sprints):
-
-Phase 1: Foundation (1 sprint)
-  Deploy tokens, no visual changes
-  Risk: LOW
-
-Phase 2: High-Impact (2-3 sprints)
-  Migrate Button, Input, Card
-  Expected ROI: $31,200/month savings
-  Risk: MEDIUM
-
-Phase 3: Long-Tail (2-4 sprints)
-  Cleanup remaining 15 patterns
-  Risk: LOW
-
-Phase 4: Enforcement (1 sprint)
-  CI/CD validation, prevent regression
-  Risk: LOW
-
-💰 ROI Projection:
-  Investment: ~$12,000
-  Breakeven: Week 6 (Phase 2 complete)
-  Year 1 Savings: $374,400
-
-✅ Migration docs saved: outputs/design-system/my-app/migration/
-✅ Ready for Atlas to build components
-```
-
-### Example 2: Component Mapping
-
-```json
-{
-  "buttons": {
-    ".btn-primary": "Button variant='primary'",
-    ".button-primary": "Button variant='primary'",
-    ".btn-main": "Button variant='primary'",
-    ".btn-secondary": "Button variant='secondary'",
-    ".btn-danger": "Button variant='destructive'"
-  },
-  "props_changed": {
-    "Button": {
-      "old": "type='primary'",
-      "new": "variant='primary'"
-    }
-  }
-}
-```
-
-## Notes
-
-- Phase 1 must complete before Phase 2 (foundation required)
-- High-impact patterns = most instances × easiest to migrate
-- Rollback gets harder as system grows - do it early if needed
-- CI/CD enforcement prevents regression (Phase 4 critical)
-- Timeline assumes team works on migration alongside features
-- Brad says: "Phased rollout = safe rollout. No big-bang rewrites."
-- After this, hand off to Atlas: *agent atlas for component building
+# Generate Phased Migration Strategy
+
+> Task ID: brad-generate-migration-strategy
+> Agent: Brad (Design System Architect)
+> Version: 1.0.0
+
+## Execution Modes
+
+**Choose your execution mode:**
+
+### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+- Autonomous decision making with logging
+- Minimal user interaction
+- **Best for:** Simple, deterministic tasks
+
+### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+- Explicit decision checkpoints
+- Educational explanations
+- **Best for:** Learning, complex decisions
+
+### 3. Pre-Flight Planning - Comprehensive Upfront Planning
+- Task analysis phase (identify all ambiguities)
+- Zero ambiguity execution
+- **Best for:** Ambiguous requirements, critical work
+
+**Parameter:** `mode` (optional, default: `interactive`)
+
+---
+
+## Task Definition (AIOS Task Format V1.0)
+
+```yaml
+task: generateMigrationStrategy()
+responsável: Dara (Sage)
+responsavel_type: Agente
+atomic_layer: Strategy
+
+**Entrada:**
+- campo: name
+  tipo: string
+  origem: User Input
+  obrigatório: true
+  validação: Must be non-empty, lowercase, kebab-case
+
+- campo: options
+  tipo: object
+  origem: User Input
+  obrigatório: false
+  validação: Valid JSON object with allowed keys
+
+- campo: force
+  tipo: boolean
+  origem: User Input
+  obrigatório: false
+  validação: Default: false
+
+**Saída:**
+- campo: created_file
+  tipo: string
+  destino: File system
+  persistido: true
+
+- campo: validation_report
+  tipo: object
+  destino: Memory
+  persistido: false
+
+- campo: success
+  tipo: boolean
+  destino: Return value
+  persistido: false
+```
+
+---
+
+## Pre-Conditions
+
+**Purpose:** Validate prerequisites BEFORE task execution (blocking)
+
+**Checklist:**
+
+```yaml
+pre-conditions:
+  - [ ] Target does not already exist; required inputs provided; permissions granted
+    tipo: pre-condition
+    blocker: true
+    validação: |
+      Check target does not already exist; required inputs provided; permissions granted
+    error_message: "Pre-condition failed: Target does not already exist; required inputs provided; permissions granted"
+```
+
+---
+
+## Post-Conditions
+
+**Purpose:** Validate execution success AFTER task completes
+
+**Checklist:**
+
+```yaml
+post-conditions:
+  - [ ] Resource created successfully; validation passed; no errors logged
+    tipo: post-condition
+    blocker: true
+    validação: |
+      Verify resource created successfully; validation passed; no errors logged
+    error_message: "Post-condition failed: Resource created successfully; validation passed; no errors logged"
+```
+
+---
+
+## Acceptance Criteria
+
+**Purpose:** Definitive pass/fail criteria for task completion
+
+**Checklist:**
+
+```yaml
+acceptance-criteria:
+  - [ ] Resource exists and is valid; no duplicate resources created
+    tipo: acceptance-criterion
+    blocker: true
+    validação: |
+      Assert resource exists and is valid; no duplicate resources created
+    error_message: "Acceptance criterion not met: Resource exists and is valid; no duplicate resources created"
+```
+
+---
+
+## Tools
+
+**External/shared resources used by this task:**
+
+- **Tool:** component-generator
+  - **Purpose:** Generate new components from templates
+  - **Source:** .aios-core/scripts/component-generator.js
+
+- **Tool:** file-system
+  - **Purpose:** File creation and validation
+  - **Source:** Node.js fs module
+
+---
+
+## Scripts
+
+**Agent-specific code for this task:**
+
+- **Script:** create-component.js
+  - **Purpose:** Component creation workflow
+  - **Language:** JavaScript
+  - **Location:** .aios-core/scripts/create-component.js
+
+---
+
+## Error Handling
+
+**Strategy:** retry
+
+**Common Errors:**
+
+1. **Error:** Resource Already Exists
+   - **Cause:** Target file/resource already exists in system
+   - **Resolution:** Use force flag or choose different name
+   - **Recovery:** Prompt user for alternative name or force overwrite
+
+2. **Error:** Invalid Input
+   - **Cause:** Input name contains invalid characters or format
+   - **Resolution:** Validate input against naming rules (kebab-case, lowercase, no special chars)
+   - **Recovery:** Sanitize input or reject with clear error message
+
+3. **Error:** Permission Denied
+   - **Cause:** Insufficient permissions to create resource
+   - **Resolution:** Check file system permissions, run with elevated privileges if needed
+   - **Recovery:** Log error, notify user, suggest permission fix
+
+---
+
+## Performance
+
+**Expected Metrics:**
+
+```yaml
+duration_expected: 5-20 min (estimated)
+cost_estimated: $0.003-0.015
+token_usage: ~2,000-8,000 tokens
+```
+
+**Optimization Notes:**
+- Iterative analysis with depth limits; cache intermediate results; batch similar operations
+
+---
+
+## Metadata
+
+```yaml
+story: N/A
+version: 1.0.0
+dependencies:
+  - N/A
+tags:
+  - automation
+  - workflow
+updated_at: 2025-11-17
+```
+
+---
+
+
+## Description
+
+Create realistic 4-phase migration plan to gradually adopt design system without blocking sprints. Prioritizes high-impact patterns first, includes rollback procedures, tracks progress.
+
+## Prerequisites
+
+- Tokenization completed (*tokenize command run successfully)
+- .state.yaml contains consolidation and token data
+- Token files exist (tokens.yaml, exports)
+
+## Workflow
+
+### Interactive Elicitation
+
+This task uses interactive elicitation to customize migration strategy.
+
+1. **Assess Team Context**
+   - Ask about team size and velocity
+   - Current sprint length
+   - Risk tolerance (conservative vs aggressive rollout)
+   - Availability for migration work
+
+2. **Review Pattern Priority**
+   - Show most-used patterns (highest impact first)
+   - Confirm prioritization strategy
+   - Identify any must-have-first patterns
+
+3. **Define Phase Timeline**
+   - Estimate effort per phase
+   - Map to sprint schedule
+   - Set milestone dates
+   - Confirm realistic timeline
+
+### Steps
+
+1. **Load Token and Consolidation Data**
+   - Read .state.yaml for consolidation metrics
+   - Load token locations
+   - Identify pattern counts and reduction percentages
+   - Validation: Tokenization phase completed
+
+2. **Analyze Pattern Impact**
+   - Calculate usage frequency for each pattern type
+   - Identify highest-impact patterns (most instances)
+   - Estimate migration effort per pattern
+   - Prioritize by impact/effort ratio
+   - Validation: Priority list created
+
+3. **Design Phase 1: Foundation**
+   - Goal: Deploy token system with zero visual changes
+   - Tasks: Add token files, configure build, update CSS to use tokens
+   - Risk: Low (no component changes)
+   - Duration: 1 sprint
+   - Validation: Phase plan defined
+
+4. **Design Phase 2: High-Impact Patterns**
+   - Goal: Replace most-used components for immediate ROI
+   - Identify top 3 patterns (buttons, inputs, cards typically)
+   - Calculate instances to migrate
+   - Estimate effort and ROI
+   - Risk: Medium
+   - Duration: 2-3 sprints
+   - Validation: High-impact patterns identified
+
+5. **Design Phase 3: Long-Tail Cleanup**
+   - Goal: Consolidate remaining patterns
+   - List remaining components
+   - Group by complexity
+   - Estimate effort
+   - Risk: Low (proven system exists)
+   - Duration: 2-4 sprints
+   - Validation: Cleanup plan created
+
+6. **Design Phase 4: Enforcement**
+   - Goal: Prevent regression
+   - Add CI/CD pattern validation
+   - Deprecate old components
+   - Monitor adoption metrics
+   - Risk: Low
+   - Duration: 1 sprint
+   - Validation: Enforcement strategy defined
+
+7. **Create Component Mapping**
+   - Generate old component → new component mapping
+   - Document prop changes
+   - Create migration snippets (find/replace patterns)
+   - Validation: Complete mapping for all components
+
+8. **Define Rollback Procedures**
+   - Document rollback steps for each phase
+   - Identify rollback trigger conditions
+   - Ensure backups exist
+   - Validation: Rollback plan documented
+
+9. **Generate Migration Documentation**
+   - Create migration-strategy.md (executive summary)
+   - Create phase-specific guides (phase-1.md, phase-2.md, etc)
+   - Generate component mapping file
+   - Include code examples
+   - Validation: Complete migration docs created
+
+10. **Calculate ROI Timeline**
+    - Estimate when ROI breakeven occurs
+    - Project cumulative savings by phase
+    - Show investment vs savings curve
+    - Validation: ROI projection created
+
+11. **Update State File**
+    - Add migration section to .state.yaml
+    - Record phase count, timeline, priorities
+    - Update phase to "migration_strategy_complete"
+    - Set ready_for_atlas flag
+    - Validation: State updated for Atlas handoff
+
+## Output
+
+- **migration-strategy.md**: Executive summary with 4-phase plan
+- **phase-1-foundation.md**: Detailed Phase 1 tasks
+- **phase-2-high-impact.md**: Detailed Phase 2 tasks
+- **phase-3-long-tail.md**: Detailed Phase 3 tasks
+- **phase-4-enforcement.md**: Detailed Phase 4 tasks
+- **component-mapping.json**: Old → new component map
+- **migration-progress.yaml**: Progress tracking template
+- **.state.yaml**: Updated with migration plan
+
+### Output Format
+
+```markdown
+# Migration Strategy
+
+## Executive Summary
+
+**Target**: Adopt design system with >80% pattern reduction
+**Timeline**: 6-8 sprints (12-16 weeks)
+**Risk Level**: Medium (phased approach reduces risk)
+**ROI Breakeven**: Phase 2 completion (~6 weeks)
+
+## Phase 1: Foundation (1 sprint)
+
+**Goal**: Deploy tokens, zero visual changes
+
+**Tasks**:
+- [ ] Add token files to project (tokens.yaml, exports)
+- [ ] Configure build pipeline to process tokens
+- [ ] Update existing CSS to use CSS custom properties
+- [ ] No component changes yet
+
+**Success Criteria**: Tokens deployed, no visual regressions
+
+**Rollback**: Remove token files, revert CSS
+
+## Phase 2: High-Impact Patterns (2-3 sprints)
+
+**Goal**: Replace most-used components for immediate ROI
+
+**Priorities**:
+1. Button (327 instances → 3 variants) - 93% reduction
+2. Input (189 instances → 5 variants) - 87% reduction
+3. Card (145 instances → 2 variants) - 85% reduction
+
+**Success Criteria**: Top 3 patterns migrated, measurable velocity improvement
+
+**Rollback**: Component-level rollback, old components still available
+
+## Phase 3: Long-Tail Cleanup (2-4 sprints)
+
+**Goal**: Consolidate remaining patterns
+
+**Tasks**:
+- [ ] Forms (23 variations → 5)
+- [ ] Modals (12 variations → 2)
+- [ ] Navigation (8 variations → 3)
+
+**Success Criteria**: >85% overall pattern consolidation achieved
+
+## Phase 4: Enforcement (1 sprint)
+
+**Goal**: Prevent regression
+
+**Tasks**:
+- [ ] Add CI/CD pattern validation
+- [ ] Deprecate old components
+- [ ] Block non-system patterns
+- [ ] Monitor adoption metrics
+
+**Success Criteria**: System enforced, adoption sustained
+```
+
+## Critical References
+
+**ALWAYS include these in migration strategy docs:**
+
+- **Migration Validation Checklist** (`migration-validation-checklist.md`)
+  - Run AFTER every migration script execution
+  - Detects corrupted classes, build failures, visual regressions
+  - 5-10 min validation saves hours of debugging
+  - **Non-negotiable** - must be followed before committing
+
+- **Migration Pitfalls** (`migration-pitfalls.md`)
+  - Common mistakes and how to avoid them
+  - Anti-patterns from real incidents
+  - Detection patterns for corruption
+  - Prevention strategies
+
+**In every phase guide, include:**
+```markdown
+## Validation
+
+After executing migration scripts:
+1. Run migration-validation-checklist.md (ALL steps)
+2. Review migration-pitfalls.md for common issues
+3. Do NOT commit until validation passes
+
+See: Squads/super-agentes/checklists/migration-validation-checklist.md
+```
+
+## Success Criteria
+
+- [ ] 4 distinct phases defined with clear goals
+- [ ] Phase 1 has zero visual changes (safe foundation)
+- [ ] Phase 2 prioritizes highest-impact patterns
+- [ ] Each phase has success criteria and rollback plan
+- [ ] Timeline is realistic for team size/velocity
+- [ ] Component mapping covers all patterns
+- [ ] ROI breakeven projected accurately
+
+## Error Handling
+
+- **No tokenization data**: Exit with message to run *tokenize first
+- **Cannot estimate timeline**: Use defaults, warn user to adjust
+- **Insufficient pattern data**: Recommend re-running audit
+- **Team context missing**: Use conservative defaults
+
+## Security Considerations
+
+- Migration scripts run with user permissions only
+- Validate component mapping to prevent injection
+- Backup files before any automated changes
+- Rollback procedures tested before execution
+
+## Examples
+
+### Example 1: Migration Strategy Generation
+
+```bash
+*migrate
+```
+
+Output:
+```
+🔍 Brad: Generating phased migration strategy...
+
+📊 Pattern Analysis:
+  - Buttons: 327 instances (highest priority)
+  - Inputs: 189 instances
+  - Colors: 1247 usages
+
+🗓️ MIGRATION PLAN (4 phases, 6-8 sprints):
+
+Phase 1: Foundation (1 sprint)
+  Deploy tokens, no visual changes
+  Risk: LOW
+
+Phase 2: High-Impact (2-3 sprints)
+  Migrate Button, Input, Card
+  Expected ROI: $31,200/month savings
+  Risk: MEDIUM
+
+Phase 3: Long-Tail (2-4 sprints)
+  Cleanup remaining 15 patterns
+  Risk: LOW
+
+Phase 4: Enforcement (1 sprint)
+  CI/CD validation, prevent regression
+  Risk: LOW
+
+💰 ROI Projection:
+  Investment: ~$12,000
+  Breakeven: Week 6 (Phase 2 complete)
+  Year 1 Savings: $374,400
+
+✅ Migration docs saved: outputs/design-system/my-app/migration/
+✅ Ready for Atlas to build components
+```
+
+### Example 2: Component Mapping
+
+```json
+{
+  "buttons": {
+    ".btn-primary": "Button variant='primary'",
+    ".button-primary": "Button variant='primary'",
+    ".btn-main": "Button variant='primary'",
+    ".btn-secondary": "Button variant='secondary'",
+    ".btn-danger": "Button variant='destructive'"
+  },
+  "props_changed": {
+    "Button": {
+      "old": "type='primary'",
+      "new": "variant='primary'"
+    }
+  }
+}
+```
+
+## Notes
+
+- Phase 1 must complete before Phase 2 (foundation required)
+- High-impact patterns = most instances × easiest to migrate
+- Rollback gets harder as system grows - do it early if needed
+- CI/CD enforcement prevents regression (Phase 4 critical)
+- Timeline assumes team works on migration alongside features
+- Brad says: "Phased rollout = safe rollout. No big-bang rewrites."
+- After this, hand off to Atlas: *agent atlas for component building