mosaic/stack
1
0
Fork 0
Code Issues 10 Pull Requests Actions Packages Projects Releases 2 Wiki Activity

docs: initialize MS18 Theme & Widget System mission #492

Merged
jason.woltje merged 1 commits from chore/ms18-planning into main 2026-02-23 13:36:10 +00:00
Conversation 0 Commits 1 Files Changed 4 +146 -60
4 changed files with 146 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/MISSION-MANIFEST.md
View File

@@ -1,40 +1,41 @@
# Mission Manifest — PRD implementation # Mission Manifest — MS18 Theme & Widget System
> Persistent document tracking full mission scope, status, and session history. > Persistent document tracking full mission scope, status, and session history.
> Updated by the orchestrator at each phase transition and milestone completion. > Updated by the orchestrator at each phase transition and milestone completion.
## Mission ## Mission
**ID:** prd-implementation-20260222 **ID:** ms18-theme-widgets-20260223
**Statement:** Implement MS16+MS17 (Pages & Data Integration) — build all remaining pages, wire to real API data, eliminate mock data, deploy to production **Statement:** Implement MS18 (Theme & Widget System) — multi-theme package system, customizable widget dashboard, WYSIWYG knowledge editor, and enhanced Kanban filtering
**Phase:** Execution **Phase:** Planning
**Current Milestone:** MS16+MS17-PagesDataIntegration **Current Milestone:** MS18-ThemeWidgets
**Progress:** 1 / 1 milestones **Progress:** 0 / 1 milestones
**Status:** completed **Status:** active
**Last Updated:** 2026-02-22T23:40Z **Last Updated:** 2026-02-23T13:30Z
## Success Criteria ## Success Criteria
1. All sidebar links navigate to functional pages (no 404s from sidebar navigation) 1. Theme system supports 5+ themes (dark, light, + 3 additional built-in)
2. Projects page: list, create, view, edit, delete projects 2. Themes are defined as TypeScript packages with CSS variable overrides
3. Workspace page: view single project with tasks and agent sessions 3. Theme selection UI in Settings with live preview swatches
4. Kanban page: drag-and-drop board with 5 TaskStatus columns 4. UserPreference.theme persists selected theme across sessions
5. File Manager page: tree/list view with CRUD operations 5. Dashboard uses customizable WidgetGrid (drag, resize, add, remove widgets)
6. Logs page: log viewer with filtering and auto-refresh 6. Widget picker UI allows browsing and adding widgets from registry
7. Settings root page: category index linking to all subpages 7. Per-widget configuration dialog (data source, filters, colors)
8. Custom 404 page for unknown routes 8. Layout save/load/rename via UserLayout API
9. Profile page linked from sidebar user card 9. WYSIWYG editor (Tiptap) for knowledge entries with toolbar
10. /tasks, /calendar, /knowledge pages use real API data (no mock) 10. Markdown ↔ rich text round-trip (import/export)
11. All new pages support light/dark theme 11. Kanban board supports project-level and user-level filtering
12. All new pages are responsive (sm/md/lg/xl breakpoints) 12. Kanban filter bar: project, assignee, priority, search
13. Lint, typecheck, and tests pass 13. All features support all themes (dark/light + new themes)
14. Deployed and smoke-tested at mosaic.woltje.com 14. Lint, typecheck, and tests pass
15. Deployed and smoke-tested at mosaic.woltje.com
## Milestones ## Milestones
| # | ID | Name | Status | Branch | Issue | Started | Completed | | # | ID | Name | Status | Branch | Issue | Started | Completed |
| --- | --------- | ------------------------ | -------- | ------------------------- | ------------------- | ---------- | ---------- | | --- | ---- | --------------------- | ----------- | ------------------------- | ------------------------ | ------- | --------- |
| 1 | MS16+MS17 | Pages & Data Integration | complete | per-task feature branches | #466,#467,#468,#469 | 2026-02-22 | 2026-02-23 | | 1 | MS18 | Theme & Widget System | not-started | per-task feature branches | #487,#488,#489,#490,#491 | — | — |
## Deployment ## Deployment
@@ -46,18 +47,16 @@
| Metric | Value | | Metric | Value |
| ------ | ----------------- | | ------ | ----------------- |
| Budget | ~320K (estimated) | | Budget | ~500K (estimated) |
| Used | 0 | | Used | 0 |
| Mode | normal | | Mode | normal |
## Session History ## Session History
| Session | Runtime | Started | Duration | Ended Reason | Last Task | | Session | Runtime | Started | Duration | Ended Reason | Last Task |
| ------- | --------------- | ----------------- | -------- | ------------- | ----------------------------------- | | ------- | --------------- | ----------------- | -------- | ------------ | ------------------- |
| S1 | Claude Opus 4.6 | 2026-02-22T21:20Z | ~2.5h | context limit | PG-VER-001 (all 13 impl tasks done) | | S1 | Claude Opus 4.6 | 2026-02-23T13:30Z | — | — | Planning (PLAN-001) |
| S2 | Claude Opus 4.6 | 2026-02-22T23:40Z | ~30m | completed | PG-VER-002 (deploy + smoke test) |
| S3 | Claude Opus 4.6 | 2026-02-23T16:00Z | ~10m | close-out | Mission close-out + PRD update |
## Scratchpad ## Scratchpad
Path: `docs/scratchpads/prd-implementation-20260222.md` Path: `docs/scratchpads/ms18-theme-widgets-20260223.md`

