feat: unify Specs and Planner into one page #557

New issue

Closed

opened 2026-04-29 22:54:51 +00:00 by claude-desktop · 2 comments

claude-desktop commented 2026-04-29 22:54:51 +00:00

Collaborator

Copy link

As an operator, I want a single workspace that handles both spec authoring and planner sessions so that I stop context-switching between two routes that already share most of their data.

Today the foreman surface is split:

• /specs is document-first — list of .md files, full-page markdown editor, breakdown preview, "Create issues" button. Uses ForemanFileEntry[] + React Query.
• /planner is session-first — three-column layout with sessions sidebar, transcript, composer. Uses usePlannerStore (Zustand) + SSE streaming. Has an inline ?spec=<name> mode that already opens a spec in the middle column.

These are two views of the same workflow (spec → breakdown → issues, optionally guided by a chat session). The unification follows the agents-page model: single route, accordion-style sections for each surface, drawers for transient detail, autosave instead of explicit Save buttons.

Acceptance criteria

Information architecture

• One top-nav entry replaces "Specs" and "Planner". Working name: Workspace (/workspace). Final name decided during implementation.
• Single page exposes three concerns:
  • Sessions list (left rail) — chronological foreman chat sessions, "+ New session" CTA.
  • Active editor (center) — switches between spec markdown editor and chat transcript depending on what the operator opened.
  • Composer / actions (bottom or right) — message input for chat mode, "Create issues" / breakdown preview controls for spec mode.
• URL state encodes the selection: ?session=<id> and/or ?spec=<name>. Bookmarkable. Deep-linkable from issue comments.
• When neither is selected, the editor pane shows an empty state with the two primary CTAs ("Open spec", "Start session").

Sessions

• Sessions list collapses to a slide-in drawer below sm: (mobile pattern matches the agents page).
• Each session row: title (first user message preview), agent role chip, last-active timestamp.
• Click a session → loads transcript into the center pane; ?session=<id> replaces any prior ?spec.

Specs

• Specs list lives in the same sidebar as sessions, separated by a labelled section header (Sessions / Specs).
• Click a spec → loads markdown editor into the center pane; ?spec=<name> replaces any prior ?session.
• Spec editor preserves current behaviour: live breakdown preview, "Create issues" action, hotkeys.
• Spec autosaves on blur — no explicit Save button (mirror agents-page autosave + inline status pill).
• "Create issues" is a primary CTA in the right-side action region; opens the existing breakdown preview drawer.

Cross-mode

• Composer is only visible in chat mode.
• Switching between spec and session is instant — no full page reload, no double fetch.
• An inline action lets the operator promote a chat session to a spec ("Save as spec…") and lets a spec optionally open a session for clarification ("Discuss with foreman").
• Drawers (history, breakdown preview, etc.) use the <Drawer> primitive from PR #555 — role="dialog" + focus trap + focus return baked in.

Components — reuse first

• Reuse <Button> for every clickable. No raw <button> for new code paths.
• Reuse <Drawer> for any slide-out overlay.
• Reuse <ChipInput> if any tag/label input is needed.
• Lucide icons everywhere — no Unicode glyphs (e.g. ▶, ✓, ⚙, ×).
• Tokyo Night Storm tokens only — no raw hex.
• If a primitive is missing (e.g. tabs, two-pane split), add it under apps/web/src/components/ with the same a11y baseline as <Drawer>.

Responsive + a11y (parity with the agents page)

• Mobile (≤ 639px): sidebar collapses to a drawer; editor + composer stack vertically.
• Tablet (640–1023px): single-column with a top tab strip for switching between sessions / specs / composer.
• Desktop (≥ 1024px): three-column layout.
• All form inputs have associated <label> (or aria-label) and link errors via aria-describedby + aria-invalid.
• Save status (spec autosave + chat send) surfaces in a role="status" aria-live="polite" region.
• All keyboard paths exercised: Tab through sidebar → editor → composer; Esc closes drawers; Enter sends message; Cmd/Ctrl+S no-ops (autosave).
• Honours prefers-reduced-motion (already handled globally in index.css).

Migration

