vibe-breaking-change

name vibe-breaking-change description Implements Vibe Design System breaking changes with full workflow automation including component updates, migration guide updates, codemod generation, testing, and PR creation. Use when implementing breaking changes to Vibe components that require coordinated updates across the design system. Vibe Breaking Change Implementation Overview Implements breaking changes to Vibe Design System components following the established workflow with automated validation, documentation updates, and codemod generation where applicable. When to Use Use this skill when: Implementing breaking API changes to Vibe components Deprecating component props or methods Changing component behavior that affects dependent components Updating component interfaces that require migration documentation Making changes that need coordinated updates across the design system Do NOT use for: Non-breaking enhancements or bug fixes Internal refactoring that doesn't affect public APIs Style-only changes without behavioral impact Emergency hotfixes that bypass normal workflow Quick Reference Phase Actions Validation 1. Analysis Identify affected components, dependencies Component mapping complete 2. Implementation Apply breaking change, update dependents Tests pass locally 3. Testing Run full test suite, update failing tests All tests green 4. Documentation Update migration guide, add codemod if deterministic Documentation complete 5. Cleanup & Delivery lint:fix, lint, build, test → commit, push, PR with task link All checks pass, PR ready for review Core Workflow Phase 1: Analysis and Planning 🔍 Comprehensive Dependency Analysis: # 1. Find all imports and usage across packages grep -r "import.*ComponentName" packages/ grep -r "ComponentName" packages/ --include= "*.tsx" --include= "*.ts" --include= "*.jsx" --include= "*.js" # 2. Find specific prop usage being changed (comprehensive search) grep -r "oldProp=" packages/ --include= "*.tsx" --include= "*.ts" --include= "*.jsx" --include= "*.js" find packages -name "*.tsx" -o -name "*.ts" -o -name "*.jsx" -o -name "*.js" | xargs grep -l "oldProp\|deprecatedMethod" # 3. Analyze by package structure find packages/components -name "*.tsx" | xargs grep -l "ComponentName" # Standalone packages find packages/core/src -name "*.tsx" | xargs grep -l "ComponentName" # Core package find packages/docs -name "*.tsx" | xargs grep -l "ComponentName" # Documentation find packages/mcp -name "*.ts" | xargs grep -l "ComponentName" # MCP examples 📋 Analysis Checklist: Map Dependencies: Components that import the target component Components that use the target component inline Hook or utility functions that reference the component Documentation and example files Assess Impact Scope: Standalone component packages (packages/components/*) Core package components (packages/core/src/components/*) Supporting packages (docs, mcp, testkit) Test files and stories Plan Migration Strategy: Order of updates (component first, then dependents) TypeScript interface changes needed Codemod feasibility (deterministic vs manual) Documentation updates required See references/dependency-analysis.md for advanced dependency mapping techniques. 📊 Expected Findings: 20-40 component files typically need updates for major component changes Multiple package types - standalone, core, docs, examples Mixed file types - .tsx, .ts, .jsx, .js all may need updates Hidden dependencies - MCP tools, test utilities, etc. Phase 2: Implementation 🏗️ Systematic Update Approach: Step 1: Source Component Updates // 1. Update component interface interface ComponentProps { // ❌ Remove deprecated props // oldProp?: string; // deprecatedMethod?: () => void; // ✅ Add new props with better API newProp ?: string ; improvedMethod ?: () => void ; } // 2. Update component implementation const Component = ( { newProp, ...props }: ComponentProps ) => { // Implementation with new API }; Step 2: Internal Dependencies (same package) // Update hooks, utilities, and helpers in the same package // Example: Icon component's useIconProps hook export default function useIconProps ( { label, // ✅ Updated from iconLabel // iconLabel, // ❌ Removed } ) { // Implementation } Step 3: Cross-Package Updates (systematic) # Process 20-40 files systematically # Group by package for efficient updates: # A. Standalone component packages packages/components/tooltip/src/Tooltip/Tooltip.tsx packages/components/button/src/Button/Button.tsx # B. Core package components (bulk of changes) packages/core/src/components/AttentionBox/AttentionBox.tsx packages/core/src/components/Checkbox/Checkbox.tsx # ... (typically 20-30 files) # C. Supporting files packages/mcp/src/server/tools/list-vibe-icons.ts packages/docs/src/pages/components/ComponentName/ComponentName.stories.tsx 🔄 Implementation Order: Component Package - Update source component and internal dependencies Individual Packages - Update standalone packages that use the component Core Package - Systematically update all core components (largest effort) Build Fix - Address any TypeScript errors revealed by changes Supporting Files - Update docs, examples, MCP tools ✅ Implementation Checklist: Source component interface updated Internal component dependencies updated (hooks, utilities) Standalone packages updated (5-10 files typically) Core package components updated (20-30 files typically) TypeScript build errors resolved Documentation and examples updated All updates maintain semantic consistency Phase 3: Testing and Validation # Run comprehensive tests yarn workspace @vibe/core test lerna run test # Run specific component tests yarn workspace @vibe/core test -- Component # Update snapshots if needed yarn workspace @vibe/core test -- --updateSnapshot See references/testing-validation.md for detailed testing patterns and examples. Testing requirements: All existing tests pass or are updated appropriately New tests cover breaking change scenarios Integration tests verify dependent components work No TypeScript errors across the monorepo Phase 4: Documentation Updates Migration Guide Update (VIBE4_MIGRATION_GUIDE.md) ## ComponentName API Changes ### Breaking Changes **Removed `oldProp` prop** - **Before:** `<ComponentName oldProp="value" />` - **After:** `<ComponentName newProp="value" />` - **Reason:** Better API consistency and performance ### Migration Path 1. Replace `oldProp` with `newProp` in all usages 2. Update prop value format if needed 3. Test component behavior matches expected outcome ### Codemod Available ```bash npx @vibe/codemod componentname-old-prop-to-new-prop #### Codemod Generation (if deterministic) ⚠️ **CRITICAL**: Follow established Vibe codemod patterns to avoid common pitfalls. See `references/codemod-best-practices.md` and `references/codemod-examples.md` for detailed patterns and real examples. ```typescript // packages/codemod/transformations/core/v3-to-v4/ComponentName-component-migration.ts import { wrap, getImports, getComponentNameOrAliasFromImports, findComponentElements, migratePropsNames } from "../../../src/utils"; import { NEW_CORE_IMPORT_PATH } from "../../../src/consts"; import { TransformationContext } from "../../../types"; /** * ComponentName migration for v3 to v4: * 1. Rename oldProp1 to newProp1 * 2. Rename oldProp2 to newProp2 */ function transform({ j, root, filePath }: TransformationContext) { // ✅ Use correct import path detection const imports = getImports(root, NEW_CORE_IMPORT_PATH); const componentName = getComponentNameOrAliasFromImports(j, imports, "ComponentName"); if (!componentName) return; const elements = findComponentElements(root, componentName); if (!elements.length) return; // ✅ Single efficient call handles all prop renames elements.forEach(elementPath => { migratePropsNames(j, elementPath, filePath, componentName, { oldProp1: "newProp1", oldProp2: "newProp2", oldProp3: "newProp3" }); }); } export default wrap(transform); Key Pattern Elements: ✅ Use getImports(root, NEW_CORE_IMPORT_PATH) not getCoreImportsForFile() ✅ Use migratePropsNames() not non-existent renameProp() ✅ Single loop with batch prop updates ✅ Include filePath parameter for error reporting ✅ Use established utility imports Phase 5: Cleanup, Validation, and PR Creation ⚠️ ABSOLUTE REQUIREMENT: Do NOT commit, push, or create a PR until every validation step below passes with zero errors. A PR with failing CI is not acceptable. Step 1: Validation gate — run each command, fix failures, repeat until all pass Run these commands sequentially . If ANY command fails, fix the issue and restart from that command . Do NOT skip ahead. # 1. Fix lint issues across all packages yarn lint:fix # 2. Verify lint passes with zero errors yarn lint # 3. Build all packages — must exit 0 yarn build # 4. Run full test suite — must exit 0 yarn test If a step fails: Read the error output carefully Fix the root cause (do not suppress or skip) Re-run from that step through the remaining steps Repeat until all 4 steps pass cleanly in sequence Only proceed to Step 2 when lint, build, AND tests all pass with zero errors. Step 2: Create branch and commit only after all checks pass See references/pr-templates.md for PR description, commit message, and migration guide templates. See references/workflow-checklist.md for a comprehensive checklist of all phases. 📋 Monday.com Task Link: Extract the Monday.com task link from the user's original prompt if provided. The link format is: https://monday.monday.com/boards/<BOARD_ID>/pulses/<PULSE_ID> Include this link in the PR description under the "Task Link" section. If no task link was provided in the original prompt, ask the user for it before creating the PR. Commit and PR titles MUST follow Conventional Commits . Use the appropriate type based on the nature of the change: feat: — new feature or capability change fix: — bug fix refactor: — refactor without behavior change Always include a BREAKING CHANGE: footer in the commit body. # Create feature branch from vibe4 git checkout vibe4 git pull origin vibe4 git checkout -b breaking-change/component-name-api-update # Commit changes (only after all checks above pass) git add . git commit -m "feat(ComponentName): remove oldProp in favor of newProp - Remove deprecated oldProp in favor of newProp - Update all dependent components - Add migration guide and codemod - Update tests for new API BREAKING CHANGE: ComponentName.oldProp has been removed. Use ComponentName.newProp instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>" # Push and create PR git push -u origin breaking-change/component-name-api-update gh pr create \ --title "feat(ComponentName): remove oldProp in favor of newProp" \ --body "## Summary • Remove deprecated \`oldProp\` from ComponentName • Update all dependent components to use \`newProp\` • Add comprehensive migration guide • Include codemod for automated migration ## Breaking Changes - \`ComponentName.oldProp\` → \`ComponentName.newProp\` ## Task Link [Monday.com Task](https://monday.monday.com/boards/<BOARD_ID>/pulses/<PULSE_ID>) ## Test Plan - [ ] All component tests pass - [ ] Dependent components work correctly - [ ] Codemod transforms existing usage - [ ] Migration guide tested - [ ] Build and lint checks pass 🤖 Generated with [Claude Code](https://claude.com/claude-code)" Common Patterns Comprehensive Component Updates Pattern: Systematic Cross-Package Updates # Real example from Icon migration (28 files updated): # 1. Component package (source) packages/components/icon/src/Icon/Icon.tsx # Main component packages/components/icon/src/Icon/hooks/useIconProps.tsx # Internal hooks # 2. Related component packages packages/components/tooltip/src/Tooltip/Tooltip.tsx # Uses Icon packages/components/icon-button/src/IconButton/IconButton.tsx # Uses Icon internally # 3. Core package components (bulk updates) packages/core/src/components/AttentionBox/AttentionBox.tsx # 2 Icon instances packages/core/src/components/Checkbox/Checkbox.tsx # 2 Icon instances packages/core/src/components/Chips/Chips.tsx # 2 Icon instances # ... 20+ more core components # 4. Supporting updates packages/mcp/src/server/tools/list-vibe-icons.ts # Documentation examples packages/core/src/components/DatePicker/DatePickerHeader.tsx # Related component fixes 🔧 Batch Update Strategy: Use replace_all=true for simple prop renames across files Use replace_all=false for context-specific updates Group similar changes together for efficiency Verify build after each logical group of changes Deterministic Changes (Add Codemod) Simple prop renames ( iconSize → size ) Enum value updates Import path changes Method signature changes with clear mapping Non-Deterministic Changes (No Codemod) Complex behavioral changes requiring human judgment Context-dependent prop usage Changes requiring business logic updates Multi-step migration requiring staged approach Mixed Changes (Partial Codemod + Manual) Prop renames (codemod) + related component fixes (manual) API changes (codemod) + TypeScript error fixes (manual) Interface updates (codemod) + documentation updates (manual) Error Recovery If tests fail: Fix broken components, don't skip tests If build fails: Check import/export consistency If codemod fails: Validate transform logic with test cases If PR blocked: Address review feedback before merging ⚠️ Common Pitfalls & Lessons Learned Codemod Implementation Issues ❌ Wrong Function Usage: // WRONG - this function doesn't exist renameProp (j, elementPath, "oldProp" , "newProp" ); // CORRECT - use established utility migratePropsNames (j, elementPath, filePath, componentName, { oldProp : "newProp" }); ❌ Wrong Import Path: // WRONG - looks for old package name const imports = getCoreImportsForFile (root); // CORRECT - specify the right import path const imports = getImports (root, NEW_CORE_IMPORT_PATH ); // "@vibe/core" ❌ Inefficient Multiple Loops: // WRONG - separate loops for each prop