docs: add iteration 2 polish plan
This commit is contained in:
Mohamed Boudra
@@ -0,0 +1,160 @@
|
|||||||
|
# Execution Plan — Iteration 2 Projects → Workspaces → Tabs (Paseo Orchestrated)
|
||||||
|
|
||||||
|
This document describes **how** we will execute the fixes defined in:
|
||||||
|
- `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md`
|
||||||
|
|
||||||
|
It is optimized for parallel work using **Paseo-managed worktrees** and strict quality gates.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Constraints / Guardrails
|
||||||
|
|
||||||
|
- **Do not restart or modify** the user’s main daemon on `localhost:6767`.
|
||||||
|
- Use **isolated dev stacks** for manual verification (new daemon + new Metro) via:
|
||||||
|
- `PASEO_HOME=~/.paseo-<unique>` and `npm run dev` (auto-picks free ports).
|
||||||
|
- No “legacy view” preserved: we fix the current UX directly (no dead/unused code paths left behind).
|
||||||
|
- Agents must treat **terminals and agents as equal first-class tab types** (no special layouts).
|
||||||
|
- Keep changes focused to the reported issues; avoid unrelated refactors.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Work Breakdown (Parallel)
|
||||||
|
|
||||||
|
### Agent A — Sidebar drag scoping + sidebar polish
|
||||||
|
|
||||||
|
**Worktree:** `polish/sidebar-dnd-and-style`
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
- Fix project drag so dragging a **project header** reorders the **entire project section** (header + workspaces).
|
||||||
|
- Fix workspace drag so workspaces reorder **only within their project** (no cross-project placement).
|
||||||
|
- Ensure sidebar list **snaps back** to canonical `Project → Workspaces` structure after any drag.
|
||||||
|
- Sidebar visuals:
|
||||||
|
- remove workspace “border” style, match project “ghost” style language
|
||||||
|
- remove “No agents yet”
|
||||||
|
- reduce workspace indentation/padding (mobile-friendly)
|
||||||
|
- Navigation polish:
|
||||||
|
- clicking a workspace closes the left sidebar (mobile)
|
||||||
|
|
||||||
|
### Agent B — Workspace header + tabs polish (icons, unified create, persistence)
|
||||||
|
|
||||||
|
**Worktree:** `polish/workspace-tabs-and-header`
|
||||||
|
|
||||||
|
Responsibilities:
|
||||||
|
- Workspace header shows **branch name** for git workspaces (including base branch like `main`).
|
||||||
|
- Replace separate “create agent” vs “create terminal” rows with **one unified New Tab control** (agent + terminal).
|
||||||
|
- Agent tabs show **provider icons** (Claude + Codex minimum, using existing assets/components).
|
||||||
|
- Fix “remember focused tab per workspace” so:
|
||||||
|
- switching away and back restores the last focused agent/terminal tab
|
||||||
|
- stored selection is **not overwritten** while agent/terminal lists are still loading
|
||||||
|
|
||||||
|
### Agent C — Review / sanity check (no code changes)
|
||||||
|
|
||||||
|
Runs after merges to:
|
||||||
|
- review diff for edge cases + regressions
|
||||||
|
- double-check acceptance criteria mapping
|
||||||
|
- call out missing verification steps
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Launch Commands (local CLI)
|
||||||
|
|
||||||
|
We use the repo-local CLI:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run -s cli -- run --provider codex --model gpt-5.3-codex --mode full-access --worktree <name> --name "<title>" --detach "<prompt>" --quiet
|
||||||
|
```
|
||||||
|
|
||||||
|
Notes:
|
||||||
|
- `--detach --quiet` returns the agent ID quickly so we can launch in parallel.
|
||||||
|
- Each agent must **commit** their work in their worktree branch before finishing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Prompts (exact)
|
||||||
|
|
||||||
|
### Prompt for Agent A
|
||||||
|
|
||||||
|
Title: `🎭 Sidebar DnD + Polish`
|
||||||
|
|
||||||
|
Prompt:
|
||||||
|
- Implement **only** the items in “Sidebar drag behavior” + “Sidebar visuals + navigation polish” from `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md`.
|
||||||
|
- Do not change gestures beyond the required drag constraints.
|
||||||
|
- Ensure the post-drag list snaps back to the canonical project/workspace grouping.
|
||||||
|
- Remove “No agents yet” and fix workspace row styling/indentation.
|
||||||
|
- Close sidebar on workspace selection (mobile).
|
||||||
|
- Run `npm run typecheck` and `npm run test --workspace=@getpaseo/app` in the worktree.
|
||||||
|
- Commit with a clear message.
|
||||||
|
|
||||||
|
### Prompt for Agent B
|
||||||
|
|
||||||
|
Title: `🎭 Workspace Tabs + Header`
|
||||||
|
|
||||||
|
Prompt:
|
||||||
|
- Implement **only** the items in “Workspace header + tab bar fixes” from `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md`.
|
||||||
|
- Terminals and agents must be treated as identical first-class tab types (no separate rows/layout).
|
||||||
|
- Add provider icons for agent tabs (Claude/Codex minimum) using existing app icon components.
|
||||||
|
- Fix per-workspace focused-tab persistence (don’t overwrite selection while queries are pending).
|
||||||
|
- Run `npm run typecheck` and `npm run test --workspace=@getpaseo/app` in the worktree.
|
||||||
|
- Commit with a clear message.
|
||||||
|
|
||||||
|
### Prompt for Agent C (review-only)
|
||||||
|
|
||||||
|
Title: `🎭 Review: Sidebar + Tabs Polish`
|
||||||
|
|
||||||
|
Prompt:
|
||||||
|
- Review the combined diff for correctness vs acceptance criteria in `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md`.
|
||||||
|
- DO NOT edit code. Provide a checklist of anything missing or risky.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Merge Strategy (back to `main`)
|
||||||
|
|
||||||
|
1. Wait for Agents A + B to complete.
|
||||||
|
2. For each worktree branch:
|
||||||
|
- verify it has a clean commit history (no unrelated changes)
|
||||||
|
- re-run `npm run typecheck` if needed
|
||||||
|
3. Merge into `main` sequentially:
|
||||||
|
- merge A
|
||||||
|
- rebase/merge B on top of updated `main` (resolve conflicts if any)
|
||||||
|
4. Do not delete/prune worktrees until the user has manually verified.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification Gates (strict)
|
||||||
|
|
||||||
|
### 1) Automated (must pass)
|
||||||
|
|
||||||
|
From repo root on `main` after merges:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run typecheck
|
||||||
|
npm run test --workspace=@getpaseo/app
|
||||||
|
```
|
||||||
|
|
||||||
|
Optional (run if environment supports it; starts isolated daemon/metro itself):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:e2e --workspace=@getpaseo/app
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2) Manual (must be performed by us before handing back)
|
||||||
|
|
||||||
|
Use an **isolated dev stack** (new daemon + new Metro):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
PASEO_HOME=~/.paseo-iter2-polish npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Then use `agent-browser` to verify the “Manual (agent-browser)” section in:
|
||||||
|
- `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Completion Definition
|
||||||
|
|
||||||
|
We are “done” when:
|
||||||
|
- All acceptance criteria in `PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md` are met.
|
||||||
|
- Automated verification gates pass.
|
||||||
|
- Manual verification steps pass.
|
||||||
|
- Changes are merged into `main` with no leftover legacy code paths.
|
||||||
|
|
||||||
@@ -0,0 +1,185 @@
|
|||||||
|
# Iteration 2 — Projects → Workspaces → Tabs (UX Polish + Behavior Fixes)
|
||||||
|
|
||||||
|
This plan is a follow-up iteration on the already-merged “Projects → Workspaces → Tabs” redesign.
|
||||||
|
|
||||||
|
Scope is **client-only UX/behavior fixes** requested after manual testing.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Goals (What changes in this iteration)
|
||||||
|
|
||||||
|
### 1) Sidebar drag behavior (Projects + Workspaces)
|
||||||
|
|
||||||
|
- **Project drag moves the whole section**
|
||||||
|
- Dragging a **project heading** reorders the **entire project section** (heading + its workspaces), even when expanded.
|
||||||
|
- **Workspace drag is scoped**
|
||||||
|
- Dragging a **workspace** only reorders **within its project**.
|
||||||
|
- A workspace must **never end up visually under another project** after drop.
|
||||||
|
- **No “invalid” intermediate layouts**
|
||||||
|
- If a drag results in a transient invalid arrangement (e.g., a workspace visually dropped between projects), the list must **snap back** to the canonical `Project → Workspaces` structure immediately after drop.
|
||||||
|
|
||||||
|
### 2) Sidebar visuals + navigation polish
|
||||||
|
|
||||||
|
- **Workspace rows match project row styling**
|
||||||
|
- Remove the “weird border” on workspaces.
|
||||||
|
- Workspace rows should follow the same “ghost”/hover/pressed style language as project headings.
|
||||||
|
- **Reduce workspace indentation/padding**
|
||||||
|
- Workspaces are currently too indented; reduce indent, especially on mobile.
|
||||||
|
- **Remove noisy “No agents yet” label**
|
||||||
|
- Empty workspaces are valid; do not display a “No agents yet” label anywhere in the sidebar tree.
|
||||||
|
- **Workspace click closes sidebar (mobile)**
|
||||||
|
- When tapping a workspace from the left sidebar on mobile, the sidebar closes before navigation.
|
||||||
|
|
||||||
|
### 3) Workspace header + tab bar fixes
|
||||||
|
|
||||||
|
- **Workspace header title is the branch name**
|
||||||
|
- For git workspaces, the header must show the **current branch name**, including the base branch (e.g., `main`).
|
||||||
|
- For non-git workspaces, fall back to workspace name.
|
||||||
|
- **Agents and terminals are first-class tab types**
|
||||||
|
- Remove “special layout” treatment where agents and terminals have creation controls on different rows.
|
||||||
|
- Provide a **single unified “New tab” control** that can create either:
|
||||||
|
- **New agent** (draft agent flow, pre-scoped to the workspace)
|
||||||
|
- **New terminal** (create terminal tab)
|
||||||
|
- **Agent tabs show provider icons**
|
||||||
|
- Terminal tabs: terminal icon.
|
||||||
|
- Agent tabs: provider icon (at minimum: **Claude/cloud** + **Codex** using existing app icon assets/components).
|
||||||
|
- **Remember focused tab per workspace (critical)**
|
||||||
|
- If a user focuses an agent/terminal tab in Workspace A, switches to Workspace B, and returns to Workspace A, the app must restore the previously focused tab.
|
||||||
|
- This must work even if the agent/terminal lists are still loading (do not overwrite the stored selection with a fallback while data is pending).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## User Flows (Agreed / Required)
|
||||||
|
|
||||||
|
### Sidebar
|
||||||
|
|
||||||
|
1. User opens left sidebar.
|
||||||
|
2. User expands a project to reveal workspaces.
|
||||||
|
3. User drags a project header:
|
||||||
|
- Project moves relative to other projects.
|
||||||
|
- All its workspaces remain grouped with it.
|
||||||
|
4. User drags a workspace:
|
||||||
|
- Only reorders within its project.
|
||||||
|
- Cannot be dropped into another project section.
|
||||||
|
5. User taps a workspace on mobile:
|
||||||
|
- Sidebar closes.
|
||||||
|
- Workspace screen opens with branch name in header.
|
||||||
|
|
||||||
|
### Workspace screen
|
||||||
|
|
||||||
|
1. User opens a workspace.
|
||||||
|
2. User can switch between agent and terminal tabs.
|
||||||
|
3. User uses the unified “New tab” control to create either:
|
||||||
|
- a new agent (draft flow), or
|
||||||
|
- a new terminal
|
||||||
|
4. User switches to a different workspace and returns:
|
||||||
|
- The previously focused tab is restored.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Acceptance Criteria (Strict)
|
||||||
|
|
||||||
|
### Sidebar drag behavior
|
||||||
|
|
||||||
|
- Dragging a project heading reorders projects, and after drop **the project heading is never separated from its own workspaces**.
|
||||||
|
- Dragging a workspace can only reorder within its project; after drop **a workspace is never displayed under another project**.
|
||||||
|
- After any drag, the sidebar tree snaps back to valid `Project → Workspaces` grouping (no “interleaved” layout remains).
|
||||||
|
|
||||||
|
### Sidebar visuals + navigation
|
||||||
|
|
||||||
|
- Workspace rows have **no border** and visually match the “ghost” style language of project headings.
|
||||||
|
- Workspace indentation/padding is reduced (especially mobile).
|
||||||
|
- “No agents yet” is **not rendered anywhere** in the sidebar tree.
|
||||||
|
- Clicking a workspace on mobile closes the left sidebar before navigation.
|
||||||
|
|
||||||
|
### Workspace header + tabs
|
||||||
|
|
||||||
|
- Git workspace header shows **branch name**, including base branch (e.g., `main`).
|
||||||
|
- There is **one unified “New tab” control** (not separate rows for agent vs terminal creation).
|
||||||
|
- Agent tabs show provider icons (Claude/Codex at minimum).
|
||||||
|
- Focused tab is restored when returning to a workspace (agent or terminal), and stored selection is not overwritten while lists are loading.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Plan (Code)
|
||||||
|
|
||||||
|
### A) Sidebar drag scoping + snap-back
|
||||||
|
|
||||||
|
Target file(s):
|
||||||
|
- `packages/app/src/components/sidebar-agent-list.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
- Ensure drag end always triggers a re-render that restores the canonical `Project → Workspaces` structure (even if persisted order does not change).
|
||||||
|
- Ensure reorder persistence remains:
|
||||||
|
- projects: device store project order
|
||||||
|
- workspaces: device store per-project workspace order
|
||||||
|
|
||||||
|
### B) Sidebar styling + labels
|
||||||
|
|
||||||
|
Target file(s):
|
||||||
|
- `packages/app/src/components/sidebar-agent-list.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
- Remove the “No agents yet” createdAt label for empty workspaces (render empty/omitted createdAt instead).
|
||||||
|
- Align workspace row visuals with project row:
|
||||||
|
- remove border
|
||||||
|
- adjust padding
|
||||||
|
- reduce indentation (responsive: tighter on mobile)
|
||||||
|
|
||||||
|
### C) Workspace screen: header title + unified “New tab”
|
||||||
|
|
||||||
|
Target file(s):
|
||||||
|
- `packages/app/src/screens/workspace/workspace-screen.tsx`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
- Header title uses branch name for git checkouts (including base branch).
|
||||||
|
- Replace separate “Create agent” vs “Create terminal” placement with one unified “New tab” control.
|
||||||
|
|
||||||
|
### D) Workspace screen: provider icons + tab persistence
|
||||||
|
|
||||||
|
Target file(s):
|
||||||
|
- `packages/app/src/screens/workspace/workspace-screen.tsx`
|
||||||
|
- (potentially) `packages/app/src/stores/workspace-tabs-store.ts`
|
||||||
|
|
||||||
|
Work:
|
||||||
|
- Agent tab icons render provider icon (Claude/Codex).
|
||||||
|
- Fix tab restore so requested/stored tabs are respected while data loads:
|
||||||
|
- do not redirect away from a requested tab just because lists haven’t populated yet
|
||||||
|
- do not overwrite stored tab selection with fallback while queries are pending
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification Plan
|
||||||
|
|
||||||
|
### Automated
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run typecheck
|
||||||
|
npm run test --workspace=@getpaseo/app
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual (agent-browser)
|
||||||
|
|
||||||
|
Using Metro web at `http://localhost:8081`:
|
||||||
|
|
||||||
|
1. Sidebar drag:
|
||||||
|
- Expand a project, drag its heading above/below another project → confirm its workspaces stay grouped.
|
||||||
|
- Drag a workspace “across” another project → confirm after drop it remains under original project.
|
||||||
|
2. Sidebar UI:
|
||||||
|
- Confirm workspace rows have no border and are less indented.
|
||||||
|
- Confirm no “No agents yet” labels.
|
||||||
|
- On mobile breakpoint, tap a workspace → sidebar closes.
|
||||||
|
3. Workspace tabs:
|
||||||
|
- Confirm header shows branch name (including `main`).
|
||||||
|
- Confirm agent tabs show provider icons (Claude/Codex).
|
||||||
|
- Confirm there is one unified “New tab” control for both agent + terminal.
|
||||||
|
- Focus a terminal tab, switch to another workspace, switch back → terminal tab restored.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Non-goals
|
||||||
|
|
||||||
|
- No panel splitting implementation (just keep architecture compatible).
|
||||||
|
- No server protocol changes (daemon stays untouched on `:6767`).
|
||||||
|
- No additional persistence beyond what’s required to satisfy “remember focused tab”.
|
||||||
|
|
||||||
Reference in New Issue
Block a user