---
phase: 22-agent-streaming
plan: "04"
subsystem: ui
tags: [react, slash-commands, mention, popover, shadcn, routing]

# Dependency graph
requires:
  - phase: 22-00
    provides: agent-role-colors, AgentRole type, Wave 0 test stubs
  - phase: 22-02
    provides: AgentIcon component from AgentIconPicker
provides:
  - ChatSlashCommandPopover component (260px, opens upward, 5 slash commands)
  - ChatMentionPopover component (200px, opens upward, agent autocomplete)
  - slash-commands.ts utility with SLASH_COMMANDS and resolveAgentFromContent
affects: [22-05, ChatInput wiring plan]

# Tech tracking
tech-stack:
  added: []
  patterns:
    - "Popover with side=top opens popovers upward anchored to textarea"
    - "onOpenAutoFocus prevented to preserve textarea focus during popover interaction"
    - "resolveAgentFromContent: slash command priority > @mention priority > active agent fallback"
    - "Disabled commands shown with opacity-50 and (Coming soon) suffix"

key-files:
  created:
    - ui/src/lib/slash-commands.ts
    - ui/src/components/ChatSlashCommandPopover.tsx
    - ui/src/components/ChatSlashCommandPopover.test.tsx
    - ui/src/components/ChatMentionPopover.tsx
    - ui/src/components/ChatMentionPopover.test.tsx
  modified: []

key-decisions:
  - "/search command defined with routesTo: null and disabled: true — displayed greyed with Coming soon suffix per UI spec"
  - "resolveAgentFromContent prioritizes slash commands over @mentions, falls back to activeAgentId"
  - "ChatMentionPopover limits display to 5 agents (slice(0,5)) with scroll container"
  - "// @vitest-environment jsdom pragma added to component tests for JSX dynamic import support"

patterns-established:
  - "Slash command routing: SLASH_COMMANDS array + resolveAgentFromContent function for agent routing from message content"
  - "Popover autocomplete pattern: Popover > PopoverTrigger asChild > PopoverContent (side=top, onOpenAutoFocus prevented)"

requirements-completed: [INPUT-05, INPUT-06]

# Metrics
duration: 4min
completed: 2026-04-01
---

# Phase 22 Plan 04: Slash Command and @Mention Popovers Summary

**Slash command routing table (5 commands, /search disabled) and agent @mention autocomplete popover — both standalone, wired into ChatInput in plan 05.**

## Performance

- **Duration:** 4 min
- **Started:** 2026-04-01T18:23:41Z
- **Completed:** 2026-04-01T18:27:49Z
- **Tasks:** 2 completed
- **Files modified:** 5

## Accomplishments

- Created `slash-commands.ts` with `SLASH_COMMANDS` (5 entries) and `resolveAgentFromContent` routing function that prioritizes slash commands over @mentions over active agent fallback
- Created `ChatSlashCommandPopover` — 260px popover opening upward with command list; /search greyed with "Coming soon" per UI spec
- Created `ChatMentionPopover` — 200px popover opening upward showing agent icon + name + role label, filtered by query, max 5 agents, loading skeleton, empty state

## Task Commits

1. **Task 1: Slash command routing utility and ChatSlashCommandPopover** - `99d01d9e` (feat)
2. **Task 2: ChatMentionPopover component** - `a3bb02c5` (feat)

## Files Created/Modified

- `ui/src/lib/slash-commands.ts` — SLASH_COMMANDS array and resolveAgentFromContent routing utility
- `ui/src/components/ChatSlashCommandPopover.tsx` — 260px slash command popover with cmdk Command component
- `ui/src/components/ChatSlashCommandPopover.test.tsx` — routing logic tests (5 pass) + export smoke test
- `ui/src/components/ChatMentionPopover.tsx` — 200px agent mention autocomplete with icon/name/role rows
- `ui/src/components/ChatMentionPopover.test.tsx` — export smoke test + 4 todo items for future wiring tests
- `ui/src/lib/agent-role-colors.ts` — dependency copy for worktree build (exists in phase-22 branch from plan 22-00)

## Deviations from Plan

### Auto-fixed Issues

**1. [Rule 3 - Blocking] Added jsdom pragma to component tests**
- **Found during:** Task 1 test verification
- **Issue:** Dynamic `import()` of JSX component failed with `react/jsx-dev-runtime` error in node test environment
- **Fix:** Added `// @vitest-environment jsdom` pragma to both test files, matching existing pattern in ChatAgentSelector.test.tsx
- **Files modified:** ChatSlashCommandPopover.test.tsx, ChatMentionPopover.test.tsx
- **Commit:** 99d01d9e

**2. [Rule 3 - Blocking] Added agent-role-colors.ts to worktree**
- **Found during:** Task 2 implementation
- **Issue:** Worktree branch lacks phase-22-00 foundation files; ChatMentionPopover imports agent-role-colors which didn't exist in worktree
- **Fix:** Created agent-role-colors.ts with identical content to phase-22 branch version
- **Files modified:** ui/src/lib/agent-role-colors.ts (new file, already exists on phase-22 branch)
- **Commit:** a3bb02c5
- **Note:** When cherry-picked to gsd/phase-22-agent-streaming, this will be a no-op (file already exists with same content)

## Known Stubs

- `ChatMentionPopover.test.tsx`: 4 `it.todo()` items for render/interaction tests — per plan spec, wiring tests deferred until ChatInput integration in plan 22-05
- `ChatSlashCommandPopover.test.tsx` component test section: export smoke test only — render/interaction tests deferred per plan spec

## Self-Check: PASSED