Repository navigation
docs(plans): Mobile Chat v2 PRD - #4828
justincrich wants to merge 18 commits into
Conversation
|
Capy auto-review is paused for this organization because the monthly auto-review limit has been reached. Increase the limit or turn it off in billing settings to resume automatic reviews. |
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThis PR adds a complete Mobile Chat v2 PRD under plans/chat-mobile-plan/ (13+ docs), detailing scope, roles, 33 use cases across six functional groups, API surfaces (cloud tRPC, relay host-service tRPC, ElectricSQL), architecture, UI infra, dependencies, testing strategy, and an 11-sprint roadmap. ChangesMobile Chat v2 PRD
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Ready to review this PR? Stage has broken it down into 7 individual chapters for you: Chapters generated by Stage for commit ef0942c on May 22, 2026 2:05pm UTC. |
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plans/chat-mobile-plan/05-uc-comp.md`:
- Line 16: The table cell for UC-COMP-05 contains inline code with raw pipe
characters that break the table; locate the row identified by "UC-COMP-05" and
escape each pipe inside the inline code (e.g., change `off | low | medium | high
| xhigh` to `off \| low \| medium \| high \| xhigh`) so the markdown table
renders correctly.
In `@plans/chat-mobile-plan/10-technical-requirements/03-architecture-diagram.md`:
- Line 3: The fenced code block missing a language tag should be updated to
include a language identifier (e.g., change the leading ``` to ```text) so MD040
(fenced-code-language) is satisfied; locate the bare fenced code block in the
content (the triple backticks shown in the diff) and replace the opening fence
with ```text.
In `@plans/chat-mobile-plan/10-technical-requirements/05-ui-infrastructure.md`:
- Around line 7-82: The fenced code blocks showing directory listings (e.g., the
blocks starting with "components/chat/", "app/(authenticated)/chat/", and
"lib/") are missing language tags; update those triple-backtick fences to
include a language token such as text (replace ``` with ```text) for those
specific blocks and apply the same change to the other occurrences noted (lines
around 113-136 and 140-150) so markdownlint MD040 is satisfied and syntax
highlighting is preserved.
In `@plans/chat-mobile-plan/10-technical-requirements/06-open-sub-decisions.md`:
- Line 10: Update the "Host selection and workspace→host resolution" decision to
be time-bound by adding an explicit owner (person or team), a target decision
date, and a clear interim default behavior so UC-SESS and UC-COMP can proceed;
specifically, in the paragraph referencing hostId and v2WorkspaceId include an
"Owner: <team/name>", "Decision by: <YYYY-MM-DD>" and "Interim default:
<behavior — e.g., use cloud tRPC lookup and present host picker only if multiple
hosts, fallback to first available host if original is offline>" so implementers
know who decides, when, and what temporary behavior to wire into workspace→host
resolution and host picker flow.
In `@plans/chat-mobile-plan/11-component-organization-addendum.md`:
- Around line 15-20: The Markdown code fences in this document are missing
language identifiers; update each fenced block (for example the block containing
"ComponentName/", the block showing the file mapping with
"app/(authenticated)/chat/[sessionId]/index.tsx → re-exports ChatScreen" and the
block around "screens/(authenticated)/chat/[sessionId]/ChatScreen/") to include
a language tag such as ```text (or ```bash/```text as appropriate) so the fences
become ```text ... ```; ensure you update all occurrences (including the second
block around lines 65–68) and keep the fence contents unchanged.
In `@plans/chat-mobile-plan/11-testing-strategy.md`:
- Around line 120-142: The fenced code block showing the .maestro/ tree is
missing a language tag (MD040); update the opening fence for that block from ```
to ```text so the block becomes a labeled text/code fence (i.e., add the
language identifier "text" to the .maestro/ code block) to satisfy the linter
and preserve formatting.
In `@plans/chat-mobile-plan/README.md`:
- Line 26: The Version table row currently shows "1.3.1" which conflicts with
frontmatter and version history indicating "1.5.0"; update that table cell to
"1.5.0" so the PRD Metadata in README.md matches the declared PRD version,
ensuring the Version line in the markdown table is changed from "1.3.1" to
"1.5.0".
- Line 49: The index row linking to ./10-technical-requirements.md is stale;
either update the table entry in plans/chat-mobile-plan/README.md to point to
the new aggregator (for example ./10-technical-requirements/README.md or
./10-technical-requirements/index.md) or create a new top-level file named
10-technical-requirements.md that redirects/links to the subfiles under
./10-technical-requirements/; edit the table cell that currently contains
./10-technical-requirements.md so the link resolves to the actual directory
entry (or add the aggregator file) and ensure the display name and description
remain unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 05c0b189-5547-4cca-9485-a96954c0e5e8
📒 Files selected for processing (20)
plans/chat-mobile-plan/00-overview.mdplans/chat-mobile-plan/01-scope.mdplans/chat-mobile-plan/02-roles.mdplans/chat-mobile-plan/03-functional-groups.mdplans/chat-mobile-plan/04-uc-sess.mdplans/chat-mobile-plan/05-uc-comp.mdplans/chat-mobile-plan/06-uc-render.mdplans/chat-mobile-plan/07-uc-pause.mdplans/chat-mobile-plan/08-uc-platf.mdplans/chat-mobile-plan/09-team-contributions.mdplans/chat-mobile-plan/10-technical-requirements/00-system-components.mdplans/chat-mobile-plan/10-technical-requirements/01-data-schema.mdplans/chat-mobile-plan/10-technical-requirements/02-api-design.mdplans/chat-mobile-plan/10-technical-requirements/03-architecture-diagram.mdplans/chat-mobile-plan/10-technical-requirements/04-dependencies.mdplans/chat-mobile-plan/10-technical-requirements/05-ui-infrastructure.mdplans/chat-mobile-plan/10-technical-requirements/06-open-sub-decisions.mdplans/chat-mobile-plan/11-component-organization-addendum.mdplans/chat-mobile-plan/11-testing-strategy.mdplans/chat-mobile-plan/README.md
| | UC-COMP-02 | Submit message with optimistic append | User can tap Send to submit a message and see it appear in the message list before the host acknowledges. | | ||
| | UC-COMP-03 | Stop a running turn | User can interrupt an in-progress assistant turn from the composer area. | | ||
| | UC-COMP-04 | Pick the model for a turn | User can choose between available models (Opus, Sonnet, Haiku, GPT variants) from a popover. | | ||
| | UC-COMP-05 | Set thinking level and permission mode | User can adjust thinking level (`off | low | medium | high | xhigh`) and permission mode from popovers in the composer. | |
There was a problem hiding this comment.
Escape pipe characters inside the table cell to prevent broken rendering.
The value list in inline code uses raw |, which breaks the 3-column table parsing.
Suggested fix
-| UC-COMP-05 | Set thinking level and permission mode | User can adjust thinking level (`off | low | medium | high | xhigh`) and permission mode from popovers in the composer. |
+| UC-COMP-05 | Set thinking level and permission mode | User can adjust thinking level (`off \| low \| medium \| high \| xhigh`) and permission mode from popovers in the composer. |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | UC-COMP-05 | Set thinking level and permission mode | User can adjust thinking level (`off | low | medium | high | xhigh`) and permission mode from popovers in the composer. | | |
| | UC-COMP-05 | Set thinking level and permission mode | User can adjust thinking level (`off \| low \| medium \| high \| xhigh`) and permission mode from popovers in the composer. | |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 16-16: Table column count
Expected: 3; Actual: 7; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/05-uc-comp.md` at line 16, The table cell for
UC-COMP-05 contains inline code with raw pipe characters that break the table;
locate the row identified by "UC-COMP-05" and escape each pipe inside the inline
code (e.g., change `off | low | medium | high | xhigh` to `off \| low \| medium
\| high \| xhigh`) so the markdown table renders correctly.
| @@ -0,0 +1,62 @@ | |||
| # Architecture Diagram | |||
|
|
|||
| ``` | |||
There was a problem hiding this comment.
Add a language identifier to the fenced block.
Line 3 triggers MD040 (fenced-code-language). Add a language hint (for example text) so markdown linting passes consistently.
Suggested patch
-```
+```text📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 3-3: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/10-technical-requirements/03-architecture-diagram.md`
at line 3, The fenced code block missing a language tag should be updated to
include a language identifier (e.g., change the leading ``` to ```text) so MD040
(fenced-code-language) is satisfied; locate the bare fenced code block in the
content (the triple backticks shown in the diff) and replace the opening fence
with ```text.
| ``` | ||
| components/chat/ | ||
| ├── ChatInterface/ | ||
| │ ├── ChatInterface.tsx | ||
| │ ├── components/ | ||
| │ │ ├── MessageList/ | ||
| │ │ │ ├── MessageList.tsx | ||
| │ │ │ ├── components/ | ||
| │ │ │ │ ├── MessagePartsRenderer/ | ||
| │ │ │ │ │ ├── MessagePartsRenderer.tsx | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── UserMessage/ | ||
| │ │ │ │ │ ├── UserMessage.tsx | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── AssistantMessage/ | ||
| │ │ │ │ │ ├── AssistantMessage.tsx | ||
| │ │ │ │ │ ├── components/ | ||
| │ │ │ │ │ │ ├── MessageMarkdown/ | ||
| │ │ │ │ │ │ │ ├── MessageMarkdown.tsx | ||
| │ │ │ │ │ │ │ └── index.ts | ||
| │ │ │ │ │ │ └── ReasoningBlock/ | ||
| │ │ │ │ │ │ ├── ReasoningBlock.tsx | ||
| │ │ │ │ │ │ └── index.ts | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── ToolCallBlock/ | ||
| │ │ │ │ │ ├── ToolCallBlock.tsx (collapsed-only in v2) | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── PlanBlock/ | ||
| │ │ │ │ │ ├── PlanBlock.tsx | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ └── SubagentExecutionMessage/ | ||
| │ │ │ │ ├── SubagentExecutionMessage.tsx | ||
| │ │ │ │ └── index.ts | ||
| │ │ │ ├── hooks/ | ||
| │ │ │ │ └── useMessageSnapshot.ts | ||
| │ │ │ └── index.ts | ||
| │ │ ├── ChatInputFooter/ | ||
| │ │ │ ├── ChatInputFooter.tsx | ||
| │ │ │ ├── components/ | ||
| │ │ │ │ ├── TiptapPromptEditor/ | ||
| │ │ │ │ │ ├── TiptapPromptEditor.tsx (port via @10play/tentap-editor) | ||
| │ │ │ │ │ ├── SlashCommandNode.tsx (editor extension — single file) | ||
| │ │ │ │ │ ├── FileMentionNode.tsx (editor extension — single file) | ||
| │ │ │ │ │ ├── hooks/ | ||
| │ │ │ │ │ │ └── useTiptapEditor.ts | ||
| │ │ │ │ │ ├── utils/ | ||
| │ │ │ │ │ │ └── serializeEditorToText.ts (portable as-is) | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── SlashCommandMenu/ | ||
| │ │ │ │ │ ├── SlashCommandMenu.tsx | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ ├── ModelPicker/ | ||
| │ │ │ │ │ ├── ModelPicker.tsx | ||
| │ │ │ │ │ └── index.ts | ||
| │ │ │ │ └── PermissionModePicker/ | ||
| │ │ │ │ ├── PermissionModePicker.tsx | ||
| │ │ │ │ └── index.ts | ||
| │ │ │ ├── hooks/ | ||
| │ │ │ │ └── usePendingQuestion.ts | ||
| │ │ │ └── index.ts | ||
| │ │ ├── PendingApprovalCard/ | ||
| │ │ │ ├── PendingApprovalCard.tsx (inline card, container parity with desktop) | ||
| │ │ │ └── index.ts | ||
| │ │ ├── PendingApprovalFooter/ | ||
| │ │ │ ├── PendingApprovalFooter.tsx (NEW — sticky thumb-docked footer) | ||
| │ │ │ └── index.ts | ||
| │ │ ├── PendingQuestionSheet/ | ||
| │ │ │ ├── PendingQuestionSheet.tsx (bottom sheet via @gorhom/bottom-sheet) | ||
| │ │ │ └── index.ts | ||
| │ │ └── PendingActionIndicator/ | ||
| │ │ ├── PendingActionIndicator.tsx (NEW — floating "Tap to respond" pill) | ||
| │ │ └── index.ts | ||
| │ ├── hooks/ | ||
| │ │ └── useChatScroll.ts | ||
| │ └── index.ts | ||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced code blocks to satisfy markdownlint (MD040).
Three fenced blocks are missing a language specifier, which will keep docs lint noisy and can reduce syntax highlighting quality.
Proposed fix
-```
+```text
components/chat/
...
-```
+```
-```
+```text
app/(authenticated)/chat/
...
-```
+```
-```
+```text
lib/
...
-```
+```Also applies to: 113-136, 140-150
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 7-7: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/10-technical-requirements/05-ui-infrastructure.md`
around lines 7 - 82, The fenced code blocks showing directory listings (e.g.,
the blocks starting with "components/chat/", "app/(authenticated)/chat/", and
"lib/") are missing language tags; update those triple-backtick fences to
include a language token such as text (replace ``` with ```text) for those
specific blocks and apply the same change to the other occurrences noted (lines
around 113-136 and 140-150) so markdownlint MD040 is satisfied and syntax
highlighting is preserved.
| 3. **Markdown library choice**: `react-native-markdown-display` (widely-used, opinionated styling) vs `@expensify/react-native-live-markdown` (faster but newer/less battle-tested) vs custom thin wrapper. Benchmarks needed. | ||
| 4. **Tiptap WebView perf on mid-range Android**: validate that `@10play/tentap-editor` keyboard handling + input latency are acceptable on Android 11+ devices with 4GB RAM. Define a perf budget before locking in. | ||
| 5. **Snapshot polling interval (if streaming deferred)**: 250ms? 500ms? 1s? Battery vs latency vs server load. | ||
| 6. **Host selection and workspace→host resolution**: mobile cannot initiate or resume a chat session without knowing which host to route through. Desktop resolves this via its multi-pane workspace view (each pane bound to a workspace+host). Mobile needs: (a) how to resolve `hostId` from `v2WorkspaceId` (cloud tRPC lookup? relay directory? cached mapping?), (b) whether mobile shows a host picker when multiple hosts are available for a workspace, (c) what happens when the host a session belongs to is offline but another host is online. This decision blocks UC-SESS and UC-COMP transport wiring. |
There was a problem hiding this comment.
Convert the stated blocker into a time-bound decision record.
Line 10 marks host resolution as blocking UC-SESS/UC-COMP, but there’s no owner, target decision date, or interim default behavior. Please add those three fields so implementation sequencing is actionable and unblocked.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/10-technical-requirements/06-open-sub-decisions.md` at
line 10, Update the "Host selection and workspace→host resolution" decision to
be time-bound by adding an explicit owner (person or team), a target decision
date, and a clear interim default behavior so UC-SESS and UC-COMP can proceed;
specifically, in the paragraph referencing hostId and v2WorkspaceId include an
"Owner: <team/name>", "Decision by: <YYYY-MM-DD>" and "Interim default:
<behavior — e.g., use cloud tRPC lookup and present host picker only if multiple
hosts, fallback to first available host if original is offline>" so implementers
know who decides, when, and what temporary behavior to wire into workspace→host
resolution and host picker flow.
| ``` | ||
| ComponentName/ | ||
| ├── ComponentName.tsx # ONE component per file | ||
| ├── index.ts # Barrel export: export { ComponentName } from './ComponentName' | ||
| └── components/ # Subcomponents used only by this parent | ||
| ``` |
There was a problem hiding this comment.
Specify fenced code block languages (MD040).
These two fences are missing language identifiers.
Proposed fix
-```
+```text
ComponentName/
...
-```
+```
-```
+```text
app/(authenticated)/chat/[sessionId]/index.tsx → re-exports ChatScreen
screens/(authenticated)/chat/[sessionId]/ChatScreen/ → actual implementation
-```
+```Also applies to: 65-68
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 15-15: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/11-component-organization-addendum.md` around lines 15
- 20, The Markdown code fences in this document are missing language
identifiers; update each fenced block (for example the block containing
"ComponentName/", the block showing the file mapping with
"app/(authenticated)/chat/[sessionId]/index.tsx → re-exports ChatScreen" and the
block around "screens/(authenticated)/chat/[sessionId]/ChatScreen/") to include
a language tag such as ```text (or ```bash/```text as appropriate) so the fences
become ```text ... ```; ensure you update all occurrences (including the second
block around lines 65–68) and keep the fence contents unchanged.
| ``` | ||
| .maestro/ | ||
| ├── chat-sessions-list.yaml # UC-SESS-01 | ||
| ├── chat-session-resume.yaml # UC-SESS-02 | ||
| ├── chat-session-create.yaml # UC-SESS-03 | ||
| ├── chat-session-end.yaml # UC-SESS-04 | ||
| ├── chat-session-delete.yaml # UC-SESS-05 | ||
| ├── chat-compose-send.yaml # UC-COMP-01, UC-COMP-02 | ||
| ├── chat-stop-turn.yaml # UC-COMP-03 | ||
| ├── chat-model-picker.yaml # UC-COMP-04 | ||
| ├── chat-render-messages.yaml # UC-RENDER-01 | ||
| ├── chat-render-streaming.yaml # UC-RENDER-02 | ||
| ├── chat-render-markdown.yaml # UC-RENDER-03 | ||
| ├── chat-render-tool-calls.yaml # UC-RENDER-04 | ||
| ├── chat-tool-approval.yaml # UC-PAUSE-01 | ||
| ├── chat-ask-user.yaml # UC-PAUSE-02 | ||
| ├── chat-plan-approval.yaml # UC-PAUSE-03 | ||
| ├── chat-push-notifications.yaml # UC-PLATF-01 | ||
| ├── chat-background-resume.yaml # UC-PLATF-02 | ||
| ├── chat-host-offline.yaml # UC-PLATF-03 | ||
| └── utils/ | ||
| └── login.yaml # Composable sub-flow | ||
| ``` |
There was a problem hiding this comment.
Add a language to the .maestro/ tree fence (MD040).
The fenced block for flow file layout is missing a language tag.
Proposed fix
-```
+```text
.maestro/
...
-```
+```📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ``` | |
| .maestro/ | |
| ├── chat-sessions-list.yaml # UC-SESS-01 | |
| ├── chat-session-resume.yaml # UC-SESS-02 | |
| ├── chat-session-create.yaml # UC-SESS-03 | |
| ├── chat-session-end.yaml # UC-SESS-04 | |
| ├── chat-session-delete.yaml # UC-SESS-05 | |
| ├── chat-compose-send.yaml # UC-COMP-01, UC-COMP-02 | |
| ├── chat-stop-turn.yaml # UC-COMP-03 | |
| ├── chat-model-picker.yaml # UC-COMP-04 | |
| ├── chat-render-messages.yaml # UC-RENDER-01 | |
| ├── chat-render-streaming.yaml # UC-RENDER-02 | |
| ├── chat-render-markdown.yaml # UC-RENDER-03 | |
| ├── chat-render-tool-calls.yaml # UC-RENDER-04 | |
| ├── chat-tool-approval.yaml # UC-PAUSE-01 | |
| ├── chat-ask-user.yaml # UC-PAUSE-02 | |
| ├── chat-plan-approval.yaml # UC-PAUSE-03 | |
| ├── chat-push-notifications.yaml # UC-PLATF-01 | |
| ├── chat-background-resume.yaml # UC-PLATF-02 | |
| ├── chat-host-offline.yaml # UC-PLATF-03 | |
| └── utils/ | |
| └── login.yaml # Composable sub-flow | |
| ``` |
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 120-120: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/11-testing-strategy.md` around lines 120 - 142, The
fenced code block showing the .maestro/ tree is missing a language tag (MD040);
update the opening fence for that block from ``` to ```text so the block becomes
a labeled text/code fence (i.e., add the language identifier "text" to the
.maestro/ code block) to satisfy the linter and preserve formatting.
Greptile SummaryThis is a docs-only PR adding the Mobile Chat v2 PRD (
Confidence Score: 3/5The PRD content itself is thorough and well-grounded, but the README — the document's entry point and the first thing reviewers are directed to verify — has three structural problems that leave it in a broken state. The README's document index, which the PR description explicitly asks reviewers to validate, has a dead link to plans/chat-mobile-plan/README.md needs the most attention: fix the broken
|
| Filename | Overview |
|---|---|
| plans/chat-mobile-plan/README.md | Top-level index with three issues: broken link to ./10-technical-requirements.md (directory, not file), version mismatch between frontmatter (1.5.0) and Metadata table body (1.3.1), and 11-component-organization-addendum.md absent from the Document Index. |
| plans/chat-mobile-plan/11-component-organization-addendum.md | Solid component-organization conventions doc, but collides with 11-testing-strategy.md on the 11- prefix and has no entry in the README document index — it is an orphaned document. |
| plans/chat-mobile-plan/05-uc-comp.md | Composition use cases well-specified; one incorrect cross-reference in UC-COMP-01 attributes slash command handling to UC-COMP-04 (the model picker). |
| plans/chat-mobile-plan/10-technical-requirements/02-api-design.md | API surface coverage is thorough across all three layers (cloud tRPC, host-service tRPC via relay, Electric shape); procedures match the referenced router file. |
| plans/chat-mobile-plan/11-testing-strategy.md | Comprehensive three-layer testing strategy (Bun unit, Storybook component, Maestro E2E) with concrete setup snippets and sprint-phase alignment; no issues found. |
| plans/chat-mobile-plan/00-overview.md | Clear product overview; transport/architecture framing is accurate and grounded in repo evidence. |
| plans/chat-mobile-plan/01-scope.md | Thorough in-scope/out-of-scope treatment with well-reasoned deferrals and architectural justifications; no issues found. |
| plans/chat-mobile-plan/10-technical-requirements/01-data-schema.md | Clear and accurate description of the host in-memory message model, DB-write surface, and the read-write distinction; host eviction edge case is correctly documented. |
| plans/chat-mobile-plan/10-technical-requirements/06-open-sub-decisions.md | Six open sub-decisions clearly enumerated with trade-offs; JWT lifecycle and host-selection decisions are correctly flagged as blocking transport wiring. |
| plans/chat-mobile-plan/07-uc-pause.md | Mid-turn interactive prompt use cases are well-specified with container rationale (Apple HIG, NN/G, Continue.dev citations); acceptance criteria cover optimistic updates and error paths. |
Sequence Diagram
sequenceDiagram
participant Mobile as apps/mobile (Expo)
participant Relay as apps/relay (Hono+Redis)
participant HostSvc as packages/host-service (tRPC)
participant CloudAPI as apps/api (cloud tRPC)
participant Electric as apps/electric-proxy
participant DB as Neon Postgres
Note over Mobile,DB: Session lifecycle
Mobile->>Electric: "GET /api/electric/v1/shape?table=chat_sessions"
Electric-->>Mobile: Realtime chat_sessions rows
Mobile->>CloudAPI: chat.createSession(sessionId, v2WorkspaceId)
CloudAPI->>DB: INSERT chat_sessions
CloudAPI-->>Mobile: session created
Note over Mobile,HostSvc: Message flow (via relay tunnel)
Mobile->>Relay: HTTP+tRPC chat.sendMessage (JWT bearer)
Relay->>HostSvc: tunnel-forwarded HTTP
HostSvc-->>Mobile: OK (mutates in-memory RuntimeSession)
loop Polling ~4 FPS
Mobile->>Relay: chat.getDisplayState / listMessages
Relay->>HostSvc: forwarded
HostSvc-->>Mobile: state snapshot
end
Note over Mobile,HostSvc: Mid-turn pause (tool approval)
HostSvc-->>Mobile: getDisplayState PAUSED state
Mobile->>Relay: chat.respondToApproval(decision)
Relay->>HostSvc: forwarded
HostSvc-->>Mobile: OK (resumes agent loop)
Note over Mobile,DB: Push notifications
HostSvc-->>CloudAPI: notificationsEmitter event
CloudAPI-->>Mobile: Expo push notification
Prompt To Fix All With AI
Fix the following 5 code review issues. Work through them one at a time, proposing concise fixes.
---
### Issue 1 of 5
plans/chat-mobile-plan/README.md:50
**Broken document index link for technical requirements**
The table entry links to `./10-technical-requirements.md` (a file that does not exist), but the actual content lives in the `10-technical-requirements/` subdirectory with seven separate `.md` files. Clicking this link from any markdown renderer will produce a 404. The PR description's own test plan asks reviewers to "confirm the document index resolves to all 12 docs" — this entry will fail that check.
The link should either point to the folder's index (e.g. `./10-technical-requirements/00-system-components.md`) or the directory listing should be expanded into individual rows for each sub-document.
### Issue 2 of 5
plans/chat-mobile-plan/README.md:29
**Version mismatch between frontmatter and PRD Metadata table**
The YAML frontmatter declares `version: 1.5.0` and the version history table's most recent entry is `1.5.0`, but the PRD Metadata table in the body still shows `Version | 1.3.1`. Readers comparing the two will see conflicting version numbers. The Metadata table was not updated when v1.4.0 and v1.5.0 were appended to the version history.
### Issue 3 of 5
plans/chat-mobile-plan/README.md:44-58
**`11-component-organization-addendum.md` is absent from the document index**
The PR adds `plans/chat-mobile-plan/11-component-organization-addendum.md` (20 files total), but this file has no entry in the Document Index table. It is also numbered `11-`, colliding with `11-testing-strategy.md`. A reader following the index has no path to the component-organization conventions doc. The file should be added to the index and renumbered to avoid the duplicate `11-` prefix (e.g. `12-component-organization-addendum.md`).
### Issue 4 of 5
plans/chat-mobile-plan/README.md:17-19
**Unresolvable local machine path referenced for collaborators**
`~/Projects/brain/docs/PR-SEQUENCING.md` is a path on the author's local filesystem. Anyone else reading this doc cannot navigate to it. The convention it describes should either be inlined briefly here, copied into the repository, or linked via an accessible URL.
### Issue 5 of 5
plans/chat-mobile-plan/05-uc-comp.md:27
**Wrong cross-reference: slash commands attributed to UC-COMP-04**
The sentence "(handled in UC-COMP-04 and PAUSE-adjacent flows)" is attached to slash command behavior, but UC-COMP-04 is the model picker. Slash command composition and resolution are all handled within UC-COMP-01 itself (the same use case). This reference will confuse implementers tracing the slash-command flow.
Reviews (1): Last reviewed commit: "docs(plans): clarify message storage mod..." | Re-trigger Greptile
| | [08-uc-platf.md](./08-uc-platf.md) | UC-PLATF-01 through UC-PLATF-05 (Platform integration) | FEATURE_SPEC | | ||
| | [09-team-contributions.md](./09-team-contributions.md) | Source artifacts and prior research | — | | ||
| | [10-technical-requirements.md](./10-technical-requirements.md) | System components, data, API, dependencies | CONSTITUTION | | ||
| | [11-testing-strategy.md](./11-testing-strategy.md) | Testing layers, Storybook setup, Maestro E2E, Bun test, sprint test phases | CONSTITUTION | |
There was a problem hiding this comment.
Broken document index link for technical requirements
The table entry links to ./10-technical-requirements.md (a file that does not exist), but the actual content lives in the 10-technical-requirements/ subdirectory with seven separate .md files. Clicking this link from any markdown renderer will produce a 404. The PR description's own test plan asks reviewers to "confirm the document index resolves to all 12 docs" — this entry will fail that check.
The link should either point to the folder's index (e.g. ./10-technical-requirements/00-system-components.md) or the directory listing should be expanded into individual rows for each sub-document.
Prompt To Fix With AI
This is a comment left during a code review.
Path: plans/chat-mobile-plan/README.md
Line: 50
Comment:
**Broken document index link for technical requirements**
The table entry links to `./10-technical-requirements.md` (a file that does not exist), but the actual content lives in the `10-technical-requirements/` subdirectory with seven separate `.md` files. Clicking this link from any markdown renderer will produce a 404. The PR description's own test plan asks reviewers to "confirm the document index resolves to all 12 docs" — this entry will fail that check.
The link should either point to the folder's index (e.g. `./10-technical-requirements/00-system-components.md`) or the directory listing should be expanded into individual rows for each sub-document.
How can I resolve this? If you propose a fix, please make it concise.| | Version | 1.3.1 | | ||
| | Scope Posture | Full feature (default) | | ||
| | PR Sequencing | Enabled | | ||
| | Created | 2026-05-21 | |
There was a problem hiding this comment.
Version mismatch between frontmatter and PRD Metadata table
The YAML frontmatter declares version: 1.5.0 and the version history table's most recent entry is 1.5.0, but the PRD Metadata table in the body still shows Version | 1.3.1. Readers comparing the two will see conflicting version numbers. The Metadata table was not updated when v1.4.0 and v1.5.0 were appended to the version history.
Prompt To Fix With AI
This is a comment left during a code review.
Path: plans/chat-mobile-plan/README.md
Line: 29
Comment:
**Version mismatch between frontmatter and PRD Metadata table**
The YAML frontmatter declares `version: 1.5.0` and the version history table's most recent entry is `1.5.0`, but the PRD Metadata table in the body still shows `Version | 1.3.1`. Readers comparing the two will see conflicting version numbers. The Metadata table was not updated when v1.4.0 and v1.5.0 were appended to the version history.
How can I resolve this? If you propose a fix, please make it concise.| | [05-uc-comp.md](./05-uc-comp.md) | UC-COMP-01 through UC-COMP-05 (Composition + send) | FEATURE_SPEC | | ||
| | [06-uc-render.md](./06-uc-render.md) | UC-RENDER-01 through UC-RENDER-07 (Message rendering) | FEATURE_SPEC | | ||
| | [07-uc-pause.md](./07-uc-pause.md) | UC-PAUSE-01 through UC-PAUSE-04 (Mid-turn interactive prompts + pending-action indicator) — includes Design Rationale with citations | FEATURE_SPEC | | ||
| | [08-uc-platf.md](./08-uc-platf.md) | UC-PLATF-01 through UC-PLATF-05 (Platform integration) | FEATURE_SPEC | | ||
| | [09-team-contributions.md](./09-team-contributions.md) | Source artifacts and prior research | — | | ||
| | [10-technical-requirements.md](./10-technical-requirements.md) | System components, data, API, dependencies | CONSTITUTION | | ||
| | [11-testing-strategy.md](./11-testing-strategy.md) | Testing layers, Storybook setup, Maestro E2E, Bun test, sprint test phases | CONSTITUTION | | ||
|
|
||
| ## Quick Stats | ||
|
|
||
| | Metric | Value | | ||
| |--------|-------| | ||
| | Functional Groups | 5 | | ||
| | Use Cases | 26 | | ||
| | System Components | 9 | |
There was a problem hiding this comment.
11-component-organization-addendum.md is absent from the document index
The PR adds plans/chat-mobile-plan/11-component-organization-addendum.md (20 files total), but this file has no entry in the Document Index table. It is also numbered 11-, colliding with 11-testing-strategy.md. A reader following the index has no path to the component-organization conventions doc. The file should be added to the index and renumbered to avoid the duplicate 11- prefix (e.g. 12-component-organization-addendum.md).
Prompt To Fix With AI
This is a comment left during a code review.
Path: plans/chat-mobile-plan/README.md
Line: 44-58
Comment:
**`11-component-organization-addendum.md` is absent from the document index**
The PR adds `plans/chat-mobile-plan/11-component-organization-addendum.md` (20 files total), but this file has no entry in the Document Index table. It is also numbered `11-`, colliding with `11-testing-strategy.md`. A reader following the index has no path to the component-organization conventions doc. The file should be added to the index and renumbered to avoid the duplicate `11-` prefix (e.g. `12-component-organization-addendum.md`).
How can I resolve this? If you propose a fix, please make it concise.|
|
||
| **Many-to-one** (sprints share a PR): repeat the URL across rows. **One-to-many** (sprint subdivides): run `/kb-sprint-plan --delta-replan` to split it; each sub-sprint gets its own row. | ||
|
|
There was a problem hiding this comment.
Unresolvable local machine path referenced for collaborators
~/Projects/brain/docs/PR-SEQUENCING.md is a path on the author's local filesystem. Anyone else reading this doc cannot navigate to it. The convention it describes should either be inlined briefly here, copied into the repository, or linked via an accessible URL.
Prompt To Fix With AI
This is a comment left during a code review.
Path: plans/chat-mobile-plan/README.md
Line: 17-19
Comment:
**Unresolvable local machine path referenced for collaborators**
`~/Projects/brain/docs/PR-SEQUENCING.md` is a path on the author's local filesystem. Anyone else reading this doc cannot navigate to it. The convention it describes should either be inlined briefly here, copied into the repository, or linked via an accessible URL.
How can I resolve this? If you propose a fix, please make it concise.| The slash command popover (`@rn-primitives/popover`) renders both built-in commands (`/new`, `/clear`, `/stop`, `/model`, `/review`, `/plan`, `/test`, `/refactor`, etc.) and custom commands discovered by the host from project-level (`.claude/commands/`, `.agents/commands/`) and user-level (`~/.claude/commands/`) directories. The host-service `getSlashCommands` procedure already returns both categories; mobile's SlashCommandMenu popover must render them all, including descriptions and argument hints when present. See `packages/chat/src/server/desktop/slash-commands/registry.ts` for the discovery protocol. | ||
|
|
||
| **Acceptance Criteria:** | ||
| - ☐ User can type multiline freeform text into the chat input on the chat view |
There was a problem hiding this comment.
Wrong cross-reference: slash commands attributed to UC-COMP-04
The sentence "(handled in UC-COMP-04 and PAUSE-adjacent flows)" is attached to slash command behavior, but UC-COMP-04 is the model picker. Slash command composition and resolution are all handled within UC-COMP-01 itself (the same use case). This reference will confuse implementers tracing the slash-command flow.
Prompt To Fix With AI
This is a comment left during a code review.
Path: plans/chat-mobile-plan/05-uc-comp.md
Line: 27
Comment:
**Wrong cross-reference: slash commands attributed to UC-COMP-04**
The sentence "(handled in UC-COMP-04 and PAUSE-adjacent flows)" is attached to slash command behavior, but UC-COMP-04 is the model picker. Slash command composition and resolution are all handled within UC-COMP-01 itself (the same use case). This reference will confuse implementers tracing the slash-command flow.
How can I resolve this? If you propose a fix, please make it concise.There was a problem hiding this comment.
6 issues found across 20 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plans/chat-mobile-plan/README.md">
<violation number="1" location="plans/chat-mobile-plan/README.md:20">
P2: README contains a non-portable local filesystem path (`~/Projects/brain/docs/PR-SEQUENCING.md`) that cannot be resolved by other contributors or reviewers.</violation>
</file>
<file name="plans/chat-mobile-plan/00-overview.md">
<violation number="1" location="plans/chat-mobile-plan/00-overview.md:37">
P2: Overview contradicts detailed pause-state UI spec: it says all three pause states use bottom sheets, but the UC-PAUSE spec assigns a different container per interaction shape.</violation>
</file>
<file name="plans/chat-mobile-plan/05-uc-comp.md">
<violation number="1" location="plans/chat-mobile-plan/05-uc-comp.md:48">
P2: Inconsistent `chat.sendMessage` contract acceptance criteria between use cases: UC-COMP-02 implies `model` and `thinking level` are top-level fields, while UC-COMP-04 and UC-COMP-05 explicitly nest them under `metadata` (e.g., `metadata.model`, `metadata.thinkingLevel`). This contract ambiguity could cause incompatible client/server implementations during build.</violation>
</file>
<file name="plans/chat-mobile-plan/11-testing-strategy.md">
<violation number="1" location="plans/chat-mobile-plan/11-testing-strategy.md:53">
P1: Storybook Metro config is shown unconditionally without the `enabled` option needed for production-safe stripping. The `withStorybook` wrapper must receive `{ enabled: process.env.EXPO_PUBLIC_STORYBOOK === 'true' }` to actually exclude Storybook modules from production bundles. Without it, Storybook transforms, resolvers, and generated files remain active, contradicting the document's "zero production impact" and "zero risk" guarantees.</violation>
</file>
Reply with feedback, questions, or to request a fix.
Re-trigger cubic
| const { getDefaultConfig } = require("expo/metro-config"); | ||
| const config = getDefaultConfig(__dirname); | ||
| const withStorybook = require("@storybook/react-native/metro/withStorybook"); | ||
| module.exports = withStorybook(config); |
There was a problem hiding this comment.
P1: Storybook Metro config is shown unconditionally without the enabled option needed for production-safe stripping. The withStorybook wrapper must receive { enabled: process.env.EXPO_PUBLIC_STORYBOOK === 'true' } to actually exclude Storybook modules from production bundles. Without it, Storybook transforms, resolvers, and generated files remain active, contradicting the document's "zero production impact" and "zero risk" guarantees.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/11-testing-strategy.md, line 53:
<comment>Storybook Metro config is shown unconditionally without the `enabled` option needed for production-safe stripping. The `withStorybook` wrapper must receive `{ enabled: process.env.EXPO_PUBLIC_STORYBOOK === 'true' }` to actually exclude Storybook modules from production bundles. Without it, Storybook transforms, resolvers, and generated files remain active, contradicting the document's "zero production impact" and "zero risk" guarantees.</comment>
<file context>
@@ -0,0 +1,241 @@
+const { getDefaultConfig } = require("expo/metro-config");
+const config = getDefaultConfig(__dirname);
+const withStorybook = require("@storybook/react-native/metro/withStorybook");
+module.exports = withStorybook(config);
+```
+
</file context>
|
|
||
| **Many-to-one** (sprints share a PR): repeat the URL across rows. **One-to-many** (sprint subdivides): run `/kb-sprint-plan --delta-replan` to split it; each sub-sprint gets its own row. | ||
|
|
||
| Full convention: [`~/Projects/brain/docs/PR-SEQUENCING.md`](~/Projects/brain/docs/PR-SEQUENCING.md). |
There was a problem hiding this comment.
P2: README contains a non-portable local filesystem path (~/Projects/brain/docs/PR-SEQUENCING.md) that cannot be resolved by other contributors or reviewers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/README.md, line 20:
<comment>README contains a non-portable local filesystem path (`~/Projects/brain/docs/PR-SEQUENCING.md`) that cannot be resolved by other contributors or reviewers.</comment>
<file context>
@@ -0,0 +1,84 @@
+
+**Many-to-one** (sprints share a PR): repeat the URL across rows. **One-to-many** (sprint subdivides): run `/kb-sprint-plan --delta-replan` to split it; each sub-sprint gets its own row.
+
+Full convention: [`~/Projects/brain/docs/PR-SEQUENCING.md`](~/Projects/brain/docs/PR-SEQUENCING.md).
+
+## PRD Metadata
</file context>
|
|
||
| 3. **UI: parallel RN tree at `apps/mobile/components/chat/`**, mirroring the desktop ChatInterface component names (ChatInterface, MessageList, MessagePartsRenderer, UserMessage, AssistantMessage, etc.) but built with `@rn-primitives/*` + uniwind. Design audit (`f3e68314b`) confirmed ~80% of desktop's top-30 Tailwind classes work as-is under uniwind; the remaining ~20% has known mechanical translations. | ||
|
|
||
| 4. **Mid-turn interactive prompts as bottom sheets** (`@gorhom/bottom-sheet`), not inline cards. Approval / ask-user / plan-approval are the three pause states that block session progress; mobile thumb-reach UX favors sheets over inline rows. |
There was a problem hiding this comment.
P2: Overview contradicts detailed pause-state UI spec: it says all three pause states use bottom sheets, but the UC-PAUSE spec assigns a different container per interaction shape.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/00-overview.md, line 37:
<comment>Overview contradicts detailed pause-state UI spec: it says all three pause states use bottom sheets, but the UC-PAUSE spec assigns a different container per interaction shape.</comment>
<file context>
@@ -0,0 +1,45 @@
+
+3. **UI: parallel RN tree at `apps/mobile/components/chat/`**, mirroring the desktop ChatInterface component names (ChatInterface, MessageList, MessagePartsRenderer, UserMessage, AssistantMessage, etc.) but built with `@rn-primitives/*` + uniwind. Design audit (`f3e68314b`) confirmed ~80% of desktop's top-30 Tailwind classes work as-is under uniwind; the remaining ~20% has known mechanical translations.
+
+4. **Mid-turn interactive prompts as bottom sheets** (`@gorhom/bottom-sheet`), not inline cards. Approval / ask-user / plan-approval are the three pause states that block session progress; mobile thumb-reach UX favors sheets over inline rows.
+
+5. **Tiptap parity** via `@10play/tentap-editor` (WebView-hosted Tiptap) so slash commands and file mentions render with the same atomic-token UX as desktop. Wire format (`serializeEditorToText.ts`) is portable.
</file context>
| - ☐ User can tap an on-screen Send button to submit the composed message | ||
| - ☐ System appends the user message to the local message list immediately on submit (optimistic update) | ||
| - ☐ System clears the input field as soon as the user submits the message | ||
| - ☐ System calls `chat.sendMessage` over the relay with the serialized payload, sessionId, workspaceId, model, and thinking level |
There was a problem hiding this comment.
P2: Inconsistent chat.sendMessage contract acceptance criteria between use cases: UC-COMP-02 implies model and thinking level are top-level fields, while UC-COMP-04 and UC-COMP-05 explicitly nest them under metadata (e.g., metadata.model, metadata.thinkingLevel). This contract ambiguity could cause incompatible client/server implementations during build.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/05-uc-comp.md, line 48:
<comment>Inconsistent `chat.sendMessage` contract acceptance criteria between use cases: UC-COMP-02 implies `model` and `thinking level` are top-level fields, while UC-COMP-04 and UC-COMP-05 explicitly nest them under `metadata` (e.g., `metadata.model`, `metadata.thinkingLevel`). This contract ambiguity could cause incompatible client/server implementations during build.</comment>
<file context>
@@ -0,0 +1,89 @@
+- ☐ User can tap an on-screen Send button to submit the composed message
+- ☐ System appends the user message to the local message list immediately on submit (optimistic update)
+- ☐ System clears the input field as soon as the user submits the message
+- ☐ System calls `chat.sendMessage` over the relay with the serialized payload, sessionId, workspaceId, model, and thinking level
+- ☐ User can see the optimistic message replaced by the canonical server message once the host acknowledges
+- ☐ User can see an error toast and the input restored with the unsent text when `chat.sendMessage` fails
</file context>
| - **Session lifecycle**: start a new session, resume an existing one, end (dispose) a session, delete a session permanently with confirmation, rename a session title. | ||
| - **Auto-generated session titles** after first turn (host-service handles generation; mobile renders the synced value). | ||
| - **Message composition**: multiline text input via Tiptap (`@10play/tentap-editor`) for parity with desktop's slash-command and file-mention rendering. | ||
| - **Slash commands**: type `/` to open a popover with available commands from `chat.getSlashCommands`, preview expansion via `chat.previewSlashCommand`, resolve via `chat.resolveSlashCommand`. Mobile-friendly popover, not inline autocomplete. |
There was a problem hiding this comment.
I wonder if a button is better than hooking up / to this? trying to imagine opening keyboard -> typing slash -> closing keyboard -> clicking an option or something if it gets jank or no
| - **Mid-turn interactive prompts** with container chosen per interaction shape (see UC-PAUSE-* and the Design Rationale section in `07-uc-pause.md` for the full evidence trail): | ||
| - **Tool approval** → **inline card in the message stream + sticky thumb-docked action footer** (Approve / Decline / Always-allow-category). Queues 1-of-N when multiple approvals are pending. Mirrors Continue.dev's developer-tool chat pattern; preserves conversation context for frequent decisions. → `chat.respondToApproval` | ||
| - **`ask_user` question** → **bottom sheet** (`@gorhom/bottom-sheet` with `BottomSheetTextInput`) for freeform answer + optional suggested-pill prefills. Keyboard handling is the decisive factor. → `chat.respondToQuestion` | ||
| - **Plan approval** → **full-screen modal as a pushed expo-router route** (`/chat/[sessionId]/plan-review/[planId]`). Plan markdown gets full vertical scroll with docked Approve/Reject buttons; matches Apple HIG's recommendation of full-screen modals for "in-depth content or a task that involves multiple steps." → `chat.respondToPlan` |
There was a problem hiding this comment.
hmm this is interesting, I like this as a UX but do we have an equivalent on desktop? Avi also liked this idea iirc
| - **Tool approval** → **inline card in the message stream + sticky thumb-docked action footer** (Approve / Decline / Always-allow-category). Queues 1-of-N when multiple approvals are pending. Mirrors Continue.dev's developer-tool chat pattern; preserves conversation context for frequent decisions. → `chat.respondToApproval` | ||
| - **`ask_user` question** → **bottom sheet** (`@gorhom/bottom-sheet` with `BottomSheetTextInput`) for freeform answer + optional suggested-pill prefills. Keyboard handling is the decisive factor. → `chat.respondToQuestion` | ||
| - **Plan approval** → **full-screen modal as a pushed expo-router route** (`/chat/[sessionId]/plan-review/[planId]`). Plan markdown gets full vertical scroll with docked Approve/Reject buttons; matches Apple HIG's recommendation of full-screen modals for "in-depth content or a task that involves multiple steps." → `chat.respondToPlan` | ||
| - **Pending-action indicator** (`PendingActionIndicator`): floating "Tap to respond" pill near the chat input that surfaces when a session has an active pause and the user has scrolled away from the inline card OR dismissed the sheet/modal without responding. Tapping it returns the user to the relevant container. |
There was a problem hiding this comment.
I guess a scroll to bottom button could be enough? Unsure tho
| - **Host-offline UX**: clear UI state when the user's host-service is unreachable; automatic reconnect when host returns. | ||
| - **Session resume after background/foreground**: app catches up missed events using `stream-next-offset` / cursor protocol on resume. | ||
| - **Authentication via JWT bearer** routed through the relay; mobile mints / refreshes per the chosen sub-decision (see TRD). | ||
| - **Component tree at `apps/mobile/components/chat/`** mirroring desktop component names (ChatInterface, MessageList, MessagePartsRenderer, UserMessage, AssistantMessage, ThinkingMessage, PendingApprovalMessage, PendingQuestionMessage, PendingPlanApprovalMessage, ToolCallBlock, ChatInputFooter, ModelPicker, SlashCommandMenu). |
There was a problem hiding this comment.
would be good to colocate these with the page where they're used as a general rule-of-thumb, i think the AGENTS.md at the root has a good description for what I (selfishly) prefer!
| ├── collections/ | ||
| │ ├── collections.ts # MODIFY — add chat_sessions Electric collection | ||
| │ └── index.ts | ||
| └── push-notifications/ |
There was a problem hiding this comment.
Hmm what's the plan for push notifications, I may have missed it in the docs so far 🤔
There was a problem hiding this comment.
Just added it in v1.7.0 (commit be5361335) — sorry for the gap.
TL;DR: Host pushes a new push:lifecycle outbound message on its existing tunnel WS to apps/relay; relay looks up Expo push tokens (stored in Upstash KV keyed by push:org:{orgId}:user:{userId}) and calls Expo Push API. Mobile registers tokens via two new relay endpoints (POST / DELETE /push/register) using the same JWT bearer it uses for chat tRPC — no new auth surface, no new DB schema. Events fanned out: Stop + PermissionRequest only for v2 minimal (drops the "agent failed" notification — host emits no such event today). Permission flow follows Expo best practices (custom pre-prompt before the OS dialog, never on first cold launch, cold-launch re-check, deny → Linking.openSettings()). Foreground suppression is local-only via route-aware setNotificationHandler.
Details:
- Wire-level design (4 ASCII diagrams: delivery flow, token lifecycle, permission state machine, foreground suppression — plus Expo/EAS config, failure handling, observability):
11-technical-requirements/07-notifications.md - User-facing ACs (Permission / Token-lifecycle / Delivery / Foreground / Tap-handoff):
08-uc-platf.mdUC-PLATF-01 - Tap-to-open routing (silent host alignment + auto-open pause container):
09-uc-nav.mdUC-NAV-05 - 10 deferred items rationalized (preferences, Time-Sensitive, action buttons, per-host prefs, activity center, server-side presence, Universal Links, grouping, badging, "agent failed"):
01-scope.md - Architecture diagram (push delivery sibling to the chat-data flow):
11-technical-requirements/03-architecture-diagram.md
|
|
||
| ``` | ||
| app/(authenticated)/chat/ | ||
| ├── _layout.tsx # Stack layout config — STAYS IN APP |
There was a problem hiding this comment.
hmm I'm trying to imagine the best end-layout for the app - I wonder if a list of workspaces (which happen to have chat sessions) may be the right hierarchy to start? Although I could also see an argument that this would get tedious on mobile / that having a redundant list of chat sessions could be useful
Wdyt? I was leaning more towards having workspaces/{id}/chat/..., and then workspaces/{id} has tabs for the chat sessions, maybe to view files etc. (or something along those lines)
There was a problem hiding this comment.
Thanks for pushing on this — your workspaces/{id}/chat/... framing forced a useful design conversation. We brainstormed it with the team, and v1.6.0 of the PRD is live with the resolution.
TL;DR — sessions list as the Chat tab's default landing, sectioned by workspace (collapsible). One selected host at a time, Slack-style, via a header chip + @gorhom/bottom-sheet. Workspace details (files, runs) stay in the existing Workspaces tab — not duplicated in chat.
Why both framings reconciled: the list-of-sessions-grouped-by-workspace view is the "redundant but useful" surface you flagged. It wins as the default because the primary mobile task is check on an in-flight session (push notification → tap → land in chat). The workspace-rooted hierarchy you wanted is preserved underneath: routes nest under (chat)/[sessionId] for the chat tab; (home)/workspaces/[id] continues to own workspace-level navigation. Workspace section tap = collapse/expand (not navigate), which keeps the chat tab focused.
Bonus: resolves open Sub-Decision #6 (host selection). All four data sources we need — v2_hosts, v2_users_hosts, v2_workspaces, chat_sessions — are already exposed by apps/electric-proxy/src/where.ts:49-133. So the entire NAV data layer is "add four Electric collections to mobile" with no new tRPC. hostId resolves client-side from v2_workspaces.hostId.
v1.6.0 docs (just pushed):
- New:
09-uc-nav.md— 6 UCs + canonical ASCII wireframes for sessions list, host picker, new-chat picker, deep-link flow, empty states - Updated:
01-scope.md,03-functional-groups.md,11-technical-requirements/(system components, API design, dependencies, open sub-decisions) - File numbering cleaned up along the way (
10-team-contributions.md,11-technical-requirements/,12-component-organization-addendum.md,13-testing-strategy.md) — fixed the pre-existing11/11collision.
Sessions list teaser (full set + ACs in 09-uc-nav.md):
┌──────────────────────────────────────┐
│ ☰ Sessions [💻 macbook ▾] │
├──────────────────────────────────────┤
│ superset · chat-mobile-plan ▾ │
│ ⌖ Chat-v2 design · 2m ago │
│ ● How chat works… · 18m ago │
│ │
│ JustinCode · main ▾ │
│ ⚠ Auth refactor · pause pending │
│ │
│ LaneShadow · main ▸ │
│ ╭───╮ │
│ │ + │ │ ← FAB
│ ╰───╯ │
├──────────────────────────────────────┤
│ 🏠 ✓ 💬 ⋯ │
│ Home Tasks Chat More │
└──────────────────────────────────────┘
Open to iteration if any of this doesn't sit right.
There was a problem hiding this comment.
So if you can't tell this summary was from my agent ... LMK @saddlepaddle what you think of the direction. Me and Claude brainstormed on this and this felt like the right direction .. though I don't like the footer (askii is easy enough to change in these wireframes). I do like the idea of treating the device like a Slack "workspace" ... Given the context is always the host device it feels right. Furthermore I think you said we have data on the active workspaces and sessions there in. These can get bigger but I think starting w a grouped overview would be cool, we could then add a "view more" button if you have like more than 5 per workspace. We'd reverse sort by date so you always have the top 5 sessions. This way the landing gives you what's fresh and you don't need to drill into a bunch of endless list views. WDYT?
There was a problem hiding this comment.
I also just added some info on pagination per the session lists in the long view ... would love to get your 2c @saddlepaddle on "section" based pagination (pretty much show top 5 sessions and allow "load more" within the grouping. I'm thinking this list is somewhere between the ux of a contacts list with a sitcky header for each workspace and an expanding list. Maybe its a bad ux but I kinda like keeping everything flat for the user so they can get directly to the session they're looking for (also I think for the most part the session will probably be in the top 5 or 10.
…mes (v1.6.0) Adds shell-level navigation as a sixth functional group with 6 UCs covering the Chat bottom-nav tab, sessions list sectioned by workspace with collapse/expand, host-picker bottom sheet (Slack-style one-host-at-a-time), FAB + workspace-picker for new sessions, push-notification deep-link routing with host alignment, and empty-state handling. Canonical ASCII wireframes for all five surfaces in 09-uc-nav.md: - Sessions list (Chat tab default landing) - Host-picker bottom sheet - New-chat workspace picker - Deep-link routing flow - Empty states (no-hosts / no-workspaces / no-sessions) Resolves Technical Sub-Decision ParadevAI#6 (host selection and workspace->host resolution): hostId comes from v2_workspaces.hostId on Electric-synced rows, selected host persisted locally per user+org. No new tRPC procedures or cloud-router additions required for the NAV surface — all four data sources (v2_hosts, v2_users_hosts, v2_workspaces, chat_sessions) are already exposed by apps/electric-proxy/src/where.ts. Numbering cleanup along the way: - ADD 09-uc-nav.md - 09-team-contributions.md -> 10- - 10-technical-requirements/ -> 11- - 11-component-organization-addendum.md -> 12- - 11-testing-strategy.md -> 13- (fixes the existing 11/11 collision) Cross-references updated in 01-scope.md, 11-technical-requirements/ 04-dependencies.md, 11-technical-requirements/05-ui-infrastructure.md, 11-technical-requirements/06-open-sub-decisions.md. README Document Index, Quick Stats (32 UCs / 6 groups / 12 components), and version history reflect the changes. Version bumped 1.5.0 -> 1.6.0. Design grounded in: - Saddlepaddle review feedback on PR ParadevAI#4828 comment r3285215736 - Brainstorming dialog with the PRD owner: primary task = "check on in-flight session" (notifications-first), list shape = sectioned by workspace, host picker = header chip + bottom sheet, workspace tap = collapse/expand only (workspace details remain in existing Workspaces tab).
There was a problem hiding this comment.
Actionable comments posted: 2
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md (1)
11-11: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winMarkdown library choice should be a documented technical sub-decision.
The "(or alternative)" qualifier on
react-native-markdown-displaysignals unresolved evaluation. Since markdown rendering is core to assistant message display (UC-RENDER), the library choice should be explicitly tracked as an open technical sub-decision in11-technical-requirements/06-open-sub-decisions.mdwith evaluation criteria (e.g., performance, feature parity with desktop markdown, bundle size).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md` at line 11, Add a new open technical sub-decision entry documenting the markdown library choice (e.g., "Mobile Markdown renderer: react-native-markdown-display vs alternatives") into 11-technical-requirements/06-open-sub-decisions.md; state the current tentative selection (`react-native-markdown-display`), mark it as "open", and include evaluation criteria (performance, feature parity with desktop markdown, rendering fidelity for UC-RENDER, accessibility, bundle size, maintenance/compatibility and license) and a short plan for benchmarking and final selection. Ensure the entry references the existing mention in 11-technical-requirements/04-dependencies.md so reviewers can trace the unresolved qualifier "(or alternative)" to this sub-decision.
🧹 Nitpick comments (1)
plans/chat-mobile-plan/11-technical-requirements/02-api-design.md (1)
51-51: ⚡ Quick winHard-coded line numbers will become stale.
The reference to
where.ts:49-133creates a maintenance burden. As code evolves, these line numbers will drift, making the documentation misleading. Consider either removing the line reference or using a more stable identifier (e.g., "case statements for the four chat-related tables").📝 Suggested revision
-All four cases are present in `where.ts:49-133` (case statements for `v2_hosts`, `v2_users_hosts`, `v2_workspaces`, and `chat_sessions`). +All four cases are present in `where.ts` as case statements for `v2_hosts`, `v2_users_hosts`, `v2_workspaces`, and `chat_sessions`.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/11-technical-requirements/02-api-design.md` at line 51, The doc currently references hard-coded line numbers; replace the "where.ts:49-133" reference with a stable description such as "the case statements for the four chat-related tables (v2_hosts, v2_users_hosts, v2_workspaces, and chat_sessions)" or remove the line-number clause entirely, and keep the note that Mobile consumes these via the existing TanStack Electric DB Collection infrastructure (electricCollectionOptions / `@tanstack/electric-db-collection`) so readers can find the code by symbol names rather than fragile line ranges.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plans/chat-mobile-plan/09-uc-nav.md`:
- Line 111: Check whether the push notification payload field "workspaceId"
(payload: { sessionId, workspaceId, hostId, kind }) is actually read in the
deep-link routing flow; if it's unused, remove "workspaceId" from the payload
schema and all producers/consumers and tests to simplify the contract, otherwise
add a clear inline comment and documentation stating its purpose and implement
an explicit validation/usage in the routing logic (e.g., validate workspaceId
against the session or use it to select workspace context) so the routing flow
references "workspaceId" deterministically.
- Line 172: Clarify which data field and calculation define "most-recent
activity" by updating the acceptance criteria: state whether the default host is
chosen using v2_hosts.lastActiveAt, an aggregation of chat_sessions.lastActiveAt
(e.g., latest session timestamp), or another metric, and specify tie-breaker
behavior; include a cross-reference to the data schema (e.g., the v2_hosts or
chat_sessions field) so implementers use the exact column and algorithm when
implementing the default selection.
---
Outside diff comments:
In `@plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md`:
- Line 11: Add a new open technical sub-decision entry documenting the markdown
library choice (e.g., "Mobile Markdown renderer: react-native-markdown-display
vs alternatives") into 11-technical-requirements/06-open-sub-decisions.md; state
the current tentative selection (`react-native-markdown-display`), mark it as
"open", and include evaluation criteria (performance, feature parity with
desktop markdown, rendering fidelity for UC-RENDER, accessibility, bundle size,
maintenance/compatibility and license) and a short plan for benchmarking and
final selection. Ensure the entry references the existing mention in
11-technical-requirements/04-dependencies.md so reviewers can trace the
unresolved qualifier "(or alternative)" to this sub-decision.
---
Nitpick comments:
In `@plans/chat-mobile-plan/11-technical-requirements/02-api-design.md`:
- Line 51: The doc currently references hard-coded line numbers; replace the
"where.ts:49-133" reference with a stable description such as "the case
statements for the four chat-related tables (v2_hosts, v2_users_hosts,
v2_workspaces, and chat_sessions)" or remove the line-number clause entirely,
and keep the note that Mobile consumes these via the existing TanStack Electric
DB Collection infrastructure (electricCollectionOptions /
`@tanstack/electric-db-collection`) so readers can find the code by symbol names
rather than fragile line ranges.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: ce0835f0-3a46-4a24-a500-5a2c207ac9cc
📒 Files selected for processing (14)
plans/chat-mobile-plan/01-scope.mdplans/chat-mobile-plan/03-functional-groups.mdplans/chat-mobile-plan/09-uc-nav.mdplans/chat-mobile-plan/10-team-contributions.mdplans/chat-mobile-plan/11-technical-requirements/00-system-components.mdplans/chat-mobile-plan/11-technical-requirements/01-data-schema.mdplans/chat-mobile-plan/11-technical-requirements/02-api-design.mdplans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.mdplans/chat-mobile-plan/11-technical-requirements/04-dependencies.mdplans/chat-mobile-plan/11-technical-requirements/05-ui-infrastructure.mdplans/chat-mobile-plan/11-technical-requirements/06-open-sub-decisions.mdplans/chat-mobile-plan/12-component-organization-addendum.mdplans/chat-mobile-plan/13-testing-strategy.mdplans/chat-mobile-plan/README.md
💤 Files with no reviewable changes (5)
- plans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.md
- plans/chat-mobile-plan/12-component-organization-addendum.md
- plans/chat-mobile-plan/11-technical-requirements/01-data-schema.md
- plans/chat-mobile-plan/10-team-contributions.md
- plans/chat-mobile-plan/13-testing-strategy.md
✅ Files skipped from review due to trivial changes (6)
- plans/chat-mobile-plan/11-technical-requirements/00-system-components.md
- plans/chat-mobile-plan/11-technical-requirements/06-open-sub-decisions.md
- plans/chat-mobile-plan/03-functional-groups.md
- plans/chat-mobile-plan/11-technical-requirements/05-ui-infrastructure.md
- plans/chat-mobile-plan/README.md
- plans/chat-mobile-plan/01-scope.md
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plans/chat-mobile-plan/11-technical-requirements/02-api-design.md (1)
3-3:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix API-surface count in the opening statement.
Line 3 says there are three API surfaces, but this doc now defines four (including relay push endpoints in §4). Update the intro count to avoid implementation ambiguity.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/11-technical-requirements/02-api-design.md` at line 3, Update the opening statement in the API design doc to state four API surfaces (not three); specifically change the intro sentence that currently reads "Mobile consumes three API surfaces" to reference four to include the relay push endpoints described in §4, and scan the rest of the document for other counts or summaries to keep them consistent with this correction.
♻️ Duplicate comments (1)
plans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.md (1)
68-68:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a language identifier to the fenced block.
Line 68 triggers MD040 (
fenced-code-language); annotate the fence (e.g.,text) for lint consistency.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.md` at line 68, The fenced code block flagged by MD040 needs a language identifier: edit the triple-backtick fence shown in the diff (the fenced block with no language) and add a language token such as text (e.g., change ``` to ```text) so the markdown linter no longer flags it for missing a fenced-code-language; keep the content unchanged and commit the update.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plans/chat-mobile-plan/11-technical-requirements/07-notifications.md`:
- Line 21: Several fenced code blocks in the document are missing language tags
(MD040); locate the empty triple-backtick fences (``` ) and add an appropriate
language hint such as ```text (or ```ts for TypeScript snippets) so each fence
becomes ```text or ```ts; update all occurrences mentioned in the review (the
fences at the reported locations) to include the language tag to satisfy
markdownlint and CI.
---
Outside diff comments:
In `@plans/chat-mobile-plan/11-technical-requirements/02-api-design.md`:
- Line 3: Update the opening statement in the API design doc to state four API
surfaces (not three); specifically change the intro sentence that currently
reads "Mobile consumes three API surfaces" to reference four to include the
relay push endpoints described in §4, and scan the rest of the document for
other counts or summaries to keep them consistent with this correction.
---
Duplicate comments:
In `@plans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.md`:
- Line 68: The fenced code block flagged by MD040 needs a language identifier:
edit the triple-backtick fence shown in the diff (the fenced block with no
language) and add a language token such as text (e.g., change ``` to ```text) so
the markdown linter no longer flags it for missing a fenced-code-language; keep
the content unchanged and commit the update.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 6cb583a6-c04a-4fe3-9562-306b045ef0c1
📒 Files selected for processing (10)
plans/chat-mobile-plan/00-overview.mdplans/chat-mobile-plan/01-scope.mdplans/chat-mobile-plan/08-uc-platf.mdplans/chat-mobile-plan/11-technical-requirements/00-system-components.mdplans/chat-mobile-plan/11-technical-requirements/02-api-design.mdplans/chat-mobile-plan/11-technical-requirements/03-architecture-diagram.mdplans/chat-mobile-plan/11-technical-requirements/04-dependencies.mdplans/chat-mobile-plan/11-technical-requirements/06-open-sub-decisions.mdplans/chat-mobile-plan/11-technical-requirements/07-notifications.mdplans/chat-mobile-plan/README.md
✅ Files skipped from review due to trivial changes (6)
- plans/chat-mobile-plan/11-technical-requirements/06-open-sub-decisions.md
- plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md
- plans/chat-mobile-plan/08-uc-platf.md
- plans/chat-mobile-plan/00-overview.md
- plans/chat-mobile-plan/README.md
- plans/chat-mobile-plan/01-scope.md
|
|
||
| ### Diagram 1: Notification delivery flow | ||
|
|
||
| ``` |
There was a problem hiding this comment.
Add language tags to fenced code blocks (MD040).
These fences are missing a language hint. Use text (or ts where appropriate) to satisfy markdownlint and keep docs CI green.
Suggested patch
-```
+```text(Apply similarly at Lines 90, 115, 168, and 226.)
Also applies to: 90-90, 115-115, 168-168, 226-226
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/11-technical-requirements/07-notifications.md` at line
21, Several fenced code blocks in the document are missing language tags
(MD040); locate the empty triple-backtick fences (``` ) and add an appropriate
language hint such as ```text (or ```ts for TypeScript snippets) so each fence
becomes ```text or ```ts; update all occurrences mentioned in the review (the
fences at the reported locations) to include the language tag to satisfy
markdownlint and CI.
There was a problem hiding this comment.
2 issues found across 10 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md">
<violation number="1" location="plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md:13">
P1: PRD incorrectly claims `expo-device` provides a stable `deviceId` for multi-device push fanout; `expo-device` only exposes hardware metadata and Expo deprecated `Constants.deviceId`. The correct dependencies are `expo-application` (for Android `androidId`) and `expo-secure-store` (for iOS UUID persistence).</violation>
</file>
<file name="plans/chat-mobile-plan/11-technical-requirements/07-notifications.md">
<violation number="1" location="plans/chat-mobile-plan/11-technical-requirements/07-notifications.md:103">
P2: Upstash Set schema is inconsistent with claimed upsert/delete semantics — Redis SETs compare members by exact string equality, so a changing `lastSeenAt` causes duplicate entries and `SREM` cannot target members by `deviceId` alone.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| | `lucide-react-native` | matches mobile lucide version | Icon parity with desktop's `lucide-react` | https://lucide.dev/guide/packages/lucide-react-native | | ||
| | `react-native-markdown-display` (or alternative) | latest stable | Markdown rendering in assistant messages | https://github.com/iamacup/react-native-markdown-display | | ||
| | `expo-notifications` | matches Expo SDK 56 | Permission gating (`getPermissionsAsync` / `requestPermissionsAsync`), push token registration (`getExpoPushTokenAsync`), route-aware foreground handler (`setNotificationHandler`), and tap dispatch (`addNotificationResponseReceivedListener`) for the UC-NAV-05 deep-link router | https://docs.expo.dev/versions/latest/sdk/notifications/ | | ||
| | `expo-device` | matches Expo SDK 56 | Provides the stable `deviceId` used to keep a single user's phone + tablet addressable as separate entries in the relay-side Upstash token set (multi-device fanout) | https://docs.expo.dev/versions/latest/sdk/device/ | |
There was a problem hiding this comment.
P1: PRD incorrectly claims expo-device provides a stable deviceId for multi-device push fanout; expo-device only exposes hardware metadata and Expo deprecated Constants.deviceId. The correct dependencies are expo-application (for Android androidId) and expo-secure-store (for iOS UUID persistence).
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md, line 13:
<comment>PRD incorrectly claims `expo-device` provides a stable `deviceId` for multi-device push fanout; `expo-device` only exposes hardware metadata and Expo deprecated `Constants.deviceId`. The correct dependencies are `expo-application` (for Android `androidId`) and `expo-secure-store` (for iOS UUID persistence).</comment>
<file context>
@@ -9,7 +9,8 @@
| `react-native-markdown-display` (or alternative) | latest stable | Markdown rendering in assistant messages | https://github.com/iamacup/react-native-markdown-display |
-| `expo-notifications` | matches Expo SDK 56 | Push token registration + foreground/background notification handling | https://docs.expo.dev/versions/latest/sdk/notifications/ |
+| `expo-notifications` | matches Expo SDK 56 | Permission gating (`getPermissionsAsync` / `requestPermissionsAsync`), push token registration (`getExpoPushTokenAsync`), route-aware foreground handler (`setNotificationHandler`), and tap dispatch (`addNotificationResponseReceivedListener`) for the UC-NAV-05 deep-link router | https://docs.expo.dev/versions/latest/sdk/notifications/ |
+| `expo-device` | matches Expo SDK 56 | Provides the stable `deviceId` used to keep a single user's phone + tablet addressable as separate entries in the relay-side Upstash token set (multi-device fanout) | https://docs.expo.dev/versions/latest/sdk/device/ |
| `@storybook/react-native` | latest stable (v9) | Component testing — isolated UI state development via Storybook under custom root toggle | https://storybookjs.github.io/react-native/docs/intro/getting-started/ |
| `@storybook/addon-ondevice-controls` | matches storybook version | Storybook controls addon for RN | https://storybookjs.github.io/react-native/docs/intro/getting-started/ |
</file context>
|
|
||
| | Key | Type | Value | | ||
| |---|---|---| | ||
| | `push:org:{organizationId}:user:{userId}` | Set | Set of `{ token, platform, deviceId, lastSeenAt }` JSON entries | |
There was a problem hiding this comment.
P2: Upstash Set schema is inconsistent with claimed upsert/delete semantics — Redis SETs compare members by exact string equality, so a changing lastSeenAt causes duplicate entries and SREM cannot target members by deviceId alone.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/11-technical-requirements/07-notifications.md, line 103:
<comment>Upstash Set schema is inconsistent with claimed upsert/delete semantics — Redis SETs compare members by exact string equality, so a changing `lastSeenAt` causes duplicate entries and `SREM` cannot target members by `deviceId` alone.</comment>
<file context>
@@ -0,0 +1,373 @@
+
+| Key | Type | Value |
+|---|---|---|
+| `push:org:{organizationId}:user:{userId}` | Set | Set of `{ token, platform, deviceId, lastSeenAt }` JSON entries |
+
+Multi-device semantics: one user with a phone + a tablet keeps two entries in the same set, each with a distinct `deviceId`. The fanout module iterates the set and sends to every token. A re-`POST` for the same `deviceId` upserts (latest wins on `lastSeenAt`). `DELETE` removes only the specified `deviceId`.
</file context>
There was a problem hiding this comment.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
plans/chat-mobile-plan/01-scope.md (1)
17-24:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winUnify session timestamp field naming to avoid implementation drift.
This section mixes
last_active_atandlastActiveAtfor the same sort key, which makes the contract ambiguous for implementers.Proposed doc fix
-Within each section, sessions sort by `last_active_at` desc. +Within each section, sessions sort by `lastActiveAt` descending.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/01-scope.md` around lines 17 - 24, The doc mixes two names for the same timestamp key (`last_active_at` vs `lastActiveAt`) causing ambiguity—pick one canonical field name and update all references (sorting, display rules, pagination logic, and the "Session listing per workspace" bullet) to use it consistently; for this codebase prefer the existing Electric collection field on chat_sessions (use lastActiveAt) and ensure all mentions (e.g., "sorted by max(session.lastActiveAt)", "sessions sort by lastActiveAt desc", and any references in UC-NAV-02 / chat_sessions ordering) are changed to that single identifier so implementers have a clear contract.plans/chat-mobile-plan/09-uc-nav.md (1)
30-150:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd language identifiers to wireframe fenced blocks (MD040).
The new wireframe fences are missing language tags; this will keep markdownlint noisy.
Proposed fix pattern
-``` +```text ...wireframe... -``` +```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plans/chat-mobile-plan/09-uc-nav.md` around lines 30 - 150, The wireframe fenced code blocks (the triple-backtick blocks under sections like the header/wireframe, A2. Sessions list, A3. Sessions list, A4. Sticky workspace header) are missing language identifiers causing markdownlint MD040; update each triple-backtick fence that contains the ASCII wireframe to use a language tag (e.g., change ``` to ```text) so all wireframe blocks include a language identifier and the linter stops flagging MD040.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Outside diff comments:
In `@plans/chat-mobile-plan/01-scope.md`:
- Around line 17-24: The doc mixes two names for the same timestamp key
(`last_active_at` vs `lastActiveAt`) causing ambiguity—pick one canonical field
name and update all references (sorting, display rules, pagination logic, and
the "Session listing per workspace" bullet) to use it consistently; for this
codebase prefer the existing Electric collection field on chat_sessions (use
lastActiveAt) and ensure all mentions (e.g., "sorted by
max(session.lastActiveAt)", "sessions sort by lastActiveAt desc", and any
references in UC-NAV-02 / chat_sessions ordering) are changed to that single
identifier so implementers have a clear contract.
In `@plans/chat-mobile-plan/09-uc-nav.md`:
- Around line 30-150: The wireframe fenced code blocks (the triple-backtick
blocks under sections like the header/wireframe, A2. Sessions list, A3. Sessions
list, A4. Sticky workspace header) are missing language identifiers causing
markdownlint MD040; update each triple-backtick fence that contains the ASCII
wireframe to use a language tag (e.g., change ``` to ```text) so all wireframe
blocks include a language identifier and the linter stops flagging MD040.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d6e0b97d-3617-43b8-a32b-fbfa7c2bf275
📒 Files selected for processing (6)
plans/chat-mobile-plan/01-scope.mdplans/chat-mobile-plan/03-functional-groups.mdplans/chat-mobile-plan/09-uc-nav.mdplans/chat-mobile-plan/11-technical-requirements/00-system-components.mdplans/chat-mobile-plan/11-technical-requirements/05-ui-infrastructure.mdplans/chat-mobile-plan/README.md
✅ Files skipped from review due to trivial changes (3)
- plans/chat-mobile-plan/03-functional-groups.md
- plans/chat-mobile-plan/11-technical-requirements/00-system-components.md
- plans/chat-mobile-plan/README.md
There was a problem hiding this comment.
1 issue found across 6 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plans/chat-mobile-plan/01-scope.md">
<violation number="1" location="plans/chat-mobile-plan/01-scope.md:17">
P2: Inconsistent timestamp field naming: mixes `session.lastActiveAt` (camelCase) and `last_active_at` (snake_case) in the same sentence for the same sorting concept. This creates an ambiguous contract for implementers.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| ## In Scope | ||
|
|
||
| - **Chat tab in mobile bottom navigation** as a new top-level surface alongside the existing Tasks and More tabs. The legacy `(home)/workspaces` tab is a stub and is intentionally omitted from the sessions-list footer wireframe; downstream sprint planning will decide whether to formally hide or delete the Home tab from `apps/mobile`. Default landing is a sessions list; see UC-NAV-01. | ||
| - **Sessions list sectioned by workspace** with "{project} · {branch}" section headers, **sticky during scroll** (contact-directory pattern), sorted by `max(session.lastActiveAt)` descending. Within each section, sessions sort by `last_active_at` desc. Sections support collapse/expand (state persists per user+host); workspace tap = collapse/expand only (workspace details remain out of scope for this PRD). See UC-NAV-02. |
There was a problem hiding this comment.
P2: Inconsistent timestamp field naming: mixes session.lastActiveAt (camelCase) and last_active_at (snake_case) in the same sentence for the same sorting concept. This creates an ambiguous contract for implementers.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/01-scope.md, line 17:
<comment>Inconsistent timestamp field naming: mixes `session.lastActiveAt` (camelCase) and `last_active_at` (snake_case) in the same sentence for the same sorting concept. This creates an ambiguous contract for implementers.</comment>
<file context>
@@ -13,8 +13,10 @@ scope_posture: full
-- **Chat tab in mobile bottom navigation** as a new top-level surface alongside Home/Workspaces, Tasks, and More. Default landing is a sessions list; see UC-NAV-01.
-- **Sessions list sectioned by workspace** with collapsible "{project} · {branch}" section headers, sorted by most-recent activity. Collapsed state persists per user+host. Workspace tap = collapse/expand only (workspace details remain in the existing Workspaces tab, out of scope for this PRD). See UC-NAV-02.
+- **Chat tab in mobile bottom navigation** as a new top-level surface alongside the existing Tasks and More tabs. The legacy `(home)/workspaces` tab is a stub and is intentionally omitted from the sessions-list footer wireframe; downstream sprint planning will decide whether to formally hide or delete the Home tab from `apps/mobile`. Default landing is a sessions list; see UC-NAV-01.
+- **Sessions list sectioned by workspace** with "{project} · {branch}" section headers, **sticky during scroll** (contact-directory pattern), sorted by `max(session.lastActiveAt)` descending. Within each section, sessions sort by `last_active_at` desc. Sections support collapse/expand (state persists per user+host); workspace tap = collapse/expand only (workspace details remain out of scope for this PRD). See UC-NAV-02.
+- **Per-workspace session pagination** capped at 5 sessions per section on initial render when ≥2 workspaces have sessions, with a "Load more (N more)" pill that appends the next 5 in-place (no navigation). When only one workspace has sessions, the cap is disabled and all sessions render. Displayed-count state persists per `(userId, hostId, workspaceId)`. See UC-NAV-02.
+- **Cross-workspace title search/filter** via a TextInput in the sessions-list header. Case-insensitive substring match on `chat_sessions.title` across every workspace on the selected host; results preserve workspace grouping (sections with zero matches hide). Per-section cap and Load more are disabled while a query is active. Filter runs client-side over the synced Electric collection — no new backend. See UC-NAV-07.
</file context>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plans/chat-mobile-plan/ROADMAP.md`:
- Line 25: The ROADMAP.md contains a machine-local link string
`~/Projects/brain/docs/PR-SEQUENCING.md` which won’t resolve for others; update
that reference in the `**PR sequencing enabled.**` line to use a
repository-relative docs path (for example `docs/PR-SEQUENCING.md` or
`./docs/PR-SEQUENCING.md`) or a plain-text filename so it’s portable for all
contributors, and make the same replacement for the other occurrence of the same
local path elsewhere in the file.
- Line 278: The roadmap uses a misspelled component name
"RebableInSettingsBanner"; update every occurrence to the correct component name
"ReenableInSettingsBanner" (or whatever canonical name you use) so stories, task
names, and PR titles stay consistent; search for "RebableInSettingsBanner" in
this file and replace with "ReenableInSettingsBanner" and verify the same fix is
applied to related mentions noted in the comment (the other occurrences) and any
story or task references that will drive implementation/PR names.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: a12e8f37-94fa-4a55-bfde-d6c33caa05c9
📒 Files selected for processing (1)
plans/chat-mobile-plan/ROADMAP.md
|
|
||
| > **Skill-rule override (per user direction, 2026-05-21).** The `kb-sprint-plan` skill's default test-step rule rejects `\bstorybook\b` as a verification surface ("Storybook is a developer tool, not the product"). This roadmap **intentionally overrides** that rule for Phase 1 only, because the testing strategy spelled out in `13-testing-strategy.md` explicitly designates Storybook 9 (under custom root toggle `EXPO_PUBLIC_STORYBOOK=true` with build-time stripping for production) as the Phase 1 verification harness, and the user has selected this strategy. Phase 2 sprints use Maestro E2E against the running app per the default rule. | ||
|
|
||
| > **PR sequencing enabled.** Lifecycle: 🔵 Planned → 🟠 In flight → 🟣 In review → ✅ Completed → 🔴 Blocked. PR cell required for Completed status. See [`~/Projects/brain/docs/PR-SEQUENCING.md`](~/Projects/brain/docs/PR-SEQUENCING.md) for the full convention. |
There was a problem hiding this comment.
Replace local filesystem links with repo-relative docs links.
The ~/Projects/brain/docs/PR-SEQUENCING.md reference is machine-local and won’t resolve for other contributors. Use a repository-relative path (or plain text reference) so the roadmap is portable.
Also applies to: 648-648
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/ROADMAP.md` at line 25, The ROADMAP.md contains a
machine-local link string `~/Projects/brain/docs/PR-SEQUENCING.md` which won’t
resolve for others; update that reference in the `**PR sequencing enabled.**`
line to use a repository-relative docs path (for example `docs/PR-SEQUENCING.md`
or `./docs/PR-SEQUENCING.md`) or a plain-text filename so it’s portable for all
contributors, and make the same replacement for the other occurrence of the same
local path elsewhere in the file.
| **Test Steps:** | ||
| 1. Launch the mobile app in Storybook mode on iOS Simulator and Android Emulator. | ||
| 2. Navigate to **PushPrePromptScreen** stories — confirm the centered illustration / bell icon, heading copy, body copy (matching `07-notifications.md` permission rationale), benefits list, Enable primary button (`--color-primary` fill at 44pt), and Not-now text button at 48pt tap area. | ||
| 3. Navigate to **RebableInSettingsBanner** stories — verify the granted (hidden), denied (visible with `--color-destructive` accent and "Re-enable in Settings" + `Linking.openSettings()` CTA), and undetermined (informational) variants. |
There was a problem hiding this comment.
Fix component name typo for the re-enable banner.
RebableInSettingsBanner appears in multiple places and looks misspelled. Keeping this typo in roadmap/task naming can cause implementation and PR naming drift later.
Also applies to: 288-288, 303-303, 565-565
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@plans/chat-mobile-plan/ROADMAP.md` at line 278, The roadmap uses a misspelled
component name "RebableInSettingsBanner"; update every occurrence to the correct
component name "ReenableInSettingsBanner" (or whatever canonical name you use)
so stories, task names, and PR titles stay consistent; search for
"RebableInSettingsBanner" in this file and replace with
"ReenableInSettingsBanner" and verify the same fix is applied to related
mentions noted in the comment (the other occurrences) and any story or task
references that will drive implementation/PR names.
There was a problem hiding this comment.
2 issues found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plans/chat-mobile-plan/README.md">
<violation number="1" location="plans/chat-mobile-plan/README.md:20">
P2: README contains a non-portable local filesystem path (`~/Projects/brain/docs/PR-SEQUENCING.md`) that cannot be resolved by other contributors or reviewers.</violation>
</file>
<file name="plans/chat-mobile-plan/00-overview.md">
<violation number="1" location="plans/chat-mobile-plan/00-overview.md:37">
P2: Overview contradicts detailed pause-state UI spec: it says all three pause states use bottom sheets, but the UC-PAUSE spec assigns a different container per interaction shape.</violation>
</file>
<file name="plans/chat-mobile-plan/05-uc-comp.md">
<violation number="1" location="plans/chat-mobile-plan/05-uc-comp.md:48">
P2: Inconsistent `chat.sendMessage` contract acceptance criteria between use cases: UC-COMP-02 implies `model` and `thinking level` are top-level fields, while UC-COMP-04 and UC-COMP-05 explicitly nest them under `metadata` (e.g., `metadata.model`, `metadata.thinkingLevel`). This contract ambiguity could cause incompatible client/server implementations during build.</violation>
</file>
<file name="plans/chat-mobile-plan/11-testing-strategy.md">
<violation number="1" location="plans/chat-mobile-plan/11-testing-strategy.md:53">
P1: Storybook Metro config is shown unconditionally without the `enabled` option needed for production-safe stripping. The `withStorybook` wrapper must receive `{ enabled: process.env.EXPO_PUBLIC_STORYBOOK === 'true' }` to actually exclude Storybook modules from production bundles. Without it, Storybook transforms, resolvers, and generated files remain active, contradicting the document's "zero production impact" and "zero risk" guarantees.</violation>
</file>
<file name="plans/chat-mobile-plan/01-scope.md">
<violation number="1" location="plans/chat-mobile-plan/01-scope.md:17">
P2: Inconsistent timestamp field naming: mixes `session.lastActiveAt` (camelCase) and `last_active_at` (snake_case) in the same sentence for the same sorting concept. This creates an ambiguous contract for implementers.</violation>
</file>
<file name="plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md">
<violation number="1" location="plans/chat-mobile-plan/11-technical-requirements/04-dependencies.md:13">
P1: PRD incorrectly claims `expo-device` provides a stable `deviceId` for multi-device push fanout; `expo-device` only exposes hardware metadata and Expo deprecated `Constants.deviceId`. The correct dependencies are `expo-application` (for Android `androidId`) and `expo-secure-store` (for iOS UUID persistence).</violation>
</file>
<file name="plans/chat-mobile-plan/11-technical-requirements/07-notifications.md">
<violation number="1" location="plans/chat-mobile-plan/11-technical-requirements/07-notifications.md:103">
P2: Upstash Set schema is inconsistent with claimed upsert/delete semantics — Redis SETs compare members by exact string equality, so a changing `lastSeenAt` causes duplicate entries and `SREM` cannot target members by `deviceId` alone.</violation>
</file>
<file name="plans/chat-mobile-plan/ROADMAP.md">
<violation number="1" location="plans/chat-mobile-plan/ROADMAP.md:278">
P2: Misspelled component name `RebableInSettingsBanner` in roadmap (should be `ReEnableInSettingsBanner`) — will propagate into generated task artifacts.</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| **Test Steps:** | ||
| 1. Launch the mobile app in Storybook mode on iOS Simulator and Android Emulator. | ||
| 2. Navigate to **PushPrePromptScreen** stories — confirm the centered illustration / bell icon, heading copy, body copy (matching `07-notifications.md` permission rationale), benefits list, Enable primary button (`--color-primary` fill at 44pt), and Not-now text button at 48pt tap area. | ||
| 3. Navigate to **RebableInSettingsBanner** stories — verify the granted (hidden), denied (visible with `--color-destructive` accent and "Re-enable in Settings" + `Linking.openSettings()` CTA), and undetermined (informational) variants. |
There was a problem hiding this comment.
P2: Misspelled component name RebableInSettingsBanner in roadmap (should be ReEnableInSettingsBanner) — will propagate into generated task artifacts.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/ROADMAP.md, line 278:
<comment>Misspelled component name `RebableInSettingsBanner` in roadmap (should be `ReEnableInSettingsBanner`) — will propagate into generated task artifacts.</comment>
<file context>
@@ -0,0 +1,665 @@
+**Test Steps:**
+1. Launch the mobile app in Storybook mode on iOS Simulator and Android Emulator.
+2. Navigate to **PushPrePromptScreen** stories — confirm the centered illustration / bell icon, heading copy, body copy (matching `07-notifications.md` permission rationale), benefits list, Enable primary button (`--color-primary` fill at 44pt), and Not-now text button at 48pt tap area.
+3. Navigate to **RebableInSettingsBanner** stories — verify the granted (hidden), denied (visible with `--color-destructive` accent and "Re-enable in Settings" + `Linking.openSettings()` CTA), and undetermined (informational) variants.
+4. Navigate to **HostOfflineBanner** stories — confirm every dispatch outcome variant renders distinct copy: offline-idle ("Host offline — tap to retry"), offline-retrying (spinner + "Reconnecting…"), online (hidden), session-unavailable ("Session unavailable" + back link), `skipped_unpaid` ("Plan upgrade required" or equivalent), `dispatch_failed` ("Host dispatch failed" with retry).
+5. Navigate to the **NotificationIconPreview** story — confirm the 192×192 transparent PNG asset renders as a white silhouette at multiple display sizes (192pt, 96pt, 24pt) and matches the Android status-bar small-icon constraints.
</file context>
Generates a folder-structured PRD for the v0 mobile chat surface at plans/chat-mobile-plan/. Mirrors the desktop ChatInterface tree as a parallel React Native implementation, talks HTTP+tRPC to the host-service through apps/relay (same pattern as apps/desktop/src/renderer/lib/ host-service-client.ts), and uses ElectricSQL for session-list sync. Generated without a live Claude Agent Team collaboration; sourced from the prior research artifact (plans/20260521-mobile-chat-research.md on local-setup-no-env, 4 revisions) and the design-tokens audit (commit f3e68314b). Tagged 09-team-contributions.md with that lineage. Structure: - README.md v1.0.0, PR sequencing enabled, full-feature scope - 00-overview.md [PRODUCT_CONTEXT] - 01-scope.md [FEATURE_SPEC] — 25 in-scope items, deferrals to v1 PRDs - 02-roles.md [PRODUCT_CONTEXT] — User, System, Host-service - 03-functional-groups.md [FEATURE_SPEC] — 5 groups: SESS/COMP/RENDER/PAUSE/PLATF - 04-uc-sess.md [FEATURE_SPEC] — 5 UCs, session lifecycle - 05-uc-comp.md [FEATURE_SPEC] — 5 UCs, composition + send - 06-uc-render.md [FEATURE_SPEC] — 7 UCs, message rendering - 07-uc-pause.md [FEATURE_SPEC] — 3 UCs, mid-turn interactive prompts - 08-uc-platf.md [FEATURE_SPEC] — 5 UCs, platform integration - 09-team-contributions.md source artifacts + open product decisions - 10-technical-requirements.md [CONSTITUTION] — components, data, API, deps, arch diagram Total: 25 UCs across 5 groups; new deps @shopify/flash-list, @gorhom/bottom-sheet, @10play/tentap-editor, lucide-react-native, react-native-markdown-display, expo-notifications. Next: /kb-sprint-plan organizes this into human-testable sprints.
Tool approval moves from bottom-sheet to inline card + sticky thumb-docked action footer (Continue.dev pattern; preserves chat context for frequent 3-10x-per-session approvals; NN/G context-framing research). Plan approval moves from bottom-sheet to full-screen modal pushed as an expo-router route at /chat/[sessionId]/plan-review/[planId]. Apple HIG explicitly recommends full-screen modal for "in-depth content or multistep tasks"; multi-screen plan markdown fights bottom-sheet inner scroll gestures. Ask-user question stays as a bottom sheet — keyboard input is the decisive factor; @gorhom/bottom-sheet's BottomSheetTextInput handles keyboard avoidance cleanly across both iOS and Android. New UC-PAUSE-04 adds a floating "Tap to respond" pending-action indicator that surfaces when the user has scrolled away from an active pause or dismissed a sheet/modal. Adds a Design Rationale section to 07-uc-pause.md with citations: - Apple HIG — Modality (sheets vs full-screen vs alerts framework) - Apple HIG — Privacy (why agent prompts != system permissions) - Nielsen Norman Group — Permission Requests (context-framing research) - Continue.dev — Agent Mode (peer-product inline tool approval pattern) - Cline — Auto Approve (future-state escape hatch deferred to v1) - Material Design 3 — Bottom Sheets (Android parity) Updates: 01-scope.md, 03-functional-groups.md, 07-uc-pause.md (full rewrite + Design Rationale), 10-technical-requirements.md (component table + arch diagram), README.md (Quick Stats + Version History). Version bumped 1.0.0 -> 1.1.0. Use case total: 25 -> 26.
Each entry in 01-scope.md's Out-of-Scope section now carries: - A clear tag: [DEFERRED: separate PRD] vs [NOT SUPPORTED] - A one-sentence Why grounded in the originating conversation Why distinguish DEFERRED from NOT_SUPPORTED: - DEFERRED = could ship later as its own initiative (attachments, file mentions, user mentions, linked issues, Plus menu, restart-from-message, edit-last-user-message, MCP overview, Electric message persistence, attachment payload UI in messages) - NOT_SUPPORTED = architectural/product boundary that will not flip without changing this PRD's assumptions (local chat code execution on mobile, rich text formatting, multi-keystroke shortcuts, cross-platform UI component library, real-time tRPC subscriptions) Adds two previously-implicit exclusions that surfaced during the rationale audit: - "Real-time tRPC subscriptions for chat" — chat-v2 PRD proposes them but they're not merged; v0 reads via request/response tRPC with cursor protocol for resume, defers streaming to a sub-decision. - "Attachment payload UI in messages" — render must pair with send; shipping render-only would be confusing UX. Version bumped 1.1.0 -> 1.2.0 (FEATURE_SPEC clarification per kb-prd-plan versioning rules — scope wording refined, not added to).
"v2" is the platform's loaded generational term (v2-workspace,
v2-projects, v2-hosts, chat-v2 desktop architecture redesign). The
mobile app's current terminal-via-web mirror is implicit mobile chat
v1; this PRD scopes the first native chat experience as mobile-chat v2,
aligning the terminology with the rest of the platform.
Updates across README.md, 00-overview.md, 01-scope.md, 02-roles.md,
03-functional-groups.md, 05-uc-comp.md, 06-uc-render.md, 07-uc-pause.md,
09-team-contributions.md, 10-technical-requirements.md.
Untouched:
- /api/electric/v1/shape (Electric Shape protocol versioning, unrelated)
- "chat-v2" references that point to the *desktop* chat architecture
redesign (separate, planning-only effort)
- "mobile chat v1" references in the naming note (explains the rename)
Future-work references ("v1 PRD", "deferred to v1") become "a future
mobile-chat PRD" — clearer than reusing the v1 token for both past
state and future plans.
Added a naming-clarification note at the top of README.md so reviewers
don't conflate this with the desktop chat-v2 architecture work.
Per-file prd_version frontmatter bumped to 1.3.0 (CONSTITUTION,
FEATURE_SPEC, PRODUCT_CONTEXT files all updated). README version
history extended.
The desktop chat-v2 PRD is a local draft, not visible to PRD reviewers. Citing it as evidence in the mobile-chat v2 scope rationale created an "insider knowledge" footgun: anyone reading the PRD on origin/main has no way to follow the citation. Removed two references in 01-scope.md (Pure-Electric persistence Why and Real-time tRPC subscriptions Why); rewrote both to stand on the existing repo-state findings (host runtime memory only; zero tRPC subscriptions in chat path today). Trimmed the README naming note: dropped the "and the in-flight chat-v2 desktop architecture redesign" line, plus the final sentence about chat-v2 references elsewhere in the doc (there now are none). Cleaned version-history entry 1.3.0 to match. No scope change; rationale cleanup only. PATCH bump 1.3.0 -> 1.3.1.
The 1.3.1 changelog entry itself named the unmerged draft, defeating the point of stripping it from the rest of the doc. Rephrased to "an unmerged local-only PRD draft" — same meaning, no orphan name token left for reviewers to wonder about.
Codebase-verified review found 5 critical issues and 4 medium issues. All fixes applied against real file:line evidence. Critical fixes: - UC-RENDER-02: desktop uses polling at ~4 FPS, not character-drip - Transport framing: mobile relay-HTTP is deliberate adaptation of desktop IPC, not a mirror - Custom slash command awareness: ACs for rendering host-discovered custom commands in @rn-primitives/popover - Host selection sub-decision ParadevAI#6: workspace→host resolution gap - previewSlashCommand: added to API table + UC-COMP-01 ACs Medium fixes: - getDisplayState added to API table - Optimistic update ACs for UC-PAUSE-01/02/03 - Line refs corrected, expo-notifications SDK 55→56 Also includes component tree restructure into AGENTS.md co-location tree format with screen/lib directory plans. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Split the monolith 10-technical-requirements.md into a directory: 10-technical-requirements/ ├── 00-system-components.md ├── 01-data-schema.md ├── 02-api-design.md ├── 03-architecture-diagram.md ├── 04-dependencies.md ├── 05-ui-infrastructure.md └── 06-open-sub-decisions.md No content changes — pure structural split for navigability.
New 11-testing-strategy.md with three-layer pyramid: - Storybook 9 under custom root toggle (EXPO_PUBLIC_STORYBOOK=true) with build-time stripping for production — isolated UI testing prior to service integration ensures fidelity, atomic composition ensures speed and accuracy - Maestro for YAML-based E2E flows (simpler than Detox/Appium) - Bun test for shared logic unit tests Sprint strategy: Phase 1 = Storybook-gated component builds, Phase 2+ = Maestro-gated service wiring. Updated 01-scope.md, 10-technical-requirements/04-dependencies.md, and README.md index + changelog. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…e at API level Replace misleading "read-mostly client" framing in data-schema.md with explicit scope split: - mobile WRITES heavily at the host-service API layer (sendMessage, respondTo*, stop, endSession, session CRUD) - mobile writes lightly at the database layer (session metadata only) Add Host Runtime Message Storage section explaining the actual model (Map<sessionId, RuntimeSession> per host process, Mastra harness owns the per-session Memory store, eviction is possible) so planners / implementers don't assume durability. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…mes (v1.6.0) Adds shell-level navigation as a sixth functional group with 6 UCs covering the Chat bottom-nav tab, sessions list sectioned by workspace with collapse/expand, host-picker bottom sheet (Slack-style one-host-at-a-time), FAB + workspace-picker for new sessions, push-notification deep-link routing with host alignment, and empty-state handling. Canonical ASCII wireframes for all five surfaces in 09-uc-nav.md: - Sessions list (Chat tab default landing) - Host-picker bottom sheet - New-chat workspace picker - Deep-link routing flow - Empty states (no-hosts / no-workspaces / no-sessions) Resolves Technical Sub-Decision ParadevAI#6 (host selection and workspace->host resolution): hostId comes from v2_workspaces.hostId on Electric-synced rows, selected host persisted locally per user+org. No new tRPC procedures or cloud-router additions required for the NAV surface — all four data sources (v2_hosts, v2_users_hosts, v2_workspaces, chat_sessions) are already exposed by apps/electric-proxy/src/where.ts. Numbering cleanup along the way: - ADD 09-uc-nav.md - 09-team-contributions.md -> 10- - 10-technical-requirements/ -> 11- - 11-component-organization-addendum.md -> 12- - 11-testing-strategy.md -> 13- (fixes the existing 11/11 collision) Cross-references updated in 01-scope.md, 11-technical-requirements/ 04-dependencies.md, 11-technical-requirements/05-ui-infrastructure.md, 11-technical-requirements/06-open-sub-decisions.md. README Document Index, Quick Stats (32 UCs / 6 groups / 12 components), and version history reflect the changes. Version bumped 1.5.0 -> 1.6.0. Design grounded in: - Saddlepaddle review feedback on PR ParadevAI#4828 comment r3285215736 - Brainstorming dialog with the PRD owner: primary task = "check on in-flight session" (notifications-first), list shape = sectioned by workspace, host picker = header chip + bottom sheet, workspace tap = collapse/expand only (workspace details remain in existing Workspaces tab).
UC-PLATF-01 was the only notification spec; everything wire-level was
undefined. This commit locks the design after a brainstorming pass.
Architecture (relay-side fanout):
- Host emits a new outbound `push:lifecycle` message on its existing
tunnel WS to apps/relay (hosts sit behind NAT — only the tunnel
reaches them; no new connection).
- apps/relay/src/push.ts (NEW) consumes the message, looks up Expo
push tokens for org+user in Upstash KV, calls Expo Push API.
- New endpoints POST /push/register + DELETE /push/register/:deviceId
on apps/relay, gated by the same verifyJWT middleware that protects
chat tRPC routing — no new auth surface, no new DB schema.
- Tokens keyed by push:org:{orgId}:user:{userId} as a multi-device set.
Scope:
- v2 minimal: Stop + PermissionRequest events only.
- "agent failed" dropped (host-service emits no failure event today).
- Permission flow follows Expo best practices (custom pre-prompt before
OS dialog, never on first cold launch, cold-launch re-check, deny →
Linking.openSettings()).
- Foreground suppression is local-only via route-aware
setNotificationHandler.
- Custom-scheme deep-link; UC-NAV-05 (already in v1.6.0) handles tap
routing — UC-PLATF-01 cross-references it.
Files touched:
- 00-overview.md: rewrote point 7 of solution summary.
- 01-scope.md: rewrote in-scope push bullet + added 10 new
Out-of-Scope items (preferences, Time-Sensitive, action buttons,
per-host prefs, activity center, server-side presence, Universal
Links, grouping, badging, "agent failed").
- 08-uc-platf.md: UC-PLATF-01 fully rewritten — 14 ACs grouped into
Permission / Token-lifecycle / Delivery / Foreground / Tap-handoff.
- 11-technical-requirements/00-system-components.md: rewrote push
handler row; added Pre-prompt screen, Relay push fanout, Push
registration endpoints rows.
- 11-technical-requirements/02-api-design.md: added §4 Relay push
endpoints with storage layout + auth reuse details.
- 11-technical-requirements/03-architecture-diagram.md: added a
second diagram for push delivery (host → tunnel → relay → Expo).
- 11-technical-requirements/04-dependencies.md: augmented
expo-notifications row; added expo-device for stable deviceId.
- 11-technical-requirements/06-open-sub-decisions.md: marked
sub-decision ParadevAI#7 resolved.
- 11-technical-requirements/07-notifications.md (NEW): wire-level
design — 4 ASCII diagrams (delivery, token lifecycle, permission
state machine, foreground suppression), token cleanup paths,
Expo/EAS configuration, failure handling, observability.
- README.md: version → 1.7.0, document index updated for new file
(now 8 files in 11-technical-requirements/), deps count → 5,
v1.7.0 history entry.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Extends UC-NAV-02 with sticky workspace section headers, per-section
pagination (5-cap with Load more when multi-workspace, no cap in
single-workspace mode), and adds UC-NAV-07 for cross-workspace title
search. Trims the sessions-list bottom-tab footer to 3 tabs
(Tasks/Chat/More) — legacy Home is a stub and is intentionally omitted.
Wireframes added/replaced in 09-uc-nav.md:
- A. Sessions list (multi-workspace default) — adds search bar,
Load more pill on capped sections, sticky-header annotation,
3-tab footer
- A2. Sessions list (single-workspace mode) — cap disabled, all
sessions render, no Load more
- A3. Sessions list (search active) — filtered sections only, clear
affordance, plus a "no matches" empty state
- A4. Sticky-header scroll progression — 3-frame contact-directory
behavior
- E. Empty states — footer reduced to 3 tabs (Home omitted)
- Bottom-tab footer rationale section added under wireframes
UC-NAV-02 acceptance criteria extended with 8 new ACs covering:
- last_active_at desc within section
- Sticky headers during scroll
- 5-session per-section cap when multi-workspace
- Load more pill + in-place +5 append
- Hide Load more when displayed >= total
- Single-workspace bypasses the cap
- Persist sectionDisplayCounts per (userId, hostId, workspaceId)
UC-NAV-07 (new) — 10 ACs for the search input: debounced client-side
filter over the synced Electric chat_sessions collection, workspace
grouping preserved, sections with zero matches hidden, cap + Load
more disabled while query active, "no matches" empty state, clear
affordance, no new backend.
Cross-references updated:
- 01-scope.md: 3 new in-scope items (pagination, sticky headers,
search); Chat tab sibling-tab list updated to "Tasks and More"
- 03-functional-groups.md: NAV row description updated, NAV UC count
6 -> 7, total 32 -> 33
- 11-technical-requirements/00-system-components.md: Sessions list
screen entry extended with state shape (sectionDisplayCounts,
searchQuery), notes SessionSearchBar + LoadMorePill subcomponents
- 11-technical-requirements/05-ui-infrastructure.md: WorkspaceSection
now flagged as sticky-during-scroll (FlashList stickyHeaderIndices
approach + SectionList fallback noted), SessionSearchBar added to
the screen component tree with debounced filter pattern
- README.md: frontmatter 1.7.0 -> 1.8.0, metadata table version
updated, Document Index reflects UC-NAV-07, Quick Stats UCs
32 -> 33, new 1.8.0 version history entry
No new backend procedures, no new dependencies — all behaviors are
client-side over the already-synced Electric chat_sessions
collection.
Plan reference: ~/.claude/plans/mutable-twirling-curry.md
…k → Maestro E2E) Phase 1 (Sprints 01-05): pure props-driven components with co-located Storybook stories verified on simulator/emulator. Sprint 01 includes the Storybook root toggle + .rnstorybook config + Metro wrapper as discrete infra tasks. Phase 2 (Sprints 06-11): real-screen assembly composing Phase 1 components + service wiring (Electric collections, host-service tRPC, relay push pipeline, offline detection) with Maestro E2E gates against real services. 95 tasks total across react-native-ui-implementer, node-implementer, and frontend-designer specialists. PR sequencing enabled with Branch + PR columns per sprint. Phase 1 explicitly overrides the kb-sprint-plan skill's default Storybook-as-gate rejection per user direction.
…en sprint Reframes the ROADMAP to drive Phase 1 component work via the pixel-perfect plugin on a single branch / single PR, replacing the prior 5-sprint per-tier decomposition. Frontmatter - sprint_count: 11 → 7 - +phase_1_driver: pixel-perfect Sprint Sequence - Sprints 01–05 collapse into Sprint 01: Pixel-Perfect UI Components (sessions-list + chat-tree + composer + pause + platform-surface tiers, all on one branch) - Sprints 06–11 renumber to Sprints 02–07; Phase 1 dependency refs collapse to Sprint 01 Sprint 01 details - Tracks pixel-perfect manifest gates (discover/target/equip + per-platform scaffold/plan/atoms/molecules/compose) - Documents component inventory (preserves MOB-* / DESIGN-* IDs as scope reference, but no longer drives task dispatch) - Aggregates PRD coverage across all 5 original sprints (UC-NAV-01/02/03/04/06/07, UC-RENDER-01/03/04/05/06/07, UC-COMP-01/04/05, UC-PAUSE-01/02/03/04, UC-PLATF-01/03) Cross-cutting notes - Phase 1↔Phase 2 contract: pixel-perfect's plan phase owns prop interfaces - Design enrichments: reframed as inputs pixel-perfect's plan phase MUST encode - PR sequencing: Phase 1 = one branch / one PR; Phase 2 unchanged - Skill-rule override note rescoped (Phase 1 no longer routes through kb-sprint-plan)
Flip the mobile sessions-list mental model from host-first to
project-first. Sessions list becomes a flat, recency-sorted FlashList
with workspace shown as inline row metadata (no sectioning, no sticky
headers, no per-section pagination). Filter UI moves to a bottom sheet
(workspace + status) triggered from a ⚙ button next to the search bar;
applied filters render as removable chip tags below the search bar.
Tunnel lifecycle becomes lazy — opened on chat-route mount via
`workspace.hostId`, dropped on unmount.
UC cascade
- Retire UC-NAV-02 (sticky workspace sections + per-section pagination)
- Retire UC-NAV-03 (header host picker)
- Retarget UC-NAV-01 (new header composition: project chip + search + ⚙)
- Retarget UC-NAV-04 (FAB workspace picker scoped to project, rows show
`branch · host` across all hosts)
- Retarget UC-NAV-05 (push deep-link aligns project; readiness gate
awaits v2_workspaces sync, falls back to tRPC chat.getSnapshot on
cold-launch race; tunnel opens lazily on chat-route mount)
- Retarget UC-NAV-06 (5 empty states including new filters-no-match)
- Retarget UC-NAV-07 (search scope = project, host as row metadata only)
- Add UC-NAV-08 (filter sessions by workspace + status; applied chip
tags + badge count)
Component changes
- Rename SelectedHostProvider → SelectedProjectProvider, with one-time
migration that drops legacy selectedHostId from expo-secure-store
and seeds selectedProjectId via most-recent-activity / alphabetical-
first fallback. Also handles "selected project no longer accessible"
with a re-run + toast.
- Delete HostPickerSheet.
- Add ProjectPickerSheet (only renders when org has ≥2 projects),
SessionFilterSheet (workspace + status multi-select, no host axis,
no date axis), AppliedFilterTags (horizontally-scrollable chip row
with stale-chip cleanup on Electric tombstones).
- Add useChatTunnel hook with cross-remount de-dupe (single in-flight
per hostId), background/foreground lifecycle, and skeleton/retry UI
state shape.
- SessionsListScreen state shape becomes
`activeFilters: { workspaceIds[], statuses[] }` + `searchQuery: string`,
both in-memory only.
- Row truncation order locked: title → branch → host → time.
Backend invariants preserved
No new tRPC procedures. No Electric shape changes. No relay protocol
changes. The chat_sessions shape stays org-scoped at
apps/electric-proxy/src/where.ts:136-137 and all filtering happens
client-side via useLiveQuery joins to v2_workspaces (cache-first per
AGENTS.md TanStack DB rule). Push payload remains
`{ sessionId, workspaceId, hostId, kind }` — mobile derives projectId
from the synced workspace row.
Files
README.md ........................ v1.8.0 → v2.0.0, full changelog row
01-scope.md ...................... NAV in-scope items rewritten;
new [NOT SUPPORTED] / [DEFERRED]
items for sectioning, sticky
headers, host picker, per-section
pagination, host filter axis,
date filter axis, workspace
creation on mobile
03-functional-groups.md .......... NAV description rewritten;
UC count 7 → 6, total 33 → 32
09-uc-nav.md ..................... full rewrite (flat-list wireframe,
project picker wireframe, filter
sheet + applied-tag wireframe,
new-chat picker wireframe, deep-
link flow, 5 empty-state wireframes,
all new ACs)
11-technical-requirements/
00-system-components.md ........ Host-picker sheet removed,
SelectedHost→SelectedProject
renamed, Project-picker sheet +
Session-filter sheet +
useChatTunnel rows added,
Sessions list screen + Deep-link
handler rows rewritten, backend
invariant note added
02-api-design.md ............... Electric collections table
rewritten; v2_hosts/v2_users_hosts
rows removed, v2_projects added;
client-side scoping section
rewritten for project-first model
04-dependencies.md ............. expo-router route list updated
(host-picker route removed,
project-picker + filter routes
added)
05-ui-infrastructure.md ........ SessionsListScreen subcomponents
replaced, providers/hooks list
rewritten, TestIDs documented
06-open-sub-decisions.md ....... Sub-Decision ParadevAI#6 re-resolved with
the project-first model,
superseding v1.6.0 host-first
Adversarial validation
Pre-write review by react-native-ui-planner, frontend-designer, and
node-planner specialists (parallel dispatch via Task tool). All
surfaced concerns folded in: tunnel-handshake skeleton + timeout
error, legacy selectedHostId migration, deleted-project fallback,
row truncation order, FlashList tuning, accessibility states,
deep-link readiness gate, useChatTunnel dedupe, ProjectPickerSheet
cache-first counts.
Downstream
ROADMAP.md in plans/chat-mobile-plan/ROADMAP.md still references the
retired v1.x NAV components (HostPickerSheet, WorkspaceSection,
LoadMorePill, HostChip, MOB-INFRA-006 SelectedHostProvider). It is
generated by /kb-sprint-plan and should be regenerated with
/kb-sprint-plan --delta-replan to align the implementation roadmap
with the v2.0.0 spec. ROADMAP.md is intentionally NOT touched in this
commit — that is the sprint planner's job, not the PRD's.
Audit + fill wireframe coverage across the 5 non-NAV UC files. Before
this pass, 04-uc-sess / 05-uc-comp / 06-uc-render / 07-uc-pause /
08-uc-platf carried zero wireframes (0 box-drawing characters, 0 code
fences across ~570 lines of UC prose) — `09-uc-nav.md` was the only
file matching the wireframe bar. Brings every UI-bearing UC up to the
NAV-file standard.
Coverage added (drop-in ASCII per UC)
SESS
UC-SESS-01 session list loaded + empty state
UC-SESS-02 chat-view skeleton during load + error/retry
UC-SESS-03 cross-references NAV-04 §D (FAB → workspace picker)
+ SESS-02 §A (empty chat-view layout)
UC-SESS-04 session overflow menu (Rename / End / Delete…)
UC-SESS-05 delete confirmation dialog
COMP
UC-COMP-01 composer idle, typing+Send enabled, slash popover
UC-COMP-02 cross-references COMP-01 §B + RENDER-01 §A
(optimistic append is behavioral)
UC-COMP-03 composer streaming with Stop button replacing Send
UC-COMP-04 model picker popover with Anthropic/OpenAI sections
UC-COMP-05 thinking-level popover (perm-mode follows same shape)
RENDER
UC-RENDER-01 user + assistant + streaming-cursor message list
UC-RENDER-02 cross-references RENDER-01 §A streaming cursor
UC-RENDER-03 code block + inline code rendering
UC-RENDER-04 ToolCallBlock three status states (run / done / fail)
UC-RENDER-05 PlanBlock collapsed/expanded + ReasoningBlock
UC-RENDER-06 nested subagent execution group
UC-RENDER-07 scroll-back FAB (↓ Latest) with Reanimated FadeIn
PAUSE
UC-PAUSE-01 inline approval card + sticky thumb-docked footer
UC-PAUSE-02 ask_user bottom sheet with pills + raised keyboard
UC-PAUSE-03 plan-review full-screen modal with docked Approve/Reject
UC-PAUSE-04 floating PendingActionIndicator pill
PLATF
UC-PLATF-01 in-app push pre-prompt + settings denied banner
UC-PLATF-02 cross-references SESS-02 §A (resume is invisible UX)
UC-PLATF-03 host-offline banner + dispatch-outcome variants
(skipped_unpaid / dispatch_failed / skipped_offline
— matches SUPER-771 enum)
UC-PLATF-04 cross-references PLATF-03 §A (reconnect is reverse)
UC-PLATF-05 cross-references NAV-01 §A (real-time row insertion)
Conventions
- ASCII only (box-drawing chars + status emoji ⌖ ⚠ ● ○ + entity icons
🌿 📦 💻 ☁️ ✕ ✓ ⚙); no SVG, no Figma refs, no images.
- Width ~38-42 chars so wireframes render cleanly in markdown.
- Each wireframe carries a 1-2 sentence caption noting what's shown
and cross-referencing related UCs.
- UCs whose UI is fully covered by an adjacent wireframe carry an
inline cross-reference instead of a duplicated wireframe (SESS-03,
COMP-02, RENDER-02, PLATF-02, PLATF-04, PLATF-05).
- Token-palette callouts use code-token references (e.g.
`← --color-destructive`, `← --color-warning`) so designers can map
to the mobile token palette without coloring the ASCII.
Adversarial process
Audit run by frontend-designer specialist via the Agent tool. The
agent's coverage matrix flagged 21 UCs missing wireframes; spot-grep
confirmed (0 box-drawing chars, 0 code fences in all 5 target
files). All proposed wireframes folded in as-is from the agent's
output, with light editing to add cross-references where adjacent
UCs already cover a state (avoiding duplicate wireframe drift).
Files
README.md ........................ v2.0.0 → v2.0.1, full changelog row
03-functional-groups.md .......... frontmatter version bump only
04-uc-sess.md .................... +160 / -1 (4 wireframes + 1 xref)
05-uc-comp.md .................... +118 / -1 (5 wireframes + 1 xref)
06-uc-render.md .................. +158 / -1 (6 wireframes + 1 xref)
07-uc-pause.md ................... +126 / -1 (4 wireframes)
08-uc-platf.md ................... +109 / -1 (2 wireframes + 3 xrefs)
No UC behavior changes. No scope changes. No new components. No backend
changes. Pure documentation pass to bring designer/implementer
readiness across all UI-bearing UCs to the bar set by 09-uc-nav.md in
v2.0.0.
Versioning rule: PATCH bump (2.0.0 → 2.0.1) since no scope or UC
content changed — only documentation richness.
9fd088c to
d541711
Compare
….0/v2.0.1
Re-plans the chat-mobile-plan sprint roadmap against the v2.0.0 project-
first refactor and the v2.0.1 wireframes pass. User directive: keep all
UI work in Sprint 1 (pure components only — providers/hooks/wiring stay
in Phase 2). Sprints 5 and 7 unchanged; Sprints 1/2/3/4/6 changed
surgically; no new sprints, no obsolete sprints.
Sprint 01 — Pixel-Perfect UI Components (CHANGED)
Component Inventory rewritten for project-first chrome.
Retired (from v1.x host-first model):
MOB-NAV-003 WorkspaceSection + LoadMorePill
MOB-NAV-004 HostChip
MOB-NAV-008-UI HostPickerSheet
DESIGN-NAV-001 (workspace-section sticker sheet)
DESIGN-NAV-002 (HostPickerSheet sticker sheet)
Added (v2.0.0 components):
MOB-NAV-002-V2 SessionRow (flat two-line: title + 🌿 branch · 💻
host · time; truncation order title→branch→host→time)
MOB-NAV-004-V2 NewChatFab / SessionSearchBar (project-scoped) /
SessionsEmptyState (5 variants — added filters-no-match)
MOB-NAV-013 ProjectChip (static label when org has 1 project;
tappable chip + ▾ when ≥2)
MOB-NAV-014 ProjectPickerSheet
MOB-NAV-015 SessionFilterSheet (workspace + status multi-select
with Clear all + Apply footer)
MOB-NAV-016 AppliedFilterTags (horizontal-scroll removable chips
+ Clear ✕; stale-tombstone cleanup)
MOB-NAV-017 FilterButton (⚙ + ·N badge state)
DESIGN-NAV-001-V2 SessionsListScreen flat-layout sticker sheet
DESIGN-NAV-002-V2 ProjectPickerSheet sticker sheet
DESIGN-NAV-004 SessionFilterSheet + AppliedFilterTags sticker sheet
Test step 3 (sessions-list tier) fully rewritten — walks new components
only, no retired references; explicitly calls out FilterButton ·0
vs ·N badge state distinction.
PRD Coverage: dropped UC-NAV-02 / UC-NAV-03; added UC-NAV-08;
flagged 11-technical-requirements/05-ui-infrastructure.md as
v2.0.0-rewritten.
Sprint 02 — Sessions List Integration (CHANGED, host-first → project-first)
Gate sentence rewritten — flat recency-sorted, project-scoped,
project picker (when org ≥2 projects), filter sheet with applied
tags. Preserves "within 3s" desktop→mobile sync SLA clause.
Removed:
MOB-INFRA-006 SelectedHostProvider (replaced by -V2)
MOB-NAV-006 sticky-header wiring (no longer needed)
MOB-NAV-007 workspace collapse/expand persistence (no longer needed)
MOB-NAV-008-INT HostPickerSheet wiring (replaced by ProjectPickerSheet)
Added (-V2 suffix preserves task-ID traceability across the refactor):
MOB-INFRA-005-V2 Project-first Electric collections (chat_sessions,
v2_workspaces, v2_projects; drops v2_hosts +
v2_users_hosts which are no longer needed at NAV)
MOB-INFRA-006-V2 SelectedProjectProvider + idempotent one-shot
migration from legacy selectedHostId; MUST complete
before useSessionsForProject mounts (avoids empty-
list flash)
MOB-INFRA-007-V2 useSessionsForProject derived selector
(cache-first per AGENTS.md TanStack DB rule)
MOB-INFRA-011 useAccessibleProjects hook
MOB-NAV-008-V2 ProjectPickerSheet wiring (renders only when org
has ≥2 projects; counts via cache-first useLiveQuery)
MOB-NAV-010-V2 Empty-state rendering — 5 variants
MOB-NAV-013-V2 SessionFilterSheet wiring + activeFilters state
MOB-NAV-014-V2 AppliedFilterTags wiring + Electric-tombstone cleanup
MOB-NAV-017-V2 FilterButton badge wiring
Test Steps rewritten to walk project-first flow (project chip switch,
filter sheet apply, applied-tags remove, Electric-tombstone cleanup).
Sprint 02 task count: 12 → 14.
PRD Coverage: dropped UC-NAV-02 / UC-NAV-03; added UC-NAV-08.
Sprint 03 — Chat View Read + Session Management (CHANGED, add useChatTunnel)
Gate sentence adds "lazy relay tunnel opens against workspace.hostId
via useChatTunnel; skeleton during ~300ms handshake; inline retry
banner on tunnel error."
Added:
MOB-INFRA-010 useChatTunnel hook (lazy open on mount, drop on
unmount, drop on background, re-open on foreground;
cross-remount dedupe per hostId; surfaces
{ status: 'connecting' | 'open' | 'error', retry })
Updated:
MOB-SESS-002 ChatScreen mounts useChatTunnel; shows skeleton
loader during handshake; inline Can't reach {hostName}
retry banner on tunnel error
Test Steps add a tunnel-handshake observation + error-banner verification.
Sprint 03 task count: 8 → 9.
PRD Coverage: added UC-NAV-05 (lazy tunnel resolution).
Sprint 04 — Compose + Send Integration (CHANGED, NewChatSheet project scope)
Gate clarified: "workspaces in the selected project across all hosts."
Test step 1 and MOB-NAV-009-INT updated: rows show branch · host
metadata, picker scoped by projectId not hostId.
Sprint 05 — Pause Response Integration (UNCHANGED)
Sprint 06 — Push Notifications (CHANGED, deep-link aligns project)
Gate sentence rewritten (both prose locations) — "silent host alignment"
→ "silent project alignment + lazy host resolution"; spells out the
cold-launch race fallback to tRPC chat.getSnapshot.
Test step 5 rewritten — project alignment + lazy tunnel handshake +
cold-launch readiness gate fallback.
Updated:
MOB-NAV-012-V2 handleDeepLink awaits v2_workspaces readiness with
bounded timeout; falls back to tRPC chat.getSnapshot
on cold-launch race; resolves workspace.projectId;
aligns selectedProjectId; pushes chat route (lazy
tunnel opens via useChatTunnel on mount)
PRD Coverage: UC-NAV-05 entry updated to reflect project-first
alignment + cold-launch race fallback.
Sprint 07 — Offline + Background Resume (UNCHANGED)
Cross-Cutting Notes (CHANGED)
Removed: Sticky-header fallback path (sticky headers retired).
Updated: Status icon glyph palette — now references MOB-NAV-002-V2
with v2.0.0 flat two-line SessionRow layout and explicit truncation
order title→branch→host→time.
Added: Lazy tunnel handshake contract — useChatTunnel's
{ status, retry } prop contract that ChatScreen consumes for
skeleton + retry UI; pixel-perfect must pre-shape Phase 1 chat-tree
components to accept a tunnelStatus prop or render inside a host
that gates on it.
Added: Workspace filter chip uniqueness — branch · host
disambiguation when branches share names across hosts; stale-
tombstone silent drop on next render.
Header/Overview
Total Tasks: 53 → 56 (Sprint 02 +2 net, Sprint 03 +1).
Sprint Sequence table — gate-brief column updated for sprints 1,
2, 3, 4, 6; task count cells updated for sprints 2 and 3.
Hand-tuned overrides preserved
Skill-rule storybook override (Phase 1 only), pixel-perfect
manifest gate state, PR sequencing columns + Branch/PR cells,
Phase 1 ↔ Phase 2 contract section, design enrichment notes,
PR sequencing operational notes, out-of-scope reminders — all
unchanged.
Adversarial validation by react-native-ui-planner specialist
(dispatched via Task tool in background, validation completed before
edits applied). Five concerns folded in (test-step rewrite explicit,
Sprint 01 PRD Coverage deletion, status-icon truncation order
captured, Sprint 06 both prose locations rewritten, 3s SLA preserved
in Sprint 02 gate). Five suggested additions folded in (FilterButton
badge story note, SelectedProjectProvider one-shot/idempotent + must
complete before useSessionsForProject, ProjectPickerSheet ≥2-projects
assertion, useChatTunnel {status, retry} contract in Phase 1↔2
notes, 12-component-organization-addendum.md PRD Coverage ref).
No new sprints, no obsolete sprints. No threats to hand-tuned overrides.
There was a problem hiding this comment.
1 issue found across 1 file (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="plans/chat-mobile-plan/ROADMAP.md">
<violation number="1" location="plans/chat-mobile-plan/ROADMAP.md:76">
P2: Sprint 01 test step for ProjectPickerSheet mentions `useLiveQuery` data fetching, conflicting with the Phase 1 pure-component contract</violation>
</file>
Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic
| **Test Steps:** | ||
| 1. From `apps/mobile/`, run `bun storybook` — this generates `.rnstorybook/storybook.requires.ts` and launches Expo with `EXPO_PUBLIC_STORYBOOK=true`. Open the iOS Simulator and Android Emulator simultaneously. | ||
| 2. **Design System** group — navigate to Colors, Typography, Spacing, Icons. Confirm every swatch / variant / spacing step / icon reads from the existing global.css tokens (no deviation from the locked vibe). | ||
| 3. **Sessions-list tier (project-first chrome — v2.0.0)** — navigate every story for SessionRow (two-line layout: title with status icon `⌖ ⚠ ● ○` + metadata line `🌿 branch · 💻 host · time`; truncation order title → branch → host → time; long-press copy), ProjectChip (static-label variant when org has 1 project; tappable chip with `▾` when ≥2), ProjectPickerSheet (sheet handle, project rows with workspace + session counts derived via cache-first `useLiveQuery`, currently-selected check, populated + single-project-hidden variants), FilterButton (`⚙` idle state + `⚙·N` badge state when `activeFilters` length ≥ 1, with `·0` hidden vs `·N` visible distinction), AppliedFilterTags (workspace chip `🌿 branch · host` + status chip `⌖ Streaming` | `⚠ Pause pending` | `● Idle`, removable `✕` per chip, trailing `Clear ✕`, horizontal-scroll overflow, stale-chip Electric-tombstone cleanup), SessionFilterSheet (stacked Workspace multi-select rows showing `branch · host` for cross-host disambiguation + Status multi-select with Streaming / Pause pending / Idle rows, Clear all + Apply footer, `accessibilityState={{ selected }}` on rows), NewChatFab (shadow + 56pt FAB), SessionSearchBar (project-scoped placeholder, focused + clear ✕), SessionsEmptyState (no-projects / no-workspaces / no-sessions / search-no-match / filters-no-match — five variants). |
There was a problem hiding this comment.
P2: Sprint 01 test step for ProjectPickerSheet mentions useLiveQuery data fetching, conflicting with the Phase 1 pure-component contract
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At plans/chat-mobile-plan/ROADMAP.md, line 76:
<comment>Sprint 01 test step for ProjectPickerSheet mentions `useLiveQuery` data fetching, conflicting with the Phase 1 pure-component contract</comment>
<file context>
@@ -73,7 +73,7 @@ Gate state tracked in `apps/mobile/design/manifest.json`:
1. From `apps/mobile/`, run `bun storybook` — this generates `.rnstorybook/storybook.requires.ts` and launches Expo with `EXPO_PUBLIC_STORYBOOK=true`. Open the iOS Simulator and Android Emulator simultaneously.
2. **Design System** group — navigate to Colors, Typography, Spacing, Icons. Confirm every swatch / variant / spacing step / icon reads from the existing global.css tokens (no deviation from the locked vibe).
-3. **Sessions-list tier** — navigate every story for SessionRow (status icons `⌖ ⚠ ● ○` with token colors, long-press copy), WorkspaceSection (sticky-header, collapse/expand chevron, empty-with-CTA), LoadMorePill (44pt button, `--color-secondary` background, `--radius` corners), HostChip, NewChatFab (shadow + 56pt FAB), SessionSearchBar (placeholder + focused + clear ✕), SessionsEmptyState (no-hosts / no-workspaces / no-sessions / no-search variants), HostPickerSheet (sheet handle, online/offline row badges, currently-selected check, populated + empty variants).
+3. **Sessions-list tier (project-first chrome — v2.0.0)** — navigate every story for SessionRow (two-line layout: title with status icon `⌖ ⚠ ● ○` + metadata line `🌿 branch · 💻 host · time`; truncation order title → branch → host → time; long-press copy), ProjectChip (static-label variant when org has 1 project; tappable chip with `▾` when ≥2), ProjectPickerSheet (sheet handle, project rows with workspace + session counts derived via cache-first `useLiveQuery`, currently-selected check, populated + single-project-hidden variants), FilterButton (`⚙` idle state + `⚙·N` badge state when `activeFilters` length ≥ 1, with `·0` hidden vs `·N` visible distinction), AppliedFilterTags (workspace chip `🌿 branch · host` + status chip `⌖ Streaming` | `⚠ Pause pending` | `● Idle`, removable `✕` per chip, trailing `Clear ✕`, horizontal-scroll overflow, stale-chip Electric-tombstone cleanup), SessionFilterSheet (stacked Workspace multi-select rows showing `branch · host` for cross-host disambiguation + Status multi-select with Streaming / Pause pending / Idle rows, Clear all + Apply footer, `accessibilityState={{ selected }}` on rows), NewChatFab (shadow + 56pt FAB), SessionSearchBar (project-scoped placeholder, focused + clear ✕), SessionsEmptyState (no-projects / no-workspaces / no-sessions / search-no-match / filters-no-match — five variants).
4. **Chat-tree tier** — navigate every story for UserMessage (right-aligned bubble, `bg-secondary`, `max-w-[85%]`, long-press copy), AssistantMessage (left-aligned full-width, optional streaming-cursor Reanimated blink variant), MessageMarkdown (code blocks with syntax highlighting, lists / headings / blockquotes / tables / HRs, inline code contrast, tappable links, long-press copy on code blocks), ToolCallBlock (collapsed-only card with running / completed / failed status indicators + right-chevron, no expansion UI per UC-RENDER-04), PlanBlock and ReasoningBlock (collapsed + expanded with smooth chevron rotation), SubagentExecutionMessage (nested visual indentation + left border), ScrollBackButton (FadeIn / FadeOut animation, 44pt hit target).
5. **Composer tier** — navigate every story for TiptapPromptEditor (empty-with-placeholder, typed-text, slash-pill-inserted, file-mention-placeholder, multi-line autogrow, autogrow-cap; verify keyboard reveal + caret positioning), SlashCommandMenu (built-in only, built-in + custom mixed, description + arg-hint, preview-loading, empty-loading), ModelPicker (popover with mock list incl. Opus 4.7 / Sonnet 4.6 / Haiku 4.5 / GPT-5.5, selected-model trigger label), PermissionModePicker + ThinkingLevelPicker (`off / low / medium / high / xhigh` for thinking-level, permission mode variants, selected-state trigger), NewChatSheet (workspace-row layout, sessions-first sort, empty-host inline message, no-sessions meta line). Verify every toolbar control meets the 44pt hit-target rule.
</file context>
| 3. **Sessions-list tier (project-first chrome — v2.0.0)** — navigate every story for SessionRow (two-line layout: title with status icon `⌖ ⚠ ● ○` + metadata line `🌿 branch · 💻 host · time`; truncation order title → branch → host → time; long-press copy), ProjectChip (static-label variant when org has 1 project; tappable chip with `▾` when ≥2), ProjectPickerSheet (sheet handle, project rows with workspace + session counts derived via cache-first `useLiveQuery`, currently-selected check, populated + single-project-hidden variants), FilterButton (`⚙` idle state + `⚙·N` badge state when `activeFilters` length ≥ 1, with `·0` hidden vs `·N` visible distinction), AppliedFilterTags (workspace chip `🌿 branch · host` + status chip `⌖ Streaming` | `⚠ Pause pending` | `● Idle`, removable `✕` per chip, trailing `Clear ✕`, horizontal-scroll overflow, stale-chip Electric-tombstone cleanup), SessionFilterSheet (stacked Workspace multi-select rows showing `branch · host` for cross-host disambiguation + Status multi-select with Streaming / Pause pending / Idle rows, Clear all + Apply footer, `accessibilityState={{ selected }}` on rows), NewChatFab (shadow + 56pt FAB), SessionSearchBar (project-scoped placeholder, focused + clear ✕), SessionsEmptyState (no-projects / no-workspaces / no-sessions / search-no-match / filters-no-match — five variants). | |
| 3. **Sessions-list tier (project-first chrome — v2.0.0)** — navigate every story for SessionRow (two-line layout: title with status icon `⌖ ⚠ ● ○` + metadata line `🌿 branch · 💻 host · time`; truncation order title → branch → host → time; long-press copy), ProjectChip (static-label variant when org has 1 project; tappable chip with `▾` when ≥2), ProjectPickerSheet (sheet handle, project rows with workspace + session counts passed as mock/static props (data shape prefiguring Sprint 02 `useAccessibleProjects`/`useLiveQuery` wiring), currently-selected check, populated + single-project-hidden variants), FilterButton (`⚙` idle state + `⚙·N` badge state when `activeFilters` length ≥ 1, with `·0` hidden vs `·N` visible distinction), AppliedFilterTags (workspace chip `🌿 branch · host` + status chip `⌖ Streaming` | `⚠ Pause pending` | `● Idle`, removable `✕` per chip, trailing `Clear ✕`, horizontal-scroll overflow, stale-chip defensive omission when workspace not in provided props), SessionFilterSheet (stacked Workspace multi-select rows showing `branch · host` for cross-host disambiguation + Status multi-select with Streaming / Pause pending / Idle rows, Clear all + Apply footer, `accessibilityState={{ selected }}` on rows), NewChatFab (shadow + 56pt FAB), SessionSearchBar (project-scoped placeholder, focused + clear ✕), SessionsEmptyState (no-projects / no-workspaces / no-sessions / search-no-match / filters-no-match — five variants). |

Summary
PRD for Mobile Chat v2 — the first native mobile chat experience in
apps/mobile. Lives atplans/chat-mobile-plan/. Docs-only; no code changes.Ships a parallel React Native ChatInterface tree that consumes the existing
@superset/host-servicetRPC surface over the relay. No new server architecture — mobile is a thin client against the same agent loop desktop drives.Scope
AppRouter, routed throughapps/relay(per-host WS tunnel) with JWT bearer auth — deliberate mobile-specific adaptation of desktop's IPC chat pathchat_sessionsshape (zero new infra)getDisplayState+listMessages)apps/mobile/components/chat/, mirroring desktop component names but built with@rn-primitives/*+ uniwind +@10play/tentap-editor+@gorhom/bottom-sheet+@shopify/flash-listDocument 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)
Also includes:
Test plan
This is a docs-only PR — no code to run. Reviewer verification:
What's NOT in this PR
🤖 Generated with Claude Code
Summary by cubic
Adds the Mobile Chat v2 PRD in
plans/chat-mobile-plan/, defining the first native chat forapps/mobileover the@superset/host-servicetRPC viaapps/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
apps/relaywith JWT; updates via polling to match desktop behavior.chat_sessions; mobile is full read‑write at host API (send/stop/respond), with DB writes limited to session metadata.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).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
SelectedProjectProvider,useSessionsForProject, anduseChatTunnel(handshake + retry).chat.getSnapshot; total tasks now 56 across 7 sprints.Written for commit ef0942c. Summary will update on new commits. Review in cubic
Summary by CodeRabbit