nexus/docs/plans/2026-04-11-nexus-phase-9-assistant.md

# Nexus Phase 9 — Assistant Mode Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:test-driven-development` for each unit. Commit atomically per logical unit (see §Commit scheme).

**Goal:** Rebuild the Assistant experience at `/assistant` as the canonical home screen of Nexus — full-bleed chat with no inner conversation-list column, History + Memory slide-overs, a conversational "home greeting" state when no conversation is active, and an action strip that includes Promote-to-Project (the transition is Phase 12's job, not Phase 9's — Phase 9 just wires the button).

**Source of truth:** `docs/specs/2026-04-11-nexus-layout-overhaul.md` **§5** (Mode 1 — Assistant). Read §5.1–§5.7 end-to-end before starting. DESIGN.md governs all visuals. Phase 8 components at `ui/src/components/frame/*` are the reference pattern for new UI pieces.

**Branch:** `nexus/design-system-migration`. Commit directly; do not create a worktree.

---

## Ownership boundaries

**You may create or modify ONLY the following paths:**

| Path | Action |
|---|---|
| `ui/src/pages/PersonalAssistant.tsx` | Modify (major rewrite) |
| `ui/src/components/assistant/**` | Create (new subdir for Phase 9 components) |
| `ui/src/hooks/useAssistantHomeStatus.ts` | Create (new hook for home-state greeting data) |

**You MUST NOT touch:**

- `ui/src/App.tsx` — routing is controller-owned. If your rewrite needs a new route, STOP and report it in your final report; the controller will wire it up after Wave 2 completes.
- `ui/src/components/ChatPanel.tsx` — the old global slide-in chat panel. Phase 8 killed it from the Layout chrome; Phase 16 deletes the file. Do not edit it in Phase 9.
- `ui/src/components/MobileChatView.tsx` — Phase 9 is desktop only. Mobile parity is Phase 15.
- `ui/src/context/ChatPanelContext.tsx` — legacy. Phase 9's Assistant route does not consume this context.
- `ui/src/components/Layout.tsx` — already rewritten in Phase 8, do not touch.
- Any file under `server/`, `packages/`, `cli/`. Phase 9 is UI-only; the backend chat streaming, voice pipeline, and memory APIs are already built (v1.3–v1.6).
- Any file outside `ui/src/` except as noted in this plan.

**Existing code you may reuse (read-only dependencies):**

- `ui/src/components/ChatMessageList.tsx` — existing message thread renderer. Consume it as-is.
- `ui/src/components/ChatInput.tsx` — existing text input with Enter/Shift-Enter handling. Consume it as-is inside the new AssistantInputBar wrapper.
- `ui/src/components/VoiceWaveform.tsx` — existing visualizer. Lift it into the new layout.
- `ui/src/components/ChatAgentSelector.tsx` — agent selector popover. Use it as-is in the conversation header.
- `ui/src/hooks/useStreamingChat.ts` — SSE streaming hook. Reuse as-is.
- `ui/src/api/chat.ts` (or whatever the chat API client is named) — do not modify.
- `ui/src/components/frame/*` — Phase 8 patterns (createRoot test pattern, semantic tokens, focus-visible styles, cn helper).

If you need a component that already exists in `ui/src/components/` but isn't listed above, read it first to understand its contract, then reuse it. Do not duplicate functionality.

---

## Scope (strictly)

**In Phase 9:**

1. **Full-bleed chat surface** at `/assistant` — no inner conversation-list column, max-width 760px centered in canvas, messages alternate left/right.
2. **AssistantInputBar** — focal element at the bottom. Voice waveform visible above the text input, hairline divider between, generous 24px vertical padding, near-black `#141414` fill, charcoal border, sharp 8px radius.
3. **ActionStrip** — 4 actions below the input bar: `⊕ Promote to project` (volt outline, eligibility TBD but render button always for Phase 9 — Phase 12 wires the transition), `📎 Attach` (reuses existing upload flow), `🧠 Memory` (opens MemorySheet), `📁 History` (opens HistorySheet).
4. **HistorySheet** — left slide-over, 320px wide, butts against the icon rail. Lists conversations grouped by today/yesterday/this-week/older. Uses existing `ChatConversationList.tsx` as the inner content; wraps it in a slide-over container with close-on-outside-click and ESC-key-to-close.
5. **MemorySheet** — right slide-over, 340px wide. Displays what the assistant remembers about the user, with simple edit controls (reuses existing memory API if one exists; if not, render a read-only view with a "coming soon" placeholder for edit). Close-on-outside-click and ESC.
6. **AssistantHomeGreeting** — when there is no active conversation, render a synthesized greeting message at the top of the empty thread. Lists: active agents (count), pending gates (count), recent completions (list of up to 3), stale projects (list of up to 3). Data comes from a new `useAssistantHomeStatus` hook that reads existing endpoints (projects list, agents list, approvals/gates list, activity feed). Rendered as an assistant-turn bubble, NOT as a grid of widgets.
7. **PersonalAssistant.tsx rewrite** — rewire to compose the new pieces. Kill the 160px inner conversation-list column. Kill any hardcoded right-panel logic. Preserve existing streaming, voice I/O, agent switching, handoff-to-PM.

