ISA-Frontend/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a sophisticated Angular 20.1.2 monorepo managed by Nx 21.3.2. The main application is isa-app, a comprehensive inventory and returns management system for retail/e-commerce operations. The system handles complex workflows including order management (OMS), returns processing (remission), customer relationship management (CRM), product cataloging, and checkout/reward systems.

Architecture

Monorepo Structure

• apps/isa-app: Main Angular application
• libs/: Reusable libraries organized by domain and type
  • core/: Core utilities (config, logging, storage, tabs, navigation)
  • common/: Shared utilities (data-access, decorators, print)
  • ui/: UI component libraries (buttons, dialogs, inputs, etc.)
  • shared/: Shared domain components (filter, scanner, product components)
  • oms/: Order Management System features and utilities
  • remission/: Remission/returns management features
  • catalogue/: Product catalogue functionality
  • utils/: General utilities (validation, scroll position, parsing)
  • icons/: Icon library
• generated/swagger/: Auto-generated API client code from OpenAPI specs

Key Architectural Patterns

• Domain-Driven Design: Clear domain boundaries with dedicated modules (OMS, remission, CRM, catalogue, checkout)
• Layered Architecture: Strict dependency hierarchy (Feature → Shared/UI → Data Access → Infrastructure)
• Standalone Components: All new components use Angular standalone architecture with explicit imports
• Feature Libraries: Domain features organized as separate libraries (e.g., oms-feature-return-search, remission-feature-remission-list)
• Data Access Layer: Separate data-access libraries for each domain with NgRx Signals stores
• Shared UI Components: 15 dedicated UI component libraries with design system integration
• Generated API Clients: 10 auto-generated Swagger/OpenAPI clients with post-processing pipeline
• Path Aliases: Comprehensive TypeScript path mapping (@isa/domain/layer/feature)
• Component Prefixes: Domain-specific prefixes (OMS: oms-feature-*, Remission: remi-*, UI: ui-*)
• Modern State Management: NgRx Signals with entities, session persistence, and reactive patterns

Common Development Commands

Build Commands

# Build the main application (development) - default configuration
npm run build
# Or: npx nx build isa-app --configuration=development

# Build for production
npm run build-prod
# Or: npx nx build isa-app --configuration=production

# Build without using Nx cache (for fresh builds)
npx nx build isa-app --skip-nx-cache

# Serve the application with SSL (development server)
npm start
# Or: npx nx serve isa-app --ssl

Testing Commands

# Run tests for all libraries except the main app (default command)
npm test
# Or: npx nx run-many -t test --exclude isa-app --skip-nx-cache

# Run tests for a specific library (always use --skip-nx-cache for fresh results)
npx nx run <project-name>:test --skip-nx-cache
# Example: npx nx run oms-data-access:test --skip-nx-cache

# Skip Nx cache entirely (important for ensuring fresh builds/tests)
npx nx run <project-name>:test --skip-nx-cache
# Or combine with skip-cache: npx nx run <project-name>:test --skip-nx-cache --skip-nx-cache

# Run a single test file
npx nx run <project-name>:test --testFile=<path-to-test-file> --skip-nx-cache

# Run tests with coverage
npx nx run <project-name>:test --code-coverage --skip-nx-cache

# Run tests in watch mode
npx nx run <project-name>:test --watch

# Run CI tests with coverage (for CI/CD)
npm run ci
# Or: npx nx run-many -t test --exclude isa-app -c ci

Linting Commands

# Lint a specific project
npx nx lint <project-name>
# Example: npx nx lint remission-data-access

# Run linting for all projects
npx nx run-many -t lint

Other Useful Commands

# Generate Swagger API clients (regenerates all API clients)
npm run generate:swagger
# Or: npx nx run-many -t generate -p tag:generated,swagger

# Start Storybook for UI component development
npm run storybook
# Or: npx nx run isa-app:storybook

# Format code with Prettier
npm run prettier

