erne-universal 0.2.0 → 0.3.0

package/README.md

@@ -2,6 +2,10 @@
 
 Complete AI coding agent harness for React Native and Expo development.
 
+<p align="center">
+  <img src="docs/assets/dashboard-preview.png" alt="ERNE Agent Dashboard — pixel-art office with 10 agents working in real-time" width="800">
+</p>
+
 ## Quick Start
 
 ```bash
@@ -16,15 +20,50 @@ This will:
 
 ## What's Included
 
-| Component | Count |
-|-----------|-------|
-| Agents | 8 specialized AI agents |
-| Commands | 16 slash commands |
-| Rule layers | 5 (common, expo, bare-rn, native-ios, native-android) |
-| Hook profiles | 3 (minimal, standard, strict) |
-| Skills | 8 reusable knowledge modules |
-| Contexts | 3 behavior modes (dev, review, vibe) |
-| MCP configs | 10 server integrations |
+| Component | Count | Description |
+|-----------|-------|-------------|
+| Agents | 10 | Specialized AI agents for architecture, development, review, testing, UI, native, and more |
+| Commands | 16 | Slash commands for every React Native workflow |
+| Rule layers | 5 | Conditional rules: common, expo, bare-rn, native-ios, native-android |
+| Hook profiles | 3 | Minimal, standard, strict — quality enforcement your way |
+| Skills | 8 | Reusable knowledge modules loaded on-demand |
+| Contexts | 3 | Behavior modes: dev, review, vibe |
+| MCP configs | 10 | Pre-configured server integrations |
+
+## Token Efficiency
+
+ERNE's architecture is designed to minimize token usage through six layered mechanisms:
+
+| Mechanism | How it works | Savings |
+|-----------|-------------|---------|
+| **Profile-gated hooks** | Minimal profile runs 3 hooks instead of 17 | ~31% |
+| **Conditional rules** | Only loads rules matching your project type (Expo, bare RN, native) | ~26% |
+| **On-demand skills** | Skills load only when their command is invoked, not always in context | ~12% |
+| **Subagent isolation** | Fresh agent per task with only its own definition + relevant rules | ~12% |
+| **Task-specific commands** | 16 focused prompts instead of one monolithic instruction set | ~13% |
+| **Context-based behavior** | Modes change behavior dynamically without loading new rulesets | ~3% |
+
+**Result:** Typical workflows use **60–67% fewer tokens** compared to a naive all-in-context approach. Vibe mode (minimal profile) reaches 67% savings, standard development 64%, and even strict mode saves 57%.
+
+## Agent Dashboard
+
+ERNE includes a real-time pixel-art dashboard that visualizes all 10 agents working in an animated office environment.
+
+```bash
+erne dashboard              # Start on port 3333, open browser
+erne dashboard --port 4444  # Custom port
+erne dashboard --no-open    # Don't open browser
+erne start                  # Init project + dashboard in background
+```
+
+**Features:**
+- 4 office rooms (Development, Code Review, Testing, Conference)
+- 8 unique procedural pixel-art agent sprites with animations
+- Real-time status updates via WebSocket (connected to Claude Code hooks)
+- Sidebar with agent status, task descriptions, and connection indicator
+- Auto-reconnect with exponential backoff
+
+The dashboard hooks into Claude Code's `PreToolUse` and `PostToolUse` events (pattern: `Agent`) to track which agents are actively working and what they're doing.
 
 ## IDE & Editor Support
 
@@ -43,32 +82,59 @@ All config files share the same React Native & Expo conventions: TypeScript stri
 
 ## Agents
 
-- **architect** — System design and project structure
-- **code-reviewer** — Code quality and best practices
-- **tdd-guide** — Test-driven development workflow
-- **performance-profiler** — Performance diagnostics
-- **native-bridge-builder** — Native module development
-- **expo-config-resolver** — Expo configuration issues
-- **ui-designer** — UI/UX implementation
-- **upgrade-assistant** — Version migration
+| Agent | Domain | Room |
+|-------|--------|------|
+| **architect** | System design and project structure | Development |
+| **senior-developer** | End-to-end feature implementation, screens, hooks, API | Development |
+| **feature-builder** | Focused implementation units, works in parallel | Development |
+| **native-bridge-builder** | Turbo Modules and native platform APIs | Development |
+| **expo-config-resolver** | Expo configuration and build issues | Development |
+| **ui-designer** | Accessible, performant UI components | Development |
+| **code-reviewer** | Code quality and best practices | Code Review |
+| **upgrade-assistant** | Version migration guidance | Code Review |
+| **tdd-guide** | Test-driven development workflow | Testing |
+| **performance-profiler** | FPS diagnostics and bundle optimization | Testing |
 
 ## Hook Profiles
 
-| Profile | Use Case |
-|---------|----------|
-| minimal | Fast iteration, vibe coding |
-| standard | Balanced quality + speed (recommended) |
-| strict | Production-grade enforcement |
+| Profile | Hooks | Use Case |
+|---------|-------|----------|
+| minimal | 3 | Fast iteration, vibe coding — maximum speed, minimum friction |
+| standard | 11 | Balanced quality + speed (recommended) — catches real issues |
+| strict | 17 | Production-grade enforcement — full security, accessibility, perf budgets |
 
-Change profile: Edit `hookProfile` in `.claude/settings.json` or use `/vibe` context.
+Change profile: set `ERNE_PROFILE` env var, add `<!-- Hook Profile: standard -->` to CLAUDE.md, or use `/vibe` context.
 
 ## Commands
 
-Core: `/plan`, `/code-review`, `/tdd`, `/build-fix`, `/perf`, `/upgrade`, `/native-module`, `/navigate`
+**Core:** `/plan`, `/code-review`, `/tdd`, `/build-fix`, `/perf`, `/upgrade`, `/native-module`, `/navigate`
+
+**Extended:** `/animate`, `/deploy`, `/component`, `/debug`, `/quality-gate`
 
-Extended: `/animate`, `/deploy`, `/component`, `/debug`, `/quality-gate`
+**Learning:** `/learn`, `/retrospective`, `/setup-device`
+
+## Architecture
+
+```
+Claude Code Hooks ──▶ run-with-flags.js ──▶ Profile gate ──▶ Hook scripts
+                                                │
+                                     ┌──────────┴──────────┐
+                                     │   Only hooks for    │
+                                     │   active profile    │
+                                     │   are executed      │
+                                     └─────────────────────┘
+
+erne dashboard ──▶ HTTP + WS Server ──▶ Browser Canvas
+                        ▲
+Claude Code PreToolUse ─┤  (Agent pattern)
+Claude Code PostToolUse ┘
+```
 
-Learning: `/learn`, `/retrospective`, `/setup-device`
+**Key design principles:**
+- **Zero runtime dependencies** for the harness itself (ws package only for dashboard)
+- **Conditional loading** — rules, skills, and hooks load based on project type and profile
+- **Fresh subagent per task** — no context pollution between agent invocations
+- **Silent failure** — hooks never block Claude Code if something goes wrong
 
 ## Available On
 

package/agents/feature-builder.md

@@ -0,0 +1,88 @@
+---
+name: feature-builder
+description: Focused feature implementation — individual screens, components, hooks, and API endpoints. Designed to work in parallel with senior-developer. Triggered by /code, /feature, /component.
+---
+
+You are the ERNE Feature Builder agent — a focused React Native/Expo implementation specialist who builds individual feature units quickly and correctly.
+
+## Your Role
+
+Implement discrete feature units: a single screen, a custom hook, an API integration module, or a reusable component. You work best when given a clear, scoped task — often in parallel with the senior-developer agent on different parts of the same feature.
+
+## Capabilities
+
+- **Screen building**: Implement individual screens with proper data fetching and state handling
+- **Hook extraction**: Build focused custom hooks with clean interfaces and error handling
+- **API modules**: Create typed API client methods, TanStack Query wrappers, and cache invalidation
+- **Component building**: Build reusable UI components with props API, accessibility, and platform variants
+- **Utility modules**: Implement formatters, validators, transforms, and platform-specific helpers
+- **Migration scripts**: Write codemods and data migration utilities
+
+## Tech Stack
+
+```tsx
+// Screen with data fetching
+export const ProfileScreen = () => {
+  const { id } = useLocalSearchParams<{ id: string }>();
+  const { data: user, isLoading, error } = useUser(id);
+
+  if (isLoading) return <LoadingSkeleton />;
+  if (error) return <ErrorView error={error} onRetry={refetch} />;
+  if (!user) return <EmptyState message="User not found" />;
+
+  return (
+    <ScrollView contentContainerStyle={styles.container}>
+      <ProfileHeader user={user} />
+      <ProfileStats stats={user.stats} />
+      <ProfileActions userId={user.id} />
+    </ScrollView>
+  );
+};
+
+// Custom hook
+export const useUser = (userId: string) => {
+  return useQuery({
+    queryKey: ['user', userId],
+    queryFn: () => apiClient.get<User>(`/users/${userId}`),
+    enabled: !!userId,
+    staleTime: 5 * 60 * 1000,
+  });
+};
+```
+
+## Process
+
+1. **Receive scoped task** — One screen, one hook, one module at a time
+2. **Check dependencies** — Verify types, API contracts, and shared state are defined
+3. **Implement** — Write the code with all states handled (loading, error, empty, success)
+4. **Type everything** — Explicit return types, param interfaces, no `any`
+5. **Handle edges** — Null checks, empty arrays, network failures, platform differences
+6. **Deliver** — Complete file ready to integrate
+
+## Parallel Work Pattern
+
+When working alongside senior-developer:
+- **Senior-developer** handles: data layer, stores, navigation skeleton, complex multi-screen flows
+- **Feature-builder** handles: individual screens, isolated components, utility hooks, API wrappers
+- Coordinate via shared type definitions and agreed interfaces
+- Never modify files the other agent is actively editing
+
+## Guidelines
+
+- Functional components with `const` + arrow functions, named exports only
+- Group imports: react → react-native → expo → external → internal → types
+- Max 250 lines per file — if larger, you're doing too much
+- `StyleSheet.create()` always, no inline styles
+- Handle all UI states: loading, error, empty, success
+- Every public function needs a TypeScript return type
+- No `any` — use `unknown` and narrow, or define the type
+- Accessibility: `accessibilityLabel`, `accessibilityRole`, `accessibilityHint` on interactive elements
+- Test-ready: props-based, no hidden global state, injectable dependencies
+
+## Output Format
+
+For each unit:
+1. File path and complete code
+2. Props/params interface
+3. Dependencies (what it imports from other modules)
+4. Integration point (how the parent screen/module uses it)

package/agents/senior-developer.md

@@ -0,0 +1,77 @@
+---
+name: senior-developer
+description: End-to-end feature implementation — screens, hooks, API integration, state management, navigation wiring. Triggered by /code, /feature, /plan (implementation phase).
+---
+
+You are the ERNE Senior Developer agent — a senior React Native/Expo engineer who writes production-grade feature code.
+
+## Your Role
+
+Implement complete features end-to-end: screens, custom hooks, API integration, state management, navigation wiring, and error handling. You are the one who turns architect plans into working code.
+
+## Capabilities
+
+- **Screen implementation**: Build full screens with data fetching, loading/error states, pull-to-refresh, pagination
+- **Custom hooks**: Extract reusable logic into typed hooks (`useAuth`, `useForm`, `useDebounce`, etc.)
+- **API integration**: Wire TanStack Query mutations/queries, handle optimistic updates, error boundaries
+- **State management**: Implement Zustand stores for client state, connect TanStack Query for server state
+- **Navigation wiring**: Create Expo Router layouts, typed navigation params, deep link handlers
+- **Form handling**: Build validated forms with proper keyboard handling, accessibility, and submission logic
+- **Error handling**: Implement error boundaries, retry logic, user-facing error messages, offline fallbacks
+
+## Tech Stack
+
+```tsx
+// Data fetching — TanStack Query
+const { data, isLoading } = useQuery({
+  queryKey: ['users', userId],
+  queryFn: () => api.getUser(userId),
+});
+
+// Client state — Zustand
+const useAuthStore = create<AuthState>()((set) => ({
+  user: null,
+  setUser: (user) => set({ user }),
+  logout: () => set({ user: null }),
+}));
+
+// Navigation — Expo Router (typed)
+import { useLocalSearchParams, router } from 'expo-router';
+
+type Params = { id: string; mode: 'edit' | 'view' };
+const { id, mode } = useLocalSearchParams<Params>();
+
+// Secure storage
+import * as SecureStore from 'expo-secure-store';
+```
+
+## Process
+
+1. **Read the plan** — Understand the architect's design, component hierarchy, and data flow
+2. **Set up the skeleton** — Create files, routes, and type definitions
+3. **Implement data layer first** — API client, queries/mutations, stores
+4. **Build screens** — Wire data to UI, handle all states (loading, error, empty, success)
+5. **Add navigation** — Route params, transitions, deep links, back handling
+6. **Handle edge cases** — Offline, token expiry, race conditions, keyboard avoidance
+7. **Self-review** — Check for re-renders, missing error handling, accessibility, type safety
+
+## Guidelines
+
+- Functional components with `const` + arrow functions, named exports only
+- Group imports: react → react-native → expo → external → internal → types
+- Max 250 lines per component — extract hooks and subcomponents when larger
+- `StyleSheet.create()` for styles, no inline styles
+- `FlashList` over `FlatList` for 100+ items
+- Memoize with `React.memo`, `useMemo`, `useCallback` where measurable
+- No anonymous functions in JSX render paths
+- Validate all deep link params and external input
+- Use `expo-secure-store` for tokens, never AsyncStorage
+- Conventional Commits: `feat:`, `fix:`, `refactor:`
+
+## Output Format
+
+For each implementation unit:
+1. File path and complete code
+2. Type definitions (interfaces, params)
+3. Integration notes (how it connects to other modules)
+4. Known trade-offs or TODOs for follow-up

package/bin/cli.js

@@ -8,11 +8,11 @@
 
 'use strict';
 
-const { resolve, join } = require('path');
-
 const COMMANDS = {
   init: () => require('../lib/init'),
   update: () => require('../lib/update'),
+  dashboard: () => require('../lib/dashboard'),
+  start: () => require('../lib/start'),
   version: () => {
     const pkg = require('../package.json');
     console.log(`erne v${pkg.version}`);
@@ -28,6 +28,8 @@ const COMMANDS = {
   Commands:
     init       Set up ERNE in your project
     update     Update to the latest version
+    dashboard  Launch the ERNE Agent Dashboard
+    start      Init project and start dashboard
     version    Show installed version
     help       Show this help message
 

package/dashboard/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "erne-dashboard",
+  "version": "1.0.0",
+  "private": true,
+  "description": "ERNE Agent Visual Dashboard",
+  "main": "server.js",
+  "dependencies": {
+    "ws": "^8.0.0"
+  }
+}

package/dashboard/public/agents.js

@@ -0,0 +1,329 @@
+/**
+ * ERNE Dashboard — Procedural 32x32 pixel-art agent sprites with animations
+ */
+(function () {
+  'use strict';
+
+  const FRAME_SIZE = 32;
+  const SHEET_COLS = 4;
+  const SHEET_ROWS = 4;
+  const SHEET_W = FRAME_SIZE * SHEET_COLS; // 128
+  const SHEET_H = FRAME_SIZE * SHEET_ROWS; // 128
+  const ANIM_FPS = 12;
+
+  const SKIN = '#FDBCB4';
+  const HAIR = '#4A3728';
+  const LEGS_COLOR = '#2c3e50';
+
+  const AGENT_DEFS = {
+    architect:              { bodyColor: '#3498db', traitColor: '#2980b9', trait: 'hardhat' },
+    'native-bridge-builder': { bodyColor: '#e74c3c', traitColor: '#c0392b', trait: 'wrench' },
+    'expo-config-resolver': { bodyColor: '#9b59b6', traitColor: '#8e44ad', trait: 'gear' },
+    'ui-designer':          { bodyColor: '#e91e63', traitColor: '#c2185b', trait: 'paintbrush' },
+    'code-reviewer':        { bodyColor: '#2ecc71', traitColor: '#27ae60', trait: 'glasses' },
+    'upgrade-assistant':    { bodyColor: '#f39c12', traitColor: '#e67e22', trait: 'arrow' },
+    'tdd-guide':            { bodyColor: '#1abc9c', traitColor: '#16a085', trait: 'testtube' },
+    'performance-profiler': { bodyColor: '#e67e22', traitColor: '#d35400', trait: 'stopwatch' },
+    'senior-developer':     { bodyColor: '#3455db', traitColor: '#2a44b0', trait: 'laptop' },
+    'feature-builder':      { bodyColor: '#00bcd4', traitColor: '#0097a7', trait: 'hammer' },
+  };
+
+  /* ---- Drawing primitives ---- */
+
+  const drawCharacter = (ctx, ox, oy, def, headBob, typing, armOffset) => {
+    const hb = headBob || 0;
+    const ao = armOffset || 0;
+
+    // Legs
+    ctx.fillStyle = LEGS_COLOR;
+    ctx.fillRect(ox + 11, oy + 24, 4, 6);
+    ctx.fillRect(ox + 17, oy + 24, 4, 6);
+
+    // Body
+    ctx.fillStyle = def.bodyColor;
+    ctx.fillRect(ox + 9, oy + 14, 14, 11);
+    // Shirt detail
+    ctx.fillStyle = def.traitColor;
+    ctx.fillRect(ox + 14, oy + 15, 4, 3);
+
+    // Arms
+    ctx.fillStyle = def.bodyColor;
+    ctx.fillRect(ox + 5, oy + 15 + ao, 4, 8);
+    ctx.fillRect(ox + 23, oy + 15 - ao, 4, 8);
+
+    // Hands
+    ctx.fillStyle = SKIN;
+    ctx.fillRect(ox + 5, oy + 23 + ao, 4, 3);
+    ctx.fillRect(ox + 23, oy + 23 - ao, 4, 3);
+
+    // Head
+    ctx.fillStyle = SKIN;
+    ctx.fillRect(ox + 10, oy + 4 + hb, 12, 11);
+
+    // Hair
+    ctx.fillStyle = HAIR;
+    ctx.fillRect(ox + 9, oy + 3 + hb, 14, 4);
+    ctx.fillRect(ox + 9, oy + 4 + hb, 2, 6);
+
+    // Eyes
+    ctx.fillStyle = '#222';
+    ctx.fillRect(ox + 13, oy + 8 + hb, 2, 2);
+    ctx.fillRect(ox + 18, oy + 8 + hb, 2, 2);
+
+    // Mouth
+    ctx.fillStyle = '#c0392b';
+    ctx.fillRect(ox + 14, oy + 12 + hb, 4, 1);
+
+    drawTrait(ctx, ox, oy + hb, def);
+  };
+
+  const drawWalkingCharacter = (ctx, ox, oy, def, legOffset) => {
+    const lo = legOffset || 0;
+
+    // Legs — walk cycle
+    ctx.fillStyle = LEGS_COLOR;
+    ctx.fillRect(ox + 11, oy + 24 + lo, 4, 6);
+    ctx.fillRect(ox + 17, oy + 24 - lo, 4, 6);
+
+    // Body
+    ctx.fillStyle = def.bodyColor;
+    ctx.fillRect(ox + 9, oy + 14, 14, 11);
+    ctx.fillStyle = def.traitColor;
+    ctx.fillRect(ox + 14, oy + 15, 4, 3);
+
+    // Arms swing
+    ctx.fillStyle = def.bodyColor;
+    ctx.fillRect(ox + 5, oy + 15 - lo, 4, 8);
+    ctx.fillRect(ox + 23, oy + 15 + lo, 4, 8);
+    ctx.fillStyle = SKIN;
+    ctx.fillRect(ox + 5, oy + 23 - lo, 4, 3);
+    ctx.fillRect(ox + 23, oy + 23 + lo, 4, 3);
+
+    // Head
+    ctx.fillStyle = SKIN;
+    ctx.fillRect(ox + 10, oy + 4, 12, 11);
+    ctx.fillStyle = HAIR;
+    ctx.fillRect(ox + 9, oy + 3, 14, 4);
+    ctx.fillRect(ox + 9, oy + 4, 2, 6);
+    ctx.fillStyle = '#222';
+    ctx.fillRect(ox + 13, oy + 8, 2, 2);
+    ctx.fillRect(ox + 18, oy + 8, 2, 2);
+    ctx.fillStyle = '#c0392b';
+    ctx.fillRect(ox + 14, oy + 12, 4, 1);
+
+    drawTrait(ctx, ox, oy, def);
+  };
+
+  const drawTrait = (ctx, ox, oy, def) => {
+    switch (def.trait) {
+      case 'hardhat':
+        ctx.fillStyle = '#f1c40f';
+        ctx.fillRect(ox + 8, oy + 1, 16, 4);
+        ctx.fillRect(ox + 10, oy - 1, 12, 3);
+        break;
+      case 'wrench':
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 24, oy + 5, 3, 8);
+        ctx.fillRect(ox + 23, oy + 4, 5, 3);
+        break;
+      case 'gear':
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 25, oy + 5, 5, 5);
+        ctx.fillStyle = def.bodyColor;
+        ctx.fillRect(ox + 26, oy + 6, 3, 3);
+        break;
+      case 'paintbrush':
+        ctx.fillStyle = '#8B4513';
+        ctx.fillRect(ox + 25, oy + 6, 2, 10);
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 24, oy + 4, 4, 3);
+        break;
+      case 'glasses':
+        ctx.fillStyle = '#FFD700';
+        ctx.fillRect(ox + 11, oy + 7, 6, 4);
+        ctx.fillRect(ox + 16, oy + 7, 6, 4);
+        ctx.fillStyle = 'rgba(255,255,255,0.3)';
+        ctx.fillRect(ox + 12, oy + 8, 4, 2);
+        ctx.fillRect(ox + 17, oy + 8, 4, 2);
+        ctx.fillStyle = '#FFD700';
+        ctx.fillRect(ox + 17, oy + 8, 1, 1);
+        break;
+      case 'arrow':
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 25, oy + 4, 3, 8);
+        ctx.fillStyle = '#fff';
+        ctx.fillRect(ox + 24, oy + 3, 5, 3);
+        ctx.fillRect(ox + 25, oy + 2, 3, 2);
+        break;
+      case 'testtube':
+        ctx.fillStyle = '#ecf0f1';
+        ctx.fillRect(ox + 25, oy + 4, 3, 10);
+        ctx.fillStyle = '#2ecc71';
+        ctx.fillRect(ox + 25, oy + 10, 3, 4);
+        ctx.fillRect(ox + 24, oy + 13, 5, 2);
+        break;
+      case 'stopwatch':
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 24, oy + 4, 6, 6);
+        ctx.fillStyle = '#fff';
+        ctx.fillRect(ox + 25, oy + 5, 4, 4);
+        ctx.fillStyle = '#333';
+        ctx.fillRect(ox + 27, oy + 5, 1, 3);
+        ctx.fillRect(ox + 26, oy + 3, 2, 2);
+        break;
+      case 'laptop':
+        ctx.fillStyle = '#333';
+        ctx.fillRect(ox + 23, oy + 8, 7, 5);
+        ctx.fillStyle = '#5dade2';
+        ctx.fillRect(ox + 24, oy + 9, 5, 3);
+        ctx.fillStyle = '#555';
+        ctx.fillRect(ox + 22, oy + 13, 9, 2);
+        break;
+      case 'hammer':
+        ctx.fillStyle = '#8B4513';
+        ctx.fillRect(ox + 26, oy + 6, 2, 10);
+        ctx.fillStyle = def.traitColor;
+        ctx.fillRect(ox + 23, oy + 3, 8, 4);
+        break;
+    }
+  };
+
+  const drawCheckmark = (ctx, ox, oy, frame) => {
+    const bounce = Math.max(0, 3 - frame);
+    ctx.fillStyle = '#2ecc71';
+    ctx.fillRect(ox + 10, oy - 6 - bounce, 12, 10);
+    ctx.fillStyle = '#fff';
+    // Checkmark shape
+    ctx.fillRect(ox + 13, oy - 2 - bounce, 2, 2);
+    ctx.fillRect(ox + 14, oy - 1 - bounce, 2, 2);
+    ctx.fillRect(ox + 15, oy - 2 - bounce, 2, 2);
+    ctx.fillRect(ox + 16, oy - 3 - bounce, 2, 2);
+    ctx.fillRect(ox + 17, oy - 4 - bounce, 2, 2);
+  };
+
+  /* ---- Sprite sheet generation ---- */
+
+  const generateSpriteSheet = (agentName) => {
+    const def = AGENT_DEFS[agentName];
+    if (!def) return null;
+
+    const canvas = document.createElement('canvas');
+    canvas.width = SHEET_W;
+    canvas.height = SHEET_H;
+    const ctx = canvas.getContext('2d');
+
+    // Row 0: IDLE (4 frames, head bob on frames 1,2)
+    for (let f = 0; f < 4; f++) {
+      const hb = (f === 1 || f === 2) ? -1 : 0;
+      drawCharacter(ctx, f * FRAME_SIZE, 0, def, hb, false, 0);
+    }
+
+    // Row 1: WORKING (4 frames, typing arm offset alternating)
+    for (let f = 0; f < 4; f++) {
+      const ao = (f % 2 === 0) ? -2 : 2;
+      drawCharacter(ctx, f * FRAME_SIZE, FRAME_SIZE, def, 0, true, ao);
+    }
+
+    // Row 2: MOVING (4 frames, walk cycle leg offset)
+    const legOffsets = [-2, 0, 2, 0];
+    for (let f = 0; f < 4; f++) {
+      drawWalkingCharacter(ctx, f * FRAME_SIZE, FRAME_SIZE * 2, def, legOffsets[f]);
+    }
+
+    // Row 3: DONE (4 frames, checkmark popup)
+    for (let f = 0; f < 4; f++) {
+      drawCharacter(ctx, f * FRAME_SIZE, FRAME_SIZE * 3, def, 0, false, 0);
+      drawCheckmark(ctx, f * FRAME_SIZE, FRAME_SIZE * 3, f);
+    }
+
+    return canvas;
+  };
+
+  /* ---- State manager ---- */
+
+  const STATUS_TO_ROW = {
+    idle: 0,
+    working: 1,
+    moving: 2,
+    done: 3,
+  };
+
+  const agentSprites = {};
+
+  const initAgentSprites = () => {
+    for (const name of Object.keys(AGENT_DEFS)) {
+      const pos = window.OfficeCanvas.getAgentDeskPosition(name);
+      if (!pos) continue;
+      agentSprites[name] = {
+        sheet: generateSpriteSheet(name),
+        x: pos.x,
+        y: pos.y,
+        status: 'idle',
+        frame: 0,
+        frameTimer: 0,
+      };
+    }
+  };
+
+  const updateAgentState = (name, status) => {
+    if (!agentSprites[name]) return;
+    agentSprites[name].status = status;
+    agentSprites[name].frame = 0;
+    agentSprites[name].frameTimer = 0;
+  };
+
+  const updateAgentSprites = (dt) => {
+    for (const sprite of Object.values(agentSprites)) {
+      sprite.frameTimer += dt;
+      const frameDuration = 1 / ANIM_FPS;
+      if (sprite.frameTimer >= frameDuration) {
+        sprite.frameTimer -= frameDuration;
+        sprite.frame = (sprite.frame + 1) % SHEET_COLS;
+      }
+    }
+  };
+
+  const STATUS_DOT_COLORS = {
+    idle: '#9E9E9E',
+    working: '#4CAF50',
+    done: '#2196F3',
+  };
+
+  const drawAgentSprites = (ctx) => {
+    for (const [name, sprite] of Object.entries(agentSprites)) {
+      const row = STATUS_TO_ROW[sprite.status] || 0;
+      const sx = sprite.frame * FRAME_SIZE;
+      const sy = row * FRAME_SIZE;
+
+      ctx.drawImage(
+        sprite.sheet,
+        sx, sy, FRAME_SIZE, FRAME_SIZE,
+        sprite.x - FRAME_SIZE / 2, sprite.y - FRAME_SIZE / 2,
+        FRAME_SIZE, FRAME_SIZE
+      );
+
+      // Status dot
+      const dotColor = STATUS_DOT_COLORS[sprite.status] || '#9E9E9E';
+      ctx.fillStyle = dotColor;
+      ctx.beginPath();
+      ctx.arc(sprite.x, sprite.y - FRAME_SIZE / 2 - 4, 3, 0, Math.PI * 2);
+      ctx.fill();
+
+      // Name label
+      ctx.fillStyle = '#E0E0E0';
+      ctx.font = '8px monospace';
+      ctx.textAlign = 'center';
+      const shortName = name.length > 12 ? name.substring(0, 11) + '\u2026' : name;
+      ctx.fillText(shortName, sprite.x, sprite.y + FRAME_SIZE / 2 + 8);
+    }
+  };
+
+  window.AgentSprites = {
+    AGENT_DEFS,
+    agentSprites,
+    initAgentSprites,
+    updateAgentState,
+    updateAgentSprites,
+    drawAgentSprites,
+  };
+})();