oleg.m/waggle-os
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b20b138fe485817e8d69d0c60e376e3c53af149a
waggle-os/docs/ux-refactor/gap-cards/S17-workspace-creation.md
Oleg Maslov 0c3e2ead3b
Some checks failed
Installer Smoke / installer-smoke (push) Has been cancelled
Details
moving
2026-09-02 10:10:29 +02:00

16 KiB
Raw Blame History

Gap Card — S17 · Workspace Creation

Execution model: in-place incremental refactor of apps/web + targeted backend extension. Mockup is directional only (PRD §24); PRD acceptance criteria win over pixels. Every claim below cites a real file. PRD = docs/Waggle_OS_UX_Refactor_Master_Handoff_Package/Waggle_OS_UX_Refactor_PRD.md.

1. Screen & purpose

Screen 17 — Workspace Creation. "Create a workspace with suggested capabilities" — the screen that turns onboarding (or a manual "+ New Workspace") into the user's first useful context.

  • PRD §12.12 step 6 ("Workspace Creation — create first useful context") + Journeys 1/2 (PRD lines 678, 685: "Creates first workspace" / "Creates workspace manually" → lands in Home Cockpit).
  • Blueprint screen-table row 17 (_blueprint_extracted.txt:402-409): Purpose "Create a workspace with suggested capabilities"; Interactions "Enter name/type, add suggestions, review, create"; States "Empty; recommended; validation error; created"; Acceptance "Workspace becomes first useful context after onboarding."
  • Mockup screen_17_create_workspace.png (directional): a 4-step wizard (Basic info → Preferences → Review & create) with a left form column (Description, Workspace type = Project/Client/Research/ Personal cards), a center "Suggested capabilities" column (Suggested Skills / Suggested Agents / Suggested Connectors / Suggested MCPs, each with "Add all"), and a right "Workspace summary" card (name, type, description, "Includes: Skills/Agents/Connectors/MCPs" counts). Footer: Cancel / "Next: Preferences →".

Net: the mockup reframes the existing single-pane modal as a stepped wizard whose center of gravity is recommended capabilities + a live summary, driven by workspace type and persona — not just a name + template picker.

2. Required states (PRD / Blueprint)

