aiox-core 5.0.3 → 5.0.5

package/pro/squads/design/tasks/ds-generate-migration-strategy.md

@@ -1,331 +0,0 @@
-# Generate Phased Migration Strategy
-
-> Task ID: brad-generate-migration-strategy
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Hybrid`
-> **Human Checkpoint:** Review and approve the 4-phase migration plan and rollback procedures before proceeding to ROI calculation
-> **Dependencies:** depends_on: `[ds-extract-tokens]` · enables: `[ds-calculate-roi]` · workflow: `brownfield-audit`
-> **On Fail:** If tokens.yaml missing → re-run `*tokenize`. If migration plan has unresolved component mappings → review token coverage and add missing tokens manually. If human reviewer rejects plan → revise phases based on feedback and re-submit for approval. Do NOT proceed to ROI with unapproved migration plan.
-
-## 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.
-
-## Input Schema
-- **requires:** Output from `ds-extract-tokens`
-- **format:** YAML data (tokens.yaml with all design tokens)
-- **location:** `outputs/design-system/{project}/tokens/tokens.yaml`
-
-## Output Schema
-- **produces:** `outputs/design-system/{project}/migration/migration-strategy.md`
-- **format:** Markdown report
-- **consumed_by:** ds-calculate-roi
-
-## 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
-   - Check: .state.yaml contains `phase: "tokenize_complete"` AND token file paths resolve — abort with "Tokenization not completed: run *tokenize first"
-
-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
-   - Check: priority list count > 0 AND each entry has usage frequency + effort estimate — log "{N} patterns prioritized by impact/effort ratio"
-
-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
-   - Check: phase-1 has goal, task list, risk level, and duration — abort with "Phase 1 incomplete: missing {field}"
-
-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
-   - Check: top 3 patterns selected with instance counts and effort estimates — log "Phase 2 targets: {pattern1} ({N1} instances), {pattern2} ({N2}), {pattern3} ({N3})"
-
-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
-   - Check: remaining components listed with complexity groupings and effort estimates — log "{N} remaining patterns grouped into {G} complexity tiers"
-
-6. **Design Phase 4: Enforcement**
-   - Goal: Prevent regression
-   - Add CI/CD pattern validation
-   - Deprecate old components
-   - Monitor adoption metrics
-   - Risk: Low
-   - Duration: 1 sprint
-   - Check: enforcement plan includes CI/CD validation step, deprecation list, and monitoring metrics — abort with "Enforcement phase incomplete: missing {field}"
-
-7. **Create Component Mapping**
-   - Generate old component → new component mapping
-   - Document prop changes
-   - Create migration snippets (find/replace patterns)
-   - Check: mapping entries count == total component count AND each has old-to-new + prop changes — abort with "Incomplete mapping: {N} components missing"
-
-8. **Define Rollback Procedures**
-   - Document rollback steps for each phase
-   - Identify rollback trigger conditions
-   - Ensure backups exist
-   - Check: each phase has rollback steps, trigger conditions, and backup references — abort with "Rollback plan incomplete for phase {N}"
-
-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
-   - Check: `test -f migration-strategy.md` AND phase guide files exist for all 4 phases AND file sizes > 0 — abort with "Migration docs generation failed: missing {file}"
-
-10. **Calculate ROI Timeline**
-    - Estimate when ROI breakeven occurs
-    - Project cumulative savings by phase
-    - Show investment vs savings curve
-    - Check: ROI projection includes breakeven month and cumulative savings per phase — abort with "ROI projection generation failed"
-
-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
-    - Check: .state.yaml contains `phase: "migration_strategy_complete"` AND `ready_for_atlas: true` — abort with "State update failed: {missing field}"
-
-## 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
-```
-
-## Failure Handling
-
-- **No token data available:** BLOCK — re-run *tokenize first. Migration without tokens produces unusable strategy
-- **Risk assessment HIGH for >50% of components:** Recommend phased migration starting with lowest-risk components. Add Phase 0 (pilot)
-- **Estimated migration >6 months:** Split into quarterly milestones with independent go/no-go gates per milestone
-- **Conflicting frameworks detected:** Document each framework's migration path separately before creating unified strategy
-
-## 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
-
-## Quality Gate
-
-> **GATE: Migration Strategy Review** — Human approval required before any migration begins
-
-| Metric | Threshold | Action if FAIL |
-|--------|-----------|----------------|
-| Token data available | All tokens generated | BLOCK — return to *tokenize. Never plan migration without tokens |
-| Risk assessment | No CRITICAL risks unmitigated | Add mitigation plan for each CRITICAL risk before proceeding |
-| Estimated duration | Approved by stakeholder | If > 6 months, split into quarterly milestones with independent go/no-go |
-| Rollback plan | Defined for each phase | Add rollback steps — migration without rollback is not production-ready |
-
-**Rework rule:** If > 50% of components are HIGH risk, add Phase 0 (pilot) with 2-3 lowest-risk components to validate approach before full migration.
-
-## 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 Merovingian 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 Merovingian: *agent atlas for component building
-## Related Checklists
-
-- `squads/design/checklists/ds-migration-readiness-checklist.md`
-