5
docs/PRD.md
View File

@@ -400,7 +400,7 @@ These 19 NestJS modules are already implemented with Prisma and available for fr
| MS15-DashboardShell | 0.0.15 | Design system + app shell + dashboard page | COMPLETE | | MS15-DashboardShell | 0.0.15 | Design system + app shell + dashboard page | COMPLETE |
| Go-Live MVP | 0.1.0 | Dashboard polish, ingestion, agent visibility, deploy | COMPLETE | | Go-Live MVP | 0.1.0 | Dashboard polish, ingestion, agent visibility, deploy | COMPLETE |
| MS16+MS17-PagesDataIntegration | 0.1.1 | All pages built + wired to real API data | COMPLETE | | MS16+MS17-PagesDataIntegration | 0.1.1 | All pages built + wired to real API data | COMPLETE |
| MS18-ThemeWidgets | 0.1.x | Theme package system, widget registry, dashboard customization | NOT STARTED | | MS18-ThemeWidgets | 0.1.2 | Theme package system, widget registry, dashboard customization | IN PROGRESS |
| MS19-ChatTerminal | 0.1.x | Global terminal, project chat, master chat session | NOT STARTED | | MS19-ChatTerminal | 0.1.x | Global terminal, project chat, master chat session | NOT STARTED |
| MS20-MultiTenant | 0.2.0 | Multi-tenant, teams, RBAC, RLS enforcement, break-glass auth | NOT STARTED | | MS20-MultiTenant | 0.2.0 | Multi-tenant, teams, RBAC, RLS enforcement, break-glass auth | NOT STARTED |
| MS21-Federation | 0.2.x | Federation (M-M, M-S), 3 instances, key exchange, data separation | NOT STARTED | | MS21-Federation | 0.2.x | Federation (M-M, M-S), 3 instances, key exchange, data separation | NOT STARTED |
@@ -414,3 +414,6 @@ These 19 NestJS modules are already implemented with Prisma and available for fr
3. ASSUMPTION: Initial implementation supports dark/light from reference design. Multi-theme package system is a future milestone. Rationale: Foundation must be solid before extensibility. 3. ASSUMPTION: Initial implementation supports dark/light from reference design. Multi-theme package system is a future milestone. Rationale: Foundation must be solid before extensibility.
4. ASSUMPTION: MS16 and MS17 are combined into a single mission because 19 backend API modules already exist with real Prisma business logic. The remaining work is primarily frontend page creation and API wiring. Rationale: Backend audit on 2026-02-22 confirmed all required endpoints are implemented. 4. ASSUMPTION: MS16 and MS17 are combined into a single mission because 19 backend API modules already exist with real Prisma business logic. The remaining work is primarily frontend page creation and API wiring. Rationale: Backend audit on 2026-02-22 confirmed all required endpoints are implemented.
5. ASSUMPTION: File Manager page maps to Knowledge entries rather than a separate file system abstraction. Rationale: `/api/knowledge` provides full CRUD + search which matches file manager needs. Can be extended later if needed. 5. ASSUMPTION: File Manager page maps to Knowledge entries rather than a separate file system abstraction. Rationale: `/api/knowledge` provides full CRUD + search which matches file manager needs. Can be extended later if needed.
6. ASSUMPTION: Theme packages are code-level TypeScript files (not runtime-installable npm packages). Each theme exports CSS variable overrides. Rationale: Keeps the system simple for MS18; runtime package loading can be added in a future milestone.
7. ASSUMPTION: WYSIWYG editor uses Tiptap (ProseMirror-based, headless). Rationale: Headless approach integrates naturally with the CSS variable design system, excellent markdown import/export, TypeScript-first, battle-tested.
8. ASSUMPTION: MS18 includes WYSIWYG editing for knowledge entries and Kanban filtering enhancements in addition to themes and widgets. These were originally listed separately but are grouped into MS18 per PRD scope items 24-25. Rationale: All are frontend-focused enhancements that build on the existing page infrastructure.

