jb/paseo
1
0
Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add iteration 2 polish plan

Browse Source
This commit is contained in:
Mohamed Boudra
2026-03-01 20:35:27 +07:00
parent a8e867dc7b
commit e1067c623b
2 changed files with 345 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
EXECUTION_PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md
+160
View File
@@ -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.
PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md
+185
View File
@@ -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”.