agentviz copilot-instructions.md

AGENTVIZ

Session replay visualizer for AI agent workflows (Claude Code, VS Code Copilot Chat, Copilot CLI).

Stack

• React 18 + Vite 6, inline styles only, JetBrains Mono font
• Mixed JS/TS: components and hooks are plain JSX, parsers and data libs are TypeScript
• Design tokens in src/lib/theme.js

Commands

npm run dev          # Dev server
npm run build        # Production build to dist/
npm test             # Run tests via Vitest
npm run test:watch   # Watch mode
npm run typecheck    # tsc --noEmit

Rules

• Search existing code before writing new abstractions.
• Run tests after every non-trivial change.
• Prefer editing existing files over creating new ones.
• Never silently apply config changes — surface drafts first.
• Product name is always AGENTVIZ (all caps, no spaces). Never "AgentViz" or "Agentviz".
• All UI changes must conform to docs/ui-ux-style-guide.md. Review the checklist at the bottom of that file before approving any PR that touches components, styles, or visual behavior.

Five-Artifact Sync Rule

Every UI change must update ALL FIVE of these before committing. Never let them drift:

1. README.md — feature descriptions, architecture section, file tree
2. docs/ui-ux-style-guide.md — token values, patterns, rules
3. docs/color-palette.html — visual swatch reference; hex values must match theme.js and the style guide
4. docs/screenshots/ — all 8 screenshots (see Screenshots section below)
5. Repo memory — store any new conventions with store_memory

Screenshots

The README references 8 screenshot files in docs/screenshots/. All must be kept in sync.

Files: landing.png, session-hero.png, replay-view.png, tracks-view.png, waterfall-view.png, graph-view.png, stats-view.png, coach-view.png

Workflow (using Playwright MCP tools):

1. Start dev server: npm run dev
2. Navigate to http://127.0.0.1:3000, resize to 1400x860
3. Capture landing.png from the landing page (before loading a session)
4. Click "Load a demo session", then click each tab and capture: replay, tracks, waterfall, graph, stats
5. For Coach: click the tab, hide the error banner with JS before capturing:

   document.querySelectorAll('*').forEach(el => {
     if (el.children.length === 0 && el.textContent.trim().startsWith('AI analysis failed')) {
       let n = el;
       for (let i = 0; i < 6; i++) {
         if (n.parentElement?.textContent.trim().startsWith('AI analysis failed')) n = n.parentElement;
         else break;
       }
       n.style.display = 'none';
     }
   });
   

6. Copy replay-view.png to session-hero.png (hero reuses replay image)