From c7fc8d8661f1ba7a148d1e2a9bb6fbc3d73878f6 Mon Sep 17 00:00:00 2001 From: Lorenz Hilpert Date: Wed, 29 Oct 2025 13:37:56 +0100 Subject: [PATCH] =?UTF-8?q?=F0=9F=9A=9A=20refactor(skills):=20rename=20tai?= =?UTF-8?q?lwind-isa=20skill=20to=20tailwind?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename skill directory from tailwind-isa to tailwind - Update skill name in frontmatter metadata - Update all references in CLAUDE.md (2 locations) Simplifies naming while maintaining clear purpose. The skill provides Tailwind CSS utilities and design system guidance for the ISA project. --- .../{tailwind-isa => tailwind}/SKILL.md | 2 +- .../references/design-system.md | 0 CLAUDE.md | 395 ++---------------- 3 files changed, 25 insertions(+), 372 deletions(-) rename .claude/skills/{tailwind-isa => tailwind}/SKILL.md (99%) rename .claude/skills/{tailwind-isa => tailwind}/references/design-system.md (100%) diff --git a/.claude/skills/tailwind-isa/SKILL.md b/.claude/skills/tailwind/SKILL.md similarity index 99% rename from .claude/skills/tailwind-isa/SKILL.md rename to .claude/skills/tailwind/SKILL.md index 4012e5197..45679e195 100644 --- a/.claude/skills/tailwind-isa/SKILL.md +++ b/.claude/skills/tailwind/SKILL.md @@ -1,5 +1,5 @@ --- -name: tailwind-isa +name: tailwind description: This skill should be used when working with Tailwind CSS styling in the ISA-Frontend project. Use it when writing component styles, choosing color values, applying typography, creating buttons, or determining appropriate spacing and layout utilities. Essential for maintaining design system consistency. --- diff --git a/.claude/skills/tailwind-isa/references/design-system.md b/.claude/skills/tailwind/references/design-system.md similarity index 100% rename from .claude/skills/tailwind-isa/references/design-system.md rename to .claude/skills/tailwind/references/design-system.md diff --git a/CLAUDE.md b/CLAUDE.md index 9907371df..3811c02b3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,10 +1,6 @@ # CLAUDE.md -> **Last Updated:** 2025-10-29 -> **Angular Version:** 20.1.2 -> **Nx Version:** 21.3.2 -> **Node.js:** ≥22.0.0 -> **npm:** ≥10.0.0 +This file contains meta-instructions for how Claude should work with the ISA-Frontend codebase. ## 🔴 CRITICAL: Mandatory Agent Usage @@ -12,7 +8,7 @@ - **`docs-researcher`**: For ALL documentation (packages, libraries, READMEs) - **`docs-researcher-advanced`**: Auto-escalate when docs-researcher fails - **`Explore`**: For ALL code pattern searches and multi-file analysis -- **`context-manager`**: For complex projects and knowledge preservation with **persistent memory** (NEW) +- **`context-manager`**: For complex projects and knowledge preservation with **persistent memory** - **Direct tools (Read/Bash)**: ONLY for single specific files or commands **NEW**: The `context-manager` now autonomously stores project knowledge (decisions, patterns, solutions) in persistent memory for cross-session learning. @@ -28,262 +24,11 @@ - Use bullet points and structured formatting for clarity - Only provide detailed explanations when complexity requires it -## 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**: 17 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 - -### Essential Commands (Project-Specific) -```bash -# Start development server with SSL (required for authentication flows) -npm start - -# Run tests for all libraries (excludes main app) -npm test - -# Build for development -npm run build - -# Build for production -npm run build-prod - -# Regenerate all API clients from Swagger/OpenAPI specs -npm run generate:swagger - -# Regenerate library reference documentation -npm run docs:generate - -# Format code with Prettier -npm run prettier - -# Format only staged files (pre-commit hook) -npm run pretty-quick - -# Run CI tests with coverage -npm run ci -``` - -### Standard Nx Commands -For complete command reference, see [Nx Documentation](https://nx.dev/reference/commands). - -**Common patterns:** -```bash -# Test specific library (always use --skip-nx-cache) -npx nx test --skip-nx-cache - -# Lint a project -npx nx lint - -# Show project dependencies -npx nx graph - -# Run tests for affected projects (CI/CD) -npx nx affected:test --skip-nx-cache -``` - -**Important:** Always use `--skip-nx-cache` flag when running tests to ensure fresh results. - -## Testing Framework - -> **Last Reviewed:** 2025-10-22 -> **Status:** Migration in Progress (Jest → Vitest) - -### Current Setup (Migration in Progress) -- **Jest**: 40 libraries (65.6% - legacy/existing code) -- **Vitest**: 21 libraries (34.4% - new standard) -- All formal libraries now have test executors configured - -### Testing Strategy -- **New libraries**: Use Vitest + Angular Testing Utilities (TestBed, ComponentFixture) -- **Legacy libraries**: Continue with Jest + Spectator until migrated -- **Advanced mocking**: Use ng-mocks for complex scenarios - -### Key Requirements -- Test files must end with `.spec.ts` -- Use AAA pattern (Arrange-Act-Assert) -- **Always include E2E attributes**: `data-what`, `data-which`, and dynamic `data-*` in HTML templates -- Mock external dependencies appropriately for your framework - -**For detailed testing guidelines, framework comparison, and migration instructions, see [`docs/guidelines/testing.md`](docs/guidelines/testing.md).** - -**References:** -- [Jest Documentation](https://jestjs.io/) -- [Vitest Documentation](https://vitest.dev/) -- [Angular Testing Guide](https://angular.io/guide/testing) -- [Spectator](https://ngneat.github.io/spectator/) - -## 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 -- **Framework**: [Tailwind CSS](https://tailwindcss.com/docs) with extensive ISA-specific customization -- **Custom Breakpoints**: `isa-desktop` (1024px), `isa-desktop-l` (1440px), `isa-desktop-xl` (1920px) -- **Brand Color System**: `isa-*` color palette with semantic naming -- **Custom Tailwind Plugins** (7): button, typography, menu, label, input, section, select-bullet -- **Typography System**: 14 custom utilities (`.isa-text-heading-1-bold`, `.isa-text-body-2-regular`, etc.) -- **UI Component Libraries**: 17 specialized libraries with consistent APIs (see Library Reference) -- **Storybook**: Component documentation and development at `npm run storybook` - -### Responsive Design with Breakpoint Service -Use `@isa/ui/layout` for reactive breakpoint detection instead of CSS-only solutions: - -```typescript -import { breakpoint, Breakpoint } from '@isa/ui/layout'; - -// Detect screen size reactively -isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.DekstopXL]); -``` - -**Available Breakpoints:** -- `Tablet`: max-width: 1279px (mobile/tablet) -- `Desktop`: 1280px - 1439px (standard desktop) -- `DekstopL`: 1440px - 1919px (large desktop) -- `DekstopXL`: 1920px+ (extra large) - -**Template Usage:** -```html -@if (isDesktop) { - -} -``` - -**Why:** Prefer breakpoint service over CSS-only (hidden/flex) for SSR and maintainability. - -## API Integration and Data Access - -**Generated Swagger Clients:** 10 auto-generated TypeScript clients 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 -- Tool: [ng-swagger-gen](https://www.npmjs.com/package/ng-swagger-gen) with custom per-API configuration -- Post-processing: Automatic Unicode cleanup via `tools/fix-files.js` -- Regenerate: `npm run generate:swagger` - -**Architecture Pattern:** -- Business logic services wrap generated API clients -- Type safety: TypeScript + [Zod](https://zod.dev/) schema validation -- Error handling: Global HTTP interceptor with automatic re-authentication -- Modern injection: Uses `inject()` function with private field pattern -- Request cancellation: Built-in via AbortSignal and custom RxJS operators (`takeUntilAborted()`, `takeUntilKeydown()`) - -**Data Access Libraries:** See Library Reference section for domain-specific implementations (`@isa/[domain]/data-access`). - -## Build Configuration -- **Framework**: Angular with TypeScript (see `package.json` for current versions) -- **Requirements**: - - Node.js >= 22.0.0 (specified in package.json engines) - - npm >= 10.0.0 (specified in package.json engines) -- **Build System**: Nx monorepo with Vite for testing (Vitest) -- **Development Server**: Serves with SSL by default (required for authentication flows) - -## 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 - -### Project Conventions -- **Default Branch**: `develop` (not main) - Always create PRs against develop -- **Branch Naming**: When starting work on a new feature or bug, create a branch following this pattern: - - Format: `feature/{task-id}-{short-description}` or `bugfix/{task-id}-{short-description}` - - Use English kebab-case for the description - - Start with the task/issue ID (e.g., `5391`) - - Keep description concise - shorten if the full title is too long - - Example: For task "#5391 Prämie Checkout // Action Card - Versandbestellung" - - Branch: `feature/5391-praemie-checkout-action-card-delivery-order` -- **Commit Style**: [Conventional commits](https://www.conventionalcommits.org/) without co-author tags -- **Nx Cache**: Always use `--skip-nx-cache` for tests to ensure fresh results -- **Testing**: New libraries use Vitest + Angular Testing Utilities; legacy use Jest + Spectator -- **E2E Attributes**: Always include `data-what`, `data-which`, and dynamic `data-*` in templates -- **Design System**: Use ISA-specific Tailwind utilities (`isa-accent-*`, `isa-text-*`) - -### Code Quality Tools -- **Linting**: [ESLint](https://eslint.org/) with Nx dependency checks -- **Formatting**: [Prettier](https://prettier.io/) with Husky + lint-staged pre-commit hooks -- **Type Safety**: [TypeScript](https://www.typescriptlang.org/) strict mode + [Zod](https://zod.dev/) validation -- **Bundle Size**: Monitor carefully (2MB warning, 5MB error for main bundle) - -### Nx Workflow Tips -- Use `npx nx graph` to visualize dependencies -- Use `npx nx affected:test` for CI/CD optimization -- Reference: [Nx Documentation](https://nx.dev/getting-started/intro) - -## 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 - -### Researching and Investigating the Codebase +## Researching and Investigating the Codebase **🔴 MANDATORY: You MUST use subagents for research. Direct file reading/searching is FORBIDDEN except for single specific files.** -#### Required Agent Usage +### Required Agent Usage | Task Type | Required Agent | Escalation Path | |-----------|---------------|-----------------| @@ -293,7 +38,7 @@ isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.Deks | **Implementation Analysis** | `Explore` | Multiple file analysis | | **Single Specific File** | Read tool directly | No agent needed | -#### Documentation Research System (Two-Tier) +### Documentation Research System (Two-Tier) 1. **ALWAYS start with `docs-researcher`** (Haiku, 30-120s) for any documentation need 2. **Auto-escalate to `docs-researcher-advanced`** (Sonnet, 2-7min) when: @@ -302,7 +47,7 @@ isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.Deks - Need code inference - Complex architectural questions -#### Enforcement Examples +### Enforcement Examples ``` ❌ WRONG: Read libs/ui/buttons/README.md @@ -317,127 +62,35 @@ isDesktop = breakpoint([Breakpoint.Desktop, Breakpoint.DekstopL, Breakpoint.Deks **Remember: Using subagents is NOT optional - it's mandatory for maintaining context efficiency and search quality.** -#### Common Research Patterns +## Project Knowledge Management with Context-Manager -| Information Need | Required Approach | -|-----------------|-------------------| -| **Library documentation** | `docs-researcher` → Check library-reference.md → Escalate if needed | -| **Code patterns/examples** | `Explore` with "medium" or "very thorough" | -| **Architecture understanding** | `npx nx graph` + `Explore` for implementation | -| **Debugging/errors** | Direct tool use (Read specific error file, check console) | +**NEW CAPABILITY**: The `context-manager` subagent has **persistent memory** that autonomously stores and retrieves project knowledge across sessions. -#### Debugging Tips -- **TypeScript errors**: Follow error path to exact file:line -- **Test failures**: Use `--skip-nx-cache` for fresh output -- **Module resolution**: Check `tsconfig.base.json` path aliases -- **State issues**: Use Angular DevTools browser extension +### What Gets Stored Automatically -### Project Knowledge Management with Context-Manager +- **Assigned Tasks**: User-assigned tasks with context ("Remember to look up X because of Y"), TODO items, status tracking +- **Architectural Decisions**: State management patterns, API integration approaches, component architecture choices +- **Reusable Patterns**: Code conventions, testing patterns, error handling approaches +- **Integration Points**: API contracts, data flows, module boundaries +- **Domain Knowledge**: Business workflows, business rules, user roles/permissions +- **Technical Solutions**: Bug fixes with root causes, performance optimizations -**NEW CAPABILITY**: The `context-manager` subagent now has **persistent memory** that autonomously stores and retrieves project knowledge across sessions. - -#### Autonomous Knowledge Storage - -The context-manager **automatically stores** the following without being explicitly asked: - -| Information Type | What Gets Stored | -|------------------|-----------------| -| **Assigned Tasks** (NEW) | User-assigned tasks with context ("Remember to look up X because of Y"), TODO items, investigation requests, status tracking | -| **Architectural Decisions** | State management patterns, API integration approaches, component architecture choices | -| **Reusable Patterns** | Code conventions, testing patterns, error handling approaches | -| **Integration Points** | API contracts, data flows, module boundaries, third-party integrations | -| **Domain Knowledge** | Business workflows (returns, checkout), business rules, user roles/permissions | -| **Technical Solutions** | Bug fixes with root causes, performance optimizations, configuration solutions | - -**Task Assignment Examples:** -- "Remember to look up the pricing calculation function because pricing seems off" -- "TODO: investigate why the checkout flow breaks on mobile" -- "Don't forget to check the API response format for the new endpoint" - -These get stored with full context, related code locations, and status tracking. - -#### How It Works - -1. **Task Capture**: Listens for phrases like "Remember to...", "TODO:", "Don't forget...", "Investigate..." and immediately stores them with full context -2. **Automatic Storage**: As the context-manager works, it proactively stores important discoveries in persistent memory using MCP tools -3. **Knowledge Retrieval**: Before starting new work, it queries stored knowledge to provide informed recommendations -4. **Task Reminders**: At session start, proactively reminds you of pending/incomplete tasks from previous sessions -5. **Knowledge Graph**: Entities are linked together (e.g., task → relates_to → decision), building a comprehensive understanding -6. **Status Tracking**: Updates task status automatically (pending → in-progress → completed) -7. **Cross-Session Persistence**: Information persists across Claude Code sessions for true institutional knowledge - -#### When to Use Context-Manager +### When to Use Context-Manager Use the `context-manager` subagent PROACTIVELY for: - **Task Management**: Assigning tasks for later ("Remember to investigate X because of Y") - **Session Continuity**: Starting a new session (it will remind you of pending tasks) - Complex, multi-step projects requiring coordination - Long-running tasks that span multiple sessions -- When you need to preserve architectural context +- Preserving architectural context - Learning about resolved issues and their solutions -- Understanding domain-specific business logic -- **Task Status Queries**: "What was I working on?" or "What tasks are pending?" -#### Memory Entity Types +### How It Works -The system stores seven entity types: -- `task`: User-assigned tasks, reminders, TODOs with context and status (NEW) -- `decision`: Architectural and design decisions with rationale -- `pattern`: Reusable code patterns and conventions -- `integration`: API contracts and integration points -- `solution`: Resolved issues with root cause and fix -- `convention`: Coding standards and project conventions -- `domain-knowledge`: Business logic and workflow explanations +1. **Task Capture**: Listens for "Remember to...", "TODO:", "Don't forget...", stores them with full context +2. **Automatic Storage**: Proactively stores important discoveries in persistent memory +3. **Knowledge Retrieval**: Queries stored knowledge before starting new work +4. **Task Reminders**: Proactively reminds you of pending/incomplete tasks at session start +5. **Cross-Session Persistence**: Information persists across Claude Code sessions -**Task Status Values**: `pending`, `in-progress`, `blocked`, `completed`, `cancelled` - -**Benefits**: -- Eliminates context loss between sessions -- Never forget assigned tasks or TODOs -- Maintains project knowledge -- Accelerates onboarding -- Ensures consistency -- Provides task continuity across sessions - -### Library Development Patterns -- **Library Documentation**: Use `docs-researcher` for ALL library READMEs (mandatory for context management) -- **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 NgModules -- **Testing Framework**: New = Vitest + Angular Testing Utilities, Legacy = Jest + Spectator -- **Path Aliases**: Always use `@isa/[domain]/[layer]/[feature]` - avoid relative imports - -#### Library Reference Guide - -The monorepo contains **62 libraries** organized across 12 domains. For quick lookup, see **[`docs/library-reference.md`](docs/library-reference.md)**. - -**Quick Overview by Domain:** -- Availability (1) | Catalogue (1) | Checkout (6) | Common (3) | Core (5) | CRM (1) | Icons (1) -- OMS (9) | Remission (8) | Shared Components (7) | UI Components (17) | Utilities (3) - -### 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 --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 +**Benefits**: Eliminates context loss, maintains project knowledge, provides task continuity across sessions.