paseo/EXECUTION_PLAN_ITERATION_2_PROJECTS_WORKSPACES_TABS.md

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:

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:

npm run typecheck
npm run test --workspace=@getpaseo/app

Optional (run if environment supports it; starts isolated daemon/metro itself):

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):

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.