diff --git a/docs/plans/2026-04-11-nexus-phase-10-studio.md b/docs/plans/2026-04-11-nexus-phase-10-studio.md new file mode 100644 index 00000000..981e6aba --- /dev/null +++ b/docs/plans/2026-04-11-nexus-phase-10-studio.md @@ -0,0 +1,357 @@ +# Nexus Phase 10 — Studio Mode Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:test-driven-development`. Commit atomically per logical unit. + +**Goal:** Refactor ContentStudio from a 7-tab page into an **8-card workshop grid** that folds in the existing ConvertPage as the 8th workshop. Add a freeform prompt input at the bottom of the Studio home that routes to a workshop based on intent. Build a workshop detail layout (two columns: params left, preview right) for when a user selects a workshop. + +**Source of truth:** `docs/specs/2026-04-11-nexus-layout-overhaul.md` **§6** (Mode 2 — Studio). Read §6.1–§6.5 before starting. DESIGN.md governs visuals. + +**Branch:** `nexus/design-system-migration`. Commit directly. + +--- + +## Ownership boundaries + +**You may create or modify ONLY:** + +| Path | Action | +|---|---| +| `ui/src/pages/ContentStudio.tsx` | Modify (major rewrite: from tabs to workshop grid) | +| `ui/src/pages/StudioWorkshopDetail.tsx` | Create (new routed view for a single workshop) | +| `ui/src/components/studio/**` | Create (new subdir for Phase 10 components) | +| `ui/src/pages/ConvertPage.tsx` | MAY read and reference, but DO NOT DELETE. Phase 16 handles dead-file deletion. Leave the file in place; it just stops being linked from the rail. | + +**You MUST NOT touch:** + +- `ui/src/App.tsx` — routing is controller-owned. If you need new sub-routes for workshops (e.g. `/content-studio/:workshopSlug`), report them in your final report; the controller wires them up after Wave 2. +- Existing content generator backends under `server/` or `packages/`. Phase 10 is purely a frontend IA reshape. +- Any file outside `ui/src/` except as noted. +- `ui/src/components/Layout.tsx`, `ui/src/components/frame/*` — Phase 8 territory, do not touch. +- Other phases' owned paths (`ui/src/pages/PersonalAssistant.tsx`, `ui/src/pages/Projects.tsx`, `ui/src/pages/ProjectDetail.tsx`, `ui/src/components/assistant/**`, `ui/src/components/projects/**`). + +**Existing code you may reuse (read-only):** + +- The 7 existing content-generator subcomponents that the current `ContentStudio.tsx` references for its tabs. Read `ContentStudio.tsx` first to find them. You'll reuse them as the body content of each workshop's detail view, unchanged. +- `ui/src/pages/ConvertPage.tsx` — you'll embed its main content (not the whole page shell) as the body of the Convert workshop detail view. Do not delete the file; the route path `/convert` still works in Phase 10 for backwards compatibility. +- `ui/src/components/frame/*` — Phase 8 patterns (test shape, semantic tokens, focus-visible styles, cn helper, slide-overs if you need any). + +--- + +## Scope (strictly) + +**In Phase 10:** + +1. **Studio home rewrite** — replace the 7-tab layout in `ContentStudio.tsx` with a grid of **8 workshop cards**: + - `diagrams`, `icons`, `themes`, `wallpapers`, `documents`, `brand-kits`, `social`, `convert` + - 3-column grid on `>= 1024px`, 2-column on `>= 640px`, 1-column below + - Card: 1px charcoal border, 8px radius, transparent fill on idle, `bg-card` near-black on hover, 24px padding + - Title in Inter 700 uppercase 24px, subtitle in silver 14px, Lucide icon in volt top-right +2. **Convert workshop fold-in** — the 8th card routes to the existing ConvertPage body rendered inside a Studio workshop detail shell. The `/convert` top-level route must continue to work (because users might have it bookmarked) but the IconRail's Studio destination is the canonical path forward. +3. **Workshop detail view** at `StudioWorkshopDetail.tsx` — a new routed view that renders one workshop at a time: + - Two-column layout on `>= 1024px`: left = params/prompt input (40% width), right = preview (60% width) + - Mobile stacks to a single column + - Top of page shows `STUDIO / WORKSHOP-NAME` as the page title (the actual mode-breadcrumb is in TopStrip from Phase 8; this is an in-page heading) + - Action bar at the bottom of the right column: `Save`, `Export`, `Send to Assistant` +4. **StudioPromptBar** — freeform text input at the bottom of the Studio home. Placeholder: `Or just describe it: "I need a 1920×1080 wallpaper of …"`. Submits to a classifier (§6.5 of the spec) that maps intent to a workshop slug. If routing succeeds, navigate to `/content-studio/{workshopSlug}` with the prompt pre-filled. If routing fails, the prompt falls through to the Assistant as a new conversation message (see §Implementation notes). +5. **Workshop definitions** — a single source-of-truth data structure that both the grid and the detail view consume. + +**NOT in Phase 10:** + +- Any backend changes to content generators. +- The freeform prompt classifier itself — use a simple regex/keyword matching stub for Phase 10 (see §Implementation notes). A real LLM classifier is out of scope. +- Recipe integration (v1.8 planned; not part of Wave 2). +- Deleting `ConvertPage.tsx`. Phase 16 cleanup handles dead files. +- Editing `App.tsx` routes — report needed routes to the controller. +- Mobile polish beyond "grid collapses to 1 column" — Phase 15 handles mobile. + +--- + +## File plan + +### Create + +| File | Responsibility | Est. lines | +|---|---|---| +| `ui/src/components/studio/workshops.ts` | Single source-of-truth data: array of 8 workshops with `slug`, `title`, `subtitle`, `icon`, `componentKey`. Exported for consumption by both the grid and the detail view. | ~80 | +| `ui/src/components/studio/workshops.test.ts` | Tests: all 8 workshops present, slugs unique, icons are valid Lucide imports, each `componentKey` maps to a real component | ~60 | +| `ui/src/components/studio/WorkshopCard.tsx` | Single card for the grid. Props: `workshop`, `onClick`. Renders title, subtitle, icon, hover state. | ~70 | +| `ui/src/components/studio/WorkshopCard.test.tsx` | Tests: renders workshop data, click fires callback, hover state applies correctly | ~90 | +| `ui/src/components/studio/WorkshopGrid.tsx` | Responsive grid of WorkshopCards. Takes `workshops` array and `onSelect` callback. | ~60 | +| `ui/src/components/studio/WorkshopGrid.test.tsx` | Tests: renders N cards, onSelect fires with correct workshop slug, responsive class application | ~80 | +| `ui/src/components/studio/StudioPromptBar.tsx` | Freeform text input + submit button. Calls `classifyIntent` helper and either navigates or calls `onFallbackToAssistant`. | ~80 | +| `ui/src/components/studio/StudioPromptBar.test.tsx` | Tests: renders input, classifier routing, fallback path | ~110 | +| `ui/src/components/studio/classifyIntent.ts` | Pure function. Given a prompt string, returns `{ slug: string; prefilledPrompt: string } \| null`. Keyword-matching only in Phase 10. | ~70 | +| `ui/src/components/studio/classifyIntent.test.ts` | Parameterized tests: "diagram of X" → diagrams, "wallpaper of Y" → wallpapers, "convert pdf to docx" → convert, "make me a logo" → brand-kits, "random chat" → null | ~80 | +| `ui/src/pages/StudioWorkshopDetail.tsx` | Routed view. Reads `:workshopSlug` from params, looks up in workshops data, renders two-column layout with the workshop's existing generator component on the right and a params/prompt input on the left. Action bar at the bottom: Save / Export / Send to Assistant. | ~180 | +| `ui/src/pages/StudioWorkshopDetail.test.tsx` | Tests: renders workshop by slug, 404 fallback for unknown slug, action bar renders | ~120 | + +### Modify + +| File | Change | +|---|---| +| `ui/src/pages/ContentStudio.tsx` | Replace the 7-tab layout with the new WorkshopGrid + StudioPromptBar. Remove tab state and tab container. Preserve any cross-cutting concerns (e.g. error boundaries, query client usage) that the existing page has. | + +**Do not create or modify any other files.** + +--- + +## Implementation notes + +### Workshop data structure + +```ts +// ui/src/components/studio/workshops.ts +import { Sparkles, Layers, Palette, Image, FileText, Award, Share2, Repeat } from "lucide-react"; +import type { ComponentType } from "react"; + +export type WorkshopSlug = + | "diagrams" | "icons" | "themes" | "wallpapers" + | "documents" | "brand-kits" | "social" | "convert"; + +export interface WorkshopDefinition { + slug: WorkshopSlug; + title: string; // Inter 700 uppercase, e.g. "DIAGRAMS" + subtitle: string; // Inter 400 silver, single line + icon: ComponentType<{ className?: string }>; // Lucide icon + /** + * Key for looking up the generator component. The detail view maps + * this to an existing component from ContentStudio's current tab + * implementations. Phase 10 does NOT rewrite any generator internals. + */ + componentKey: string; +} + +export const WORKSHOPS: WorkshopDefinition[] = [ + { slug: "diagrams", title: "DIAGRAMS", subtitle: "Mermaid → rendered SVG", icon: Sparkles, componentKey: "diagram-renderer" }, + { slug: "icons", title: "ICONS", subtitle: "SVG sets from description", icon: Layers, componentKey: "icon-renderer" }, + { slug: "themes", title: "THEMES", subtitle: "Color → full palette", icon: Palette, componentKey: "theme-renderer" }, + { slug: "wallpapers", title: "WALLPAPERS", subtitle: "Desktop, mobile, banners", icon: Image, componentKey: "wallpaper-renderer" }, + { slug: "documents", title: "DOCUMENTS", subtitle: "PDF reports, invoices", icon: FileText, componentKey: "document-renderer" }, + { slug: "brand-kits", title: "BRAND KITS", subtitle: "Full brand identity", icon: Award, componentKey: "brand-renderer" }, + { slug: "social", title: "SOCIAL", subtitle: "Platform-ready posts", icon: Share2, componentKey: "social-renderer" }, + { slug: "convert", title: "CONVERT", subtitle: "File format conversion", icon: Repeat, componentKey: "convert" }, +]; +``` + +Pick Lucide icons that fit. If a more appropriate icon exists for a slug, use it. The above is a sensible default. + +### The `componentKey` → real component mapping + +Phase 10 does NOT rewrite any generator. For each workshop, the detail view renders the existing generator component as-is. You must read the current `ContentStudio.tsx` to find those components. They'll be something like ``, ``, etc. Build a map: + +```ts +// In StudioWorkshopDetail.tsx (or a small helper module within studio/) +const WORKSHOP_COMPONENTS: Record = { + "diagram-renderer": DiagramGeneratorTab, + "icon-renderer": IconGeneratorTab, + // ... etc. + "convert": ConvertPageBody, // see Convert fold-in notes below +}; +``` + +If a generator doesn't currently exist in `ContentStudio.tsx`'s tabs (e.g. if the current ContentStudio has only 6 tabs and we're adding Social as a future extension), render a `` inline-component that shows `"Coming soon"` for that slug. Do NOT stub out a fake generator. + +### Convert fold-in + +`ui/src/pages/ConvertPage.tsx` currently exists and is routed via `/convert`. Phase 10 needs the Convert workshop body rendered inside the Studio workshop detail shell, but the existing `/convert` route MUST continue to work (backwards compat). + +Strategy: +1. Extract the inner content of `ConvertPage.tsx` into a reusable component `ConvertPageBody`. Do this by **reading** `ConvertPage.tsx` and identifying the JSX that's the actual convert UI (the file uploader, format selector, conversion runner) vs. the page-level shell. +2. If `ConvertPage.tsx` is already structured so the inner content is a single child component, just import and reuse that component — no refactor needed. +3. If `ConvertPage.tsx` is a monolithic component and extracting `ConvertPageBody` requires a real refactor, take the smallest possible subset: wrap the whole `` in the workshop detail and accept that there's a small amount of redundant chrome. Flag as a concern. +4. Leave `ConvertPage.tsx` in place; the `/convert` route keeps rendering it directly. + +### StudioPromptBar fallback to Assistant + +When the classifier returns `null`, the prompt should fall through to the Assistant as a new conversation. The cleanest implementation is: + +1. Navigate to `//assistant?prompt=`. +2. The Assistant page (Phase 9's work) reads the `prompt` query param on mount and pre-fills the input. + +**BUT:** Phase 9's `PersonalAssistant.tsx` rewrite may not include query-param pre-fill logic. Coordinate: add a note to your final report saying "StudioPromptBar fallback assumes Phase 9 will honor `?prompt=` query param on the Assistant route". Phase 9's plan should also have this noted; if it doesn't, the controller will coordinate. + +For Phase 10's implementation, go ahead and navigate with the query param. If Phase 9 doesn't honor it yet, the worst case is the prompt is dropped and the user lands on an empty assistant — acceptable degradation. + +### classifyIntent — Phase 10 rules + +Simple keyword-based classifier. Pure function, no state, no async. + +```ts +export function classifyIntent(prompt: string): { slug: WorkshopSlug; prefilledPrompt: string } | null { + const lower = prompt.toLowerCase().trim(); + if (!lower) return null; + + // Convert intent — "convert X to Y", "from X to Y", explicit formats + if (/\bconvert\b|from\s+\w+\s+to\s+\w+|\bpdf\b|\bdocx?\b|\bmd\b/i.test(lower)) { + return { slug: "convert", prefilledPrompt: prompt }; + } + // Wallpaper intent + if (/wallpaper|background\s+image|desktop\s+bg/i.test(lower)) { + return { slug: "wallpapers", prefilledPrompt: prompt }; + } + // Diagram intent + if (/diagram|flowchart|sequence|mermaid|architecture/i.test(lower)) { + return { slug: "diagrams", prefilledPrompt: prompt }; + } + // Icon intent + if (/\bicon\b|icon\s+set|svg\s+icon/i.test(lower)) { + return { slug: "icons", prefilledPrompt: prompt }; + } + // Theme intent + if (/\btheme\b|color\s+palette|palette/i.test(lower)) { + return { slug: "themes", prefilledPrompt: prompt }; + } + // Document intent + if (/pdf|document|invoice|report|one-?pager/i.test(lower)) { + return { slug: "documents", prefilledPrompt: prompt }; + } + // Brand intent + if (/brand|logo|identity|style\s+guide/i.test(lower)) { + return { slug: "brand-kits", prefilledPrompt: prompt }; + } + // Social intent + if (/social|tweet|post|instagram|linkedin|twitter|x\.com/i.test(lower)) { + return { slug: "social", prefilledPrompt: prompt }; + } + + return null; // unclassified → fall through to Assistant +} +``` + +Test exhaustively with the parameterized test pattern from Phase 8's `ModeBreadcrumb.test.tsx`. + +### ContentStudio.tsx target structure + +```tsx +export function ContentStudio() { + const navigate = useNavigate(); + const { selectedCompanyId, selectedCompany } = useCompany(); + const prefix = selectedCompany?.issuePrefix ?? ""; + + const handleSelectWorkshop = (slug: WorkshopSlug) => { + navigate(`/${prefix}/content-studio/${slug}`); + }; + + const handleFallbackToAssistant = (prompt: string) => { + navigate(`/${prefix}/assistant?prompt=${encodeURIComponent(prompt)}`); + }; + + return ( +
+
+