55
docs/TASKS.md
View File

@@ -1,33 +1,34 @@
# Tasks — MS16+MS17 Pages & Data Integration # Tasks — MS18 Theme & Widget System
> Single-writer: orchestrator only. Workers read but never modify. > Single-writer: orchestrator only. Workers read but never modify.
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes | | id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
| ----------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------- | ---- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------ | ----------------- | ----------------- | -------- | ---- | ---------------------------------------------------------------------------- | | ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ------ | ------------------------------------------------------ | ------------------------------------------- | ------------ | ---------- | ------------ | -------- | ---- | ----- |
| PG-PLAN-001 | done | Plan MS16+MS17 task breakdown, create issues + milestone | #466-#469 | — | — | | PG-FND-001,PG-FND-002,PG-API-001,PG-API-002,PG-API-003 | orchestrator | 2026-02-22T21:20Z | 2026-02-22T21:35Z | 15K | — | Planning complete. PR #470 merged. | | TW-PLAN-001 | in-progress | Plan MS18 task breakdown, create milestone + issues, populate TASKS.md | — | — | — | | TW-THM-001,TW-WDG-001,TW-EDT-001,TW-KBN-001 | orchestrator | 2026-02-23 | — | 15K | — | |
| PG-FND-001 | done | Custom 404 page — Branded not-found page matching design system, navigation back to dashboard | #466 | web | feat/404-page | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T21:35Z | 2026-02-22T21:43Z | 10K | — | PR #472 merged. Global + authenticated 404 pages. | | TW-THM-001 | not-started | Theme architecture — Create theme definition interface, theme registry, and 5 built-in themes (Dark, Light, Nord, Dracula, Solarized) as TS files | #487 | web | TBD | TW-PLAN-001 | TW-THM-002,TW-THM-003 | worker | — | — | 30K | — | |
| PG-FND-002 | done | Settings root/index page — Category cards linking to Credentials, Domains, Personalities, Workspaces subpages | #466 | web | feat/settings-root | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T21:35Z | 2026-02-22T21:42Z | 12K | — | PR #471 merged. 4 category cards with icons. Issue #466 closed. | | TW-THM-002 | not-started | ThemeProvider upgrade — Load themes dynamically from registry, apply CSS variables, support instant theme switching without page reload | #487 | web | TBD | TW-THM-001 | TW-THM-003,TW-VER-002 | worker | — | — | 25K | — | |
| PG-API-001 | done | Wire /tasks page to real API — Replace mockTasks with fetchTasks() calls, add loading/empty/error states | #467 | web | feat/tasks-real-api | PG-PLAN-001 | PG-PAGE-003,PG-VER-001 | worker | 2026-02-22T21:44Z | 2026-02-22T22:05Z | 18K | — | PRs #473+#475 merged. Mock removed. Tests updated. | | TW-THM-003 | not-started | Theme selection UI — Settings page section with theme browser, live preview swatches, persist selection to UserPreference.theme via API | #487 | web | TBD | TW-THM-001,TW-THM-002 | TW-VER-002 | worker | — | — | 25K | — | |
| PG-API-002 | done | Wire /calendar page to real API — Replace mockEvents with fetchEvents() calls, add loading/empty/error states | #467 | web | feat/calendar-real-api | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T21:44Z | 2026-02-22T22:00Z | 18K | — | PR #474 merged. Mock removed. Issue #467 closed. | | TW-WDG-001 | not-started | Widget definition seeding — Seed 7 existing widgets into widget_definitions table with correct sizing constraints and configSchema | #488 | api | TBD | TW-PLAN-001 | TW-WDG-002 | worker | — | — | 15K | — | |
| PG-API-003 | done | Wire /knowledge pages to real API — Replace mockEntries/mockTags across list, detail, search, graph, stats pages | #467 | web | feat/knowledge-real-api | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T22:06Z | 2026-02-22T22:25Z | 25K | — | PR #476 merged. 238 lines of mock data removed. | | TW-WDG-002 | not-started | Dashboard → WidgetGrid migration — Replace hardcoded dashboard layout with WidgetGrid, load/save layout via UserLayout API, default layout on first visit | #488 | web | TBD | TW-WDG-001 | TW-WDG-003,TW-WDG-004,TW-WDG-005 | worker | — | — | 40K | — | |
| PG-PAGE-001 | done | Projects list page — Card/table layout, CRUD, wire to /api/projects. Create API client (projects.ts) | #468 | web | feat/projects-page | PG-PLAN-001 | PG-PAGE-002,PG-VER-001 | worker | 2026-02-22T22:06Z | 2026-02-22T22:30Z | 30K | — | PR #477 merged. 809 lines. Create/delete dialogs. | | TW-WDG-003 | not-started | Widget picker UI — Drawer/dialog to browse available widgets from registry, preview size/description, add to dashboard | #488 | web | TBD | TW-WDG-002 | TW-VER-001 | worker | — | — | 25K | — | |
| PG-PAGE-002 | done | Project Workspace page — Single-project view with tasks, agent sessions, settings. Wire to /api/projects/:id, /api/tasks, /api/runner-jobs | #468 | web | feat/workspace-page | PG-PAGE-001 | PG-VER-001 | worker | 2026-02-22T22:31Z | 2026-02-22T22:50Z | 35K | — | PR #479 merged. Tabbed view + runner-jobs client. Issue #468 closed. | | TW-WDG-004 | not-started | Widget configuration UI — Per-widget settings dialog using configSchema, configure data source/filters/colors/title | #488 | web | TBD | TW-WDG-002 | TW-VER-001 | worker | — | — | 30K | — | |
| PG-PAGE-003 | done | Kanban board page — Drag-and-drop columns for TaskStatus (NOT_STARTED, IN_PROGRESS, PAUSED, COMPLETED, ARCHIVED). Wire to /api/tasks | #468 | web | feat/kanban-page | PG-API-001 | PG-VER-001 | worker | 2026-02-22T22:31Z | 2026-02-22T22:50Z | 40K | — | PR #478 merged. @hello-pangea/dnd for DnD. Optimistic updates. | | TW-WDG-005 | not-started | Layout management UI — Save/rename/switch/delete layouts, reset to default. UI controls in dashboard header area | #488 | web | TBD | TW-WDG-002 | TW-VER-001 | worker | — | — | 20K | — | |
| PG-PAGE-004 | done | File Manager page — Tree/list view of knowledge entries with CRUD + search. Wire to /api/knowledge | #468 | web | feat/file-manager | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T22:51Z | 2026-02-22T23:05Z | 30K | — | PR #481 merged. List+grid views, search, create, delete. | | TW-EDT-001 | not-started | Tiptap integration — Install @tiptap/react + extensions, build KnowledgeEditor component with toolbar (headings, bold, italic, lists, code, links, tables) | #489 | web | TBD | TW-PLAN-001 | TW-EDT-002 | worker | — | — | 35K | — | |
| PG-PAGE-005 | done | Logs and Telemetry page — Log viewer with timestamp/level/source/message. Filtering + auto-refresh. Wire to /api/runner-jobs, job steps, events | #468 | web | feat/logs-page | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T22:51Z | 2026-02-22T23:00Z | 30K | — | PR #480 merged. Auto-refresh, expandable rows, filters. | | TW-EDT-002 | not-started | Markdown round-trip + File Manager integration — Import markdown to Tiptap, export to markdown + HTML. Replace textarea in knowledge create/edit | #489 | web | TBD | TW-EDT-001 | TW-VER-001 | worker | — | — | 30K | — | |
| PG-PAGE-006 | done | Profile page — User profile linked from sidebar user card. Wire to /api/users/me/preferences | #468 | web | feat/profile-page | PG-PLAN-001 | PG-VER-001 | worker | 2026-02-22T23:06Z | 2026-02-22T23:20Z | 20K | — | PR #482 merged. User card, preferences, sign out. | | TW-KBN-001 | not-started | Kanban filtering — Add filter bar (project, assignee, priority, search). Support project-level and user-level views. URL param persistence | #490 | web | TBD | TW-PLAN-001 | TW-VER-001 | worker | — | — | 30K | — | |
| PG-VER-001 | done | Cross-page theme + responsive verification — Fix tests, verify all routes in build | #469 | web | feat/theme-verification | PG-FND-001,PG-FND-002,PG-API-001,PG-API-002,PG-API-003,PG-PAGE-001,PG-PAGE-002,PG-PAGE-003,PG-PAGE-004,PG-PAGE-005,PG-PAGE-006 | PG-DOC-001,PG-VER-002 | worker | 2026-02-22T23:21Z | 2026-02-22T23:35Z | 12K | — | PR #483 merged. 3 test failures fixed. All 5125 tests pass. | | TW-VER-001 | not-started | Tests — Unit tests for new components, update existing tests, fix any regressions | #491 | web | TBD | TW-WDG-003,TW-WDG-004,TW-WDG-005,TW-EDT-002,TW-KBN-001 | TW-VER-002,TW-DOC-001 | worker | — | — | 25K | — | |
| PG-DOC-001 | done | Documentation updates — TASKS.md, manifest, scratchpad, PRD status updates | #469 | — | — | PG-VER-001 | PG-VER-002 | orchestrator | 2026-02-22T23:36Z | 2026-02-22T23:45Z | 10K | — | PR #484 merged. PRD FR statuses + scratchpad execution summary. | | TW-VER-002 | not-started | Theme verification — Verify all 5 themes render correctly on all pages, no broken colors/contrast issues | #491 | web | TBD | TW-THM-003,TW-VER-001 | TW-DOC-001 | worker | — | — | 15K | — | |
| PG-VER-002 | done | Deploy to Coolify + smoke test — Deploy to mosaic.woltje.com, verify all pages accessible, auth working, no console errors | #469 | — | — | PG-DOC-001 | | orchestrator | 2026-02-22T23:45Z | 2026-02-23T00:10Z | 15K | — | All 11 routes HTTP 200. 404 renders. Auth OIDC flow verified. CI #585 green. | | TW-DOC-001 | not-started | Documentation updates — TASKS.md, manifest, scratchpad, PRD status updates | #491 | — | — | TW-VER-001,TW-VER-002 | TW-VER-003 | orchestrator | — | — | 10K | — | |
| TW-VER-003 | not-started | Deploy to Coolify + smoke test — Deploy, verify themes/widgets/editor/kanban all functional, auth working, no console errors | #491 | — | — | TW-DOC-001 | | orchestrator | — | — | 15K | — | |
## Summary ## Summary
| Metric | Value | | Metric | Value |
| ------------- | ------------------------------ | | ------------- | ----------------- |
| Total tasks | 15 | | Total tasks | 16 |
| Completed | 15 | | Completed | 0 |
| In Progress | 0 | | In Progress | 1 (PLAN-001) |
| Remaining | 0 | | Remaining | 15 |
| PRs merged | #470-#484 (15 PRs) | | PRs merged | — |
| Issues closed | #466, #467, #468, #469 | | Issues closed | — |
| Milestone | MS16+MS17-PagesDataIntegration | | Milestone | MS18-ThemeWidgets |