package/pro/squads/design/tasks/ds-generate-shock-report.md

@@ -1,323 +0,0 @@
-# Generate Visual Shock Report
-
-> Task ID: brad-generate-shock-report
-> Agent: Brad (Design System Architect)
-> Version: 1.1.0
-> v4.0-compatible: true
-> **Execution Type:** `Agent`
-> **Dependencies:** depends_on: `[ds-calculate-roi]` · enables: `[]` · workflow: `brownfield-audit`
-
-## Description
-
-Generate self-contained HTML report showing visual evidence of UI chaos with side-by-side comparisons, cost analysis, and "horror show" presentation designed to drive stakeholder action.
-
-## Input Schema
-- **requires:** Output from `ds-calculate-roi`
-- **format:** Markdown report
-- **location:** `outputs/design-system/{project}/roi/roi-analysis.md`
-
-## Prerequisites
-
-- Audit completed (*audit command run successfully)
-- Consolidation data available (optional but recommended)
-- ROI calculated (optional but recommended for full impact)
-
-## Workflow
-
-### Interactive Elicitation
-
-This task uses interactive elicitation to customize shock report.
-
-1. **Select Report Scope**
-   - Full report (all patterns) or focused (top offenders only)
-   - Include ROI section (requires *calculate-roi)
-   - Include before/after preview
-   - Target audience (engineers vs executives)
-
-2. **Review Pattern Data**
-   - Show which patterns will be visualized
-   - Confirm most shocking examples selected
-   - Ask for any patterns to highlight
-
-3. **Configure Output**
-   - HTML only or HTML + PDF export
-   - Responsive design (mobile-viewable)
-   - Color scheme (light/dark mode)
-
-### Steps
-
-1. **Load Audit and Consolidation Data**
-   - Read .state.yaml for all pattern metrics
-   - Load inventory, consolidation, ROI data if available
-   - Validate data completeness
-   - Check: .state.yaml contains audit data with pattern count > 0 — abort with "Insufficient data: run *audit first"
-
-2. **Extract Visual Examples**
-   - Scan codebase for actual button implementations
-   - Extract CSS for representative examples
-   - Find most egregious duplicates
-   - Capture top 10 worst offenders
-   - Check: extracted example count >= 1 AND top 10 worst offenders identified — log "Extracted {N} visual examples from codebase"
-
-3. **Generate HTML Structure**
-   - Create self-contained HTML (no external dependencies)
-   - Embed CSS and minimal JavaScript
-   - Responsive design (mobile to desktop)
-   - Check: HTML contains <!DOCTYPE html> AND no external resource links (self-contained) — abort with "HTML structure invalid: {error}"
-
-4. **Create "Horror Show" Section**
-   - Display all button variations side-by-side
-   - Show color palette explosion (89 colors in grid)
-   - Visualize spacing inconsistencies
-   - Make it visually overwhelming (intentional)
-   - Check: horror section contains button grid + color grid + spacing visualization — abort with "Horror show section missing: {missing element}"
-
-5. **Add Metrics Dashboard**
-   - Pattern count cards (before/after)
-   - Reduction percentages with progress bars
-   - Redundancy factors highlighted
-   - Check: metrics section contains pattern count cards + reduction percentages + progress bars — abort with "Metrics dashboard incomplete: {missing element}"
-
-6. **Generate Cost Analysis Section**
-   - If ROI calculated, embed cost breakdown
-   - Show monthly/annual waste
-   - Display ROI metrics prominently
-   - Include savings calculator widget
-   - Check: cost section contains before/after costs AND savings figure — log "Cost analysis: ${before}/yr -> ${after}/yr, saving ${savings}/yr"
-
-7. **Create Before/After Preview**
-   - Show consolidated future state
-   - Side-by-side comparison (47 buttons → 3)
-   - Highlight simplicity and consistency
-   - Check: before/after section shows consolidated variants side-by-side — abort with "Before/after preview section missing"
-
-8. **Add Executive Summary**
-   - Top-of-page key findings
-   - One-sentence problem statement
-   - Three bullet point solution
-   - Clear call-to-action
-   - Check: executive summary contains problem statement + 3 bullet points + call-to-action — abort with "Executive summary incomplete: {missing element}"
-
-9. **Embed Interactive Elements**
-   - Savings calculator (input team size, see ROI)
-   - Pattern filter (show/hide categories)
-   - Export to PDF button
-   - Check: savings calculator accepts input AND pattern filter toggles work AND export button present — abort with "Interactive elements broken: {element}"
-
-10. **Generate Report File**
-    - Save as shock-report.html
-    - Self-contained (works offline)
-    - Optimized file size (<1MB)
-    - Check: `test -f shock-report.html` AND file size < 1MB AND no external resource links — abort with "Report file generation failed: {error}"
-
-11. **Optional: Export to PDF**
-    - If requested, generate PDF version
-    - Preserve visual layout
-    - Check: `test -f shock-report.pdf` AND file size > 0 — abort with "PDF export failed"
-
-12. **Update State File**
-    - Add shock_report section to .state.yaml
-    - Record report location and generation time
-    - Check: .state.yaml contains shock_report section with file location + generation timestamp — abort with "State update failed"
-
-## Output
-
-- **shock-report.html**: Self-contained visual report
-- **shock-report.pdf**: PDF version (optional)
-- **.state.yaml**: Updated with report location
-
-### Output Format
-
-```html
-<!DOCTYPE html>
-<html>
-<head>
-  <title>UI Pattern Chaos Report</title>
-  <style>
-    /* Embedded CSS for self-contained report */
-    body { font-family: system-ui; max-width: 1200px; margin: 0 auto; }
-    .horror-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(150px, 1fr)); gap: 10px; }
-    .metric-card { background: #f0f0f0; padding: 20px; border-radius: 8px; }
-    .metric-value { font-size: 3rem; font-weight: bold; color: #dc2626; }
-  </style>
-</head>
-<body>
-  <header>
-    <h1>🚨 UI Pattern Chaos Report</h1>
-    <p class="subtitle">Generated by Brad | 2025-10-27</p>
-  </header>
-
-  <section class="executive-summary">
-    <h2>Executive Summary</h2>
-    <p><strong>Problem:</strong> 176 redundant UI patterns cost $457,200/year in maintenance.</p>
-    <ul>
-      <li>81.8% pattern reduction possible (176 → 32)</li>
-      <li>$374,400/year savings potential</li>
-      <li>ROI breakeven in 10 days</li>
-    </ul>
-    <p><strong>Action:</strong> Approve design system implementation immediately.</p>
-  </section>
-
-  <section class="metrics">
-    <h2>The Damage</h2>
-    <div class="metric-cards">
-      <div class="metric-card">
-        <div class="metric-value">47</div>
-        <div class="metric-label">Button Variations</div>
-        <div class="metric-target">Target: 3</div>
-      </div>
-      <!-- More metric cards -->
-    </div>
-  </section>
-
-  <section class="horror-show">
-    <h2>The Horror Show</h2>
-    <h3>All 47 Button Variations</h3>
-    <div class="horror-grid">
-      <!-- Actual button examples rendered -->
-      <button class="btn-primary">Primary</button>
-      <button class="button-primary">Primary Alt</button>
-      <button class="btn-main">Main</button>
-      <!-- ...44 more variations... -->
-    </div>
-    <p class="caption">This is madness. It should be 3 variants, not 47.</p>
-  </section>
-
-  <section class="cost-analysis">
-    <h2>The Cost</h2>
-    <table>
-      <tr>
-        <th>Before</th>
-        <td>$457,200/year</td>
-      </tr>
-      <tr>
-        <th>After</th>
-        <td>$82,800/year</td>
-      </tr>
-      <tr>
-        <th>Savings</th>
-        <td class="highlight">$374,400/year</td>
-      </tr>
-    </table>
-  </section>
-
-  <section class="future-state">
-    <h2>The Solution</h2>
-    <h3>Consolidated: 3 Button Variants</h3>
-    <div class="clean-grid">
-      <button class="btn-primary-new">Primary</button>
-      <button class="btn-secondary-new">Secondary</button>
-      <button class="btn-destructive-new">Destructive</button>
-    </div>
-    <p class="caption">Clean. Consistent. Maintainable.</p>
-  </section>
-
-  <footer>
-    <p>Generated by Brad (Design System Architect)</p>
-    <p>Powered by SuperAgentes</p>
-  </footer>
-</body>
-</html>
-```
-
-## Failure Handling
-
-- **No visual examples extracted from codebase:** Fall back to synthetic examples generated from pattern metrics, annotate as "representative" rather than "actual"
-- **HTML file exceeds 1MB size limit:** Reduce grid density (show top 20 worst offenders instead of all variations), compress embedded CSS/JS, remove redundant styling
-- **ROI data incomplete or missing cost breakdowns:** Generate report without cost section, add prominent banner noting ROI analysis skipped with link to run *calculate-roi
-- **Browser rendering breaks for interactive elements:** Disable JavaScript features (calculator, filters), convert to static report with all content visible, log degraded mode in console
-
-## Success Criteria
-
-- [ ] Self-contained HTML (no external dependencies)
-- [ ] Visual "horror show" section maximizes impact
-- [ ] All pattern types visualized (buttons, colors, spacing)
-- [ ] Cost analysis included (if ROI calculated)
-- [ ] Before/after comparison shows consolidation benefit
-- [ ] Executive summary is stakeholder-ready
-- [ ] Report opens in all major browsers
-- [ ] File size <1MB for easy sharing
-
-## Error Handling
-
-- **No audit data**: Exit with message to run *audit first
-- **Missing visual examples**: Use text descriptions instead
-- **Browser compatibility issues**: Fall back to simpler HTML
-- **Large file size**: Reduce examples, compress images
-
-## Security Considerations
-
-- No external resources loaded (self-contained)
-- Sanitize any user-provided text
-- No code execution in report
-- Safe to share via email or intranet
-
-## Examples
-
-### Example 1: Generate Shock Report
-
-```bash
-*shock-report
-```
-
-Output:
-```
-🔍 Brad: Generating visual shock report...
-
-📸 Extracting pattern examples...
-  - Captured 47 button variations
-  - Captured 89 color swatches
-  - Captured spacing inconsistencies
-
-📊 Building metrics dashboard...
-  - Pattern counts: ✓
-  - Reduction percentages: ✓
-  - ROI analysis: ✓ ($374,400/year savings)
-
-🎨 Creating horror show visualization...
-  - Button grid: 47 variations displayed
-  - Color explosion: 89 colors in grid
-  - Spacing chaos: Visualized
-
-✅ Shock report generated: outputs/design-system/my-app/audit/shock-report.html
-
-👀 Open in browser to see the horror show.
-📧 Share with stakeholders to drive action.
-
-Brad says: "Show them the numbers. They can't argue with this."
-```
-
-### Example 2: Opening the Report
-
-```bash
-open outputs/design-system/my-app/audit/shock-report.html
-```
-
-Browser displays:
-- Executive summary at top
-- Metric cards showing 47, 89, 176 (in red)
-- Grid of 47 actual button variations (overwhelming)
-- Cost table: $457k → $83k = $374k savings
-- Clean future state: 3 buttons
-
-## Notes
-
-- Visual impact is the goal - make it shocking
-- Self-contained HTML for easy sharing (email, Slack, etc)
-- Works offline (no CDN dependencies)
-- Optimized for executive review (5-minute read)
-- Include real code examples when possible
-- Color explosion grid is particularly effective
-- ROI section is the closer for stakeholder buy-in
-- Brad recommends: Send to decision-makers before meetings
-- Update report after consolidation to show progress
-- Use this to justify design system investment
-
-
-## Related Checklists
-
-- `squads/design/checklists/ds-component-quality-checklist.md`
-- `squads/design/checklists/ds-pattern-audit-checklist.md`
-
-## Process Guards
-- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.