AI Agent Teams for upgrading Angular applications across ANY major version — from v2 to v21+
Quick Start • Features • How It Works • Installation • Docs • Contributing
Angular upgrades are painful. Really painful.
If you've ever tried upgrading an enterprise Angular app across multiple major versions, you know the drill:
- 📖 Reading changelogs for every version in between
- 🔍 Hunting for breaking changes across hundreds of files
- 🛠️ Manually fixing TypeScript errors, template syntax, and deprecated APIs
- 🔄 Running
ng update, fixing, building, testing... over and over - 😰 Praying nothing breaks in production
We faced this exact nightmare: a 142-component enterprise monorepo stuck on Angular 9.1, needing to reach v21. That's 12 major version jumps, each with its own breaking changes, Node.js requirements, and TypeScript constraints.
So we built this — a Claude Code plugin that turns Angular upgrades into an orchestrated, agent-driven pipeline. Eight specialized AI agents work together, each with a focused role, running in parallel tmux panes where you can watch everything happen in real-time.
The result? Angular 9.1 → 21. 142 components. 55 services. 46 modules. 3 internal libraries. Zero regressions.
| Feature | Description | |
|---|---|---|
| 🎯 | Any Version → Latest | Supports Angular v2 through v21+ with 18 version reference files |
| 🤖 | 8 AI Agents | Planner, Scout, Upgrader, Builder, Fixer, Test Runner, UI Tester, Verifier |
| 📺 | Visual Monitoring | Agents run in tmux split panes — watch all work simultaneously |
| 🔒 | Safety Hooks | 7 lifecycle hooks prevent dangerous commands, protect state files, auto-log failures |
| 📚 | Version Knowledge | Detailed breaking changes with BEFORE/AFTER code examples for every version |
| 🧩 | MCP Integrations | Context7 (live docs), Playwright (UI testing), Fetch (changelogs) |
| 🔄 | Three-Era Strategy | Handles Pre-CLI (v2–v5), Early CLI (v6–v11), and Modern (v12+) Angular |
| 📊 | Progress Tracking | Automatic state management, audit logs, build reports |
| 🛡️ | Zero Dependencies | All hooks use Node.js built-ins only — nothing to install |
| 🌐 | Cross-Platform | Works on macOS, Linux, and Windows |
Four specialized agents run in parallel tmux panes, coordinating via message passing:
┌────────────────────────────────────────────────────────────────────┐
│ TMUX SESSION │
├────────────────┬────────────────┬────────────────┬─────────────────┤
│ @planner │ @scout │ @upgrader │ @builder │
│ │ │ │ │
│ • Roadmap │ • Deps audit │ • ng update │ • Library build │
│ • Risk map │ • Pattern │ • Fix configs │ • App build │
│ • Node matrix │ scanning │ • Apply fixes │ • Error fix │
│ • Timeline │ • Compat │ • TS version │ • Run tests │
│ │ check │ │ │
│ ROADMAP ────► │ CLEAR ──────► │ APPLIED ─────► │ PASSED │
└────────────────┴────────────────┴────────────────┴────────┬────────┘
│
┌─────┴──────┐
│ @verifier │
│ │
│ GO/NO-GO │
│ git commit │
└────────────┘
The plugin recognizes that Angular upgrades fall into three distinct eras, each requiring a fundamentally different approach:
Era 1: Pre-CLI (v2→v5) Era 2: Early CLI (v6→v11) Era 3: Modern (v12→v21+)
┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
│ • Manual pkg edits │ │ • ng update works │ │ • Full schematics │
│ • No schematics │ v5→v6 │ • View Engine era │ v11→v12 │ • Ivy-only │
│ • SystemJS/Webpack │ ──────► │ • RxJS 5→6 → 6→7 │ ──────► │ • Agent Teams │
│ • Node 6.x/8.x │ ERA │ • Ivy preview→def │ ERA │ • MDC, Signals │
│ • TS 2.x │ SHIFT │ • Node 8→12.x │ SHIFT │ • Node 14→22.x │
└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
# 1. Plan your upgrade path
/upgrade-plan
# 2. Start upgrading one version at a time
/upgrade-to 14
# 3. Check progress
/upgrade-status
# 4. If build fails, fix and retry
/upgrade-fix| Command | Purpose |
|---|---|
/upgrade-plan |
Generate full upgrade roadmap with effort estimates |
/upgrade-to <V> |
Upgrade to the next Angular version |
/upgrade-mdc |
v14→v15 Material MDC migration (4 parallel workers) |
/upgrade-controlflow |
v17 control flow syntax migration |
/upgrade-status |
Show progress dashboard |
/upgrade-fix |
Re-run build-fix-verify cycle |
/upgrade-verify |
Re-run GO/NO-GO verification gate |
/test-ui |
On-demand Playwright browser smoke tests |
# Add the Acheron marketplace and install
/plugin marketplace add https://github.com/Acheron-AI/angular-upgrade-kit
/plugin install angular-upgrade-kitgit clone https://github.com/Acheron-AI/angular-upgrade-kit.git
cd angular-upgrade-kit
node scripts/install.jsgit clone https://github.com/Acheron-AI/angular-upgrade-kit.git
claude --plugin-dir ./angular-upgrade-kitCopy agents/, commands/, hooks/, skills/ into your project's .claude/ directory. Merge settings.json and mcp.json.
| Angular | Node.js | TypeScript | Difficulty |
|---|---|---|---|
| 2 | ^6.9.5 | ~2.0 | 🟢 Easy |
| 4 | ^6.9.5 | ~2.2 | 🟢 Easy |
| 5 | ^6.9 / ^8.9 | 2.4–2.5 | 🟢 Easy |
| 6 | ^8.9.4 | ~2.7 | 🔴 Hard (RxJS 5→6) |
| 7 | ^8.9 / ^10.9 | ~3.1 | 🟢 Easy |
| 8 | ^10.9 | ~3.4 | 🟡 Medium |
| 9 | ^10.13 / ^12.11 | 3.6–3.7 | 🟡 Medium (Ivy default) |
| 10 | ^10.13 / ^12.11 | ~3.9 | 🟢 Easy |
| 11 | ^10.13 / ^12.11 | ~4.0 | 🟢 Easy |
| 12 | ^12.14 / ^14.15 | ~4.2–4.3 | 🟡 Medium |
| 13 | ^14 / ^16 | ~4.4 | 🟡 Medium |
| 14 | ^14 / ^16 | ~4.6–4.7 | 🟡 Medium |
| 15 | ^14 / ^16 / ^18 | ~4.8 | 🔴 Hard (Material MDC) |
| 16 | ^16 / ^18 | ~5.0 | 🟢 Easy |
| 17 | ^18 / ^20 | ~5.2 | 🟡 Medium (Control Flow) |
| 18 | ^18 / ^20 | ~5.4 | 🟢 Easy |
| 19 | ^18 / ^20 / ^22 | ~5.5–5.6 | 🟢 Easy |
| 20 | ^20 / ^22 | ~5.8 | 🟡 Medium |
| 21 | ^20 / ^22 | ~5.8–5.9 | 🟡 Medium |
angular-upgrade-kit/
├── .claude-plugin/ # Plugin manifest & marketplace config
├── agents/ # 8 AI agents
│ ├── planner.md # → Upgrade path planning (read-only)
│ ├── scout.md # → Pre-upgrade dependency scanning (read-only)
│ ├── upgrader.md # → Core ng update execution
│ ├── builder.md # → Build verification
│ ├── fixer.md # → Build error resolution
│ ├── test-runner.md # → Unit test execution
│ ├── ui-tester.md # → Playwright browser smoke tests (on-demand)
│ └── verifier.md # → Final GO/NO-GO decision gate
├── commands/ # 8 slash commands
├── hooks/ # 7 lifecycle hooks (Node.js, zero deps)
│ ├── session-start.js # → Loads upgrade state into context
│ ├── session-stop.js # → Saves session metadata
│ ├── pre-bash-guard.js # → Blocks dangerous commands
│ ├── pre-edit-guard.js # → Protects state files
│ ├── post-bash-gate.js # → Auto-logs build failures
│ ├── post-edit-typecheck.js # → TypeScript check after edits
│ └── subagent-log.js # → Agent spawning audit trail
├── skills/
│ ├── angular-upgrade-kit/ # Main skill + 18 version references (v2→v21)
│ ├── material-mdc/ # Material MDC CSS class mapping
│ └── rxjs7/ # RxJS 6→7 migration patterns
├── schemas/ # JSON schema for upgrade state
├── scripts/ # Interactive install script
├── docs/ # Architecture, hooks reference, version guide
├── examples/ # Example project-specific module skills
├── settings.json # Hook configuration template
└── mcp.json # MCP server configuration (Context7, Playwright, Fetch)
When Angular v22 is released:
- Create
skills/angular-upgrade-kit/references/v21-to-v22.md - Follow the template in CONTRIBUTING.md
- Update the version table in
skills/angular-upgrade-kit/SKILL.md - Submit a PR
For complex projects, you can add module-specific skill files that give agents deeper knowledge about your architecture. See examples/module-skills/ for templates.
| Document | Description |
|---|---|
| Architecture | Plugin structure, agent teams model, hook lifecycle |
| How Agents Work | Agent roles, message passing, context isolation |
| Hooks Reference | All 7 hooks with triggers, inputs, outputs |
| Version Reference | Complete v2→v21 compatibility matrix |
| Settings Reference | Configuration, MCP servers, directory structure |
| Contributing | How to add versions, improve agents, submit PRs |
| Security | Hook data handling, no external calls, exit codes |
| Changelog | Release history |
This plugin was battle-tested during a real-world Angular upgrade:
| Metric | Value |
|---|---|
| Source Version | Angular 9.1 |
| Target Version | Angular 21 |
| Version Jumps | 12 major versions |
| Components | 142 |
| Services | 55 |
| Modules | 46 |
| Internal Libraries | 3 |
| Regressions | 0 |
Contributions are welcome! Whether it's adding support for a new Angular version, improving agent behavior, or fixing bugs — every PR helps.
See CONTRIBUTING.md for guidelines.
|
Tenshkumar K Creator & Maintainer LinkedIn • GitHub |
Built at Acheron Software Consultancy Pvt. Ltd. — the first AI open-source contribution from Acheron-AI.
MIT — Free for personal and commercial use.
If this plugin saves you time, consider giving it a ⭐ on GitHub!