Modernize (Brownfield Upgrade)

modernize: true

When to Use This Skill

• Brownfield path with

  modernize: true

  flag set
• Gears 1-6 are complete (specs established, gaps implemented)
• Ready to upgrade all dependencies to latest versions
• Want to modernize while maintaining spec-driven control

• State file has

  path: "brownfield"

  AND

  modernize: true

• Gear 6 (implement) is complete
• User requested "Brownfield Upgrade" during Gear 1

What This Skill Does

1. Detect Package Manager - npm, yarn, pnpm, pip, go mod, cargo, etc.
2. Audit Current Versions - Document what's installed before upgrade
3. Upgrade Dependencies - Use appropriate upgrade command for tech stack
4. Run Tests - Identify breaking changes
5. Fix Breaking Changes - Iteratively fix with spec guidance
6. Update Specs - Synchronize specs with API/behavior changes
7. Validate Coverage - Ensure tests meet 85%+ threshold
8. Verify Specs Match - Run /speckit.analyze to confirm alignment

Process Overview

Phase 1: Pre-Upgrade Audit

# Create upgrade baseline
cat package.json > .modernize/baseline-package.json

# Run tests to establish baseline
npm test > .modernize/baseline-test-results.txt

# Document current coverage
npm run test:coverage > .modernize/baseline-coverage.txt

# Check for available updates
npm outdated > .modernize/upgrade-plan.txt

# Identify major version bumps (potential breaking changes)
# Highlight security vulnerabilities
# Note deprecated packages

Phase 2: Dependency Upgrade

# Update all dependencies
npm update

# Or for major versions:
npx npm-check-updates -u
npm install

# Check for security issues
npm audit fix

# Update all dependencies
pip install --upgrade -r requirements.txt
pip freeze > requirements.txt

# Or use pip-upgrader
pip-upgrade requirements.txt

# Update all dependencies
go get -u ./...
go mod tidy

# Update dependencies
cargo update

# Check for outdated packages
cargo outdated

Phase 3: Breaking Change Detection

# Run full test suite
npm test

# Capture failures
npm test 2>&1 | tee .modernize/post-upgrade-test-results.txt

# Compare to baseline
diff .modernize/baseline-test-results.txt .modernize/post-upgrade-test-results.txt

• TypeScript compilation errors
• Test failures
• Runtime errors
• API signature changes
• Deprecated method usage

Phase 4: Fix Breaking Changes (Spec-Guided)

1. Identify affected feature:
   • Match failing test to feature spec
   • Determine which spec the code implements
2. Review spec requirements:
   • What behavior SHOULD exist (from spec)
   • What changed in the upgrade
   • How to preserve spec compliance
3. Fix with spec guidance:
   • Update code to work with new dependency
   • Ensure behavior still matches spec
   • Refactor if needed to maintain spec alignment
4. Update tests:
   • Fix broken tests
   • Add tests for new edge cases from upgrade
   • Maintain 85%+ coverage threshold
5. Verify spec alignment:
   • Behavior unchanged from user perspective
   • Implementation may change but spec compliance maintained

Phase 5: Spec Synchronization

• Date formatting libraries (moment → date-fns)
• Validation libraries (joi → zod)
• HTTP clients (axios → fetch)
• ORM updates (Prisma major versions)

1. Update relevant feature spec to document new behavior
2. Update acceptance criteria if needed
3. Update technical requirements with new dependencies
4. Run /speckit.analyze to validate changes

• No spec updates needed
• Just update technical details (versions, file paths)

Phase 6: Test Coverage Improvement

1. Run coverage report:
   bash

   npm run test:coverage

2. Identify gaps:
   • Modules below 85%
   • Missing edge case tests
   • Integration test gaps
3. Add tests with spec guidance:
   • Each spec has acceptance criteria
   • Write tests to cover all criteria
   • Use spec success criteria as test cases
4. Validate:
   bash

   npm run test:coverage
   # All modules should be 85%+

Phase 7: Final Validation

1. Build succeeds:
   bash

   npm run build
   # No errors

2. All tests pass:
   bash

   npm test
   # 0 failures