# Format staged files only (used in pre-commit hooks)
npm run pretty-quick

# List all projects in the workspace
npx nx list

# Show project dependencies graph (visual)
npx nx graph

# Run affected tests (based on git changes)
npx nx affected:test

Testing Framework

Current Setup (Migration in Progress)

• Jest: Used by 40 libraries (76% of codebase) - existing/legacy libraries
• Vitest: Used by 13 libraries (24% of codebase) - newer libraries and migrations
• Testing Utilities Migration:
  • Angular Testing Utilities (TestBed, ComponentFixture): Preferred for new tests (25 test files)
  • Spectator: Legacy testing utility for existing tests (56 test files)
  • ng-mocks: For advanced mocking scenarios and child component mocking

Migration Status by Domain

• Migrated to Vitest: crm-data-access, checkout-*, several ui/* components, remission/* libraries
• Still on Jest: Core oms/* libraries, main application, most legacy libraries
• New Libraries: Should use Vitest + Angular Testing Utilities from the start

Test File Requirements

• Test files must end with .spec.ts
• Use AAA pattern (Arrange-Act-Assert) consistently across both frameworks
• Include E2E testing attributes (data-what, data-which, dynamic data-* attributes) in HTML templates
• Mock external dependencies and child components using appropriate framework tools
• Verify E2E attributes are correctly applied in component unit tests

State Management

• NgRx Signals: Primary state management with modern functional approach using signalStore()
• Entity Management: Uses withEntities() for normalized data storage
• Session Persistence: State persistence with withStorage() using SessionStorageProvider
• Reactive Methods: rxMethod() with takeUntilKeydownEscape() for user-cancellable operations
• Custom RxJS Operators: Specialized operators like takeUntilAborted(), takeUntilKeydown()
• Error Handling: tapResponse() for handling success/error states in stores
• Lifecycle Hooks: withHooks() for cleanup and initialization (e.g., orphaned entity cleanup)
• Navigation State: Use @isa/core/navigation for temporary navigation context (return URLs, wizard state) instead of query parameters

Styling and Design System

• Tailwind CSS: Primary styling framework with extensive ISA-specific customization
  • Custom Breakpoints: isa-desktop (1024px), isa-desktop-l (1440px), isa-desktop-xl (1920px)
  • Brand Color System: Comprehensive isa-* color palette with semantic naming
  • Design Tokens: Consistent spacing, typography, shadows, and border-radius values
• Custom Tailwind Plugins (7 plugins): button, typography, menu, label, input, section, select-bullet
• SCSS Integration: Component-scoped SCSS with BEM-like naming conventions
• CSS Custom Properties: Extensive use of CSS variables for theming and component variants
• Typography System: 14 custom text utilities (.isa-text-heading-1-bold, .isa-text-body-2-regular)
• UI Component Libraries: 15 specialized UI libraries with consistent API patterns
• Storybook Integration: Component documentation and development environment
• Responsive Design & Breakpoints:
  • Breakpoint Service: Use @isa/ui/layout for reactive breakpoint detection in components
  • Available Breakpoints:
    • Breakpoint.Tablet: (max-width: 1279px) - Mobile and tablet devices
    • Breakpoint.Desktop: (min-width: 1280px) and (max-width: 1439px) - Standard desktop screens
    • Breakpoint.DekstopL: (min-width: 1440px) and (max-width: 1919px) - Large desktop screens
    • Breakpoint.DekstopXL: (min-width: 1920px) - Extra large desktop screens
  • Usage Pattern:

    import { breakpoint, Breakpoint } from '@isa/ui/layout';
    
    isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.DekstopXL]);
    

  • Template Integration: Use with @if control flow for conditional rendering based on screen size
  • Note: Prefer the breakpoint service over CSS-only solutions (hidden/flex classes) for proper server-side rendering and better maintainability

API Integration and Data Access

• Generated Swagger Clients: 10 auto-generated TypeScript clients from OpenAPI specs in generated/swagger/
  • Available APIs: availability-api, cat-search-api, checkout-api, crm-api, eis-api, inventory-api, isa-api, oms-api, print-api, wws-api
  • Generation Tool: ng-swagger-gen with custom configurations per API
  • Post-processing: Automatic Unicode character cleanup via tools/fix-files.js
• Data Access Architecture:
  • Business Logic Services: Domain-specific services that wrap generated API clients
  • Type Safety: Full TypeScript integration with Zod schema validation
  • Error Handling: Global HTTP interceptor with custom error classes and automatic re-authentication
  • Configuration Management: Dynamic API endpoint configuration through dependency injection
  • Request Cancellation: Built-in support via AbortSignal and custom operators
• Service Patterns:
  • Modern Injection: Uses inject() function with private field pattern
  • Logging Integration: Comprehensive logging throughout data access layer
  • Consistent API: Standardized service interfaces across all domains

Build Configuration

• Angular 20.1.2: Latest Angular version
• TypeScript 5.8.3: For type safety
• Node.js >= 22.0.0: Required Node version (specified in package.json engines)
• npm >= 10.0.0: Required npm version (specified in package.json engines)
• Nx 21.3.2: Monorepo build system and development tools
• Vite 6.3.5: Build tool for faster development and testing (used with Vitest)

Important Conventions and Patterns

Library Organization

• Naming Pattern: [domain]-[layer]-[feature] (e.g., oms-feature-return-search, ui-buttons)
• Path Aliases: @isa/[domain]/[layer]/[feature] (e.g., @isa/oms/data-access, @isa/ui/buttons)
• Project Names: Found in each library's project.json file, following consistent naming

Component Architecture

• Standalone Components: All new components must be standalone with explicit imports
• Component Prefixes: Domain-specific prefixes for clear identification
  • OMS features: oms-feature-* (e.g., oms-feature-return-search-main)
  • Remission features: remi-*
  • UI components: ui-*
  • Core utilities: core-*
• Signal-based Inputs: Use Angular signals (input(), computed()) for reactive properties
• Host Binding: Dynamic CSS classes via Angular host properties

Dependency Rules

• Unidirectional Dependencies: Feature → Shared/UI → Data Access → Infrastructure
• Import Boundaries: Use path aliases, avoid relative imports across domain boundaries
• Generated API Imports: Import from @generated/swagger/[api-name] for API clients

Code Quality

• Modern Angular Patterns: Prefer inject() over constructor injection
• Type Safety: Use Zod schemas for runtime validation alongside TypeScript
• Error Handling: Custom error classes with specific error codes
• E2E Testing: Always include data-what and data-which attributes in templates

Development Workflow and Best Practices

Essential Commands

• Development: npm start (serves with SSL enabled by default)
• Testing: npm test (runs all library tests, skips main app)
• Building: npm run build (development), npm run build-prod (production)
• Code Generation: npm run generate:swagger (regenerates all API clients)
• Code Quality: npm run prettier (formats all files), npm run pretty-quick (staged files only)

Nx Workflow Optimization

• Always use npx nx run pattern for executing specific tasks
• Include --skip-nx-cache flag when running tests to ensure fresh results
• Use --skip-nx-cache to bypass Nx cache entirely for guaranteed fresh builds/tests (important for reliability)
• Use affected commands for CI/CD optimization: npx nx affected:test
• Visualize project dependencies: npx nx graph
• The default git branch is develop (not main)

Testing Best Practices

• New Libraries: Use Vitest + Angular Testing Utilities
• Legacy Libraries: Continue using Jest + Spectator until migrated
• Migration Priority: UI components and new domains migrate first
• E2E Attributes: Verify data-what, data-which, and dynamic data-* attributes in tests
• Mock Strategy: Use appropriate framework tools (Spectator's mocks array vs TestBed providers)

Code Quality Guidelines

• Linting: ESLint flat config with Nx dependency checks
• Formatting: Prettier with pre-commit hooks via Husky and lint-staged
• Type Safety: Zod validation for API boundaries, TypeScript strict mode
• Bundle Optimization: Monitor bundle sizes (2MB warning, 5MB error for main bundle)
• Performance: Use NgRx Signals for reactive state management with session persistence

Development Notes and Guidelines

Getting Started

• Application Startup: Only isa-app can be started - it's the main application entry point
• SSL Development: The development server runs with SSL by default (npm start), which is crucial for production-like authentication flows
• Node Requirements: Ensure Node.js ≥22.0.0 and npm ≥10.0.0 before starting development
• First-Time Setup: After cloning, run npm install then npm start to verify everything works

Essential Documentation References

• Testing Guidelines: Review docs/guidelines/testing.md before writing any tests - it covers the Jest→Vitest migration, Spectator→Angular Testing Utilities transition, and E2E attribute requirements
• Code Review Standards: Follow the structured review process in .github/review-instructions.md with categorized feedback (🚨 Critical, ❗ Minor, ⚠️ Warnings, ✅ Good Practices)
• E2E Testing Requirements: Always include data-what, data-which, and dynamic data-* attributes in HTML templates - these are essential for automated testing by QA colleagues

Library Development Patterns

• Understanding Internal Libraries: Before using any internal library from the libs/ directory, always read its README.md file first to understand its purpose, API, and proper usage patterns
• Library Documentation: All libraries have comprehensive README.md documentation. To prevent context pollution, always use a subagent (preferably docs-architect or general-purpose) to retrieve specific information from library documentation rather than reading the entire file directly
• New Library Creation: Use Nx generators with domain-specific naming ([domain]-[layer]-[feature])
• Standalone Components: All new components must be standalone with explicit imports - no more NgModules
• Testing Framework Selection:
  • New libraries: Use Vitest + Angular Testing Utilities
  • Existing libraries: Continue with Jest + Spectator until migrated
• Path Aliases: Always use @isa/[domain]/[layer]/[feature] - avoid relative imports across domain boundaries

Library Reference Guide

All 62 libraries in the monorepo have comprehensive README.md documentation. Use subagents to retrieve specific information from these READMEs to avoid context pollution.

Availability Domain (1 library)

• @isa/availability/data-access - Product availability service supporting 6 order types (InStore, Pickup, Delivery, DIG-Versand, B2B-Versand, Download) with intelligent routing, Zod validation, and business rule enforcement

Catalogue Domain (1 library)

• @isa/catalogue/data-access - Product search and availability validation service with multi-type search (EAN, Term, Loyalty), download validation, and DIG/B2B delivery availability

Checkout Domain (6 libraries)

• @isa/checkout/data-access - Shopping cart management and checkout orchestration supporting 6 order types with reward system integration, payment type logic, and CRM data transformation
• @isa/checkout/feature/reward-order-confirmation - Order confirmation page for reward/premium orders with address display and item list
• @isa/checkout/feature/reward-shopping-cart - Complete reward shopping cart feature with checkout workflow, item management, and order completion orchestration
• @isa/checkout/feature/reward-catalog - Reward catalog browsing with customer bonus points, filtering, pagination, and item selection
• @isa/checkout/shared/product-info - Product information display components for checkout (redemption info, destination info, stock info)
• @isa/checkout/shared/reward-selection-dialog - Product selection dialog for adding items to reward shopping cart

Common Libraries (3 libraries)

• @isa/common/data-access - Foundational data access utilities including error hierarchy, custom RxJS operators (takeUntilAborted, takeUntilKeydown), batching infrastructure, and Zod integration
• @isa/common/decorators - TypeScript decorators for validation (ValidateParams), caching (Cache), debouncing (Debounce), and in-flight request management (InFlight, InFlightWithKey, InFlightWithCache)
• @isa/common/print - Platform-aware print service supporting both label and office printers with smart printer selection and reusable print dialog components

Core Libraries (5 libraries)

• @isa/core/config - Type-safe configuration management with runtime Zod validation, nested object access via dot notation, and environment-specific configuration
• @isa/core/logging - Centralized logging service with log levels, contextual information, and Angular integration
• @isa/core/navigation - Context preservation service for multi-step navigation flows with automatic tab-scoped storage and cleanup
• @isa/core/storage - User storage abstraction with SessionStorage/IndexedDB backends and automatic serialization
• @isa/core/tabs - Tab management system with NgRx Signals, persistent storage, intelligent history pruning, and Router integration

CRM Domain (1 library)

• @isa/crm/data-access - Customer relationship management data access with customer fetching, shipping address management, bonus cards, payer info, and tab-based state management

Icons (1 library)

• @isa/icons - Icon library with Angular icon components and SVG assets

OMS Domain (9 libraries)

• @isa/oms/data-access - Order Management System data access with return search, question-based workflows, state management (3 stores), and print integration
• @isa/oms/feature/return-details - Receipt details view with item display, customer history, quantity management, and return eligibility validation
• @isa/oms/feature/return-process - Dynamic question-based return process with 6 product categories, 5 question types, form validation, and state persistence
• @isa/oms/feature/return-review - Final review step for return process with task summary, receipt reprinting, and navigation protection
• @isa/oms/feature/return-search - Return search with filtering, pagination, infinite scroll, and automatic redirect to details when single result found
• @isa/oms/feature/return-summary - Pre-submission summary of return process with item review and final confirmation before order creation
• @isa/oms/shared/product-info - Product display component for OMS workflows with image, navigation, and format icons
• @isa/oms/shared/task-list - Task list component with dual appearance modes (main/review), NgRx integration, and tab-based isolation
• @isa/oms/utils/translation - Receipt type translation utility with 13 German translations and dependency injection support

Remission Domain (8 libraries)

• @isa/remission/data-access - Remission/returns management data access supporting Pflichtremission (mandatory) and Abteilungsremission (department overflow) with stock batching, state management, and supplier/branch services
• @isa/remission/feature/remission-list - Main remission list with dual types, filtering, search, and resource-based data fetching
• @isa/remission/feature/remission-return-receipt-details - Receipt details view with items, metadata, and action integration
• @isa/remission/feature/remission-return-receipt-list - List view for all return receipts with sorting, filtering, and parallel resource fetching
• @isa/remission/shared/product - Product display components for remission workflows (info, stock info, shelf meta)
• @isa/remission/shared/remission-start-dialog - Two-step dialog for receipt creation and package assignment
• @isa/remission/shared/return-receipt-actions - Action components for receipt deletion, continuation, and completion
• @isa/remission/shared/search-item-to-remit-dialog - Dialog for adding unlisted items to remission with search-to-remit flow

Shared Component Libraries (7 libraries)

• @isa/shared/address - Address display components (multi-line and inline) with country name resolution and German address special handling
• @isa/shared/filter - Advanced filtering system with filter groups, date ranges, search, and scanner integration
• @isa/shared/product-format - Product format display with icon and text components supporting 6 format codes (HC, PB, EB, AB, DIG, AUD)
• @isa/shared/product-image - Product image directive with CDN integration, configurable dimensions, and lazy loading
• @isa/shared/product-router-link - EAN-based product navigation directive with pluggable URL builder pattern
• @isa/shared/quantity-control - Accessible quantity selector with dropdown presets, manual input mode, and smart logic
• @isa/shared/scanner - Barcode scanner integration with camera and keyboard input support

UI Component Libraries (17 libraries)

• @isa/ui/bullet-list - Bullet list component with parent-child icon inheritance and signal-based reactivity
• @isa/ui/buttons - Five button components (Button, TextButton, IconButton, InfoButton, StatefulButton) with pending states, size/color variants, and ARIA support
• @isa/ui/datepicker - Range datepicker with validators, calendar views, and ControlValueAccessor integration
• @isa/ui/dialog - Dialog system with 5 preset types (message, confirmation, text-input, number-input, feedback) and injection-based API
• @isa/ui/empty-state - Empty state component with 4 appearance variants (general, no-results, no-data, error) and SVG icons
• @isa/ui/expandable - Expandable/collapsible container with smooth animations
• @isa/ui/input-controls - Form control components (checkbox, dropdown, text-field, chips, checklist, listbox, inline-input) with ControlValueAccessor integration
• @isa/ui/item-rows - Item display rows with data components and directive-based composition
• @isa/ui/label - Label component with Tag/Notice types and High/Medium/Low priority levels
• @isa/ui/layout - Breakpoint service for responsive design with 4 breakpoints (Tablet, Desktop, DesktopL, DesktopXL)
• @isa/ui/menu - CDK Menu wrapper components with keyboard navigation and ARIA compliance
• @isa/ui/progress-bar - Determinate and indeterminate progress indicators with computed width
• @isa/ui/search-bar - Search bar with clear button, Angular Forms integration, and focus management
• @isa/ui/skeleton-loader - Loading state component with structural directive and customizable dimensions
• @isa/ui/toolbar - Toolbar component with two size variants (small/medium) and content projection
• @isa/ui/tooltip - Tooltip directive with positioning and accessibility
• @isa/ui/bullet-list - Bullet list component with customizable icons and nested list support

Utility Libraries (3 libraries)

• @isa/utils/ean-validation - EAN barcode validation with Angular Forms validator, standalone validation function, and comprehensive GS1 prefix reference
• @isa/utils/scroll-position - Scroll position restoration service with tab-based storage
• @isa/utils/z-safe-parse - Safe Zod parsing utility with automatic fallback and console warnings

API Integration Workflow

• Swagger Generation: Run npm run generate:swagger to regenerate all 10 API clients when backend changes
• Data Services: Wrap generated API clients in domain-specific data-access services with proper error handling and Zod validation
• State Management: Use NgRx Signals with signalStore(), entity management, and session persistence for complex state

Performance and Quality Considerations

• Bundle Monitoring: Watch bundle sizes (2MB warning, 5MB error for main bundle)
• Testing Cache: Always use --skip-nx-cache flag when running tests to ensure reliable results
• Code Quality: Pre-commit hooks enforce Prettier formatting and ESLint rules automatically
• Memory Management: Clean up subscriptions and use OnPush change detection for optimal performance

Common Troubleshooting

• Build Issues: Check Node version and run npm install if encountering module resolution errors
• Test Failures: Use --skip-nx-cache flag and ensure test isolation (no shared state between tests)
• Nx Cache Issues: If you see existing outputs match the cache, left as is during build or testing:
  • Option 1: Run npx nx reset to clear the Nx cache completely
  • Option 2: Use --skip-nx-cache flag to bypass Nx cache for a specific command (e.g., npx nx test <project> --skip-nx-cache)
  • When to use: Always use --skip-nx-cache when you need guaranteed fresh builds or test results
• SSL Certificates: Development server uses SSL - accept certificate warnings in browser for localhost
• Import Errors: Verify path aliases in tsconfig.base.json and use absolute imports for cross-library dependencies

Domain-Specific Conventions

• Component Prefixes: Use oms-feature-* for OMS, remi-* for remission, ui-* for shared components
• Git Workflow: Default branch is develop (not main), use conventional commits without co-author tags
• Design System: Use ISA-specific Tailwind utilities (isa-accent-*, isa-text-*) and custom breakpoints (isa-desktop-*)
• Logging: Use centralized logging service (@isa/core/logging) with contextual information for debugging
• Navigation State: Use @isa/core/navigation for passing temporary state between routes (return URLs, form context) instead of query parameters - keeps URLs clean and state reliable

Claude Code Workflow Definition

Based on comprehensive analysis of development patterns and available tools/MCP servers, here's the formal workflow for handling requests using the Task tool with specialized subagents:

Phase 1: Request Analysis and Routing

1.1 Initial Analysis (Always Use Subagents)

Trigger: Any user request Subagents: general-purpose (for research) + domain specialists as needed

1. Parse request intent and complexity level
2. Classify request type:
   - Feature Development (new functionality)
   - Bug Fix/Maintenance (corrections)
   - Code Quality/Refactoring (improvements)
   - Testing/QA (validation)
   - Architecture/Design (structure)
   - Research/Investigation (exploration)
3. Assess information completeness and ambiguity
4. Determine required domains and expertise

1.2 Clarification Decision Matrix

IF (high ambiguity + high impact) → REQUEST clarification
IF (medium ambiguity + architectural changes) → REQUEST optional clarification
IF (low ambiguity OR simple changes) → PROCEED with documented assumptions

Phase 2: Task Decomposition and Agent Assignment

2.1 Complexity-Based Routing

Simple Tasks (Single file, isolated change):

• Route directly to specialist (frontend-developer, typescript-pro, etc.)
• Single quality gate at completion

Moderate Tasks (Multiple related files, limited scope):

• Decompose into 2-4 parallel subagent tasks
• Example: angular-mcp + test-automator + docs-architect

Complex Tasks (Multiple domains, significant scope):

• Hierarchical task tree with dependencies
• Example: general-purpose (analysis) → nx-mcp (structure) → frontend-developer + test-automator (parallel) → code-reviewer (validation)

Architectural Tasks (System-wide changes):

• Multi-phase with user approval gates
• Example: architect-review → user approval → frontend-developer + backend-architect + database-optimizer → performance-engineer (validation)

2.2 Optimal Agent Combinations

Feature Development Pattern:

context7 (fetch latest APIs)
→ frontend-developer + test-automator (parallel TDD)
→ ui-ux-designer (if UI changes)
→ code-reviewer (quality validation)

Bug Fix Pattern:

error-detective (analyze issue)
→ debugger (reproduce and fix)
→ test-automator (regression tests)
→ performance-engineer (if performance-related)

Refactoring Pattern:

general-purpose (understand current state)
→ legacy-modernizer (plan modernization)
→ test-automator (safety tests)
→ frontend-developer (implement changes)
→ architect-review (validate architecture)

Phase 3: Execution with Progressive Quality Gates

3.1 Standard Execution Flow

1. Each subagent receives atomic task with clear requirements
2. Subagent performs implementation with embedded quality checks
3. Results validated against project standards (E2E attributes, naming conventions)
4. Integration compatibility verified
5. Progress reported to user with next steps

3.2 Quality Gates by Task Type

• Code Changes: test-automator → code-reviewer → performance-engineer
• UI Changes: ui-visual-validator → frontend-security-coder → code-reviewer
• Architecture Changes: architect-review → user approval → implementation → performance-engineer
• API Changes: api-documenter → backend-security-coder → integration tests

Phase 4: Integration and Validation

4.1 Continuous Validation

- Every file change triggers appropriate quality subagent
- Integration points validated by architect-review
- Performance impacts assessed by performance-engineer
- Security changes reviewed by security-auditor

4.2 User Communication Strategy

- Real-time: Critical decisions and blockers
- Milestone-based: Major phase completions
- Exception-driven: Alternative approaches or issues
- Summary-based: Long-running workflow progress

Specialized Subagent Usage Patterns

Always Use These Subagents Proactively:

• general-purpose: For codebase analysis, research, and complex multi-step tasks
• Available specialist agents based on task requirements (see full list below)

Available MCP Server Integration:

• nx-mcp: nx_workspace, nx_project_details, nx_run_generator, nx_visualize_graph, etc.
• angular-mcp: list_projects, search_documentation
• context7: resolve-library-id, get-library-docs for latest package documentation

Project-Relevant Subagent Types:

Tier 1 - Essential (Most Frequently Needed):

• frontend-developer: Angular 20.1.2 feature development, standalone components, domain library implementation
• typescript-pro: Advanced TypeScript 5.8.3 patterns, type system optimization, interface design
• test-automator: Jest→Vitest migration, Spectator→Angular Testing Utilities, unit testing, E2E attributes
• ui-ux-designer: Tailwind CSS design system, UI component libraries, responsive design

Tier 2 - Important (Regularly Needed):

• code-reviewer: ESLint compliance, Angular best practices, code quality validation
• performance-engineer: Angular optimization, bundle analysis, NgRx performance patterns
• api-documenter: Swagger/OpenAPI integration, API client documentation
• docs-architect: Technical documentation, architecture guides, CLAUDE.md maintenance

Tier 3 - Specialized (Domain-Specific):

• architect-review: Nx monorepo architecture, domain-driven design validation
• frontend-security-coder: Angular security patterns, XSS prevention, authentication flows
• deployment-engineer: Angular build pipelines, Nx CI/CD, npm script automation
• debugger: Error analysis, RxJS debugging, state management troubleshooting

Cross-Cutting Support:

• general-purpose: Complex analysis, codebase research, multi-domain investigations
• error-detective: Production issue investigation, log analysis, performance bottlenecks

Escalation and Error Handling

Immediate Escalation Triggers:

• Subagent cannot access required files or resources
• Conflicting requirements between parallel tasks
• Security vulnerabilities discovered
• Breaking changes with no compatibility path

Recovery Hierarchy:

1. Subagent self-resolution (retry with different approach)
2. Alternative subagent assignment (different specialist)
3. Task redecomposition (break down further)
4. User consultation (clarification or decision needed)

Example Workflow: "Add Dark Mode Feature"

1. ANALYSIS PHASE:
   Task(general-purpose, "Research Angular/Tailwind dark mode patterns and analyze ISA theme system")

2. PLANNING PHASE:
   Task(ui-ux-designer, "Design dark mode integration with ISA color system and Tailwind classes")
   Task(frontend-developer, "Plan component modifications and theme service architecture")

3. IMPLEMENTATION PHASE (can run in parallel):
   Task(frontend-developer, "Implement Angular theme service and component modifications")
   Task(typescript-pro, "Create TypeScript interfaces and type-safe theme system")
   Task(test-automator, "Create Jest/Vitest tests with E2E attributes for theme functionality")

4. VALIDATION PHASE:
   Task(code-reviewer, "Review Angular patterns, NgRx integration, and code quality")
   Task(performance-engineer, "Assess bundle size impact and runtime performance")

5. INTEGRATION PHASE:
   Task(test-automator, "Run full Nx test suite and validate E2E attributes")
   Task(docs-architect, "Update Storybook documentation and component usage guides")

MCP Server Integration Workflow: "Integrate New Angular Library"

1. RESEARCH PHASE:
   - Use mcp__context7__resolve-library-id to find the library
   - Use mcp__context7__get-library-docs to understand APIs
   - Use mcp__angular-mcp__search_documentation for Angular integration patterns

2. PROJECT SETUP:
   - Use mcp__nx-mcp__nx_generators to find appropriate generators
   - Use mcp__nx-mcp__nx_run_generator to scaffold integration components
   - Use mcp__nx-mcp__nx_project_details to understand impact scope

3. IMPLEMENTATION WITH SUBAGENTS:
   Task(typescript-pro, "Create TypeScript interfaces for library integration")
   Task(frontend-developer, "Implement Angular service wrapping the library")
   Task(test-automator, "Create unit and integration tests")

4. VALIDATION:
   - Use mcp__nx-mcp__nx_visualize_graph to verify dependency relationships
   - Use mcp__nx-mcp__nx_current_running_tasks_details to monitor builds
   Task(code-reviewer, "Review integration patterns and code quality")

This comprehensive workflow leverages ALL available MCP servers and specialized subagents for maximum efficiency, with each agent handling both analysis AND implementation tasks according to their expertise.