docs(plans): Mobile Chat v2 PRD
Summary
PRD for Mobile Chat v2 — the first native mobile chat experience in apps/mobile. Lives at plans/chat-mobile-plan/. Docs-only; no code changes.
Ships a parallel React Native ChatInterface tree that consumes the existing @superset/host-service tRPC surface over the relay. No new server architecture — mobile is a thin client against the same agent loop desktop drives.
Scope
- Functional groups (5): Session Lifecycle, Composition + Send, Message Rendering, Mid-Turn Interactive Prompts (tool approval / ask_user / plan approval), Platform Integration (push, background/foreground, reconnect)
- Use cases: 26 across the 5 groups
- Transport: typed HTTP+tRPC client against the host-service
AppRouter, routed throughapps/relay(per-host WS tunnel) with JWT bearer auth — deliberate mobile-specific adaptation of desktop's IPC chat path - Session listing: existing ElectricSQL
chat_sessionsshape (zero new infra) - Streaming: mirrors desktop's polling pattern (~4 FPS against
getDisplayState+listMessages) - UI: parallel RN tree at
apps/mobile/components/chat/, mirroring desktop component names but built with@rn-primitives/*+ uniwind +@10play/tentap-editor+@gorhom/bottom-sheet+@shopify/flash-list - Mid-turn prompts: container per interaction shape — inline card + sticky footer for tool approval (Continue.dev pattern), bottom sheet for ask_user (keyboard handling), full-screen modal as pushed expo-router route for plan approval (Apple HIG)
- Testing: three-layer pyramid — Bun test (unit), Storybook 9 under custom root toggle with build-time stripping (component, isolated UI testing prior to service integration), Maestro for YAML-based E2E (feature)
Document structure
```
plans/chat-mobile-plan/
├── README.md # Index + version history
├── 00-overview.md # Product description, problem, solution
├── 01-scope.md # In scope / Out of scope (with rationale)
├── 02-roles.md # User / System / Host-service roles
├── 03-functional-groups.md # 5 groups, 26 UCs summary
├── 04-uc-sess.md # Session lifecycle (5 UCs)
├── 05-uc-comp.md # Composition + send (5 UCs)
├── 06-uc-render.md # Message rendering (7 UCs)
├── 07-uc-pause.md # Mid-turn prompts (4 UCs) + Design Rationale
├── 08-uc-platf.md # Platform integration (5 UCs)
├── 09-team-contributions.md # Source artifacts and prior research
├── 10-technical-requirements/ # System components, data, API, dependencies, UI infra
└── 11-testing-strategy.md # Storybook + Maestro + Bun test strategy
```
Version history (highlights)
- 1.5.0 — Added testing strategy (Storybook with custom root toggle + build-time stripping; Maestro E2E; sprint-phase alignment)
- 1.4.0 — Red-hat adversarial review against real codebase: corrected streaming description (polling, not character-drip), transport framing (deliberate adaptation, not mirror), added custom slash command awareness, host selection sub-decision, `previewSlashCommand` + `getDisplayState` to API table, optimistic updates on PAUSE UCs
- 1.3.x — Terminology alignment (v0 → mobile-chat v2), scope rationale (`[DEFERRED]` vs `[NOT SUPPORTED]`)
- 1.2.0 — Annotated every Out-of-Scope item with a "Why"
- 1.1.0 — Container per interaction shape for PAUSE UCs with citations (Apple HIG, NN/G, Continue.dev, Cline, Material Design 3)
- 1.0.0 — Initial PRD
Also includes:
- Clarification that mobile is a full read-write client at the API level (sendMessage, respondToApproval/Question/Plan, stop, etc.) — DB-write narrowness is architectural (no `chat_messages` table), not a scope cut
- Host runtime message storage model documented: per-session `Map<sessionId, RuntimeSession>`, Mastra harness per session, eviction is possible
Test plan
This is a docs-only PR — no code to run. Reviewer verification:
- Read `README.md` and confirm the document index resolves to all 12 docs
- Spot-check 2-3 UCs against the existing host-service router at `packages/host-service/src/trpc/router/chat/chat.ts` — confirm referenced procedures exist
- Read `11-testing-strategy.md` and confirm the Storybook build-flag pattern + Maestro flow conventions are acceptable for the mobile app
- Read `01-scope.md` Out of Scope items and confirm the deferrals are reasonable
What's NOT in this PR
- No code changes
- No sprint roadmap yet (`/kb-sprint-plan` will run after PRD is approved)
- No per-task expansion (handled JIT by `/kb-sprint-tasks-plan` per sprint)
🤖 Generated with Claude Code
Summary by cubic
Adds the Mobile Chat v2 PRD in plans/chat-mobile-plan/, defining the first native chat for apps/mobile over the @superset/host-service tRPC via apps/relay, with a project‑first sessions list and minimal push notifications; docs‑only. ROADMAP is delta‑replanned for the project‑first model with a pixel‑perfect Sprint 01.
-
New Features
- Scope: 6 functional groups with 32 use cases (sessions, compose/send, render, mid‑turn prompts, platform integration, navigation). Navigation is project‑first with a flat, recency‑sorted list, project chip, search, bottom‑sheet filters, applied filter chips, new‑chat picker, deep‑link routing, and lazy tunnel opening on chat‑route mount.
- Transport: typed HTTP+tRPC to the host via
apps/relaywith JWT; updates via polling to match desktop behavior. - Data: session listing via ElectricSQL
chat_sessions; mobile is full read‑write at host API (send/stop/respond), with DB writes limited to session metadata. - UI: parallel RN chat tree at
apps/mobile/components/chat/; mid‑turn prompts use inline card + sticky footer (tool approval), bottom sheet (ask_user), and full‑screen modal route (plan approval). - Notifications: relay‑side fanout from host tunnel to Expo Push;
POST /push/registerandDELETE /push/register/:deviceId(JWT‑gated), tokens in Upstash KV, foreground suppression client‑side, and tap deep‑links into the session; scope limited to Stop and PermissionRequest events.
-
Roadmap
- Sprint 01 collapses UI work under pixel‑perfect; component inventory updated for project‑first chrome (ProjectChip, ProjectPickerSheet, SessionFilterSheet, AppliedFilterTags, FilterButton, flat SessionRow).
- Sprints 02–03 shift sessions‑list integration to project‑first and add
SelectedProjectProvider,useSessionsForProject, anduseChatTunnel(handshake + retry). - Sprint 06 updates deep‑link handling to align project and lazily resolve host, with a cold‑launch fallback to
chat.getSnapshot; total tasks now 56 across 7 sprints.
Summary by CodeRabbit
- Documentation
- Added a comprehensive Mobile Chat v2 PRD and roadmap covering scope, functional groups, sprint plan, and acceptance criteria.
- Specifies user-facing behaviors: sessions list/navigation, deep links, Tiptap-based composer parity (slash commands), streaming assistant text, mid-turn interactive prompts and pause/approval flows, pending-action indicators, and host-offline/resume UX.
- Documents push-notification flows, testing strategy, component organization, and platform integration expectations.