frontend-agent-chat-shell

Files (6)

• SKILL.md
• chat-shell-mockup.html · assets/
• cases.yaml · evals/
• results.json · evals/
• artifacts-resume-collaboration.md · references/
• chat-shell-composer-sessions.md · references/

SKILL.md (first lines)

# Agent Chat Shell

> The thread is not the product. Around every AI chat thread sits a shell — how a session is started,
> found, named, resumed, branched, shared, and how long-running work stays visible while the user is
> looking elsewhere. That shell is where agent-chat products are weakest, because every tutorial
> stops at the message list.

## The seam: this skill stops at the bubble

**Everything inside a message bubble belongs to `frontend-ai-generative-ui`.**

| This skill owns | `frontend-ai-generative-ui` owns |
|---|---|
| Sidebar, stack order, org primitives | The message list, virtualization |
| Recents as a live task surface | Scroll anchoring, jump-to-latest |
| Empty-state hero, onboarding slot | Token/markdown/code streaming render |
| Composer chrome, model chip, dictation vs voice | Tool-call cards, thinking disclosure |
| Sessions/projects/history + search | Message actions (copy/regenerate/edit) |
| Artifact **placement**, panel mechanics | Artifact **content** rendering |
| Stream **resume**, interrupted-response honesty | `aria-live`/`role=log`, SDK wiring |
| Mobile shell, focus transfer | |

If the request is about what a rendered message looks like, route it. Editing *inside* a generated
artifact is not for this skill (use frontend-canvas-doc-editor): selection-scoped patches,
suggested edits, version history.

## Scope

- Building or redesigning a chat UI for an assistant or agent product.
- Adding a session sidebar, history search, projects, or an agent gallery.
- Designing composer chrome: model/effort chip, attachments, drafts, slash and @ popovers.
- Deciding where generated artifacts live (side panel, inline, or their own route).
- Background work must stay visible while the user works elsewhere.
- Streams must survive a refresh, a closed tab, or a dropped connection.
- Adding branching, sharing, or multi-user access to sessions.

## Do NOT use for

- Anything rendered inside a message bubble -> `frontend-ai-generative-ui`.
- Dialogue content, persona, tone, fallback/repair copy -> `conversational-ai-ux`.
- Transport mechanics (WebSocket/SSE plumbing, reconnect backoff) -> `realtime-websockets`.
- Trust, disclosure and AI-labelling UX -> `ai-trust-transparency-ux`.
- Remediating an already-dense screen -> `ui-density-refactor`.

## Provenance legend

Every claim carries its evidence class — an invariant you can lean on is not the same object as a
pattern one vendor ships.

- `[observed N/4]` — counted across four 2026-07-29 teardowns (ChatGPT Pro, Onyx v4.4.0, Claude,
  Gemini Ultra). **N=1 or 2 is a menu option, not a rule.**
- `[verified: source, date]` — external primary source, named and dated.
- `[portfolio requirement]` — our own products need it; not a market claim.
- `[optional pattern]` — defensible, deliberately not universal.

## Pillar 1 — three zones and a near-constant sidebar order

The shell is a collapsible left sidebar (~260-300px, collapsing to an icon rail), a main canvas, and
— conditionally — a third surface for artifacts (Pillar 4 decides whether it exists at all).

Sidebar stack order, top to bottom `[observed 4/4]`: **new-chat CTA** (most prominent control) ->
**search over chats** (never behind a menu) -> **libraries** -> **org primitives** -> **recents with
live status** (Pillar 2) -> *(role-gated entry such as an admin console sits HERE, just above the
account block)* -> **account + plan badge**.

**Org primitives are a menu, not a checklist** `[observed 4/4]`. Each product shipped two or three of
{pinned, projects, agent gallery, notebooks, media library, scheduled} at nav level; none shipped all.
A v1 shipping six has not made a product decision — it deferred one into the navigation, where the
user pays for it.

**Empty state is one moment, not a tour** `[observed 4/4]`: a localized greeting and a centered
composer, nothing else. At most one onboarding banner `[observed 1/4]`. No feature grid, no cards.

**Theme:** all four were dark at capture time `[observed 4/4]`, but that is `[optional pattern]`,
not an invariant — four screenshots of a default setting are not evidence that light mode is
second-class. Build both from tokens and let the user or OS decide.

**Variant — a multi-agent panel** `[observed]`: when several agents answer one prompt, the roster is
a **strip** with per-agent state, and rounds land by **mutation of a round record**, not token
streaming — nobody reads five streams. Cancel is therefore **per round**, mid-round, leaving finished
rounds intact, and **citation density is a panel parameter**: the answer is judged on whether each
claim traces. Seen in a production healthcare app; multi-*agent*, not Pillar 5's withdrawn
multi-*human* pattern.

## Pillar 2 — recents are a task surface, not a history list

`[observed 2/4]` for live status inside recents, `[portfolio requirement]` for anything that runs
long. Two of four surfaced in-flight work in the sidebar list itself: per-chat spinners, and a status
dot on a running generation. Where a session holds work that outlives the user's attention, that row
is the cheapest correct place to say so — state belongs where attention already is, not behind a bell
icon.

**Status-structured beats a single dot** `[optional pattern]`: richer surfaces group by state
instead of decorating a flat list — completed / needs-input / scheduled, or per-agent status with
the action currently running. `needs-input` pays for itself immediately: a job blocked on the user
is invisible in a flat list and unmissable in a grouped one.

Rules that hold regardless of grouping:

- A row's status derives from server state, never from local optimism.
- `needs-input` outranks `running` in sort order; a blocked job beats a busy one.
- Terminal failure stays visible until acknowledged; a job dying silently teaches the user to
  distrust the whole surface.
- Do not animate every row. Motion on a list is paid for by every row that is not moving.

## Pillar 3 — the composer is the identity anchor

The composer tells the user who they are talking to before they commit a message.

**Model/effort chip, visible pre-send** `[observed 3/4]` — three of four exposed the active model
(and in one, its effort level) as a chip in or beside the input; the fourth exposed tools and a
timer. Where more than one model or effort tier exists, showing it pre-send is what makes the choice
real rather than a settings-screen abstraction.

**Dictation and a voice session are two different affordances** `[observed 2/4]`. Two products placed
a microphone *and* a waveform control side by side — not two doors to one feature:

| Affordance | What it does | Where output lands |
|---|---|---|

From rafaelob/aiLine, Apache-2.0.

More from rafaelob/aiLine