**NOT in Phase 9 (explicitly deferred):**

- The promote-to-project animated transition (Phase 12). Phase 9 renders the button; Phase 12 wires the 700ms compress-and-rise animation.
- Voice routing from non-Assistant modes to the Assistant inbox (Phase 14).
- The globalized ⌘K palette searching across conversations (Phase 14).
- Mobile full-screen chat (Phase 15 — keep existing MobileChatView untouched for now; Phase 9 is desktop-only).
- Any visual edge-polish beyond what the semantic tokens already produce.
- Memory API changes or new persistence. If no memory API exists, render MemorySheet as read-only "coming soon" stub.
- Editing the home-greeting data source or the underlying endpoints. Compose from what exists.
- Deletion of `ChatPanel.tsx` / `ChatPanelContext.tsx` — Phase 16 cleanup.

---

## File plan

### Create

| File | Responsibility | Est. lines |
|---|---|---|
| `ui/src/components/assistant/AssistantInputBar.tsx` | Voice waveform + text input composite with hairline divider. Wraps existing `ChatInput` and `VoiceWaveform`. | ~80 |
| `ui/src/components/assistant/AssistantInputBar.test.tsx` | Tests: renders waveform + input, forwards onSend, shows correct state when streaming | ~100 |
| `ui/src/components/assistant/ActionStrip.tsx` | 4-action row: Promote, Attach, Memory, History. Icon + label buttons, volt outline on Promote when eligible. | ~90 |
| `ui/src/components/assistant/ActionStrip.test.tsx` | Tests: all 4 buttons render, onClick callbacks fire, Promote disabled when `canPromote={false}` | ~120 |
| `ui/src/components/assistant/HistorySheet.tsx` | Left slide-over (320px), close-on-outside-click, ESC-to-close. Wraps existing `ChatConversationList`. | ~90 |
| `ui/src/components/assistant/HistorySheet.test.tsx` | Tests: opens when `open`, closes on ESC, closes on backdrop click, renders conversation list inside | ~100 |
| `ui/src/components/assistant/MemorySheet.tsx` | Right slide-over (340px). Read-only memory view with placeholder edit hook. | ~90 |
| `ui/src/components/assistant/MemorySheet.test.tsx` | Tests: open/close, renders memory content, read-only mode disables edit | ~80 |
| `ui/src/components/assistant/AssistantHomeGreeting.tsx` | Synthesized home-state message rendered as an assistant-turn bubble when no active conversation. | ~100 |
| `ui/src/components/assistant/AssistantHomeGreeting.test.tsx` | Tests: renders greeting when no conversation, lists active agents/pending gates/etc., hidden when conversation active | ~110 |
| `ui/src/hooks/useAssistantHomeStatus.ts` | Data hook: aggregates projects, agents, gates, activity from existing APIs. Returns `{ activeAgents, pendingGates, recentCompletions, staleProjects, loading }`. | ~80 |
| `ui/src/hooks/useAssistantHomeStatus.test.ts` | Tests: aggregates correctly, handles loading state, handles errors | ~100 |

### Modify

| File | Change |
|---|---|
| `ui/src/pages/PersonalAssistant.tsx` | Major rewrite: compose new pieces, remove inner conversation list column, remove any right-panel logic, preserve streaming + voice + handoff |

**Do not create or modify any other files.**

---

## Implementation notes

### Layout skeleton (the target JSX)

```tsx
// ui/src/pages/PersonalAssistant.tsx (simplified target structure)
export function PersonalAssistant() {
  const { conversationId } = useParams();
  const [historyOpen, setHistoryOpen] = useState(false);
  const [memoryOpen, setMemoryOpen] = useState(false);
  // ... existing chat state, streaming hook, voice state ...

  return (
    <div className="relative flex h-full flex-col">
      {/* conversation thread: max-w-[760px] centered */}
      <div className="flex-1 overflow-auto">
        <div className="mx-auto w-full max-w-[760px] px-6 py-8">
          {!activeConversation && <AssistantHomeGreeting />}
          {activeConversation && <ChatMessageList ... />}
        </div>
      </div>

      {/* input bar + action strip anchored at bottom */}
      <div className="border-t border-border bg-background">
        <div className="mx-auto w-full max-w-[760px] px-6 py-4">
          <AssistantInputBar ... />
          <ActionStrip
            canPromote={canPromoteCurrentConversation}
            onPromote={() => {/* Phase 12 wires the transition */}}
            onAttach={...}
            onOpenMemory={() => setMemoryOpen(true)}
            onOpenHistory={() => setHistoryOpen(true)}
          />
        </div>
      </div>

      {/* slide-overs */}
      <HistorySheet open={historyOpen} onClose={() => setHistoryOpen(false)} />
      <MemorySheet open={memoryOpen} onClose={() => setMemoryOpen(false)} />
    </div>
  );
}
```

