Overview
As enterprise frontend applications age, staying on outdated Angular versions becomes a compounding liability. Security vulnerabilities go unpatched, libraries drop support, developer productivity declines, and hiring becomes increasingly difficult when candidates see legacy frameworks on the stack.
Acheron’s internal production application, acheron-mpm, was running on Angular 9.1 — a version from 2020. The application comprised 142 components, 55 services, 46 modules, and an internal shared library with 77 components built via ng-packagr. A traditional manual upgrade was estimated at 3–4 weeks with a dedicated 2-person team.
Using Claude Code Agent Teams, the entire upgrade from Angular 9.1 to 21 was completed in approximately 3 days — with a single engineer orchestrating specialized AI agents
Challenges
The upgrade presented significant technical complexity due to the scale of the codebase and the accumulated technical debt:
- 12 Major Version Gap: Angular’s upgrade path requires sequential, one-version-at-a-time hops. Each major version introduces breaking changes that must be resolved before proceeding to the next.
- Internal Library Lockstep: The shared library (mpm-library) had to upgrade in lockstep with the main application, requiring peer dependency updates and separate build verification at every step.
- Material Design Component (MDC) Migration: Angular 15 introduced a complete rewrite of Material component internals, changing 186 CSS class selectors, requiring a full Sass theming rewrite from @import to @use syntax, and altering DOM structures across every Material component.
- Accumulated Technical Debt: The codebase carried legacy patterns including RxJS 6 toPromise() calls, class-based route guards, old HttpClientModule patterns, tslint configuration, and Protractor test setup — all of which became blockers at various upgrade steps.
- Zero Test Coverage: The application had no passing unit tests, making it impossible to detect regressions through automated testing. Verification relied on successful builds and manual UI inspection.
Objectives
The project aimed to validate AI-assisted framework upgrades as a viable approach for production enterprise applications:
- Complete Framework Upgrade: Successfully migrate from Angular 9.1 to Angular 21 with zero functional regressions.
- Minimize Human Effort: Reduce the upgrade from a multi-week manual endeavor to days of AI-orchestrated automation.
- Ensure Safety and Reproducibility: Build deterministic safety gates that prevent AI agents from making dangerous mistakes such as skipping versions or running untested code.
- Create a Reusable System: Develop an upgrade infrastructure (agents, skills, hooks, commands) that can be applied to other Angular projects, not just this specific codebase
The Solution
Acheron developed a complete AI-native upgrade infrastructure using Claude Code, evolving through three progressively more sophisticated approaches before arriving at the final system.
Approach 1: Plain Prompts
The initial approach involved writing detailed upgrade instructions and providing them directly to Claude Code for each version hop. While functional for simple steps, this approach suffered from context window exhaustion, high hallucination rates (15–20%), and zero state persistence between sessions. Estimated effort: ~6 days.
Approach 2: Skills + Commands + Hooks
The second approach introduced structured context engineering:
- SKILL.md files containing exact breaking changes, before/after code patterns, and fix instructions for each Angular version
- Slash commands (/upgrade-to, /upgrade-mdc, /upgrade-controlflow) that automated the full upgrade pipeline
- Hooks (PreToolUse, PostToolUse) that enforced safety deterministically — blocking dangerous commands and catching build failures with 100% reliability
This reduced hallucination to 5–8% and effort to ~4 days.
Approach 3: Agent Teams (Final System)
The breakthrough came with Claude Code Agent Teams — specialized AI agents running in parallel tmux terminal panes, each with its own isolated 200K-token context window:
- @scout — Pre-upgrade intelligence agent. Scans the codebase for breaking patterns, reads version-specific skills, reports risks, and blocks the pipeline if issues are detected. Read-only access.
- @upgrader — Core upgrade executor. Updates library peer dependencies, runs ng update, applies version-specific fixes. Only activates after @scout reports CLEAR.
- @builder — Build verification agent. Compiles the library, then the application, fixes compilation errors (up to 3 cycles), and runs available tests. Reports BUILD_PASSED or BUILD_FAILED.
For the most complex step (Material MDC migration at v15), 4 parallel Agent Team workers were deployed simultaneously — @sass-rewriter, @css-migrator, @flex-remover, and @config-cleaner — each operating on different file types without conflicts.
Key Technical Discovery:
A rule written in CLAUDE.md (e.g., “never skip Angular versions”) is followed approximately 70% of the time — it is probabilistic. A PreToolUse hook that programmatically blocks the command if the target version is not exactly current+1 works 100% of the time — it is deterministic. For safety-critical operations, hooks are non-negotiable.
The Complete System
The final upgrade infrastructure comprises:
How It Works
The upgrade pipeline follows a structured, repeatable process for each version hop:
- Branch Creation: A new Git branch is created for each version hop (e.g., upgrade/angular-17).
- Scout Phase: The @scout agent scans the codebase against the version-specific SKILL.md, identifying breaking patterns, stale dependencies, and technical debt that must be resolved before the upgrade.
- Pre-Upgrade Fixes: Any blocking technical debt identified by @scout is resolved — such as RxJS toPromise() replacements, Sass theming rewrites, or guard conversions.
- Upgrade Execution: The @upgrader agent updates library peer dependencies, runs ng update for core, CLI, Material, and CDK packages, and applies version-specific fixes.
- Build Verification: The @builder agent compiles the internal library first, then the main application. If compilation fails, the agent analyzes errors and applies fixes for up to 3 cycles.
- Commit and Advance: Upon successful build, changes are committed with a descriptive message and the pipeline advances to the next version.
- Hooks Throughout: At every step, deterministic hooks enforce safety — preventing version skipping, catching build failures, and logging all agent actions for audit.
Benefits
The AI-native upgrade approach delivered strategic benefits across multiple dimensions:
- Dramatic Time Reduction: A 3–4 week manual upgrade was completed in approximately 3 days, freeing engineering resources for product development.
- Near-Zero Hallucination: Agent Teams with isolated context windows and version-specific skills reduced AI hallucination from 15–20% (plain prompts) to less than 2%.
- Deterministic Safety: Hooks provided 100% reliable enforcement of upgrade rules, preventing dangerous operations that instructions alone could not guarantee.
- Clean Git History: One version per commit created a fully bisectable Git history, enabling instant rollback to any intermediate version if issues were discovered.
- Reproducible Pipeline: The entire system — agents, skills, hooks, commands — is project-agnostic and can be applied to any Angular monorepo upgrade.
Technology Stack
The Outcome
The Claude Code Agent Teams approach delivered measurable improvements across the entire upgrade lifecycle:
- ~93% reduction in upgrade effort — from an estimated 3–4 weeks to approximately 3 days.
- 12 major Angular versions traversed — from v9.1 to v21, each with a clean Git commit.
- 142 components, 55 services, 46 modules migrated with zero functional regressions.
- All critical technical debt resolved — RxJS modernized, guards converted to functional patterns, Sass theming rewritten, Karma removed, Dockerfile updated.
Production-ready codebase on Angular 21 — fully buildable, deployable, and functionally identical to the original application.
TENSHKUMAR K
Software Engineer @Acheron | Full-Stack · AI Agents · Cloud · System Design | SIH’23 National Winner | Building Agentic Automation & AI-Powered Solutions