• /specs and /planner redirect to the new route preserving query params (?spec= / ?session=).
• Existing tests for spec editor + planner composer migrate to the new route or get rewritten to target the new IA.
• docs/foreman.md updated to describe the unified surface; docs/breakdown.md follow-up if needed.

Out of scope

• Server-side endpoint changes — /foreman/specs/*, /foreman/chat, /foreman/sessions/* stay as-is.
• Adding new chat capabilities (slash commands, MCP wiring, etc.) — strictly a UX merge.
• Multi-user collaboration / locking on specs — single-operator system today.
• Removing the inline ?spec= mode that already exists in the planner — it gets superseded by the new IA but the URL contract stays.

References

• Agents-page redesign as the model: PR #555 (feat/agents-history-drawer), commit da25428 for the <Drawer> primitive.
• Survey: apps/web/src/routes/specs.index.tsx (230 LOC), apps/web/src/routes/specs.$specName.tsx (~5.8K LOC), apps/web/src/routes/planner.index.tsx (636 LOC), feature folders components/spec-editor/ (5 files, ~2.2K LOC) and components/planner/ (5 files, ~2.2K LOC).
• Server endpoints: POST /foreman/chat, GET /foreman/sessions/:id, GET /foreman/stream/:task_id, POST /foreman/specs/:name, POST /foreman/breakdown-preview, POST /foreman/create-issues.
• Existing milestone context: M22 — UI consolidation (already merged Monitor work).

As an operator, I want a single workspace that handles both spec authoring and planner sessions so that I stop context-switching between two routes that already share most of their data. Today the foreman surface is split: - **`/specs`** is document-first — list of `.md` files, full-page markdown editor, breakdown preview, "Create issues" button. Uses `ForemanFileEntry[]` + React Query. - **`/planner`** is session-first — three-column layout with sessions sidebar, transcript, composer. Uses `usePlannerStore` (Zustand) + SSE streaming. Has an inline `?spec=<name>` mode that already opens a spec in the middle column. These are two views of the same workflow (spec → breakdown → issues, optionally guided by a chat session). The unification follows the agents-page model: single route, accordion-style sections for each surface, drawers for transient detail, autosave instead of explicit Save buttons. ## Acceptance criteria ### Information architecture - [ ] One top-nav entry replaces "Specs" and "Planner". Working name: **Workspace** (`/workspace`). Final name decided during implementation. - [ ] Single page exposes three concerns: - **Sessions list** (left rail) — chronological foreman chat sessions, "+ New session" CTA. - **Active editor** (center) — switches between spec markdown editor and chat transcript depending on what the operator opened. - **Composer / actions** (bottom or right) — message input for chat mode, "Create issues" / breakdown preview controls for spec mode. - [ ] URL state encodes the selection: `?session=<id>` and/or `?spec=<name>`. Bookmarkable. Deep-linkable from issue comments. - [ ] When neither is selected, the editor pane shows an empty state with the two primary CTAs ("Open spec", "Start session"). ### Sessions - [ ] Sessions list collapses to a slide-in drawer below `sm:` (mobile pattern matches the agents page). - [ ] Each session row: title (first user message preview), agent role chip, last-active timestamp. - [ ] Click a session → loads transcript into the center pane; `?session=<id>` replaces any prior `?spec`. ### Specs - [ ] Specs list lives in the same sidebar as sessions, separated by a labelled section header (Sessions / Specs). - [ ] Click a spec → loads markdown editor into the center pane; `?spec=<name>` replaces any prior `?session`. - [ ] Spec editor preserves current behaviour: live breakdown preview, "Create issues" action, hotkeys. - [ ] Spec autosaves on blur — no explicit Save button (mirror agents-page autosave + inline status pill). - [ ] "Create issues" is a primary CTA in the right-side action region; opens the existing breakdown preview drawer. ### Cross-mode - [ ] Composer is only visible in chat mode. - [ ] Switching between spec and session is instant — no full page reload, no double fetch. - [ ] An inline action lets the operator promote a chat session to a spec ("Save as spec…") and lets a spec optionally open a session for clarification ("Discuss with foreman"). - [ ] Drawers (history, breakdown preview, etc.) use the `<Drawer>` primitive from PR #555 — `role="dialog"` + focus trap + focus return baked in. ### Components — reuse first - [ ] Reuse `<Button>` for every clickable. No raw `<button>` for new code paths. - [ ] Reuse `<Drawer>` for any slide-out overlay. - [ ] Reuse `<ChipInput>` if any tag/label input is needed. - [ ] Lucide icons everywhere — no Unicode glyphs (e.g. ▶, ✓, ⚙, ×). - [ ] Tokyo Night Storm tokens only — no raw hex. - [ ] If a primitive is missing (e.g. tabs, two-pane split), add it under `apps/web/src/components/` with the same a11y baseline as `<Drawer>`. ### Responsive + a11y (parity with the agents page) - [ ] Mobile (≤ 639px): sidebar collapses to a drawer; editor + composer stack vertically. - [ ] Tablet (640–1023px): single-column with a top tab strip for switching between sessions / specs / composer. - [ ] Desktop (≥ 1024px): three-column layout. - [ ] All form inputs have associated `<label>` (or `aria-label`) and link errors via `aria-describedby` + `aria-invalid`. - [ ] Save status (spec autosave + chat send) surfaces in a `role="status" aria-live="polite"` region. - [ ] All keyboard paths exercised: Tab through sidebar → editor → composer; Esc closes drawers; Enter sends message; Cmd/Ctrl+S no-ops (autosave). - [ ] Honours `prefers-reduced-motion` (already handled globally in `index.css`). ### Migration - [ ] `/specs` and `/planner` redirect to the new route preserving query params (`?spec=` / `?session=`). - [ ] Existing tests for spec editor + planner composer migrate to the new route or get rewritten to target the new IA. - [ ] `docs/foreman.md` updated to describe the unified surface; `docs/breakdown.md` follow-up if needed. ## Out of scope - Server-side endpoint changes — `/foreman/specs/*`, `/foreman/chat`, `/foreman/sessions/*` stay as-is. - Adding new chat capabilities (slash commands, MCP wiring, etc.) — strictly a UX merge. - Multi-user collaboration / locking on specs — single-operator system today. - Removing the inline `?spec=` mode that already exists in the planner — it gets superseded by the new IA but the URL contract stays. ## References - Agents-page redesign as the model: PR #555 (`feat/agents-history-drawer`), commit `da25428` for the `<Drawer>` primitive. - Survey: `apps/web/src/routes/specs.index.tsx` (230 LOC), `apps/web/src/routes/specs.$specName.tsx` (~5.8K LOC), `apps/web/src/routes/planner.index.tsx` (636 LOC), feature folders `components/spec-editor/` (5 files, ~2.2K LOC) and `components/planner/` (5 files, ~2.2K LOC). - Server endpoints: `POST /foreman/chat`, `GET /foreman/sessions/:id`, `GET /foreman/stream/:task_id`, `POST /foreman/specs/:name`, `POST /foreman/breakdown-preview`, `POST /foreman/create-issues`. - Existing milestone context: M22 — UI consolidation (already merged Monitor work).

claude-desktop referenced this issue 2026-04-29 22:55:31 +00:00

feat: responsive + a11y sweep across the remaining web routes #558

claude-desktop added the

area:dashboard

type:user-story

labels 2026-04-29 22:55:42 +00:00

claude-desktop referenced this issue 2026-04-29 22:58:46 +00:00

chore: rip out the stats feature (rebuild later) #556

claude-desktop referenced this issue 2026-04-29 22:58:58 +00:00

feat: responsive + a11y sweep across the remaining web routes #558

claude-desktop commented 2026-04-29 22:59:11 +00:00

Author

Collaborator

Copy link

Dispatch coordination

Blocked by #558's foundation commit. Wait until #558's first commit (Tabs primitive at apps/web/src/components/tabs.tsx + apps/web/CLAUDE.md conventions update) lands on main. Then rebase off main and proceed.

Routing: boss (new IA — merging document-first + session-first mental models, drawer-pattern carry-over, autosave wiring).

Why the wait: the unification needs a tabs/section-switcher UI and the <Tabs> primitive is being designed in #558. If both tickets land tabs independently, two implementations diverge and one has to be rewritten. Pulling from #558 keeps the design system coherent.

Soft-parallel with #556 (stats removal — different feature folders entirely).

Conflict points to watch:

• apps/web/src/components/app-shell.tsx — collapse the Specs + Planner nav entries into one Workspace entry. #556 will also drop /stats from the same file; rebase to pick up that change.
• apps/web/CLAUDE.md — #558 lands its conventions section first; append your specs/planner notes after rebase.
• apps/web/src/components/tabs.tsx — IMPORTED, not authored. If you reach for it before #558 commits, fall back to base-ui-components/tabs or hand-roll inline (with a TODO to swap in once #558 lands).

Implementation note: the existing ?spec=<name> URL parameter in planner.index.tsx is the precedent for cross-mode deep-links. Preserve that contract, then add ?session=<id> per the AC.

## Dispatch coordination **Blocked by #558's foundation commit.** Wait until #558's first commit (Tabs primitive at `apps/web/src/components/tabs.tsx` + `apps/web/CLAUDE.md` conventions update) lands on `main`. Then rebase off main and proceed. **Routing:** boss (new IA — merging document-first + session-first mental models, drawer-pattern carry-over, autosave wiring). **Why the wait:** the unification needs a tabs/section-switcher UI and the `<Tabs>` primitive is being designed in #558. If both tickets land tabs independently, two implementations diverge and one has to be rewritten. Pulling from #558 keeps the design system coherent. **Soft-parallel with #556** (stats removal — different feature folders entirely). **Conflict points to watch:** - `apps/web/src/components/app-shell.tsx` — collapse the `Specs` + `Planner` nav entries into one `Workspace` entry. #556 will also drop `/stats` from the same file; rebase to pick up that change. - `apps/web/CLAUDE.md` — #558 lands its conventions section first; append your specs/planner notes after rebase. - `apps/web/src/components/tabs.tsx` — IMPORTED, not authored. If you reach for it before #558 commits, fall back to base-ui-components/tabs or hand-roll inline (with a TODO to swap in once #558 lands). **Implementation note:** the existing `?spec=<name>` URL parameter in `planner.index.tsx` is the precedent for cross-mode deep-links. Preserve that contract, then add `?session=<id>` per the AC.

claude-desktop referenced this issue 2026-04-29 23:30:38 +00:00

feat(agents): redesign — drawers, design-system foundation, a11y, mobile #559

charles referenced this issue from a commit 2026-04-29 23:31:48 +00:00

feat(agents): redesign — drawers, design-system foundation, a11y, mobile (#559)

claude-desktop added a new dependency 2026-04-29 23:34:58 +00:00

#558 feat: responsive + a11y sweep across the remaining web routes

code-lead self-assigned this 2026-04-30 00:13:22 +00:00

code-lead commented 2026-04-30 00:13:22 +00:00

Collaborator

Copy link

🤖 Auto-assigned to boss (heuristic: area:dashboard + body 5840 bytes (> 2 KB) — boss (heavy)). Reply /unassign to reroute.

🤖 Auto-assigned to **boss** (heuristic: area:dashboard + body 5840 bytes (> 2 KB) — boss (heavy)). Reply `/unassign` to reroute.

code-lead referenced this issue from a commit 2026-04-30 00:31:58 +00:00

feat(web): unify Specs and Planner into /workspace (#557)

code-lead referenced this issue from a pull request that will close it, 2026-04-30 00:32:21 +00:00

feat(web): unify Specs and Planner into /workspace #562

code-lead closed this issue 2026-04-30 00:52:54 +00:00

code-lead referenced this issue from a commit 2026-04-30 00:52:55 +00:00

feat(web): unify Specs and Planner into /workspace (#562)

Sign in to join this conversation.

No Branch/Tag specified

Branches Tags

main

chore/sync-pre-push-from-forge-base

fix/flows-yaml-dispatch-identity

feat/board-tap-to-assign

dev/1107

code-lead/1106

code-lead/1108

dev/1104

code-lead/1103

code-lead/1080

dev/1087

feat/flows-yaml-ci-events

chore/board-drop-stalled-and-density-controls

fix/flows-yaml-routes-always-register

flows-yaml/api-defaults

dev/1023

fix/event-log-history-bleed

fix/janitor-fix-ci-logs-and-cap

dev/1022

fix/board-card-provider

code-lead/1036

dev/1025

code-lead/1020

dev/1017

code-lead/1026

feat/web-shortcut-registry-1018

dev/1015

code-lead/1009

code-lead/1008

dev/975

dev/969

dev/973

dev/967

code-lead/968

code-lead/953

dev/970

dev/976

code-lead/966

code-lead/956

code-lead/951

dev/962

dev/963

dev/977

dev/955

dev/983

dev/961

dev/974

code-lead/950

code-lead/939

dev/941

dev/940

dev/937

dev/938

dev/936

dev/935

feat/web-i18n-fr-locale

feat/spec-editor-ui-polish

chore/drop-legacy-compat

fix/skills-drop-preview-pane

fix/882-skills-safety-rail

dev/911

dev/909

dev/923

dev/917

dev/915

feat/879-sr11-m2-drop-legacy-skill

code-lead/873

dev/881

code-lead/869

dev/867

code-lead/845

code-lead/843

code-lead/844

dev/837

dev/861

dev/849

code-lead/837

code-lead/842

fix/dedup-rebase-inflight

dev/838

code-lead/847

dev/833

code-lead/848

pr/838

code-lead/841

feat/settings-save-bar/836

code-lead/840

dev/846

code-lead/839

dev/832

fix/board-sse-stale-cache

dev/834

dev/835

feat/settings-breadcrumbs

feat/forge-oauth-credentials

refactor/service-config-consolidation

feat/agent-tokens-to-secrets

feat/gitlab-oauth-to-db

feat/authelia-rip-and-voice-fixes

fix/rebase-storm-and-dead-letter

code-lead/797

code-lead/796

dev/811

code-lead/798

dev/810

code-lead/795

dev/808

code-lead/794

dev/805

dev/802

dev/803

feat/avatar-menu-settings-entry

feat/per-agent-token-tracking

dev/793

dev/747

dev/752

code-lead/790

code-lead/759

dev/756

dev/760

dev/741

dev/767

dev/740

dev/709

dev/644

dev/637

boss/614

dev/600

dev/611

dev/585

fix/login-bonus-fixes

boss/544

dev/542

refactor/api-prefix-and-session-gate

dev/489

boss/531

boss/518

dev/499

boss/516

dev/530

dev/517

dev/519

dev/515

dev/522

dev/503

dev/471

boss/329

dev/417

dev/418

dev/402

boss/327

dev/334

dev/332

boss/326

boss/325

dev/331

boss/324

boss/323

boss/322

dev/294

test/s11-task-analytics

dev/262

boss/270

dev/268

foreman/ui-consolidation-spec

dev/234

boss/196

boss/176

boss/164

fix/124-session-persist-bind

boss/52

dev/87

boss/73

dev/77

dev/81

dev/82

boss/79

dev/42

dev/35

boss/7

No results found.

Labels

Clear labels   

area:agents

Agent types, pool scheduling, per-instance config

  

area:dashboard

Dashboard UI and observability surfaces

  

area:database

DB layer — schema, migrations, ORM, raw SQL

  

area:design

UI/UX mockup work — routes to designer agent

  

area:design-review

Design review dispatch — routes to design-reviewer agent

  

area:flows

Flow runner — YAML loader, executor, op registry, expression eval

  

area:infra

Deployment, isolation, containers, systemd units

  

area:meta

Tracking, scaffolding, project setup

  

area:security

Security — routes to reviewer-security (opus)

  

area:sessions

Session-id store, Claude SDK resume logic

  

area:webhook

Forgejo webhook routing and handlers

  

area:workdir

Clone cache, worktrees, git identity

  

security

Security-sensitive issue

  

type:bug

Bug

  

type:chore

Chore

  

type:meta

Tracking or decisions, not implementation work

  

type:user-story

User story

No labels

area:agents

area:dashboard

area:database

area:design

area:design-review

area:flows

area:infra

area:meta

area:security

area:sessions

area:webhook

area:workdir

security

type:bug

type:chore

type:meta

type:user-story

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

code-lead

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Depends on

#558 feat: responsive + a11y sweep across the remaining web routes

charles/claude-hooks

Reference

charles/claude-hooks#557

No description provided.