3. Coverage meets threshold:
   bash

   npm run test:coverage
   # 85%+ on all modules

4. Specs validated:
   bash

   /speckit.analyze
   # No drift, all specs match implementation

5. Dependencies secure:
   bash

   npm audit
   # No high/critical vulnerabilities

Output

.modernize/UPGRADE_REPORT.md

# Dependency Modernization Report

**Date**: {date}
**Project**: {name}

## Summary

- **Dependencies upgraded**: {X} packages
- **Major version bumps**: {X} packages
- **Breaking changes**: {X} fixed
- **Tests fixed**: {X} tests
- **New tests added**: {X} tests
- **Coverage improvement**: {before}% → {after}%
- **Specs updated**: {X} specs

## Upgraded Dependencies

| Package | Old Version | New Version | Breaking? |
|---------|-------------|-------------|-----------|
| react | 17.0.2 | 18.3.1 | Yes |
| next | 13.5.0 | 14.2.0 | Yes |
| ... | ... | ... | ... |

## Breaking Changes Fixed

1. **React 18 Automatic Batching**
   - Affected: User state management
   - Fix: Updated useEffect dependencies
   - Spec: No behavior change
   - Tests: Added async state tests

2. **Next.js 14 App Router**
   - Affected: Routing architecture
   - Fix: Migrated pages/ to app/
   - Spec: Updated file paths
   - Tests: Updated route tests

## Spec Updates

- Updated technical requirements with new versions
- Updated file paths for App Router migration
- No functional spec changes (behavior preserved)

## Test Coverage

- Before: 78%
- After: 87%
- New tests: 45 tests added
- All modules: ✅ 85%+

## Validation

- ✅ All tests passing
- ✅ Build successful
- ✅ /speckit.analyze: No drift
- ✅ npm audit: 0 high/critical
- ✅ Coverage: 87% (target: 85%+)

## Next Steps

Application is now:
- ✅ Fully modernized (latest dependencies)
- ✅ 100% spec coverage maintained
- ✅ Tests passing with high coverage
- ✅ Specs synchronized with implementation
- ✅ Ready for ongoing spec-driven development

Configuration in State File

{
  "path": "brownfield",
  "modernize": true,
  "metadata": {
    "modernizeRequested": "2024-11-17T12:00:00Z",
    "upgradeScope": "all-dependencies",
    "targetCoverage": 85
  }
}

When Modernize Runs

• Automatically runs after Gear 6 if

  modernize: true

• Skill becomes available after Gear 6 completes
• User explicitly invokes:

  /stackshift.modernize

  or skill auto-activates

Success Criteria

• ✅ All dependencies updated to latest stable versions
• ✅ All tests passing
• ✅ Test coverage ≥ 85% on all modules
• ✅ Build successful (no compilation errors)
• ✅ /speckit.analyze shows no drift
• ✅ No high/critical security vulnerabilities
• ✅ Specs updated where behavior changed
• ✅ Upgrade report generated

Benefits of Brownfield Upgrade

vs. Standard Brownfield:

• ✅ Modern dependencies (not stuck on old versions)
• ✅ Security updates (latest patches)
• ✅ Performance improvements (newer libraries often faster)
• ✅ New features (latest library capabilities)
• ✅ Reduced technical debt (no old dependencies)

vs. Greenfield:

• ✅ Faster (upgrade vs. rebuild)
• ✅ Lower risk (incremental changes vs. rewrite)
• ✅ Spec-guided (specs help fix breaking changes)
• ✅ Keeps working code (only changes dependencies)

Use Case:

Technical Approach

Spec-Driven Upgrade Strategy

1. Specs as Safety Net:
   • Every feature has acceptance criteria
   • Run tests against specs after each upgrade
   • If tests fail, specs guide the fix
2. Incremental Upgrades:
   • Upgrade in phases (minor first, then majors)
   • Run tests after each phase
   • Rollback if too many failures
3. Coverage as Quality Gate:
   • Must maintain 85%+ throughout upgrade
   • Add tests for new library behaviors
   • Ensure edge cases covered
4. Spec Synchronization:
   • If library changes behavior, update spec
   • If implementation changes, update spec
   • /speckit.analyze validates alignment