STUDIO

+

+ Eight workshops. Pick one or describe what you need. +

+
+ + + +
+ navigate(`/${prefix}/content-studio/${slug}?prompt=${encodeURIComponent(prefilled)}`)} + onFallbackToAssistant={handleFallbackToAssistant} + /> +
+
+ ); +} +``` + +Preserve any existing cross-cutting concerns (error boundaries, query client, auth checks) from the current ContentStudio. + +### StudioWorkshopDetail routing + +**You are NOT allowed to edit App.tsx.** You'll need sub-routes for Studio workshops, e.g. `//content-studio/:workshopSlug`. The existing App.tsx currently only has `//content-studio` without a sub-route param. + +**Workaround for Phase 10:** render StudioWorkshopDetail as a child of ContentStudio, not as a separate route. ContentStudio checks for a `:workshopSlug` path segment via `useLocation()` (not `useParams()`, because the App.tsx routes don't define the param). If there's a slug, render StudioWorkshopDetail; otherwise render the grid. + +```tsx +// ContentStudio.tsx pseudocode +export function ContentStudio() { + const location = useLocation(); + const match = location.pathname.match(/\/content-studio\/([^/]+)/); + const workshopSlug = match?.[1]; + + if (workshopSlug) { + return ; + } + return ; +} +``` + +This is hacky but correct for Phase 10. Report to the controller: "New App.tsx routes needed: `content-studio/:workshopSlug`". The controller will replace the pathname-matching with a proper route param after Wave 2. + +--- + +## Acceptance criteria + +Phase 10 is complete when: + +1. Loading `/NEX/content-studio` renders an 8-card grid with the new workshop definitions — no tab strip visible anywhere on the page. +2. Each card navigates to `/NEX/content-studio/{slug}` when clicked. +3. Loading `/NEX/content-studio/{slug}` renders the workshop detail view with the existing generator component on the right and a params panel on the left. +4. Loading `/NEX/content-studio/convert` renders the ConvertPage body inside the workshop detail shell. +5. Loading `/NEX/convert` (the legacy route) still works — backwards compat. +6. The StudioPromptBar at the bottom of the grid view accepts text input and routes correctly: + - `"diagram of the auth flow"` → navigates to `/NEX/content-studio/diagrams?prompt=...` + - `"convert this pdf to markdown"` → navigates to `/NEX/content-studio/convert?prompt=...` + - `"random musing"` → navigates to `/NEX/assistant?prompt=...` (fallback) +7. All new components have tests using the Phase 8 manual createRoot + act pattern. +8. `npx vitest run src/components/studio/ src/pages/StudioWorkshopDetail.test.tsx` passes. +9. `npx tsc --noEmit 2>&1 | grep -E "studio/|ContentStudio\.tsx|StudioWorkshopDetail\.tsx"` returns no errors. +10. The `/convert` top-level route still renders the ConvertPage. +11. No file outside the declared ownership is modified. + +--- + +## Commit scheme + +Suggested atomic commits (one per logical unit): + +1. `feat(nexus): add WORKSHOPS data + classifyIntent helper (phase 10)` — workshops.ts, classifyIntent.ts, their tests +2. `feat(nexus): add WorkshopCard and WorkshopGrid components (phase 10)` — cards + grid + tests +3. `feat(nexus): add StudioPromptBar with intent routing (phase 10)` — prompt bar + tests +4. `feat(nexus): add StudioWorkshopDetail page (phase 10)` — detail view + tests +5. `refactor(nexus): rewire ContentStudio to workshop grid (phase 10)` — ContentStudio.tsx rewrite + +Each commit must build and pass tests. Include `Co-Authored-By: Claude Opus 4.6 (1M context) ` on every commit. + +--- + +## Before you begin + +Ask the controller if any of these are unclear: + +- The component names and import paths of the current ContentStudio's 7 tabs (read the file first and report what's there) +- Whether `ConvertPage.tsx` is extractable or if you should wrap the whole thing +- Whether the new sub-routes the controller needs to add warrant a pause and App.tsx edit, or if the hacky path-matching workaround is acceptable +- Anything in §6 of the spec that reads as ambiguous + +If you find that the current ContentStudio has fewer than 7 tabs (e.g. only 5 generators are actually built), report it — the spec assumes 7 existing + 1 new (convert). The workshop grid can still show 8 cards with placeholder content for missing generators. + +--- + +## When you're in over your head + +Escalate early if: + +- ConvertPage body extraction breaks tests in the legacy `/convert` route +- The current ContentStudio has a global state or context that doesn't compose cleanly with the new grid → detail flow +- Any generator component has hardcoded dependencies on the tab layout you're removing +- classifyIntent is pulling in too many edge cases (stop at ~10 keyword patterns; more is Phase 14's classifier) + +--- + +## Report format (final) + +- **Status** +- **Commits produced** +- **Files created / modified** +- **Tests added and passing count** +- **Typecheck result** for Phase 10 files +- **Routing needs** for the controller to add to App.tsx +- **ConvertPage fold-in notes** — did you extract a body component or wrap the whole page? +- **Open concerns** +- **Deviations from the plan** +- **Self-review findings** diff --git a/docs/plans/2026-04-11-nexus-phase-11-projects-builder.md b/docs/plans/2026-04-11-nexus-phase-11-projects-builder.md new file mode 100644 index 00000000..a94f1f0c --- /dev/null +++ b/docs/plans/2026-04-11-nexus-phase-11-projects-builder.md @@ -0,0 +1,336 @@ +# Nexus Phase 11 — Projects + Builder Mode Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:test-driven-development`. Commit atomically per logical unit. This is the **largest phase in Wave 2** by file count and integration surface. + +**Goal:** Replace the existing Projects list page with hero-stat cards (72px Inter Black volt percentage), rebuild the Project Detail page with a 7-tab **Builder mode** strip (Overview · Issues · Agents · Gates · Costs · Activity · Org), demote the current global routes (Issues, Agents, Approvals→Gates, Costs, Activity, Org) into per-project tabs, rename Approvals to "Gates" in the UI display layer, and wire the Assistant dot indicator for pending gates. + +**Source of truth:** `docs/specs/2026-04-11-nexus-layout-overhaul.md` **§7** (Mode 3 — Projects + Builder mode). Read §7.1–§7.3 thoroughly before starting. DESIGN.md governs visuals. Phase 8 components at `ui/src/components/frame/*` are the reference pattern. + +**Branch:** `nexus/design-system-migration`. Commit directly. + +--- + +## Ownership boundaries + +**You may create or modify ONLY:** + +| Path | Action | +|---|---| +| `ui/src/pages/Projects.tsx` | Modify (list page rewrite) | +| `ui/src/pages/ProjectDetail.tsx` | Modify (add Builder tab strip, preserve existing sub-view logic) | +| `ui/src/components/projects/**` | Create (new subdir for Phase 11 components) | + +**You MUST NOT touch:** + +- `ui/src/App.tsx` — routing is controller-owned. Per-project tab sub-routes (`/projects/:id/agents`, `/projects/:id/gates`, etc.) already partially exist in App.tsx from the Paperclip base. Report any routes you need added in your final report. +- `ui/src/pages/Issues.tsx`, `ui/src/pages/Agents.tsx`, `ui/src/pages/Approvals.tsx`, `ui/src/pages/Costs.tsx`, `ui/src/pages/Activity.tsx`, `ui/src/pages/OrgChart.tsx` (or whatever the existing org page is called), `ui/src/pages/Goals.tsx`, `ui/src/pages/Inbox.tsx`, `ui/src/pages/Routines.tsx`. These pages stay on their existing global routes for backwards compat during Phase 11. Phase 16 deletes dead top-level pages if/when fully replaced. +- Any existing list component that those pages use (`IssuesList.tsx`, `AgentList.tsx`, etc.). You MAY render these inside your new project tabs, scoped by project ID via props. +- `ui/src/components/Layout.tsx`, `ui/src/components/frame/*` — Phase 8. +- Any file outside `ui/src/` except as noted. +- Other phases' owned paths. + +**Existing code you may reuse (read-only):** + +- `IssuesList`, `AgentList`, `ApprovalsList` (or whatever the current list components are named) — render inside your new project tabs with a project-id filter prop. **If these components don't already accept a `projectId` filter prop**, report BLOCKED rather than modifying them unilaterally. The controller will coordinate with a follow-up. +- `projectsApi`, `issuesApi`, `agentsApi`, `approvalsApi`, `costsApi`, `activityApi` — existing backend clients. Reuse unchanged. +- Existing milestone tracking data if any (the spec §7.2.1 shows a milestone checklist in the Overview tab — if no milestone data exists in the backend, render a placeholder with "No milestones defined" and note it as a Phase 11 gap). +- `ui/src/components/frame/*` — Phase 8 patterns (test shape, tokens, focus-visible, etc.). + +--- + +## Scope (strictly) + +**In Phase 11:** + +### 1. Projects list page rewrite (`ui/src/pages/Projects.tsx`) + +- Full-width cards (or 2-up on `>= 1024px`), stacked vertically with 16px gap +- Card: 1px charcoal border, 8px radius, transparent fill +- Each card shows: + - **Title row:** project slug in Inter 700 uppercase 16px white + status dot (forest = idle, volt pulsing = working, pale yellow = waiting on gate) at right + - **Hero stat:** percentage in **Inter Black 900, 72px, volt (`text-primary`)** — the performance-stat pattern from DESIGN.md §4 + - **Sub-line:** `Phase N of M · Next gate: {name}` in Inter 500 14px silver + - **Progress bar:** 8px tall, charcoal track (`bg-border`), volt fill (`bg-primary`), sharp 4px corners, no pill + - **Footer line:** `${cost} burned · last activity ${when}` in Inter 400 12px silver +- Click navigates to `//projects/{slug}/overview` +- Top-right: `⊕ NEW PROJECT` button in **Forest Green** (`bg-[#166534] text-white`) — the secondary CTA per DESIGN.md. onClick opens the existing project-create dialog or brainstormer (use whatever the existing `NewProjectDialog` already wires up). +- **No table view, no filters, no sort dropdowns.** ⌘K handles search in Phase 14; Phase 11 just renders the cards. +- **Empty state:** if `projects.length === 0`, render a full-canvas message — `NO PROJECTS YET` in Inter Black 96px volt (`font-black text-[96px] text-primary leading-none`), below it a Forest Green `⊕ START YOUR FIRST PROJECT` CTA that opens the same project-create flow + +### 2. Project Detail rewrite (`ui/src/pages/ProjectDetail.tsx`) + +- **Builder tab strip** just below the TopStrip (note: TopStrip is Phase 8's top bar; the Builder tab strip is an ADDITIONAL 40px horizontal strip specific to Project Detail, rendered as the top of the page content — not in the global chrome). +- Tabs, left to right: `OVERVIEW · ISSUES · AGENTS · GATES · COSTS · ACTIVITY · ORG` + - Inter 600 14px uppercase, `tracking-[0.1em]` + - Silver default (`text-muted-foreground`), volt active with 2px volt bottom border + - Active tab also has `text-primary` + - 24px gap between tabs, 24px left padding + - Tab strip itself has `border-b border-border` +- Each tab renders a different inner component (see §Tab components below) +- Default tab is OVERVIEW (if the URL has no tab segment, redirect to `…/overview`) +- Tab click navigates via React Router `Link` so the URL reflects the current tab + +### 3. Tab components — each in `ui/src/components/projects/tabs/` + +- **`OverviewTab`** (`OverviewTab.tsx`) — renders: + - Hero stat row: `47%` in Inter Black 900 72px volt + `4 AGENTS ACTIVE` in Inter 700 14px silver + - Milestone checklist card (1px charcoal border, 8px radius, 24px padding, uppercase title) + - Checkbox list of milestones: completed milestones get `[✓]` prefix and white text; pending get `[○]`/`[ ]` prefix and silver text; the "next gate" milestone gets a pale-yellow bullet and a `← NEXT GATE` label + - If no milestone data exists in the backend: render a small-muted placeholder `"No milestones defined"` and stop — do not fabricate data + - **Origin chat card** (if the project has an `originConversationId` field on the project record): small card linking back to the conversation that birthed the project. Show the first line of the conversation as a quote. If no origin conversation, omit the card. + - **Activity card:** rolling 24h activity for this project. Count commits, issues closed, gates awaiting, cost burned. Compose from existing `activityApi` with a project filter. +- **`IssuesTab`** — renders `` if the existing list component supports that prop. If it doesn't, STOP and report BLOCKED. +- **`AgentsTab`** — renders `` scoped. Same rule. +- **`GatesTab`** — renders the existing approvals list filtered by project. In the UI copy, label it "Gates" everywhere visible to the user. Do NOT rename the backend API, the route, or any code identifiers. "Approvals → Gates" is a **display-only** rename per the spec. +- **`CostsTab`** — renders existing `` or equivalent. +- **`ActivityTab`** — renders existing activity feed scoped to project. +- **`OrgTab`** — renders existing org chart scoped to project. **Hide** the tab entirely for projects with fewer than 2 agents (single-agent projects don't need an org chart). Implement this as a conditional tab — the tab strip shows 6 tabs for single-agent projects, 7 for multi-agent. + +### 4. Assistant icon dot indicator for pending gates + +The spec §10.4 says the single notification surface is the volt dot on the Assistant icon. Phase 11's scope for this is minimal: when there's at least one pending gate globally, the Assistant icon in the IconRail should show a small volt dot overlay. + +**Implementation strategy:** +- Create a new hook `ui/src/hooks/useGateIndicator.ts` that reads the existing approvals endpoint, filters by pending status, returns `{ hasPendingGates: boolean, count: number }`. +- **You may NOT modify IconRail directly** — that's Phase 8's file. Instead, report this to the controller: "Phase 11 needs the IconRail Assistant icon to show a volt dot when `useGateIndicator().hasPendingGates` is true. The controller will wire this up after Wave 2 by importing the hook in IconRail and conditionally rendering a dot element." + +Alternative: if you're confident the dot wiring is trivial (a single line of conditional JSX in IconRail + importing the hook), you may **create a PR-style note** in your final report with the exact diff the controller should apply. Do NOT commit the IconRail change yourself. + +### 5. "Approvals → Gates" display rename + +- All user-visible strings containing "Approval" or "Approvals" in the contexts affected by your changes become "Gate" / "Gates" in the UI copy. +- Do NOT rename any symbol, file, function, API path, component name, CSS class, or test ID. +- Scope of the rename: only strings that end up on screen inside your Phase 11 pages or components. If Phase 13 (Settings) or Phase 14 (⌘K) later references Approvals, they'll handle their own rename. + +### 6. Goals fold-in and demotions + +- Goals collapses into the Overview tab's milestone checklist. For Phase 11, do NOT actually integrate Goals data — the milestone checklist reads from project.milestones (if exists) or shows a placeholder. Goals remains at `/goals` as a top-level page for backwards compat; Phase 16 cleanup decides whether to delete it. +- Inbox has no direct replacement in Phase 11. It stays at `/inbox` for backwards compat; the spec §7.3 says it's replaced by ⌘K + Assistant dot, which Phase 14 handles. +- Routines moves to Settings in Phase 13. Phase 11 does not touch Routines. + +**NOT in Phase 11:** + +- Creation of `Gates` as a new API surface (it's a display rename only). +- Modification of existing list components to add `projectId` props if they don't already have them (escalate instead). +- Deletion of `Goals.tsx`, `Inbox.tsx`, `Routines.tsx`, or any of the existing global-list pages. +- Modification of `App.tsx` (controller owns). +- Modification of IconRail or any other frame component. +- Any visual polish beyond DESIGN.md's rules. +- Multi-select, batch operations, or table views on the Projects list. + +--- + +## File plan + +### Create + +| File | Responsibility | Est. lines | +|---|---|---| +| `ui/src/components/projects/ProjectCard.tsx` | Hero-stat card for Projects list. Props: `project` record, `onClick`. Renders title, status dot, 72px percentage hero, progress bar, sub-line, footer. | ~120 | +| `ui/src/components/projects/ProjectCard.test.tsx` | Tests: renders all fields, status dot color per status, hero stat font-black 72px, click fires callback | ~140 | +| `ui/src/components/projects/BuilderTabStrip.tsx` | Horizontal tab strip for Project Detail. Props: `projectId`, `activeTab`, `hasMultipleAgents` (controls Org tab visibility). | ~100 | +| `ui/src/components/projects/BuilderTabStrip.test.tsx` | Tests: renders 7 tabs by default, hides Org for single-agent, active tab styling, Link navigation | ~130 | +| `ui/src/components/projects/tabs/OverviewTab.tsx` | The OVERVIEW tab content. Hero stat + milestone checklist + origin chat card + activity card. | ~200 | +| `ui/src/components/projects/tabs/OverviewTab.test.tsx` | Tests: renders hero stat, milestone list, origin chat when present and omitted when absent, activity counts | ~150 | +| `ui/src/components/projects/tabs/IssuesTab.tsx` | Thin wrapper that renders the existing IssuesList with projectId filter. | ~30 | +| `ui/src/components/projects/tabs/AgentsTab.tsx` | Thin wrapper for agents list. | ~30 | +| `ui/src/components/projects/tabs/GatesTab.tsx` | Thin wrapper for approvals list, with "Gates" display copy. | ~40 | +| `ui/src/components/projects/tabs/CostsTab.tsx` | Thin wrapper for costs breakdown. | ~30 | +| `ui/src/components/projects/tabs/ActivityTab.tsx` | Thin wrapper for activity feed. | ~30 | +| `ui/src/components/projects/tabs/OrgTab.tsx` | Thin wrapper for org chart. | ~30 | +| `ui/src/components/projects/tabs/tabs.test.tsx` | A single file covering all 6 thin wrappers (just verify they render and pass projectId through) | ~120 | +| `ui/src/hooks/useGateIndicator.ts` | Hook: reads approvals endpoint, returns `{ hasPendingGates, count }`. Used in post-Wave IconRail wiring. | ~50 | +| `ui/src/hooks/useGateIndicator.test.ts` | Tests: returns correct count, loading state, error state | ~80 | + +### Modify + +| File | Change | +|---|---| +| `ui/src/pages/Projects.tsx` | Rewrite the list page to use ProjectCard grid. Preserve any existing data-loading hooks, error boundaries, toast wiring. | +| `ui/src/pages/ProjectDetail.tsx` | Add BuilderTabStrip at the top. Route tab content based on a tab segment from the URL (either use `useParams` if the App.tsx route has a `:tab` param, or parse from `useLocation().pathname`). Default to OVERVIEW. Render the appropriate tab component. | + +**Do not create or modify any other files.** + +--- + +## Implementation notes + +### ProjectCard hero-stat progress % + +The percentage comes from the project's milestone progress. Check the existing `projectsApi` response shape. Common patterns: + +- `project.milestoneProgress` (a number 0–100) +- `project.phasesCompleted / project.phasesTotal` +- `project.completedMilestones.length / project.milestones.length` + +Pick the one that exists and compute. If none exist, render `—%` (em-dash percent) and note it as a gap for the backend team. Do NOT fabricate a value. + +Status dot color mapping: +- Forest `#166534` = idle (no active agents, no pending gates) +- Volt `text-primary` with pulse animation = working (at least one agent in "working" state) +- Pale Yellow `#f4f692` = waiting on user gate (pending approval exists) + +Priority if multiple conditions hold: waiting > working > idle. + +### BuilderTabStrip URL structure + +The existing App.tsx has these project routes (from my earlier read): + +``` +} /> +} /> +} /> +} /> +} /> +} /> +``` + +So overview, issues exist already. Missing: `/agents`, `/gates`, `/costs`, `/activity`, `/org`. **Report these** as routes the controller needs to add. For Phase 11 implementation, use path-matching inside ProjectDetail to infer the current tab: + +```tsx +const match = location.pathname.match(/\/projects\/[^/]+\/([^/?#]+)/); +const activeTab = (match?.[1] as ProjectTab) ?? "overview"; +``` + +Tab `Link` `to` values can point at the routes that don't exist yet — React Router will render whatever catches them, which will likely fall back to ProjectDetail via the base `/projects/:projectId` route. Test that this works in practice. + +### Preserving ProjectDetail's existing behavior + +The existing `ProjectDetail.tsx` probably has logic for the `configuration` and `budget` sub-routes (visible in the route table). You must preserve that behavior for backwards compat. Options: + +1. **Union the old and new tab logic.** In the new ProjectDetail, after deriving `activeTab`, first check if it's `configuration` or `budget` — if so, render the existing behavior unchanged. Otherwise dispatch to the new Builder tabs. +2. **Add Configuration and Budget as 8th/9th tabs.** The spec says 7 tabs but also says "Configuration" isn't in the list — probably because it should be folded into OVERVIEW or dropped. For Phase 11, err on the side of preserving: keep them accessible but don't surface them in the BuilderTabStrip. + +Decision: go with **option 1** — Builder tabs for the new 6/7 tabs, existing behavior for `configuration` and `budget` (silent, not surfaced in the tab strip but still routable). Report the configuration/budget preservation decision to the controller. + +### "Approvals → Gates" display rename (scope) + +Inside your Phase 11 files, any user-visible string that says "Approval" or "Approvals" should say "Gate" or "Gates": + +- Tab label: `GATES` (not `APPROVALS`) +- Tab ARIA label: `Gates` (not `Approvals`) +- Empty state: "No pending gates" (not "No pending approvals") + +Do NOT rename: +- The `approvalsApi` client +- The `/api/approvals` endpoints +- The `Approval` TypeScript type +- The `Approvals` top-level page at `/approvals` (backwards compat) +- Any component named `ApprovalsList` or similar +- Any test ID or CSS class + +The rename is display-only. + +### Hero stat typography + +DESIGN.md specifies `Inter Black 900` at `72px` for hero stats. Implementation: + +```tsx +
+ {Math.round(progress)}% +
+``` + +The font-weight 900 is Tailwind's `font-black`. The `leading-none` matches DESIGN.md §3 line-height 1.0 for display text. + +For the empty state (96px), use `font-black text-[96px] leading-none text-primary`. + +### Status dot animations + +```tsx +// working state — pulsing volt dot +