83
docs/scratchpads/ms18-theme-widgets-20260223.md Normal file
View File

@@ -0,0 +1,83 @@
# Mission Scratchpad — MS18 Theme & Widget System
> Append-only log. NEVER delete entries. NEVER overwrite sections.
> This is the orchestrator's working memory across sessions.
## Original Mission Prompt
```
Close out MS16+MS17 mission and initialize new mission for MS18 — Theme/Widgets.
User confirmed: all 4 feature areas (themes, widgets, WYSIWYG, Kanban filtering).
WYSIWYG editor library: agent's choice → Tiptap selected.
```
## Planning Decisions
### 2026-02-23 — Scope & Architecture
**Decision: Tiptap for WYSIWYG editor**
- ProseMirror-based, headless (fits our CSS variable design system perfectly)
- Excellent markdown import/export via tiptap-markdown
- Battle-tested, TypeScript-first, largest React ecosystem
- Alternatives considered: Plate (Slate-based, more opinionated UI, smaller community)
**Decision: Theme packages as TypeScript files, not DB**
- Themes defined in `apps/web/src/themes/` as TS files exporting CSS variable maps
- Aligns with PRD's "installable packages from Mosaic Stack repo" concept
- No new Prisma model needed — `UserPreference.theme` (string field) already exists
- Theme files export: name, displayName, description, author, colorPreview, cssVariables
- Built-in themes: Dark (default), Light, Nord, Dracula, Solarized Dark
- ASSUMPTION: Theme packages are code-level packages (TS files), not runtime-installable npm packages. Rationale: keeps the system simple for MS18; runtime package loading can be added later.
**Decision: Dashboard migration to WidgetGrid**
- Current dashboard has hardcoded layout (DashboardMetrics, OrchestratorSessions, QuickActions, ActivityFeed, TokenBudget)
- Will migrate to WidgetGrid with these as default widget placements
- Need to seed WidgetDefinition records for the 7 registered widgets
- Default layout created on first visit if no UserLayout exists
- Existing dashboard components become widget implementations
**Decision: Kanban filtering approach**
- Add filter bar above columns (project, assignee, priority, search)
- User-level view: tasks assigned to current user across all projects
- Project-level view: all tasks in selected project
- Filters stored in URL params for shareability/bookmarkability
**Codebase findings:**
- 7 widgets already registered in WidgetRegistry.tsx
- WidgetGrid.tsx uses react-grid-layout (12-col, 100px row height)
- BaseWidget.tsx provides consistent wrapper with loading/error states
- Backend widget data endpoints exist (stat-card, chart, list, calendar-preview, active-projects, agent-chains)
- UserLayout model ready (workspace+user scoped, JSON layout, metadata)
- Widget definitions NOT seeded in DB — need seed data
- KnowledgeEntry.contentHtml field exists but unused (ready for WYSIWYG)
**Task structure: 17 tasks across 5 phases:**
- Phase 1 (Theme System): Theme architecture + built-in themes + theme UI + ThemeProvider upgrade
- Phase 2 (Widget Dashboard): Widget seeding + dashboard migration + picker UI + config UI + layout management
- Phase 3 (WYSIWYG): Tiptap setup + markdown round-trip + file manager integration
- Phase 4 (Kanban): Filtering + user-level view
- Phase 5 (Verification): Tests + theme verification + deploy
**Estimate:** ~500K tokens total across multiple sessions.
## Session Log
| Session | Date | Milestone | Tasks Done | Outcome |
| ------- | ---------- | --------- | ---------- | -------------------- |
| S1 | 2026-02-23 | MS18 | PLAN-001 | Planning in progress |
## Open Questions
1. **Widget config schema**: How complex should per-widget configuration be? Start simple (title, data source) and extend later.
2. **Theme hot-reload**: Should theme changes apply instantly or require page reload? Targeting instant via CSS variable swap.
3. **Tiptap extensions**: Which extensions to include? Start with: StarterKit, Markdown, Table, CodeBlockLowlight, Link, Image, Placeholder.
## Corrections
(none)