(null);
+
+ // ========================================
+ // STORE OBSERVABLES (READ)
+ // ========================================
+
+ // Read observable values from store
+ const storeValue = store.someObservable;
+ const anotherValue = store.anotherObservable;
+
+ // ========================================
+ // INITIALIZATION
+ // ========================================
+
+ useEffect(() => {
+ const initialize = async () => {
+ try {
+ setIsLoading(true);
+ setError(null);
+
+ // Fetch initial data from SDK (if needed)
+ // const result = await store.cc.someMethod(params);
+ // setData(result);
+
+ } catch (err) {
+ const error = err as Error;
+ setError(error);
+ props.onError?.(error);
+ } finally {
+ setIsLoading(false);
+ }
+ };
+
+ initialize();
+
+ // Cleanup
+ return () => {
+ // Unsubscribe from events
+ // Clear timers
+ // Cancel pending requests
+ };
+ }, []); // Add dependencies as needed
+
+ // ========================================
+ // EVENT HANDLERS
+ // ========================================
+
+ /**
+ * Handles primary action
+ */
+ const handleAction = useCallback(async (param: string) => {
+ try {
+ // Call SDK method
+ // const result = await store.cc.someAction(param);
+
+ // Update store (if needed)
+ runInAction(() => {
+ // store.setSomeValue(newValue);
+ });
+
+ // Call callback
+ props.onSomeEvent?.({
+ id: 'id',
+ value: param,
+ timestamp: Date.now(),
+ });
+
+ } catch (err) {
+ const error = err as Error;
+ setError(error);
+ props.onError?.(error);
+ }
+ }, [props]);
+
+ /**
+ * Handles secondary action
+ */
+ const handleSecondaryAction = useCallback(() => {
+ // Implementation
+ }, []);
+
+ // ========================================
+ // RETURN API
+ // ========================================
+
+ return {
+ // State
+ data,
+ isLoading,
+ error,
+ storeValue,
+
+ // Handlers
+ handleAction,
+ handleSecondaryAction,
+ };
+}
+```
+
+**Pattern Notes:**
+- Use `useCallback` for handlers to prevent re-renders
+- Use `runInAction` for store mutations
+- Handle errors and call `onError` callback
+- Clean up subscriptions in useEffect return
+- Document all returned values
+
+---
+
+## Step 3: Widget Component
+
+**File:** `src/{widget-name}/index.tsx`
+
+```typescript
+import React from 'react';
+import { observer } from 'mobx-react-lite';
+import { ErrorBoundary } from 'react-error-boundary';
+import { use{WidgetName} } from '../helper';
+import { {WidgetName}Component } from '@webex/cc-components';
+import type { {WidgetName}Props } from './{widget-name}.types';
+
+/**
+ * Internal widget component (with observer HOC)
+ * This is the smart/container component
+ */
+const {WidgetName}Internal: React.FC<{WidgetName}Props> = observer((props) => {
+ const {
+ className = '',
+ customStyles,
+ ...restProps
+ } = props;
+
+ // Use custom hook for business logic
+ const {
+ data,
+ isLoading,
+ error,
+ storeValue,
+ handleAction,
+ handleSecondaryAction,
+ } = use{WidgetName}(props);
+
+ // Handle error state
+ if (error) {
+ return (
+
+
+ Error: {error.message}
+
+
+ Something went wrong. Please try again.
+
+
+ }
+ onError={(error, errorInfo) => {
+ console.error('{WidgetName} Error:', error, errorInfo);
+ props.onError?.(error);
+ }}
+ >
+ <{WidgetName}Internal {...props} />
+
+);
+
+// Display name for debugging
+{WidgetName}.displayName = '{WidgetName}';
+
+export { {WidgetName} };
+export type { {WidgetName}Props };
+```
+
+**Pattern Notes:**
+- MUST use `observer` HOC for MobX reactivity
+- MUST wrap with `ErrorBoundary`
+- Handle loading and error states
+- Pass only processed data to presentational component
+- Set display names for debugging
+
+---
+
+## Step 4: Package Exports
+
+**File:** `src/index.ts`
+
+```typescript
+import { {WidgetName} } from './{widget-name}';
+import { withMetrics } from '@webex/cc-ui-logging';
+
+/**
+ * {WidgetName} wrapped with metrics tracking
+ * Automatically logs:
+ * - WIDGET_MOUNTED
+ * - WIDGET_UNMOUNTED
+ * - Errors (if onError not handled)
+ */
+const {WidgetName}WithMetrics = withMetrics({WidgetName}, '{WidgetName}');
+
+// Export with metrics wrapper
+export { {WidgetName}WithMetrics as {WidgetName} };
+
+// Export types
+export type { {WidgetName}Props } from './{widget-name}/{widget-name}.types';
+```
+
+**Pattern Notes:**
+- ALWAYS wrap with `withMetrics` HOC
+- Export wrapped version as default
+- Export types separately
+
+---
+
+## Step 5: Web Component Export
+
+**File:** `src/wc.ts`
+
+```typescript
+import { {WidgetName} } from './{widget-name}';
+
+/**
+ * Export unwrapped component for r2wc conversion
+ * The metrics wrapper interferes with r2wc, so we export clean component
+ */
+export { {WidgetName} };
+```
+
+**Pattern Notes:**
+- Export WITHOUT metrics wrapper
+- r2wc wrapping happens in cc-widgets
+- Keep minimal - just re-export
+
+---
+
+## Step 6: Package Configuration
+
+### package.json
+
+**File:** `package.json`
+
+```json
+{
+ "name": "@webex/cc-{widget-name}",
+ "description": "Webex Contact Center Widgets: {Widget Display Name}",
+ "license": "Cisco's General Terms (https://www.cisco.com/site/us/en/about/legal/contract-experience/index.html)",
+ "version": "1.28.0-ccwidgets.124",
+ "main": "dist/index.js",
+ "types": "dist/types/index.d.ts",
+ "publishConfig": {
+ "access": "public"
+ },
+ "files": [
+ "dist/",
+ "package.json"
+ ],
+ "scripts": {
+ "clean": "rm -rf dist && rm -rf node_modules",
+ "clean:dist": "rm -rf dist",
+ "build": "yarn run -T tsc",
+ "build:src": "yarn run clean:dist && webpack",
+ "build:watch": "webpack --watch",
+ "test:unit": "tsc --project tsconfig.test.json && jest --coverage",
+ "test:styles": "eslint"
+ },
+ "dependencies": {
+ "@webex/cc-components": "workspace:*",
+ "@webex/cc-store": "workspace:*",
+ "mobx-react-lite": "^4.1.0",
+ "react-error-boundary": "^6.0.0"
+ },
+ "devDependencies": {
+ "@babel/core": "7.25.2",
+ "@babel/preset-env": "7.25.4",
+ "@babel/preset-react": "7.24.7",
+ "@babel/preset-typescript": "7.25.9",
+ "@eslint/js": "^9.20.0",
+ "@testing-library/dom": "10.4.0",
+ "@testing-library/jest-dom": "6.6.2",
+ "@testing-library/react": "16.0.1",
+ "@types/jest": "29.5.14",
+ "@types/node": "^22.13.13",
+ "@webex/test-fixtures": "workspace:*",
+ "babel-jest": "29.7.0",
+ "babel-loader": "9.2.1",
+ "eslint": "^9.20.1",
+ "jest": "29.7.0",
+ "jest-environment-jsdom": "29.7.0",
+ "typescript": "5.6.3",
+ "webpack": "5.94.0",
+ "webpack-cli": "5.1.4"
+ },
+ "peerDependencies": {
+ "@momentum-ui/react-collaboration": ">=26.201.9",
+ "react": ">=18.3.1",
+ "react-dom": ">=18.3.1"
+ }
+}
+```
+
+---
+
+### Configuration Files
+
+**Copy these from station-login without modification:**
+
+1. **tsconfig.json** - TypeScript configuration
+2. **tsconfig.test.json** - TypeScript test configuration
+3. **webpack.config.js** - Webpack bundling
+4. **babel.config.js** - Babel transpilation
+5. **eslint.config.mjs** - ESLint rules
+
+**Command to copy:**
+```bash
+# From project root
+cp packages/contact-center/station-login/tsconfig.json packages/contact-center/{widget-name}/
+cp packages/contact-center/station-login/tsconfig.test.json packages/contact-center/{widget-name}/
+cp packages/contact-center/station-login/webpack.config.js packages/contact-center/{widget-name}/
+cp packages/contact-center/station-login/babel.config.js packages/contact-center/{widget-name}/
+cp packages/contact-center/station-login/eslint.config.mjs packages/contact-center/{widget-name}/
+```
+
+---
+
+## Code Quality Checklist
+
+Before proceeding to next module, verify:
+
+### Architecture
+- [ ] Widget → Hook → Component layer separation maintained
+- [ ] No layer violations (Widget doesn't call SDK directly)
+- [ ] Component doesn't access store directly
+
+### MobX Integration
+- [ ] Widget wrapped with `observer` HOC
+- [ ] Store mutations use `runInAction`
+- [ ] No reactions created in render
+
+### Error Handling
+- [ ] ErrorBoundary wraps widget
+- [ ] Try-catch in async operations
+- [ ] onError callback called on errors
+- [ ] Error states displayed to user
+
+### TypeScript
+- [ ] All types exported
+- [ ] Props interface documented with JSDoc
+- [ ] No `any` types (use proper types)
+- [ ] Optional props marked with `?`
+
+### React Best Practices
+- [ ] useCallback for handlers
+- [ ] useEffect cleanup functions
+- [ ] Display names set
+- [ ] Loading states handled
+- [ ] Error states handled
+
+### Metrics
+- [ ] Widget wrapped with `withMetrics` in index.ts
+- [ ] NOT wrapped in wc.ts (for r2wc compatibility)
+
+---
+
+## Next Steps
+
+**After code generation complete:**
+
+1. **If new components needed:**
+ - Go to: 03-component-generation.md
+
+2. **If using existing components:**
+ - Skip to: 04-integration.md
+
+3. **Always required:**
+ - 04-integration.md
+ - 05-test-generation.md
+ - ../documentation/create-agent-md.md
+ - ../documentation/create-architecture-md.md
+ - 06-validation.md
+
+---
+
+## Reference Widgets
+
+**For patterns and examples, see:**
+- Simple: `packages/contact-center/station-login/`
+- Medium: `packages/contact-center/user-state/`
+- Complex: `packages/contact-center/task/`
+
+---
+
+_Template Version: 1.0.0_
+_Last Updated: 2025-11-26_
+
diff --git a/ai-docs/templates/new-widget/03-component-generation.md b/ai-docs/templates/new-widget/03-component-generation.md
new file mode 100644
index 000000000..38454e456
--- /dev/null
+++ b/ai-docs/templates/new-widget/03-component-generation.md
@@ -0,0 +1,552 @@
+# Component Generation Module
+
+## Overview
+
+This module guides you through creating new presentational components in the cc-components library.
+
+**⚠️ Only use this module if:** Pre-questions indicated new components are needed
+
+**Purpose:** Generate pure presentational components
+
+**Location:** `packages/contact-center/cc-components/`
+
+---
+
+## When to Create New Components
+
+**Create new component when:**
+- Widget needs UI that doesn't exist in cc-components
+- Reusable UI pattern that other widgets might use
+- Complex UI that should be tested in isolation
+
+**Use existing component when:**
+- Similar component already exists
+- Component can be customized via props
+- Minor styling changes only
+
+---
+
+## Component Directory Structure
+
+Create in `packages/contact-center/cc-components/src/components/{ComponentName}/`:
+
+```
+{ComponentName}/
+├── {component-name}.tsx # Component implementation
+├── {component-name}.types.ts # TypeScript interfaces
+├── {component-name}.scss # Styles (optional)
+├── {component-name}.utils.ts # Helper functions (optional)
+└── constants.ts # Constants (optional)
+```
+
+---
+
+## Step 1: Component Types
+
+**File:** `src/components/{ComponentName}/{component-name}.types.ts`
+
+```typescript
+import { CSSProperties } from 'react';
+
+/**
+ * Props for {ComponentName} component
+ */
+export interface {ComponentName}Props {
+ // ========================================
+ // DATA PROPS
+ // ========================================
+
+ /**
+ * Main data to display
+ */
+ data: SomeDataType;
+
+ /**
+ * Additional data (optional)
+ */
+ metadata?: MetadataType;
+
+ // ========================================
+ // BEHAVIOR PROPS
+ // ========================================
+
+ /**
+ * Callback when user interacts
+ * @param data - Interaction data
+ */
+ onAction?: (data: ActionData) => void;
+
+ /**
+ * Callback on error
+ * @param error - Error object
+ */
+ onError?: (error: Error) => void;
+
+ // ========================================
+ // STYLING PROPS
+ // ========================================
+
+ /**
+ * Custom CSS class
+ */
+ className?: string;
+
+ /**
+ * Custom inline styles
+ */
+ customStyles?: CSSProperties;
+
+ /**
+ * Disable the component
+ * @default false
+ */
+ disabled?: boolean;
+
+ /**
+ * Loading state
+ * @default false
+ */
+ isLoading?: boolean;
+}
+
+/**
+ * Supporting types
+ */
+export interface SomeDataType {
+ id: string;
+ name: string;
+ value: string;
+}
+
+export interface ActionData {
+ id: string;
+ action: string;
+ timestamp: number;
+}
+```
+
+---
+
+## Step 2: Component Implementation
+
+**File:** `src/components/{ComponentName}/{component-name}.tsx`
+
+```typescript
+import React from 'react';
+import { Button, Icon, Input, Text } from '@momentum-design/components/dist/react';
+import type { {ComponentName}Props } from './{component-name}.types';
+import './{component-name}.scss';
+
+/**
+ * {ComponentName} - Pure presentational component
+ *
+ * @param props - Component props
+ * @returns Rendered component
+ */
+export const {ComponentName}: React.FC<{ComponentName}Props> = (props) => {
+ const {
+ data,
+ metadata,
+ onAction,
+ onError,
+ className = '',
+ customStyles,
+ disabled = false,
+ isLoading = false,
+ } = props;
+
+ // ========================================
+ // EVENT HANDLERS (LOCAL ONLY)
+ // ========================================
+
+ const handleClick = () => {
+ if (disabled) return;
+
+ try {
+ onAction?.({
+ id: data.id,
+ action: 'clicked',
+ timestamp: Date.now(),
+ });
+ } catch (error) {
+ onError?.(error as Error);
+ }
+ };
+
+ // ========================================
+ // RENDER
+ // ========================================
+
+ // Handle loading state
+ if (isLoading) {
+ return (
+
+ );
+ }
+
+ // Handle no data
+ if (!data) {
+ return (
+
+ );
+ }
+
+ // Main render
+ return (
+
+
+ {data.name}
+
+
+
+
{data.value}
+
+ {metadata && (
+
+ {metadata.info}
+
+ )}
+
+
+
+
+
+
+
Select Widgets to Display
+
+ {/* Existing widgets */}
+
+
+ {/* NEW: Add checkbox */}
+
+
+```
+
+### 3.5 Add Widget Rendering
+
+```jsx
+{/* NEW: {Widget Display Name} Widget */}
+{selectedWidgets.{widgetName} && (
+
+
+
+
+
+)}
+```
+
+**Complete example section:**
+```jsx
+return (
+
+ {/* Widget Selector */}
+
+
+
+
+
+
+ {/* Widgets */}
+ {selectedWidgets.stationLogin && (
+
+
+
+ )}
+
+ {selectedWidgets.{widgetName} && (
+
+
+
+
+
+ )}
+
+
Select Widgets to Display
+
+
+
+
+
+
+`;
+```
+
+### 4.3 Add Widget Creation Function
+
+```javascript
+/**
+ * Create {Widget Display Name} widget
+ */
+function create{WidgetName}Widget() {
+ // Create element
+ {widgetName}Widget = document.createElement('widget-cc-{widget-name}');
+
+ // Set properties
+ {widgetName}Widget.requiredProp = 'test-value';
+ {widgetName}Widget.optionalConfig = {
+ option1: 'value',
+ option2: 10
+ };
+
+ // Add event listeners
+ {widgetName}Widget.addEventListener('someEvent', (event) => {
+ console.log('{WidgetName} event:', event.detail);
+ // Handle event
+ });
+
+ {widgetName}Widget.addEventListener('error', (event) => {
+ console.error('{WidgetName} error:', event.detail);
+ // Handle error
+ });
+
+ // Append to container
+ const container = document.getElementById('widgets-container');
+ const wrapper = document.createElement('div');
+ wrapper.className = 'widget-box';
+ wrapper.id = '{widget-name}-container';
+
+ const legend = document.createElement('h3');
+ legend.textContent = '{Widget Display Name}';
+ wrapper.appendChild(legend);
+
+ wrapper.appendChild({widgetName}Widget);
+ container.appendChild(wrapper);
+
+ console.log('{WidgetName} widget created');
+}
+
+/**
+ * Remove {Widget Display Name} widget
+ */
+function remove{WidgetName}Widget() {
+ if ({widgetName}Widget) {
+ const container = document.getElementById('{widget-name}-container');
+ if (container) {
+ container.remove();
+ }
+ {widgetName}Widget = null;
+ console.log('{WidgetName} widget removed');
+ }
+}
+```
+
+### 4.4 Add Toggle Handler
+
+```javascript
+// Add event listener for toggle
+document.getElementById('toggle-{widget-name}')?.addEventListener('change', (event) => {
+ if (event.target.checked) {
+ create{WidgetName}Widget();
+ } else {
+ remove{WidgetName}Widget();
+ }
+});
+```
+
+**Complete example:**
+```javascript
+// Widget references
+let stationLoginWidget = null;
+let {widgetName}Widget = null;
+
+// Initialize function
+function initializeApp() {
+ // Setup widget toggles
+ document.getElementById('toggle-station-login')?.addEventListener('change', (e) => {
+ if (e.target.checked) {
+ createStationLoginWidget();
+ } else {
+ removeStationLoginWidget();
+ }
+ });
+
+ // NEW: {Widget Display Name} toggle
+ document.getElementById('toggle-{widget-name}')?.addEventListener('change', (e) => {
+ if (e.target.checked) {
+ create{WidgetName}Widget();
+ } else {
+ remove{WidgetName}Widget();
+ }
+ });
+}
+
+// NEW: Widget functions
+function create{WidgetName}Widget() {
+ {widgetName}Widget = document.createElement('widget-cc-{widget-name}');
+
+ // Set props
+ {widgetName}Widget.requiredProp = 'test-value';
+ {widgetName}Widget.optionalConfig = { option1: 'value', option2: 10 };
+
+ // Add listeners
+ {widgetName}Widget.addEventListener('someEvent', (e) => {
+ console.log('{WidgetName} event:', e.detail);
+ });
+
+ {widgetName}Widget.addEventListener('error', (e) => {
+ console.error('{WidgetName} error:', e.detail);
+ });
+
+ // Append to DOM
+ const container = document.getElementById('widgets-container');
+ const wrapper = document.createElement('div');
+ wrapper.className = 'widget-box';
+ wrapper.id = '{widget-name}-container';
+
+ const legend = document.createElement('h3');
+ legend.textContent = '{Widget Display Name}';
+ wrapper.appendChild(legend);
+ wrapper.appendChild({widgetName}Widget);
+
+ container.appendChild(wrapper);
+}
+
+function remove{WidgetName}Widget() {
+ const container = document.getElementById('{widget-name}-container');
+ if (container) container.remove();
+ {widgetName}Widget = null;
+}
+
+// Initialize on load
+document.addEventListener('DOMContentLoaded', initializeApp);
+```
+
+---
+
+## Integration Checklist
+
+Before proceeding, verify:
+
+### cc-widgets Package
+- [ ] Widget imported in src/index.ts
+- [ ] Widget exported in src/index.ts
+- [ ] Widget imported in src/wc.ts (from dist/wc, not dist/index)
+- [ ] r2wc wrapper created with correct prop mappings
+- [ ] Custom element registered in components array
+- [ ] Element name follows pattern: `widget-cc-{widget-name}`
+
+### React Sample App
+- [ ] Widget imported from @webex/cc-widgets
+- [ ] Widget toggle state added to defaultWidgets
+- [ ] Callback handlers defined
+- [ ] Checkbox added to widget selector
+- [ ] Widget rendering added with conditional
+- [ ] All required props passed
+- [ ] Callbacks wired up correctly
+
+### Web Component Sample App
+- [ ] Widget reference variable created
+- [ ] Checkbox added to HTML
+- [ ] Create widget function implemented
+- [ ] Remove widget function implemented
+- [ ] Toggle event listener added
+- [ ] Properties set correctly
+- [ ] Event listeners attached
+- [ ] Widget appended to DOM
+
+### Testing
+- [ ] Widget appears in both sample apps
+- [ ] Toggling works (show/hide)
+- [ ] Props passed correctly
+- [ ] Callbacks fire correctly
+- [ ] No console errors
+- [ ] No console warnings
+
+---
+
+## Build & Test
+
+### Build cc-widgets
+
+```bash
+# From project root
+cd packages/contact-center/cc-widgets
+yarn build
+```
+
+### Build Widget
+
+```bash
+# From project root
+cd packages/contact-center/{widget-name}
+yarn build
+```
+
+### Run React Sample
+
+```bash
+# From project root
+cd widgets-samples/cc/samples-cc-react-app
+yarn start
+```
+
+**Test:**
+1. Check widget checkbox
+2. Verify widget renders
+3. Interact with widget
+4. Verify callbacks fire
+5. Uncheck widget
+6. Verify widget removed
+
+### Run Web Component Sample
+
+```bash
+# From project root
+cd widgets-samples/cc/samples-cc-wc-app
+# Open index.html in browser
+```
+
+**Test:**
+1. Check widget checkbox
+2. Verify widget renders
+3. Interact with widget
+4. Check console for events
+5. Uncheck widget
+6. Verify widget removed
+
+---
+
+## Common Issues
+
+### Issue 1: Widget Not Appearing
+
+**Symptoms:**
+- Checkbox checked but widget doesn't render
+- No errors in console
+
+**Possible Causes:**
+- Widget not exported from cc-widgets
+- Import path incorrect
+- Build not run
+
+**Solutions:**
+1. Verify exports in cc-widgets/src/index.ts
+2. Rebuild cc-widgets: `yarn build`
+3. Check import path in sample app
+4. Check browser console for errors
+
+---
+
+### Issue 2: Props Not Passing
+
+**Symptoms:**
+- Widget renders but props undefined
+- Default values used instead of passed values
+
+**Possible Causes:**
+- r2wc mapping incorrect
+- Prop type mismatch
+- Prop name typo
+
+**Solutions:**
+1. Check r2wc props mapping in wc.ts
+2. Verify prop types (string, number, json, function)
+3. Check prop names match exactly
+4. For objects/arrays, use 'json' type
+
+---
+
+### Issue 3: Callbacks Not Firing
+
+**Symptoms:**
+- Interactions don't trigger callbacks
+- Console shows no events
+
+**Possible Causes:**
+- Callback not passed
+- r2wc function mapping missing
+- Event listener not attached (WC)
+
+**Solutions:**
+1. Verify callback passed in React sample
+2. Check r2wc maps callback as 'function'
+3. Add addEventListener in WC sample
+4. Check event name matches exactly
+
+---
+
+## Next Steps
+
+**After integration complete:**
+1. Go to: 05-test-generation.md
+2. Then: ../documentation/create-agent-md.md
+3. Then: ../documentation/create-architecture-md.md
+4. Finally: 06-validation.md
+
+---
+
+_Template Version: 1.0.0_
+_Last Updated: 2025-11-26_
+
diff --git a/ai-docs/templates/new-widget/05-test-generation.md b/ai-docs/templates/new-widget/05-test-generation.md
new file mode 100644
index 000000000..5bd95234b
--- /dev/null
+++ b/ai-docs/templates/new-widget/05-test-generation.md
@@ -0,0 +1,674 @@
+# Test Generation Module
+
+## Overview
+
+This module guides you through generating comprehensive tests for the widget: unit tests, hook tests, and E2E tests.
+
+**Purpose:** Ensure widget quality and prevent regressions
+
+**Prerequisites:** Widget and integration code complete
+
+---
+
+## Test Structure
+
+```
+packages/contact-center/{widget-name}/tests/
+├── helper.ts # Hook unit tests
+└── {widget-name}/
+ └── index.tsx # Widget unit tests
+
+playwright/tests/
+└── {widget-name}-test.spec.ts # E2E tests (optional)
+```
+
+---
+
+## Step 1: Widget Unit Tests
+
+**File:** `tests/{widget-name}/index.tsx`
+
+```typescript
+import React from 'react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import '@testing-library/jest-dom';
+import { {WidgetName} } from '../../src/{widget-name}';
+import type { {WidgetName}Props } from '../../src/{widget-name}/{widget-name}.types';
+import { mockCC, mockProfile } from '@webex/test-fixtures';
+
+// Mock store
+jest.mock('@webex/cc-store', () => ({
+ __esModule: true,
+ default: {
+ getInstance: jest.fn(() => ({
+ cc: mockCC,
+ profile: mockProfile,
+ // Add other store observables as needed
+ someObservable: 'test-value',
+ })),
+ someObservable: 'test-value',
+ },
+}));
+
+describe('{WidgetName}', () => {
+ let defaultProps: {WidgetName}Props;
+
+ beforeEach(() => {
+ // Reset mocks before each test
+ jest.clearAllMocks();
+
+ // Setup default props
+ defaultProps = {
+ requiredProp: 'test-value',
+ onSomeEvent: jest.fn(),
+ onError: jest.fn(),
+ };
+
+ // Setup mock responses
+ mockCC.someMethod = jest.fn().mockResolvedValue({ success: true });
+ });
+
+ afterEach(() => {
+ jest.resetAllMocks();
+ });
+
+ // ========================================
+ // RENDERING TESTS
+ // ========================================
+
+ describe('Rendering', () => {
+ it('renders without crashing', () => {
+ render(<{WidgetName} {...defaultProps} />);
+ expect(screen.getByText(/expected text/i)).toBeInTheDocument();
+ });
+
+ it('renders with required props only', () => {
+ render(
+ <{WidgetName}
+ requiredProp={defaultProps.requiredProp}
+ />
+ );
+
+ expect(screen.getByText(/expected text/i)).toBeInTheDocument();
+ });
+
+ it('renders with all props', () => {
+ render(
+ <{WidgetName}
+ {...defaultProps}
+ optionalProp={10}
+ className="custom-class"
+ />
+ );
+
+ expect(screen.getByText(/expected text/i)).toBeInTheDocument();
+ });
+ });
+
+ // ========================================
+ // PROP TESTS
+ // ========================================
+
+ describe('Props', () => {
+ it('uses required prop correctly', () => {
+ render(<{WidgetName} {...defaultProps} requiredProp="custom-value" />);
+
+ // Verify prop is used
+ expect(screen.getByText(/custom-value/i)).toBeInTheDocument();
+ });
+
+ it('uses optional prop when provided', () => {
+ render(<{WidgetName} {...defaultProps} optionalProp={20} />);
+
+ // Verify optional prop is used
+ expect(screen.getByText(/20/i)).toBeInTheDocument();
+ });
+
+ it('uses default value when optional prop not provided', () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ // Verify default value is used
+ expect(screen.getByText(/default/i)).toBeInTheDocument();
+ });
+
+ it('applies custom className', () => {
+ const { container } = render(
+ <{WidgetName} {...defaultProps} className="custom-class" />
+ );
+
+ expect(container.firstChild).toHaveClass('custom-class');
+ });
+ });
+
+ // ========================================
+ // CALLBACK TESTS
+ // ========================================
+
+ describe('Callbacks', () => {
+ it('calls onSomeEvent when action occurs', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ // Trigger action
+ fireEvent.click(screen.getByRole('button', { name: /action/i }));
+
+ // Wait for callback
+ await waitFor(() => {
+ expect(defaultProps.onSomeEvent).toHaveBeenCalledWith({
+ id: expect.any(String),
+ value: expect.any(String),
+ timestamp: expect.any(Number),
+ });
+ });
+ });
+
+ it('calls onError when error occurs', async () => {
+ // Setup mock to throw error
+ mockCC.someMethod = jest.fn().mockRejectedValue(new Error('Test error'));
+
+ render(<{WidgetName} {...defaultProps} />);
+
+ // Wait for error
+ await waitFor(() => {
+ expect(defaultProps.onError).toHaveBeenCalledWith(
+ expect.objectContaining({
+ message: 'Test error',
+ })
+ );
+ });
+ });
+
+ it('does not crash when callbacks are undefined', () => {
+ render(
+ <{WidgetName}
+ requiredProp={defaultProps.requiredProp}
+ />
+ );
+
+ // Trigger action
+ fireEvent.click(screen.getByRole('button', { name: /action/i }));
+
+ // Should not crash
+ expect(screen.getByRole('button')).toBeInTheDocument();
+ });
+ });
+
+ // ========================================
+ // STATE TESTS
+ // ========================================
+
+ describe('State Management', () => {
+ it('displays loading state initially', () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ expect(screen.getByText(/loading/i)).toBeInTheDocument();
+ });
+
+ it('displays data after loading', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+ expect(screen.getByText(/expected data/i)).toBeInTheDocument();
+ });
+ });
+
+ it('displays error state when error occurs', async () => {
+ mockCC.someMethod = jest.fn().mockRejectedValue(new Error('Test error'));
+
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.getByText(/error/i)).toBeInTheDocument();
+ expect(screen.getByText(/test error/i)).toBeInTheDocument();
+ });
+ });
+ });
+
+ // ========================================
+ // INTERACTION TESTS
+ // ========================================
+
+ describe('User Interactions', () => {
+ it('handles button click', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ fireEvent.click(screen.getByRole('button', { name: /action/i }));
+
+ expect(mockCC.someMethod).toHaveBeenCalled();
+ });
+
+ it('handles input change', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ const input = screen.getByRole('textbox');
+ fireEvent.change(input, { target: { value: 'test input' } });
+
+ expect(input).toHaveValue('test input');
+ });
+
+ it('handles form submission', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ const form = screen.getByRole('form');
+ fireEvent.submit(form);
+
+ await waitFor(() => {
+ expect(defaultProps.onSomeEvent).toHaveBeenCalled();
+ });
+ });
+ });
+
+ // ========================================
+ // STORE INTEGRATION TESTS
+ // ========================================
+
+ describe('Store Integration', () => {
+ it('reads from store observable', () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ // Verify store value is displayed
+ expect(screen.getByText(/test-value/i)).toBeInTheDocument();
+ });
+
+ it('calls SDK method', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(mockCC.someMethod).toHaveBeenCalledWith(
+ expect.objectContaining({
+ // Expected parameters
+ })
+ );
+ });
+ });
+ });
+
+ // ========================================
+ // EDGE CASES
+ // ========================================
+
+ describe('Edge Cases', () => {
+ it('handles empty data', async () => {
+ mockCC.someMethod = jest.fn().mockResolvedValue(null);
+
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.getByText(/no data/i)).toBeInTheDocument();
+ });
+ });
+
+ it('handles invalid prop values', () => {
+ render(<{WidgetName} {...defaultProps} requiredProp="" />);
+
+ // Should handle gracefully
+ expect(screen.getByText(/invalid/i)).toBeInTheDocument();
+ });
+
+ it('handles rapid interactions', async () => {
+ render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ const button = screen.getByRole('button', { name: /action/i });
+
+ // Rapid clicks
+ fireEvent.click(button);
+ fireEvent.click(button);
+ fireEvent.click(button);
+
+ // Should handle gracefully (debounce or disable)
+ await waitFor(() => {
+ expect(mockCC.someMethod).toHaveBeenCalledTimes(1);
+ });
+ });
+ });
+
+ // ========================================
+ // SNAPSHOT TEST
+ // ========================================
+
+ describe('Snapshot', () => {
+ it('matches snapshot', async () => {
+ const { container } = render(<{WidgetName} {...defaultProps} />);
+
+ await waitFor(() => {
+ expect(screen.queryByText(/loading/i)).not.toBeInTheDocument();
+ });
+
+ expect(container.firstChild).toMatchSnapshot();
+ });
+ });
+});
+```
+
+---
+
+## Step 2: Hook Unit Tests
+
+**File:** `tests/helper.ts`
+
+```typescript
+import { renderHook, act, waitFor } from '@testing-library/react';
+import { use{WidgetName} } from '../src/helper';
+import type { {WidgetName}Props } from '../src/{widget-name}/{widget-name}.types';
+import { mockCC, mockProfile } from '@webex/test-fixtures';
+
+// Mock store
+jest.mock('@webex/cc-store', () => ({
+ __esModule: true,
+ default: {
+ getInstance: jest.fn(() => ({
+ cc: mockCC,
+ profile: mockProfile,
+ someObservable: 'test-value',
+ })),
+ someObservable: 'test-value',
+ },
+}));
+
+describe('use{WidgetName}', () => {
+ let defaultProps: {WidgetName}Props;
+
+ beforeEach(() => {
+ jest.clearAllMocks();
+
+ defaultProps = {
+ requiredProp: 'test-value',
+ onSomeEvent: jest.fn(),
+ onError: jest.fn(),
+ };
+
+ mockCC.someMethod = jest.fn().mockResolvedValue({ success: true });
+ });
+
+ // ========================================
+ // INITIALIZATION TESTS
+ // ========================================
+
+ describe('Initialization', () => {
+ it('initializes with correct default state', () => {
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ expect(result.current.data).toBeNull();
+ expect(result.current.isLoading).toBe(true);
+ expect(result.current.error).toBeNull();
+ });
+
+ it('fetches initial data', async () => {
+ mockCC.someMethod = jest.fn().mockResolvedValue({
+ id: 'test-id',
+ value: 'test-value',
+ });
+
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.data).toEqual({
+ id: 'test-id',
+ value: 'test-value',
+ });
+ });
+ });
+
+ it('handles initialization error', async () => {
+ const error = new Error('Init failed');
+ mockCC.someMethod = jest.fn().mockRejectedValue(error);
+
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ await waitFor(() => {
+ expect(result.current.isLoading).toBe(false);
+ expect(result.current.error).toEqual(error);
+ expect(defaultProps.onError).toHaveBeenCalledWith(error);
+ });
+ });
+ });
+
+ // ========================================
+ // HANDLER TESTS
+ // ========================================
+
+ describe('Handlers', () => {
+ it('handleAction calls SDK method', async () => {
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ await act(async () => {
+ await result.current.handleAction('test-param');
+ });
+
+ expect(mockCC.someAction).toHaveBeenCalledWith('test-param');
+ });
+
+ it('handleAction calls callback on success', async () => {
+ mockCC.someAction = jest.fn().mockResolvedValue({ data: 'result' });
+
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ await act(async () => {
+ await result.current.handleAction('test-param');
+ });
+
+ expect(defaultProps.onSomeEvent).toHaveBeenCalledWith({
+ id: expect.any(String),
+ value: 'test-param',
+ timestamp: expect.any(Number),
+ });
+ });
+
+ it('handleAction calls onError on failure', async () => {
+ const error = new Error('Action failed');
+ mockCC.someAction = jest.fn().mockRejectedValue(error);
+
+ const { result } = renderHook(() => use{WidgetName}(defaultProps));
+
+ await act(async () => {
+ await result.current.handleAction('test-param');
+ });
+
+ expect(defaultProps.onError).toHaveBeenCalledWith(error);
+ });
+ });
+
+ // ========================================
+ // CLEANUP TESTS
+ // ========================================
+
+ describe('Cleanup', () => {
+ it('cleans up subscriptions on unmount', () => {
+ const unsubscribeMock = jest.fn();
+ mockCC.on = jest.fn().mockReturnValue({ unsubscribe: unsubscribeMock });
+
+ const { unmount } = renderHook(() => use{WidgetName}(defaultProps));
+
+ unmount();
+
+ expect(unsubscribeMock).toHaveBeenCalled();
+ });
+
+ it('cancels pending requests on unmount', async () => {
+ const abortMock = jest.fn();
+ mockCC.someMethod = jest.fn().mockImplementation(() => {
+ return new Promise((resolve) => {
+ setTimeout(resolve, 1000);
+ });
+ });
+
+ const { unmount } = renderHook(() => use{WidgetName}(defaultProps));
+
+ unmount();
+
+ // Verify no state updates after unmount
+ await waitFor(() => {
+ expect(abortMock).toHaveBeenCalled();
+ }, { timeout: 100 });
+ });
+ });
+
+ // ========================================
+ // DEPENDENCY TESTS
+ // ========================================
+
+ describe('Dependencies', () => {
+ it('re-initializes when props change', async () => {
+ const { rerender } = renderHook(
+ ({ props }) => use{WidgetName}(props),
+ { initialProps: { props: defaultProps } }
+ );
+
+ await waitFor(() => {
+ expect(mockCC.someMethod).toHaveBeenCalledTimes(1);
+ });
+
+ // Change props
+ rerender({ props: { ...defaultProps, requiredProp: 'new-value' } });
+
+ await waitFor(() => {
+ expect(mockCC.someMethod).toHaveBeenCalledTimes(2);
+ });
+ });
+ });
+});
+```
+
+---
+
+## Step 3: E2E Tests (Optional)
+
+**File:** `playwright/tests/{widget-name}-test.spec.ts`
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('{WidgetName} Widget E2E', () => {
+ test.beforeEach(async ({ page }) => {
+ // Navigate to sample app
+ await page.goto('http://localhost:3000');
+
+ // Enable widget
+ await page.check('input[type="checkbox"][id="toggle-{widget-name}"]');
+
+ // Wait for widget to appear
+ await page.waitForSelector('.{widget-name}', { state: 'visible' });
+ });
+
+ test('renders widget correctly', async ({ page }) => {
+ // Verify widget is visible
+ const widget = page.locator('.{widget-name}');
+ await expect(widget).toBeVisible();
+
+ // Verify expected elements
+ await expect(page.getByText('Expected Text')).toBeVisible();
+ });
+
+ test('handles user interaction', async ({ page }) => {
+ // Click button
+ await page.click('button:has-text("Action")');
+
+ // Verify result
+ await expect(page.getByText('Success')).toBeVisible();
+ });
+
+ test('displays error state', async ({ page }) => {
+ // Trigger error condition
+ await page.click('button:has-text("Trigger Error")');
+
+ // Verify error message
+ await expect(page.getByText('Error:')).toBeVisible();
+ });
+
+ test('handles toggle off', async ({ page }) => {
+ // Verify widget is visible
+ await expect(page.locator('.{widget-name}')).toBeVisible();
+
+ // Toggle off
+ await page.uncheck('input[type="checkbox"][id="toggle-{widget-name}"]');
+
+ // Verify widget is removed
+ await expect(page.locator('.{widget-name}')).not.toBeVisible();
+ });
+});
+```
+
+---
+
+## Test Checklist
+
+Before proceeding, verify:
+
+### Widget Unit Tests
+- [ ] Rendering tests (with/without props)
+- [ ] Prop tests (required, optional, defaults)
+- [ ] Callback tests (all callbacks)
+- [ ] State tests (loading, error, data)
+- [ ] Interaction tests (clicks, inputs, forms)
+- [ ] Store integration tests
+- [ ] Edge case tests
+- [ ] Snapshot test
+
+### Hook Unit Tests
+- [ ] Initialization tests
+- [ ] Handler tests (success, error)
+- [ ] Cleanup tests
+- [ ] Dependency tests
+
+### E2E Tests (Optional)
+- [ ] Widget renders in sample app
+- [ ] User interactions work
+- [ ] Error states handled
+- [ ] Toggle on/off works
+
+### Test Quality
+- [ ] All tests pass: `yarn test:unit`
+- [ ] Coverage > 80%
+- [ ] No console errors
+- [ ] No flaky tests
+- [ ] Clear test descriptions
+
+---
+
+## Run Tests
+
+### Unit Tests
+
+```bash
+# From widget directory
+cd packages/contact-center/{widget-name}
+yarn test:unit
+```
+
+### E2E Tests
+
+```bash
+# From project root
+yarn test:e2e
+```
+
+### Coverage Report
+
+```bash
+cd packages/contact-center/{widget-name}
+yarn test:unit --coverage
+```
+
+---
+
+## Next Steps
+
+**After tests complete:**
+1. Go to: ../documentation/create-agent-md.md
+2. Then: ../documentation/create-architecture-md.md
+3. Finally: 06-validation.md
+
+---
+
+_Template Version: 1.0.0_
+_Last Updated: 2025-11-26_
+
diff --git a/ai-docs/templates/new-widget/06-validation.md b/ai-docs/templates/new-widget/06-validation.md
new file mode 100644
index 000000000..ffb0ab8d8
--- /dev/null
+++ b/ai-docs/templates/new-widget/06-validation.md
@@ -0,0 +1,775 @@
+# Validation Module
+
+## Overview
+
+This module provides comprehensive validation checklists to ensure the widget is production-ready before deployment.
+
+**Purpose:** Quality assurance and completeness verification
+
+**Use:** After all code, tests, and documentation are complete
+
+---
+
+## Validation Categories
+
+1. **Code Quality** - Architecture, patterns, best practices
+2. **Testing** - Unit, hook, E2E tests
+3. **Documentation** - AGENTS.md, ARCHITECTURE.md completeness
+4. **Integration** - cc-widgets, sample apps
+5. **Manual Testing** - Real-world usage verification
+
+---
+
+## 1. Code Quality Validation
+
+### Architecture & Layer Separation
+
+- [ ] **Widget → Hook → Component → Store → SDK** pattern followed
+- [ ] Widget component wrapped with `observer` HOC
+- [ ] Widget wrapped with `ErrorBoundary`
+- [ ] Hook contains all business logic
+- [ ] Component is pure presentational (if separate component)
+- [ ] No layer violations (Widget doesn't call SDK directly)
+- [ ] No component accessing store directly
+
+### MobX Integration
+
+- [ ] Widget uses `observer` HOC from mobx-react-lite
+- [ ] Store observables accessed correctly
+- [ ] Store mutations wrapped in `runInAction`
+- [ ] No direct store mutations outside runInAction
+- [ ] No reactions created in render
+
+### TypeScript
+
+- [ ] All types exported from types file
+- [ ] Props interface fully documented with JSDoc
+- [ ] No `any` types used (proper types everywhere)
+- [ ] Optional props marked with `?`
+- [ ] Default values documented
+- [ ] Return types specified on functions
+- [ ] Complex types have interfaces/types
+- [ ] Exported types available to consumers
+
+### React Best Practices
+
+- [ ] Functional components used (not class components)
+- [ ] Hooks used correctly (rules of hooks)
+- [ ] `useCallback` for event handlers
+- [ ] `useMemo` for expensive computations
+- [ ] `useEffect` dependencies correct
+- [ ] `useEffect` cleanup functions present
+- [ ] Display names set for debugging
+- [ ] Loading states handled
+- [ ] Error states handled
+- [ ] Empty states handled
+
+### Error Handling
+
+- [ ] ErrorBoundary wraps widget
+- [ ] Try-catch in all async operations
+- [ ] Errors logged to console
+- [ ] `onError` callback called on errors
+- [ ] User-friendly error messages displayed
+- [ ] Error recovery possible
+- [ ] No unhandled promise rejections
+
+### Code Style
+
+- [ ] Linting passes: `yarn test:styles`
+- [ ] No console.log statements (use proper logging)
+- [ ] Comments explain "why", not "what"
+- [ ] Complex logic documented
+- [ ] TODO comments removed
+- [ ] Dead code removed
+- [ ] Consistent naming conventions
+
+### Metrics & Logging
+
+- [ ] Widget wrapped with `withMetrics` HOC in index.ts
+- [ ] NOT wrapped with `withMetrics` in wc.ts
+- [ ] WIDGET_MOUNTED logged automatically
+- [ ] WIDGET_UNMOUNTED logged automatically
+- [ ] Custom metrics logged where appropriate
+
+---
+
+## 2. Functional Validation (NEW - CRITICAL)
+
+### Purpose
+
+Verify that the widget actually WORKS as intended, not just that it compiles. Test the complete data flow from user action to UI update.
+
+### Sequence Diagram Validation
+
+**FIRST STEP: Load approved sequence diagrams from 01-pre-questions.md**
+
+Before running any tests, verify implementation matches approved diagrams:
+
+- [ ] Load all sequence diagrams from pre-questions
+- [ ] Load SDK API documentation from pre-questions
+- [ ] Load data transformation mappings from pre-questions
+
+### SDK Integration Test
+
+**Compare implemented code against approved sequence diagrams:**
+
+**For each SDK method in sequence diagrams:**
+
+- [ ] Method exists in [contact-centre-sdk-apis/contact-center.json](../../contact-centre-sdk-apis/contact-center.json)
+- [ ] **Exact path matches sequence diagram** (e.g., `store.cc.someService.someMethod`)
+- [ ] **Parameters match diagram specification** (type, order, values)
+- [ ] **Return type matches SDK documentation AND diagram**
+- [ ] Accessed via `store.cc.methodName()` (not direct import)
+- [ ] Error handling present (try/catch) as per error flow diagram
+- [ ] Success callbacks fire on success (verify timing per diagram)
+- [ ] Error callbacks fire on error (verify error path per diagram)
+- [ ] Response structure matches documented structure
+
+**Example Verification:**
+
+```typescript
+// From sequence diagram: store.cc.someService.someMethod(param1, param2)
+// ✓ Exists in SDK JSON at exact path
+// ✓ Parameters: (param1: value1, param2: value2) - matches diagram
+// ✓ Return type: Promise<{statusCode: number, data: {...}}>
+// ✓ Error handling: try/catch present with setError() call
+// ✓ Callback: props.onSuccess?.(data) called on success
+// ✓ Error callback: props.onError?.(error) called on failure
+// ✓ Response accessed: response.data.items (matches diagram)
+```
+
+**If method not found in SDK or signature mismatch → RETURN to sequence diagrams and fix**
+
+**Data Transformation Validation:**
+
+- [ ] **Every transformation matches diagram mapping**
+- [ ] Source fields extracted correctly (e.g., `session.other.name`)
+- [ ] Fallback values match diagram (e.g., `|| 'Unknown'`)
+- [ ] Type conversions correct (e.g., ISO string → timestamp)
+- [ ] Optional field handling matches diagram (`?? operator`)
+
+**Example:**
+```typescript
+// Diagram says: contactName = session.other.name || session.other.primaryDisplayString || 'Unknown'
+// Code implements:
+contactName: session.other?.name || session.other?.primaryDisplayString || 'Unknown'
+// ✓ Matches diagram
+```
+
+### Event Flow Test
+
+**Validate implementation against sequence diagrams:**
+
+**For EACH sequence diagram, manually test the flow:**
+
+#### Testing Procedure
+
+1. **Load sequence diagram** from pre-questions for scenario
+2. **Perform user action** shown in diagram
+3. **Verify EACH step** in diagram occurs in correct order
+4. **Check state updates** match diagram timing
+5. **Confirm UI updates** match diagram end state
+
+#### Example: Button Click Flow (from sequence diagram)
+
+Per diagram sequence:
+1. User clicks button → Event handler called? ✓
+2. Handler sets `isLoading=true` → State updated? ✓
+3. Handler sets `error=null` → State cleared? ✓
+4. Handler calls SDK method → Method invoked with correct params? ✓
+5. SDK returns response → Response structure matches diagram? ✓
+6. Handler transforms data → Transformation per diagram mappings? ✓
+7. Handler sets `data=records` → State updated with transformed data? ✓
+8. Handler sets `isLoading=false` → Loading state cleared? ✓
+9. Component re-renders → UI shows new data? ✓
+
+**If ANY step fails or order wrong → Debug against sequence diagram**
+
+**For YOUR widget, test ALL diagram scenarios:**
+
+**Scenario 1:** (from sequence diagram: _______________)
+```
+Diagram step → Implemented code → Verified?
+───────────────────────────────────────────
+User action: _______________ → _______________ → [ ]
+Handler called: _______________ → _______________ → [ ]
+State update 1: _______________ → _______________ → [ ]
+State update 2: _______________ → _______________ → [ ]
+SDK call: _______________ → _______________ → [ ]
+SDK response: _______________ → _______________ → [ ]
+Data transform: _______________ → _______________ → [ ]
+Final state: _______________ → _______________ → [ ]
+UI renders: _______________ → _______________ → [ ]
+
+Overall Status: [ ] VERIFIED [ ] FAILED
+```
+
+**Scenario 2:** (from sequence diagram: _______________)
+```
+Diagram step → Implemented code → Verified?
+───────────────────────────────────────────
+User action: _______________ → _______________ → [ ]
+Handler called: _______________ → _______________ → [ ]
+State update 1: _______________ → _______________ → [ ]
+State update 2: _______________ → _______________ → [ ]
+SDK call: _______________ → _______________ → [ ]
+SDK response: _______________ → _______________ → [ ]
+Data transform: _______________ → _______________ → [ ]
+Final state: _______________ → _______________ → [ ]
+UI renders: _______________ → _______________ → [ ]
+
+Overall Status: [ ] VERIFIED [ ] FAILED
+```
+
+**Scenario 3:** (from sequence diagram: _______________)
+```
+Diagram step → Implemented code → Verified?
+───────────────────────────────────────────
+User action: _______________ → _______________ → [ ]
+Handler called: _______________ → _______________ → [ ]
+State update 1: _______________ → _______________ → [ ]
+State update 2: _______________ → _______________ → [ ]
+SDK call: _______________ → _______________ → [ ]
+SDK response: _______________ → _______________ → [ ]
+Data transform: _______________ → _______________ → [ ]
+Final state: _______________ → _______________ → [ ]
+UI renders: _______________ → _______________ → [ ]
+
+Overall Status: [ ] VERIFIED [ ] FAILED
+```
+
+### Data Flow Test
+
+**Trace data through ALL layers:**
+
+```
+User Action (UI)
+ ↓
+Widget Handler (index.tsx)
+ ↓
+Hook Method (helper.ts)
+ ↓
+Store/SDK Call
+ ↓
+Response/Observable Update
+ ↓
+Hook State Update
+ ↓
+Component Props
+ ↓
+UI Render
+```
+
+**Verification:**
+
+- [ ] User action triggers widget handler
+- [ ] Widget handler calls hook method correctly
+- [ ] Hook method accesses store/SDK correctly
+- [ ] Response updates hook state
+- [ ] Hook state passes to component props
+- [ ] Component renders with updated props
+- [ ] UI reflects the change
+
+**If any transition fails → Debug and fix**
+
+### Import Validation Test
+
+**Check for circular dependencies:**
+
+```bash
+# In widget code, search for cc-widgets import:
+grep -r "from '@webex/cc-widgets'" packages/contact-center/{widget-name}/src/
+# Expected: NO MATCHES
+
+# In cc-components, search for widget imports:
+grep -r "from '@webex/cc-.*-widget'" packages/contact-center/cc-components/src/
+# Expected: NO MATCHES
+```
+
+**Validation:**
+
+- [ ] No matches for `@webex/cc-widgets` in widget code
+- [ ] No matches for widget packages in cc-components
+- [ ] All imports follow one-directional flow
+- [ ] No circular dependencies detected
+
+**If any matches found → Refactor imports**
+
+### UI Visual Test
+
+**Compare with design input (Figma/screenshot/spec):**
+
+- [ ] Colors match design (or use Momentum tokens)
+- [ ] Spacing matches (8px/0.5rem grid adhered)
+- [ ] Layout matches (flex/grid structure correct)
+- [ ] Components match design (correct Momentum components used)
+- [ ] Typography matches (sizes, weights correct)
+- [ ] Interactions work (hover, active, focus states)
+- [ ] Theme switching works (light/dark modes)
+
+**Visual differences found:**
+
+| Element | Design | Generated | Status | Notes |
+|---------|--------|-----------|--------|-------|
+| _____ | _____ | _____ | [ ] Fixed | _____ |
+| _____ | _____ | _____ | [ ] Fixed | _____ |
+| _____ | _____ | _____ | [ ] Fixed | _____ |
+
+**If visual mismatch → Update styling**
+
+### Compiler Test
+
+```bash
+# Build the widget
+yarn build
+
+# Expected: NO ERRORS
+```
+
+**Common compiler errors and fixes:**
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| Type error | Missing/incorrect types | Add proper type definitions |
+| Import error | Wrong path or missing export | Check paths and exports |
+| Circular dependency | Improper imports | Refactor to follow dependency flow |
+| Syntax error | Code syntax issue | Fix syntax |
+
+**Validation:**
+
+- [ ] `yarn build` completes without errors
+- [ ] No TypeScript errors
+- [ ] No import errors
+- [ ] No syntax errors
+- [ ] Bundle size reasonable
+
+**Fix ALL compiler errors before completing**
+
+### Runtime Test (Manual)
+
+**Run sample app and test widget:**
+
+```bash
+# Start React sample app
+yarn samples:serve-react
+```
+
+**Test checklist:**
+
+- [ ] Widget renders without errors
+- [ ] All buttons work
+- [ ] All inputs work
+- [ ] All dropdowns/selects work
+- [ ] Callbacks fire correctly
+- [ ] State updates reflect in UI immediately
+- [ ] Error scenarios handled gracefully
+- [ ] No console errors or warnings
+
+**Test scenarios:**
+
+1. **Happy Path:**
+ - [ ] Primary user flow works end-to-end
+ - [ ] UI updates correctly
+ - [ ] Callbacks fire with correct data
+
+2. **Error Scenarios:**
+ - [ ] Invalid input shows error message
+ - [ ] API errors handled gracefully
+ - [ ] Error callbacks fire
+ - [ ] User can recover from errors
+
+3. **Edge Cases:**
+ - [ ] Empty state handled
+ - [ ] Loading state shown
+ - [ ] No data scenario handled
+ - [ ] Rapid clicks handled
+
+**If runtime errors → Debug and fix**
+
+---
+
+## 3. Testing Validation
+
+### Unit Tests - Widget
+
+- [ ] Widget renders without crashing
+- [ ] Renders with required props only
+- [ ] Renders with all props
+- [ ] All required props tested
+- [ ] All optional props tested
+- [ ] Default values tested
+- [ ] Custom className applied
+- [ ] Custom styles applied
+- [ ] All callbacks tested (called correctly)
+- [ ] Callbacks work when undefined
+- [ ] Loading state tested
+- [ ] Error state tested
+- [ ] Empty/no-data state tested
+- [ ] User interactions tested (clicks, inputs, etc.)
+- [ ] Store integration tested
+- [ ] SDK calls tested
+- [ ] Edge cases tested
+- [ ] Snapshot test included
+
+### Unit Tests - Hook
+
+- [ ] Hook initializes correctly
+- [ ] Initial data fetch tested
+- [ ] Initialization errors handled
+- [ ] All handlers tested (success cases)
+- [ ] All handlers tested (error cases)
+- [ ] Callbacks called correctly
+- [ ] Cleanup functions tested
+- [ ] Subscriptions unsubscribed
+- [ ] Dependency changes tested
+- [ ] Re-initialization tested
+
+### Test Quality
+
+- [ ] All tests pass: `yarn test:unit`
+- [ ] Test coverage > 80%
+- [ ] No skipped tests (.skip removed)
+- [ ] No focused tests (.only removed)
+- [ ] Tests are deterministic (not flaky)
+- [ ] Tests are independent (can run in any order)
+- [ ] Mock setup/teardown correct
+- [ ] No console warnings during tests
+- [ ] No console errors during tests
+
+### E2E Tests (Optional)
+
+- [ ] Widget renders in sample app
+- [ ] User interactions work end-to-end
+- [ ] Error scenarios tested
+- [ ] Toggle on/off works
+- [ ] Multi-widget scenarios tested
+
+---
+
+## 3. Documentation Validation
+
+### AGENTS.md Completeness
+
+- [ ] Overview section complete
+- [ ] Package name stated
+- [ ] Version references package.json
+- [ ] Purpose clearly explained
+- [ ] 3-5 key capabilities listed
+- [ ] 4-6 usage examples provided
+- [ ] Basic usage example (React)
+- [ ] Web Component usage example
+- [ ] Common use case examples
+- [ ] Error handling example
+- [ ] Dependencies documented
+- [ ] Dependencies reference package.json (no hardcoded versions)
+- [ ] Props API table complete
+- [ ] All props documented
+- [ ] Required/optional marked
+- [ ] Default values shown
+- [ ] Installation instructions included
+- [ ] Link to ARCHITECTURE.md at END (token optimization)
+
+### ARCHITECTURE.md Completeness
+
+- [ ] Component overview complete
+- [ ] Component table has all components
+- [ ] File structure documented
+- [ ] Layer communication diagram (Mermaid)
+- [ ] 3-5 sequence diagrams (Mermaid)
+- [ ] All diagrams use Mermaid (not PlantUML)
+- [ ] Diagrams render correctly
+- [ ] Hook/business logic explained
+- [ ] Store integration explained
+- [ ] SDK integration explained
+- [ ] 5-8 troubleshooting issues documented
+- [ ] Each issue has symptoms, causes, solutions
+- [ ] Code examples in troubleshooting
+- [ ] Related documentation linked
+
+### Documentation Quality
+
+- [ ] Markdown renders correctly
+- [ ] Code blocks have language tags
+- [ ] Tables format properly
+- [ ] No broken links
+- [ ] Consistent heading levels
+- [ ] No typos
+- [ ] Examples are realistic
+- [ ] Examples work (tested)
+
+---
+
+## 4. Integration Validation
+
+### cc-widgets Package
+
+- [ ] Widget imported in `cc-widgets/src/index.ts`
+- [ ] Widget exported in `cc-widgets/src/index.ts`
+- [ ] Widget imported in `cc-widgets/src/wc.ts` (from dist/wc)
+- [ ] r2wc wrapper created
+- [ ] All props mapped correctly in r2wc
+- [ ] String props use 'string'
+- [ ] Number props use 'number'
+- [ ] Boolean props use 'boolean'
+- [ ] Object/Array props use 'json'
+- [ ] Function props use 'function'
+- [ ] Custom element registered
+- [ ] Element name: `widget-cc-{widget-name}`
+- [ ] cc-widgets builds successfully: `yarn build`
+
+### React Sample App
+
+- [ ] Widget imported from @webex/cc-widgets
+- [ ] Widget toggle state added
+- [ ] Checkbox added to widget selector
+- [ ] Callback handlers defined
+- [ ] Widget rendering section added
+- [ ] All required props passed
+- [ ] Callbacks wired correctly
+- [ ] Sample app runs: `yarn start`
+- [ ] Widget appears when toggled on
+- [ ] Widget disappears when toggled off
+- [ ] Widget functions correctly
+
+### Web Component Sample App
+
+- [ ] Widget reference variable created
+- [ ] Checkbox added to HTML
+- [ ] Create widget function implemented
+- [ ] Remove widget function implemented
+- [ ] Toggle event listener attached
+- [ ] Properties set correctly
+- [ ] Event listeners attached correctly
+- [ ] Widget appended to DOM correctly
+- [ ] Sample app loads in browser
+- [ ] Widget appears when toggled on
+- [ ] Widget disappears when toggled off
+- [ ] Widget functions correctly
+- [ ] Events fire correctly (check console)
+
+---
+
+## 5. Manual Testing Validation
+
+### Functional Testing
+
+- [ ] Widget renders without errors
+- [ ] All features work as expected
+- [ ] Props passed correctly
+- [ ] Callbacks fire correctly
+- [ ] User interactions work
+- [ ] Loading states display correctly
+- [ ] Error states display correctly
+- [ ] Empty states display correctly
+- [ ] Data updates in real-time (if applicable)
+- [ ] Store integration works
+- [ ] SDK calls work
+
+### Visual Testing
+
+- [ ] Widget looks correct (matches design)
+- [ ] Layout is correct
+- [ ] Colors are correct
+- [ ] Typography is correct
+- [ ] Icons display correctly
+- [ ] Spacing is correct
+- [ ] Responsive (if applicable)
+- [ ] Works in light theme
+- [ ] Works in dark theme
+
+### Browser Testing
+
+- [ ] Chrome (latest)
+- [ ] Firefox (latest)
+- [ ] Safari (latest)
+- [ ] Edge (latest)
+
+### Accessibility Testing
+
+- [ ] Keyboard navigation works
+- [ ] Tab order is logical
+- [ ] Focus visible
+- [ ] Screen reader friendly
+- [ ] ARIA labels present
+- [ ] Color contrast sufficient
+- [ ] No keyboard traps
+
+### Performance Testing
+
+- [ ] Widget renders quickly (< 1s)
+- [ ] No memory leaks
+- [ ] No excessive re-renders
+- [ ] No console warnings
+- [ ] No console errors
+
+### Error Scenarios
+
+- [ ] Invalid props handled gracefully
+- [ ] Missing props handled gracefully
+- [ ] SDK errors handled gracefully
+- [ ] Network errors handled gracefully
+- [ ] Empty data handled gracefully
+- [ ] User shown appropriate error message
+- [ ] Error logged to console
+- [ ] `onError` callback called
+
+---
+
+## 6. Build & Deploy Validation
+
+### Build Process
+
+- [ ] Widget builds successfully
+ ```bash
+ cd packages/contact-center/{widget-name}
+ yarn build
+ ```
+- [ ] No build errors
+- [ ] No build warnings
+- [ ] dist/ folder created
+- [ ] Types generated (dist/types/)
+- [ ] Source maps generated
+
+### Package Configuration
+
+- [ ] package.json name correct: `@webex/cc-{widget-name}`
+- [ ] package.json description correct
+- [ ] package.json version correct
+- [ ] package.json main points to dist/index.js
+- [ ] package.json types points to dist/types/index.d.ts
+- [ ] Dependencies correct
+- [ ] DevDependencies correct
+- [ ] PeerDependencies correct
+
+### File Structure
+
+- [ ] All required files present
+- [ ] No unnecessary files in dist/
+- [ ] README or link to docs present
+- [ ] License file present
+
+---
+
+## 7. Pattern Compliance
+
+### Check Against Pattern Docs
+
+- [ ] Follows [TypeScript Patterns](../../patterns/typescript-patterns.md)
+- [ ] Follows [React Patterns](../../patterns/react-patterns.md)
+- [ ] Follows [MobX Patterns](../../patterns/mobx-patterns.md)
+- [ ] Follows [Web Component Patterns](../../patterns/web-component-patterns.md)
+- [ ] Follows [Testing Patterns](../../patterns/testing-patterns.md)
+
+### Naming Conventions
+
+- [ ] Widget name is kebab-case: `agent-directory`
+- [ ] Component name is PascalCase: `AgentDirectory`
+- [ ] File names match conventions
+- [ ] Function names are camelCase
+- [ ] Constants are UPPER_SNAKE_CASE
+- [ ] Types/Interfaces are PascalCase
+
+---
+
+## 8. Final Checklist
+
+### Code Complete
+
+- [ ] All modules from 01-06 completed
+- [ ] Widget code generated
+- [ ] Hook code generated
+- [ ] Types defined
+- [ ] Component created (if needed)
+- [ ] Tests written
+- [ ] Documentation written
+
+### Quality Gates Passed
+
+- [ ] Linting passes
+- [ ] Tests pass (100%)
+- [ ] Build succeeds
+- [ ] No console errors
+- [ ] No console warnings
+
+### Integration Complete
+
+- [ ] cc-widgets updated
+- [ ] React sample updated
+- [ ] Web Component sample updated
+- [ ] Both samples tested
+
+### Documentation Complete
+
+- [ ] AGENTS.md complete
+- [ ] ARCHITECTURE.md complete
+- [ ] All examples tested
+- [ ] All diagrams render
+
+### Ready for Review
+
+- [ ] All checklists completed
+- [ ] No known issues
+- [ ] Ready for peer review
+- [ ] Ready for QA
+- [ ] Ready for production
+
+---
+
+## Issue Tracking
+
+If any checklist items fail, document here:
+
+### Issues Found
+
+| Issue | Severity | Description | Solution | Status |
+|-------|----------|-------------|----------|--------|
+| 1. | High/Med/Low | Description | Solution | Open/Fixed |
+| 2. | High/Med/Low | Description | Solution | Open/Fixed |
+| 3. | High/Med/Low | Description | Solution | Open/Fixed |
+
+### Notes
+
+(Add any notes about the validation process, workarounds, or decisions made)
+
+---
+
+## Sign-Off
+
+**Validation completed by:** _______________
+
+**Date:** _______________
+
+**Widget name:** _______________
+
+**Version:** _______________
+
+**Status:** ✅ READY FOR PRODUCTION / ⚠️ NEEDS WORK
+
+**Notes:**
+```
+(Any final notes or observations)
+```
+
+---
+
+## Next Steps After Validation
+
+**If all checks pass:**
+1. Commit changes to version control
+2. Create pull request
+3. Request peer review
+4. Update CHANGELOG
+5. Prepare for release
+
+**If checks fail:**
+1. Document issues in tracking table
+2. Fix issues
+3. Re-run validation
+4. Repeat until all checks pass
+
+---
+
+_Template Version: 1.0.0_
+_Last Updated: 2025-11-26_
+