From the blueprint state list + PRD acceptance criteria:

  1. Empty — fresh form, no name/type, nothing suggested yet.
  2. Recommended — once type/persona/template chosen, Suggested Skills/Agents/Connectors/MCPs populate (silent default ordering, per feedback_silent_recommendations_dont_ask.md — recommend, don't interrogate).
  3. Validation error — name required (PRD acceptance: validation surfaced inline); tier workspace-limit reached (FREE = 5; existing 403 path); local storage-path missing.
  4. Created — workspace persisted, becomes active, transitions to Home Cockpit (S?) / Workspace Desktop.
  5. (Onboarding-embedded variant) — same flow but rendered as step 6 of the wizard, no modal chrome, handing off to step 7 Home Cockpit (PRD §12.12).

PRD §12.12 acceptance that bears on this screen: "Connectors/MCPs/skills are recommended from user selections" and "Onboarding asks user questions, not infrastructure questions."

3. Current state in repo

Disposition: rework (keep + heavily extend the existing component; do not create-new — the modal, its template/persona/storage/agent-group machinery, and the live folder picker are all reusable substrate).

File What it does today
apps/web/src/components/os/overlays/CreateWorkspaceDialog.tsx (1129 LOC) The live create-workspace modal. Single scrolling pane (NOT stepped). Fields: Template picker (category filter + search + 15 built-ins + custom CRUD via TemplateCreatorModal), Workspace Name, Group (STANDARD_GROUPS), Storage Type (virtual/local/team) + path + FolderPickerModal (live adapter.browseLocal/browseLocalMkdir), Agent (single persona grid from PERSONAS OR agent-group picker), Share with team toggle. Calls onCreate({ name, group, persona?, agentGroupId?, shared?, storageType?, storagePath?, templateId? }).
apps/web/src/components/os/overlays/WorkspaceSwitcher.tsx Quick-switch list only (filters E2E/test names). Not a creation surface — adjacent, unchanged by S17.
apps/web/src/hooks/useWorkspaces.ts:27-51 createWorkspace(data) → adapter.createWorkspace(data), optimistic add + select, local fallback on error.
apps/web/src/lib/skill-recommendations.ts:103 recommendSkills(personaId) → persona→skill-chip map w/ universal fallback. Already the seed for "Suggested Skills".
apps/web/src/components/os/overlays/OnboardingWizard.tsx:278,314 Onboarding's own inline adapter.createWorkspace(...) call (the embedded variant) — bypasses this dialog today.

Gaps vs mockup/PRD in the current component:

  • No stepped wizard — it's one scrolling modal, not Basic info → Preferences → Review.
  • No "Workspace type" concept (Project/Client/Research/Personal) — only Group (free-string chips) + templateId. (WorkspaceType is a missing schema field — see §5/§6.)
  • No Suggested Agents / Suggested Connectors / Suggested MCPs panels. Suggested skills logic exists (recommendSkills) but is not wired into this dialog. Connectors are fetched but only used for the template editor's chip list, not surfaced as workspace-scoped recommendations.
  • No "Workspace summary" / Includes-counts card (the right rail in the mockup).
  • No description field.

Two real FE bugs to fix in passing (surgical, in-scope):

  1. useWorkspaces.createWorkspace typed signature (useWorkspaces.ts:27) omits storageType, storagePath, agentGroupId even though the dialog passes them — they're silently dropped at the type boundary (the object still flows through to adapter.createWorkspace, but the local-fallback path :35-46 and the type contract lose them). Widen the param type.
  2. CreateWorkspaceDialog.onCreate payload uses persona/shared (FE display names) while the backend POST expects personaId and has no shared/group→team mapping — shared is accepted by the dialog but never reaches POST /api/workspaces (which has no shared field; team linkage is teamId). Reconcile during rework.

4. Frontend work

Rework CreateWorkspaceDialog.tsx into a 3-step wizard (keep the file; restructure internals). Prefer extracting step bodies into small co-located components to respect the 800-LOC ceiling (current file is already 1129 LOC — this rework should reduce it by extracting).

Components to create (new, under overlays/workspace-create/):

  • WorkspaceTypePicker.tsx — Project/Client/Research/Personal cards (drives type + default suggestions). Maps to new WorkspaceType union (§6).
  • SuggestedCapabilities.tsx — 4 sections (Skills/Agents/Connectors/MCPs) each with per-item add + "Add all". Reuse recommendSkills(personaId) for Skills; derive Agents from PERSONAS + adapter.getAgentGroups(); Connectors from adapter.getConnectors() (already fetched here); MCPs from a new MCP list source (§5). Silent-default ordering (no "which tools?" prompt).
  • WorkspaceSummaryCard.tsx — live right-rail: name, type, description, "Includes" counts (skills/agents/ connectors/mcps selected).
  • WizardStepper.tsx — Basic info / Preferences / Review header (or reuse a stepper primitive if added).

Reuse targets (do NOT rebuild): TemplateCreatorModal, FolderPickerModal, ChipPicker, Tooltip, STORAGE_OPTIONS, the persona grid, STANDARD_GROUPS, LockedFeature (tier gate), useFeatureGate (multi-workspace), useWorkspaces.

State/props additions:

  • Local state: step (0|1|2), description, type (WorkspaceType), selectedSkills[], selectedAgentIds[], selectedConnectorIds[], selectedMcpIds[].
  • Extend onCreate(...) payload to include description, type, skills, agentIds, connectorIds, mcpIds.
  • Wire recommendSkills + a new recommendCapabilities(type, personaId) helper in apps/web/src/lib/ (extends existing skill-recommendations pattern) so suggestions react to type/persona without a backend call where possible.

Adapter/hook:

  • Widen useWorkspaces.createWorkspace param type (fix §3 bug 1) to carry the new fields + storage fields.
  • adapter.createWorkspace already POSTs the body through (lib/adapter.ts createWorkspace → POST /api/workspaces); new body fields ride along once the route accepts them (§5).
  • For Suggested MCPs, add adapter.getMcps() if a /api/mcps (or capabilities-derived) source is built (§5).

Onboarding parity: route OnboardingWizard step 6 through the same step bodies (render without modal chrome) instead of its bespoke adapter.createWorkspace calls (OnboardingWizard.tsx:278,314) — single source of truth for the create flow.

5. Backend work (PRD §16.2 + suggestion sources)

§16.2 endpoints used by/adjacent to this screen:

PRD endpoint Status Extend vs net-new / substrate
POST /api/workspaces EXISTS workspaces.ts:116-135. EXTEND the Body type + WorkspaceManager.create to accept description, type (WorkspaceType), skills[], agentIds[], connectorIds[], mcpIds[], status. These are additive fields on WorkspaceConfig/CreateWorkspaceOptions (workspace-manager.ts:5-95). Substrate: workspace.json (file, not SQLite).
GET /api/workspaces EXISTS workspaces.ts:101. Unchanged.
GET /api/workspaces/:id EXISTS workspaces.ts. Unchanged.
PATCH /api/workspaces/:id EXISTS Used post-create for edits; should accept the new fields too.
GET /api/workspace-templates EXISTS (not in §16 but central here) workspace-templates.ts:33 (15 built-ins). Templates already carry persona, connectors, suggestedCommands, starterMemory — the seed for Suggested panels. May EXTEND the WorkspaceTemplate shape to add skills[]/mcps[]/type so a chosen template can pre-populate all 4 suggestion lists.

Suggested-capabilities data sources (mockup center column):

  • Skills — no new endpoint; FE recommendSkills + starter-pack catalog (GET /api/skills/starter-pack/catalog, EXISTS). On create, the route already auto-installs starter skills (workspaces.ts:198-211) and seeds template starter-memory frames (:223-249).
  • Agents — GET /api/personas (EXISTS) + GET /api/agent-groups (EXISTS). No new endpoint.
  • Connectors — GET /api/connectors (EXISTS). No new endpoint.
  • MCPs — PARTIAL/MISSING: per backend-routes inventory §16.9, there is no GET /api/mcps. MCP servers surface inside GET /api/capabilities/status (mcpServers[]) and the static catalog @waggle/shared mcp-catalog.ts. EXTEND rather than net-new store: add a thin GET /api/mcps read route that composes capabilities/status + mcp-catalog, OR have the FE read the existing catalog
    • capabilities/status directly for the Suggested-MCPs panel (lower-risk for S17; defer the dedicated route to S20/MCP screen).

No new data store needed. Persisting agentIds/connectorIds/mcpIds on the workspace = additive optional fields on the workspace.json config (substrate-types §a confirms: no DB migration — these live in JSON, not SQLite). WorkspaceManager.create/update (workspace-manager.ts:124-244) writes the JSON; update() should also stamp updatedAt (currently missing, substrate-types §a) — fold that in here since we're extending the write path anyway.

.mind migration: None required for S17. (The memory-side metadata/confidence migration in substrate-types §c belongs to the Memory screen, not workspace creation.)

6. Shared types needed (PRD §15 vs lib/types.ts)

  • WorkspaceType (PRD §15.2/§15.3) — MISSING everywhere. New literal union; mockup implies 'project' | 'client' | 'research' | 'personal' (confirm exact set — see Open Questions). Add to FE apps/web/src/lib/types.ts AND backend WorkspaceConfig (workspace-manager.ts). Keep the existing free-string group (don't drop — substrate-types §a "keep, do not drop").
  • WorkspaceConfigV2 deltas (PRD §15.3, lines 961-985) touched by this screen: add description, type, status ('active'|'paused'|'archived', default 'active'), agentIds[], connectorIds[], mcpIds[], updatedAt. (storageType/storagePath/teamId/teamRole/riskLevel/created already present.) Per substrate-types §a these are pure additive optional fields, no DB migration.
  • FE Workspace (lib/types.ts:22-40) is a lossy projection (persona string vs config personaId; derived memoryCount/lastActive/etc.). Add the same type/description/status + capability-id arrays; reconcile persona→personaId mapping at the adapter boundary (don't break the switcher, which reads ws.persona).

7. Dependencies (screens / phases first)

  • Schema additions are foundational — WorkspaceType + the V2 config fields are shared by S?? Home Cockpit, S?? Workspace Desktop (header shows type/status, substrate-types §b), and the Agent/Artifact screens. Land the type + POST/PATCH /api/workspaces extension as a shared early phase before the S17 UI rework so downstream screens consume the same fields.
  • Suggested capabilities depends on the Skills (recommendSkills, exists), Personas/Agent-groups (exist), Connectors (exists) sources — all available now. Only Suggested MCPs has a missing/partial backend; gate that panel behind the MCP source decision (don't block S17 on the dedicated /api/mcps).
  • Onboarding (S?? §12.12) consumes this flow as step 6 — unify after the standalone modal rework so both paths share one implementation.
  • PRD roadmap places this in Sprint 5 — Onboarding and workspace creation (PRD line 1335).

8. Effort

M. The modal, template/persona/storage/agent-group machinery, folder picker, and skill-recommendation helper all exist — the work is restructuring into a 3-step wizard, adding 3-4 small components (type picker, suggested-capabilities, summary card), wiring existing suggestion sources, and additive (no-migration) backend field extension on the workspace config. Pushed toward the high end of M by the Suggested-MCPs source ambiguity, the onboarding-parity unification, and the two FE bugs to reconcile; not L because there is no new data store and no .mind migration.

9. Open questions

  1. Exact WorkspaceType values. Mockup shows Project/Client/Research/Personal. PRD §15.2 names WorkspaceType but does not enumerate. Confirm the canonical set (and whether type replaces or coexists with the existing free-string group/STANDARD_GROUPS). Recommendation: coexist — type is the new structured axis, group stays as the user's organizational label.
  2. Suggested MCPs source for S17. Build the thin GET /api/mcps now, or read capabilities/status + mcp-catalog directly from the FE and defer the dedicated route to the MCP screen? (Lower-risk = defer.)
  3. shared/team handoff. The dialog has a "Share with team" toggle that currently never reaches the backend (no shared field on POST /api/workspaces). For S17, does "share" set teamId/teamRole (requires a team to exist + TEAMS tier), or is it deferred to the Team screen? Today it's a dead toggle.
  4. Wizard vs modal in onboarding. Confirm the embedded onboarding variant should render the same step bodies (preferred, single source of truth) vs keeping OnboardingWizard's bespoke create call.
  5. Does S17 install/connect on create, or only stage selections? PRD says recommend; mockup "Add all" implies staging. Confirm that selected connectors/MCPs are recorded as workspace intent (ids on the config) vs actually installed/connected at create time (the latter pulls in install-audit + connector OAuth flows — much larger scope; recommend record-only for S17).
Reference in New Issue View Git Blame Copy Permalink