From 18d4df339fab38bf5bdc082763df496fedb23b4c Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Sun, 1 Mar 2026 23:18:54 +0700 Subject: [PATCH] Add iteration plans for workspace header/layout restore --- ...ERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md | 60 +++++++++ ...ATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md | 113 ++++++++++++++++ ...ERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md | 124 ++++++++++++++++++ ...ATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md | 120 +++++++++++++++++ 4 files changed, 417 insertions(+) create mode 100644 EXECUTION_PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md create mode 100644 EXECUTION_PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md create mode 100644 PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md create mode 100644 PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md diff --git a/EXECUTION_PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md b/EXECUTION_PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md new file mode 100644 index 000000000..fa29cfc3d --- /dev/null +++ b/EXECUTION_PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md @@ -0,0 +1,60 @@ +# Iteration 3 Execution Plan — Paseo Orchestrated + +## Principles + +- Work happens in an isolated git worktree and merges back to `main` once verified. +- Do not restart or touch the daemon on `localhost:6767`. +- Use the repo’s existing Playwright global setup (isolated daemon/metro) for E2E. +- Pass all gates before merging: + - Typecheck + - Vitest + - Playwright E2E + - Manual `agent-browser` verification + +## Agent Delegation (Paseo) + +### Implementation agent (1) + +- **Agent:** Codex +- **Mode:** full-access +- **Worktree:** `iter3-workspace-header-tabs-restore` +- **Mission:** + - Fix New tab dropdown visibility (on-screen, correct pattern) + - Restore workspace header structure + explorer toggle + agent kebab menu + - Add terminal close (X) from workspace tab strip + - Add/adjust Playwright E2E specs for the above + - Run verification commands before declaring done + +### Reviewer (optional, if needed) + +- Only used if implementation is large/risky or tests expose subtle regressions. +- Codex or Claude Sonnet as a second-pass reviewer for UI regressions. + +## Merge Strategy + +1. Agent commits all changes in the worktree. +2. Orchestrator reviews the diff on the worktree. +3. Run gates locally on the worktree: + - `npm run typecheck` + - `npm run test --workspace=@getpaseo/app` + - `npm run test:e2e --workspace=@getpaseo/app` +4. Manual `agent-browser` verification: + - Desktop viewport: New tab menu visible + explorer toggle + kebab menu + - Mobile viewport: explorer icon uses git/folder, toggles right sidebar, left sidebar unaffected +5. Merge worktree back into `main` with a fast-forward merge if possible; otherwise merge commit. + +## Verification Checklist (strict) + +- [ ] New tab menu opens and is visible (desktop) +- [ ] Selecting Agent tab routes to draft agent flow scoped to workspace +- [ ] Selecting Terminal tab creates terminal and focuses it +- [ ] Terminal tabs show X; closing kills terminal and removes tab +- [ ] Workspace header shows branch name +- [ ] Workspace header has explorer toggle with correct icon behavior +- [ ] Agent kebab menu exists when Agent tab active +- [ ] Right sidebar opens/closes via header and mobile swipe gesture +- [ ] Left sidebar gestures unchanged +- [ ] `npm run typecheck` ✅ +- [ ] `npm run test --workspace=@getpaseo/app` ✅ +- [ ] `npm run test:e2e --workspace=@getpaseo/app` ✅ + diff --git a/EXECUTION_PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md b/EXECUTION_PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md new file mode 100644 index 000000000..b6b9aafc0 --- /dev/null +++ b/EXECUTION_PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md @@ -0,0 +1,113 @@ +# Execution Plan — Iteration 4 (Paseo-orchestrated) + +## Strategy + +Use a Paseo-managed implementation agent in an isolated git worktree to patch the workspace screen to restore legacy header/layout parity while keeping tabs. Then review, validate with tests + agent-browser, and merge back to `main`. + +## Agents + +### 1) Implementation agent (Codex) + +- Provider/model: `codex / gpt-5.3-codex` +- Mode: `full-access` +- Worktree: `iter4-workspace-header-layout-restore` (base: `main`) +- Responsibilities: + - Fix `New tab` dropdown to use the established dropdown/menu pattern (not off-screen combobox). + - Restore workspace header explorer toggle parity with legacy `AgentReadyScreen` (icons, aria state). + - Restore agent overflow (kebab) menu when active tab is an agent. + - Add terminal tab close `X` on desktop with confirm + kill terminal mutation. + - Add/extend Playwright E2E specs for `New tab` on-screen + explorer toggle open/close. + - Commit changes. + +### 2) Reviewer/validator (you/me) + +- Review diffs locally. +- Run: + - `npm run typecheck` + - `npm run test --workspace=@getpaseo/app` + - Targeted Playwright spec(s) for this iteration +- Perform agent-browser manual verification (desktop + mobile viewports). + +## Tooling / Commands (canonical) + +### Create agent (detached) + +```bash +paseo run -d \ + --worktree iter4-workspace-header-layout-restore \ + --base main \ + --provider codex \ + --model gpt-5.3-codex \ + --mode full-access \ + --name "🎭 Iter4 workspace header/layout restore" \ + "" +``` + +### Wait + +```bash +paseo wait +``` + +### Review worktree diff + +```bash +cd ~/.paseo/worktrees//iter4-workspace-header-layout-restore +git status --short --branch +git log -n 5 --oneline +git diff main..HEAD +``` + +### Merge into main + +Prefer `git cherry-pick ` into `/Users/moboudra/dev/paseo` `main` after verification. + +## Verification gates (must be green) + +### 1) Typecheck + +```bash +npm run typecheck +``` + +### 2) App unit tests + +```bash +npm run test --workspace=@getpaseo/app +``` + +### 3) Playwright E2E (targeted) + +Run only the spec(s) for this iteration (avoid unrelated flakes): + +```bash +cd packages/app +npx playwright test e2e/workspace-header-tabs-restore.spec.ts +``` + +## Manual verification (agent-browser) + +Use explicit sessions: + +```bash +agent-browser --session iter4-desktop open http://localhost:8081 +agent-browser --session iter4-mobile open http://localhost:8081 +``` + +Desktop: +- Validate `New tab` dropdown opens on-screen +- Validate explorer toggle opens/closes explorer +- Validate kebab menu appears for agent tabs +- Validate terminal tab `X` close flow + +Mobile viewport: +- Validate git/folder icon for explorer toggle +- Validate gestures for left/right sidebars + +## Rollback plan + +If verification fails: +- Do not merge. +- Patch in worktree until acceptance criteria + gates pass. +- Only then cherry-pick/merge into `main`. + diff --git a/PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md b/PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md new file mode 100644 index 000000000..dd1000573 --- /dev/null +++ b/PLAN_ITERATION_3_WORKSPACE_HEADER_TABS_RESTORE.md @@ -0,0 +1,124 @@ +# Iteration 3 Plan — Workspace Header + Tabs Restore + +## Goal + +Bring the `Workspace` screen layout back in line with the pre-tabs “Agent screen” structure (left sidebar + center content + right explorer sidebar), while keeping the new **workspace-scoped tabs** model (Agent + Terminal tabs) and the **project → workspaces** sidebar. + +This iteration focuses on restoring missing/incorrect UX affordances: + +- **New tab** dropdown must open and be visible. +- **Right explorer sidebar** must be togglable from the workspace header (with the correct icon behavior). +- **Chat overflow (kebab) menu** must exist again when an Agent tab is active. +- **Terminal tabs** must be closable from the workspace tab strip (X), since terminals are first-class tabs. +- **Gestures** for opening/closing sidebars must remain unchanged. + +## Non‑Goals (for this iteration) + +- Panel splitting / VS Code-style split views (explicitly deferred). +- Changing the existing left sidebar open/close gestures or right explorer swipe gestures (must remain behaviorally identical). +- Introducing a DB / rehydration changes (agent hydration is already handled at startup). + +## Acceptance Criteria + +### A. New Tab menu + +1. Clicking **New tab** in the workspace header opens a visible dropdown/menu on desktop web. +2. The menu contains exactly: + - **Agent tab** → navigates to the draft agent flow pre-scoped to the current workspace. + - **Terminal tab** → creates a new terminal for the current workspace and focuses it. +3. The menu placement is correct (not off-screen), following established in-app patterns. + +### B. Workspace header parity (restored controls) + +1. Workspace header shows **workspace name = branch name** (as already implemented). +2. Header contains: + - Left sidebar toggle (existing) + - Right explorer sidebar toggle (restored) + - Chat overflow **kebab menu** (restored) when an Agent tab is active +3. Right explorer toggle icon matches legacy behavior: + - On mobile: **Git** workspace → Git icon; non-git → Folder icon + - Visual “open” state is reflected (muted vs active color). + +### C. Tabs UX parity + +1. Desktop workspace tab strip: + - Shows provider icon for Agent tabs (Claude/Codex) and terminal icon for Terminal tabs. + - Terminal tabs include an **X** close affordance. +2. Closing a terminal tab: + - Calls the existing kill terminal API + - Removes the terminal from the workspace tab strip + - Leaves the workspace in a valid focused state (falls back to another available tab). + +### D. Right explorer sidebar structure & gestures (no regressions) + +1. Explorer sidebar is the same **right panel** conceptually as before: + - Not embedded “inside” the tab content surface + - Toggled by header button and swipe gesture on mobile +2. Gestures remain unchanged: + - Left sidebar: swipe right to open (mobile), swipe left/backdrop to close + - Right sidebar: swipe left to open (mobile), swipe right/backdrop/X to close + +### E. Verification gates + +1. `npm run typecheck` passes. +2. `npm run test --workspace=@getpaseo/app` (vitest) passes. +3. Playwright E2E: + - Add/update a spec that proves New tab menu opens and is on-screen. + - Add/update a spec that toggles the explorer sidebar from the workspace header. + - Run `npm run test:e2e --workspace=@getpaseo/app` (uses isolated daemon/metro; must NOT hit `:6767`). +4. Manual verification with `agent-browser` (desktop + mobile viewport) confirms: + - New tab menu visible and clickable + - Explorer toggle present and works + - Kebab menu present for Agent tab + - Terminal close X works + +## Implementation Outline + +### 1) Workspace header composition + +- Refactor `packages/app/src/screens/workspace/workspace-screen.tsx` header to match the legacy “agent header” affordances: + - Use the same header primitives used by `AgentReadyScreen` (`MenuHeader`, `HeaderToggleButton`, `DropdownMenu`). + - Restore explorer toggle button in the workspace header. + - Restore agent kebab menu (only when active tab is an Agent tab). + +### 2) New tab dropdown placement fix + +- Ensure the New tab dropdown uses a pattern that cannot render off-screen near the top of the viewport: + - Prefer the existing header-menu pattern (DropdownMenu), or + - If using Combobox, set an explicit `desktopPlacement` that renders below the trigger. + +### 3) Terminal tab close affordance + +- Add close (X) for terminal tabs in the workspace tab strip. +- Implement a minimal kill-terminal mutation in `WorkspaceScreen` (mirroring the existing `TerminalPane` mutation behavior) and ensure focus fallback. + +### 4) E2E coverage + +- Add `packages/app/e2e/workspace-tabs-header.spec.ts` (or similar) covering: + - New tab menu opening (visible on screen) + - Explorer toggle presence + open/close behavior + +## User Flows (must work) + +1. **Open workspace** + - Tap workspace in sidebar → sidebar closes → workspace screen opens + - Header shows branch name + +2. **Open new terminal tab** + - Header → New tab → Terminal tab + - Terminal appears as a tab (with terminal icon) + - Terminal is focused + +3. **Close terminal tab** + - Click X on terminal tab + - Terminal is killed and disappears from tab strip + - Focus returns to another tab + +4. **Toggle explorer** + - Header right icon toggles right sidebar + - Mobile swipe gesture still opens the right sidebar + +5. **Agent overflow menu** + - With an Agent tab active, kebab menu opens + - Menu content appears (parity with previous agent overflow) + diff --git a/PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md b/PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md new file mode 100644 index 000000000..8d93fbec7 --- /dev/null +++ b/PLAN_ITERATION_4_WORKSPACE_HEADER_LAYOUT_RESTORE.md @@ -0,0 +1,120 @@ +# Iteration 4 — Workspace header/layout restore (tabs + explorer parity) + +## Goal + +Fix regressions introduced by the workspace-tabs migration by restoring the **legacy workspace/agent screen layout and gestures**, while keeping the new **workspace tab model** (agent + terminal tabs). + +This iteration focuses on **header controls + panel layout parity**, and fixing the broken **New tab** menu on desktop. + +## Context (what must remain true) + +- **Left sidebar** stays as-is (projects/workspaces list) and keeps existing swipe/gesture behavior. +- **Right sidebar** stays as-is (Changes/Files explorer) and keeps existing swipe/gesture behavior. +- **Terminals and agents are first-class tabs**: + - Terminal tabs are not “special” or in a different layout region. + - New tab creation UI must treat agent + terminal options equally (same menu surface). +- Workspace header shows **workspace name (branch name when git, otherwise workspace name)**. +- No “legacy view” routing or duplicate UI kept around; everything uses the new workspace-tabs flow. +- Do **not** touch/restart the main daemon on `:6767`. Tests/dev servers must use isolated ports/homes. + +## UX Requirements (desktop + mobile) + +### Header structure (parity with legacy AgentReadyScreen) + +Workspace screen header must include: + +1) **Left sidebar toggle** (same component/gesture behavior as before). +2) **Title** = branch name if git & branch is known; otherwise workspace name. +3) **Right explorer toggle** (same behavior as before): + - Desktop icon: panel/right icon + - Mobile icon: `GitBranch` if git checkout, else `Folder` + - Correct `aria-expanded` state and open/closed coloring +4) **New tab** dropdown button that reliably opens on-screen (desktop + mobile). +5) **Overflow (kebab / 3-dot) menu for agent chat**: + - Visible only when the active tab is an **agent** (i.e. “chat context”). + - Menu items should mirror legacy intent (at minimum: open chat view with full header). + +### Tabs + +- Tabs remain horizontally scrollable (browser-style). +- Tabs must include an icon per tab type: + - Agent tabs show provider icon (Claude/Codex; fallback bot). + - Terminal tabs show terminal icon. +- Tabs must support closing terminal tabs via `X` (desktop): + - Confirm destructive close. + - Killing terminal updates the list and selects a valid remaining tab (or falls back to workspace root). + +### Panel layout + +- Keep the screen layout: **header → tabs row → content center → explorer right panel**. +- Do not nest the explorer UI inside tab content in a way that changes layout/gesture wiring. + +### Gestures (must not regress) + +- Left sidebar open/close gestures unchanged. +- Explorer (right sidebar) open/close gestures unchanged. +- Mobile “open explorer” pan gesture on content remains wired the same as before. + +## Acceptance Criteria + +### New tab dropdown + +- Clicking the `New tab` header button opens a dropdown that is **visible on-screen** on desktop (not positioned off-screen). +- Dropdown contains **two options**: + - Agent tab → opens draft agent flow for that workspace. + - Terminal tab → creates a terminal and opens its tab. + +### Workspace header parity + +- Header shows both sidebar toggles (left menu + right explorer toggle). +- Right explorer toggle icon matches legacy behavior: + - Mobile: git vs folder icon + - Desktop: panel-right icon +- Explorer toggle opens/closes the explorer reliably and updates `aria-expanded`. + +### Agent kebab menu + +- When an agent tab is active, the kebab menu is visible and opens correctly. +- When a terminal tab is active, the kebab menu is not shown. + +### Tab close + +- Terminal tabs display an `X` close affordance on desktop (hover or active). +- Closing a terminal: + - Confirms close + - Calls kill terminal RPC + - Removes the tab from the list + - Focuses a valid remaining tab (or navigates to workspace root if none) + +### Regression checks + +- Explorer panel remains on the right and behaves the same as before (including gestures). +- Left sidebar gestures remain unchanged. + +## Verification + +### Automated + +- `npm run typecheck` (must pass) +- `npm run test --workspace=@getpaseo/app` (must pass) +- Playwright E2E: + - Add/ensure a spec that asserts `New tab` dropdown opens and is within the viewport. + - Add/ensure a spec that toggles explorer via header button and asserts open/close. + +### Manual (agent-browser) + +Desktop (Metro web): +- Confirm header shows: left toggle, title, explorer toggle, `New tab` dropdown, kebab menu (agent only). +- Confirm `New tab` dropdown opens and is visible. +- Confirm terminal tab shows `X` close and closes correctly. + +Mobile viewport (Metro web responsive): +- Confirm explorer toggle uses git/folder icon. +- Confirm swipes/gestures for sidebars still work. + +## Non-goals (explicitly out of scope for this iteration) + +- Panel splitting / drag-to-split implementation (architectural compatibility only). +- New workspace creation UX, workspace archiving rules beyond existing behavior. +- Agent hydration/indexing redesign (local SQL DB) beyond current in-memory hydration. +