### Design tokens to use (from Phase 1–3 migration and DESIGN.md)

- `bg-background` for canvas (pure black)
- `bg-card` for input-bar fill (`#141414` near-black)
- `border-border` for charcoal borders
- `text-primary` / `bg-primary` for volt accents
- `text-muted-foreground` for silver
- `rounded-[8px]` for input bar
- `rounded-[4px]` for small buttons/badges
- Inter weights via Tailwind defaults; no custom font classes needed
- Uppercase labels with `tracking-[0.1em]` for small section titles (matches ModeBreadcrumb)
- Focus-visible: `focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary focus-visible:ring-offset-2 focus-visible:ring-offset-background` on all interactive elements

### Slide-over pattern (reusable mental model for HistorySheet and MemorySheet)

Use a simple portal-free pattern:

```tsx
export function Sheet({
  open,
  onClose,
  side,              // "left" | "right"
  width,             // e.g. 320 or 340
  children,
  "aria-label": ariaLabel,
}: SheetProps) {
  // Close on ESC
  useEffect(() => {
    if (!open) return;
    const onKey = (e: KeyboardEvent) => e.key === "Escape" && onClose();
    document.addEventListener("keydown", onKey);
    return () => document.removeEventListener("keydown", onKey);
  }, [open, onClose]);

  if (!open) return null;
  return (
    <>
      {/* backdrop */}
      <button
        type="button"
        onClick={onClose}
        aria-label="Close"
        className="fixed inset-0 z-40 bg-black/40"
      />
      {/* panel */}
      <aside
        aria-label={ariaLabel}
        className={cn(
          "fixed top-12 bottom-0 z-50 bg-background border-border flex flex-col",
          side === "left" ? "left-[56px] border-r" : "right-0 border-l",
        )}
        style={{ width }}
      >
        {children}
      </aside>
    </>
  );
}
```

(`top-12` = 48px — below the TopStrip. `left-[56px]` on the left side = butts against the IconRail.)

You don't need to extract this into a shared `Sheet` primitive — inlining the same pattern twice in HistorySheet and MemorySheet is fine. But if you choose to extract, put it at `ui/src/components/assistant/Sheet.tsx` (still within your ownership).

### ActionStrip eligibility for Promote

For Phase 9, `canPromote` should be `true` when:
- There is an active conversation
- AND the conversation has at least one user message and one assistant message

Do not implement the actual brainstormer-eligibility check — that's Phase 12 territory. Phase 9 just needs a boolean that correctly enables/disables the button.

### AssistantHomeGreeting data shape

```ts
interface HomeStatus {
  activeAgents: number;          // count of agents currently working
  pendingGates: Array<{ projectName: string; gateName: string; href: string }>;
  recentCompletions: Array<{ projectName: string; summary: string; when: string }>;
  staleProjects: Array<{ name: string; lastActivity: string; href: string }>;
  loading: boolean;
}
```

The `useAssistantHomeStatus` hook reads:
- Active agents: from existing `agentsApi` or similar — filter by `status === "working"`
- Pending gates: from existing `approvalsApi` (still named "approvals" in the backend; the UI label is "Gates" but the API endpoint stays as `/api/approvals`) — filter by `status === "pending"`
- Recent completions: from existing `activityApi` — last 24h, filter by `type === "completion"` or similar
- Stale projects: from existing `projectsApi` — filter by `lastActivity > 3 days ago`

Do not create new API endpoints. Compose from what exists. If any of these endpoints are missing, gracefully degrade — return empty arrays and log a console.warn once in development.

### Rendering the home greeting

Not as a grid of widgets. Render as an assistant-turn chat bubble with formatted markdown content:

```
Good morning, Mikkel.

Since we last talked:
 • nexus-design-migration: 4 commits, Phase 4 ready
 • personal-finance-dashboard: idle 3 days
 • 1 gate awaiting approval (nexus, Phase 4 audit)

What do you want to do?
```

Reuse existing markdown rendering components (`ChatMarkdownMessage.tsx` or similar) to match the rest of the chat visual language. The greeting should look indistinguishable from a real assistant turn.

---

## Acceptance criteria

Phase 9 is complete when:

1. Loading `/NEX/assistant` with no active conversation renders the AssistantHomeGreeting inside a max-w-760px centered column, with no inner left conversation list.
2. Loading `/NEX/assistant` with an active conversation renders the existing message thread using `ChatMessageList`, with no inner left conversation list.
3. The AssistantInputBar shows the voice waveform above the text input with a hairline divider between them, anchored at the bottom of the canvas.
4. The ActionStrip renders 4 buttons below the input bar: Promote (volt outline, disabled when no conversation), Attach, Memory, History.
5. Clicking History opens a left slide-over at 320px wide, butted against the 56px icon rail, showing the existing ChatConversationList inside. ESC closes. Backdrop click closes.
6. Clicking Memory opens a right slide-over at 340px wide. ESC closes. Backdrop click closes.
7. Streaming, voice I/O, agent switching, and handoff-to-PM from the existing PersonalAssistant still work — Phase 9 rewires composition but preserves functionality.
8. All new components have tests using the Phase 8 pattern (manual createRoot + act, `// @vitest-environment jsdom`, `vi.mock("@/context/CompanyContext", ...)` where `Link` is used).
9. `npx vitest run src/components/assistant/ src/hooks/useAssistantHomeStatus.test.ts` passes.
10. `npx tsc --noEmit 2>&1 | grep -E "assistant/|PersonalAssistant\.tsx|useAssistantHomeStatus"` returns no errors in Phase 9 files.
11. Typecheck on the full UI may still show pre-existing errors in other files — do not try to fix them.
12. No file outside the declared ownership is modified.

---

## Commit scheme

One atomic commit per logical unit. Each commit is independently reviewable. Prefix with `feat(nexus):` or `refactor(nexus):` per existing repo convention. Include `Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>` on every commit.

Suggested commits (adjust as needed):

1. `feat(nexus): add useAssistantHomeStatus hook (phase 9)` — the hook + its tests
2. `feat(nexus): add AssistantHomeGreeting component (phase 9)` — greeting + tests
3. `feat(nexus): add AssistantInputBar composite (phase 9)` — input bar + tests
4. `feat(nexus): add ActionStrip for assistant actions (phase 9)` — action strip + tests
5. `feat(nexus): add HistorySheet slide-over (phase 9)` — history sheet + tests
6. `feat(nexus): add MemorySheet slide-over (phase 9)` — memory sheet + tests
7. `refactor(nexus): rewire PersonalAssistant to use new frame pieces (phase 9)` — the main page rewrite

If you find a cleaner grouping, use it. Each commit must build and pass its own tests.

---

## Before you begin

Ask the controller (your dispatching session) questions if any of the following are unclear:

- The existing memory API — does it exist, and what's its shape?
- The existing `activityApi` / `approvalsApi` / `projectsApi` — what endpoints are available for the home greeting?
- Whether `ChatMessageList` / `ChatInput` / `VoiceWaveform` / `ChatConversationList` / `ChatMarkdownMessage` exist and what their props are (read their files first; if any are missing or named differently, report it)
- Anything in §5 of the spec that reads as ambiguous after a careful re-read

If you find a genuine architectural obstacle (e.g., `useStreamingChat` is tangled with the old ChatPanel context in a way that makes full-bleed rendering hard), STOP and report BLOCKED with the specifics. Do not silently invent workarounds.

---

## When you're in over your head

It is always OK to stop and say "this is too hard for me." Bad work is worse than no work. Escalate early if:

- You can't find a reference API for the home greeting data
- The existing chat state machine doesn't compose cleanly with the new layout
- Any of the reused components (ChatInput, ChatMessageList, etc.) turn out to need changes you're not allowed to make
- You hit a TypeScript error in a Phase 9 file you can't resolve
- Phase 8's Layout.tsx behavior conflicts with how PersonalAssistant wants to render

Report BLOCKED with specific details about what's stuck, what you've tried, and what kind of help you need.

---

## Report format (final)

When Phase 9 is complete or blocked, report:

- **Status:** DONE | DONE_WITH_CONCERNS | BLOCKED | NEEDS_CONTEXT
- **Commits produced:** list of SHAs with one-line summaries
- **Files created:** list
- **Files modified:** list (with line counts)
- **Tests added:** total count + per-file breakdown
- **Tests passing:** `npx vitest run src/components/assistant/ src/hooks/useAssistantHomeStatus.test.ts` output summary
- **Typecheck result:** grep output for Phase 9 files
- **Routing needs:** any new routes the controller needs to add to `App.tsx` after Wave 2 (describe the route pattern and the page component it maps to)
- **Open concerns:** anything the reviewer should look at specially
- **Deviations from the plan:** any places where you had to adapt because of codebase reality, with justification
- **Self-review findings:** what you found when re-reading your own code