Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
119 lines (107 loc) · 6.49 KB

ARCHITECTURE.md

File metadata and controls

119 lines (107 loc) · 6.49 KB

Architecture

Plugin Structure

angular-upgrade-kit/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest (name, version, metadata)
│   └── marketplace.json     # Marketplace catalog for distribution
├── agents/                  # 8 specialized 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
│   ├── upgrade-plan.md     # /upgrade-plan — Full path planning
│   ├── upgrade-to.md       # /upgrade-to — Main upgrade pipeline
│   ├── upgrade-mdc.md      # /upgrade-mdc — v14→v15 Material MDC
│   ├── upgrade-fix.md      # /upgrade-fix — Re-run build-fix cycle
│   ├── upgrade-status.md   # /upgrade-status — Progress dashboard
│   ├── upgrade-verify.md   # /upgrade-verify — Re-run verification
│   ├── upgrade-controlflow.md # /upgrade-controlflow — v17 control flow
│   └── test-ui.md          # /test-ui — On-demand browser tests
├── hooks/                   # 7 lifecycle hooks
│   ├── session-start.js    # Loads upgrade 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/                  # Knowledge base
│   ├── angular-upgrade-kit/ # Main skill + 19 version references
│   ├── material-mdc/       # Material MDC CSS mapping
│   └── rxjs7/              # RxJS 6→7 migration patterns
├── schemas/                 # JSON schemas
├── scripts/                 # Install script
├── docs/                    # Documentation
├── examples/                # Example project-specific skills
├── settings.json            # Hook configuration template
└── mcp.json                 # MCP server configuration

Three-Era Strategy

Angular upgrades span three distinct eras with different tooling:

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     │
└─────────────────────┘         └─────────────────────┘         └─────────────────────┘

Agent Teams Model

The upgrade pipeline uses Claude Code's Agent Teams feature to run multiple agents in parallel tmux panes:

┌─────────────────────────────────────────────────────────┐
│                  TMUX SESSION                            │
├──────────────┬──────────────┬──────────────┬────────────┤
│   @planner   │   @scout     │  @upgrader   │  @builder  │
│   (plan)     │   (scan)     │  (ng update) │  (compile) │
│              │              │              │            │
│ Roadmap      │ Deps audit   │ Core update  │ Lib build  │
│ Risk map     │ Patterns     │ Fixes apply  │ App build  │
│ Node matrix  │ Compat check │ Config patch │ Error fix  │
│              │              │              │ Tests run  │
│  ROADMAP ──> │  CLEAR ────> │ APPLIED ───> │ PASSED     │
└──────────────┴──────────────┴──────────────┴────────────┘
                                                    │
                                              ┌─────┴──────┐
                                              │ @verifier  │
                                              │ GO/NO-GO   │
                                              │ git commit │
                                              └────────────┘

Hook Lifecycle

Session Start
    │
    ├─ session-start.js → Loads upgrade/state.json into context
    │
    ├─ [User or Agent runs command]
    │   │
    │   ├─ pre-bash-guard.js → Blocks dangerous bash commands
    │   ├─ pre-edit-guard.js → Protects state files from edits
    │   │
    │   ├─ [Command executes]
    │   │
    │   ├─ post-bash-gate.js → Auto-logs build failures as blockers
    │   └─ post-edit-typecheck.js → Runs tsc after .ts edits
    │
    ├─ [Agent spawned]
    │   └─ subagent-log.js → Audit trail for agent activity
    │
Session Stop
    └─ session-stop.js → Saves session metadata, git state

State Management

All upgrade state is stored in upgrade/state.json:

  • Created automatically on first /upgrade-to run
  • Updated by hooks (blockers, session timestamps)
  • Updated by commands (step completion, test results)
  • Protected from direct edits by pre-edit-guard.js
  • Schema defined in schemas/upgrade-state.schema.json