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

Browse Source 
Planning artifacts for MS18: multi-theme packages, customizable widget
dashboard, WYSIWYG knowledge editor (Tiptap), and Kanban filtering.

- Mission manifest with 15 success criteria
- 16 tasks across 5 phases (theme, widget, editor, kanban, verification)
- Gitea milestone 0.1.2 and issues #487-#491 created
- PRD updated with 3 new assumptions and MS18 status
- Scratchpad with architecture decisions and codebase findings

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
2026-02-23 07:35:38 -06:00
parent 3d78b09064
commit 6218fb31ff
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.
> Updated by the orchestrator at each phase transition and milestone completion.
## Mission
**ID:** prd-implementation-20260222
**Statement:** Implement MS16+MS17 (Pages & Data Integration) — build all remaining pages, wire to real API data, eliminate mock data, deploy to production
**Phase:** Execution
**Current Milestone:** MS16+MS17-PagesDataIntegration
**Progress:** 1 / 1 milestones
**Status:** completed
**Last Updated:** 2026-02-22T23:40Z
**ID:** ms18-theme-widgets-20260223
**Statement:** Implement MS18 (Theme & Widget System) — multi-theme package system, customizable widget dashboard, WYSIWYG knowledge editor, and enhanced Kanban filtering
**Phase:** Planning
**Current Milestone:** MS18-ThemeWidgets
**Progress:** 0 / 1 milestones
**Status:** active
**Last Updated:** 2026-02-23T13:30Z
## Success Criteria
1. All sidebar links navigate to functional pages (no 404s from sidebar navigation)
2. Projects page: list, create, view, edit, delete projects
3. Workspace page: view single project with tasks and agent sessions
4. Kanban page: drag-and-drop board with 5 TaskStatus columns
5. File Manager page: tree/list view with CRUD operations
6. Logs page: log viewer with filtering and auto-refresh
7. Settings root page: category index linking to all subpages
8. Custom 404 page for unknown routes
9. Profile page linked from sidebar user card
10. /tasks, /calendar, /knowledge pages use real API data (no mock)
11. All new pages support light/dark theme
12. All new pages are responsive (sm/md/lg/xl breakpoints)
13. Lint, typecheck, and tests pass
14. Deployed and smoke-tested at mosaic.woltje.com
1. Theme system supports 5+ themes (dark, light, + 3 additional built-in)
2. Themes are defined as TypeScript packages with CSS variable overrides
3. Theme selection UI in Settings with live preview swatches
4. UserPreference.theme persists selected theme across sessions
5. Dashboard uses customizable WidgetGrid (drag, resize, add, remove widgets)
6. Widget picker UI allows browsing and adding widgets from registry
7. Per-widget configuration dialog (data source, filters, colors)
8. Layout save/load/rename via UserLayout API
9. WYSIWYG editor (Tiptap) for knowledge entries with toolbar
10. Markdown ↔ rich text round-trip (import/export)
11. Kanban board supports project-level and user-level filtering
12. Kanban filter bar: project, assignee, priority, search
13. All features support all themes (dark/light + new themes)
14. Lint, typecheck, and tests pass
15. Deployed and smoke-tested at mosaic.woltje.com
## Milestones
| # | 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 |
| # | ID | Name | Status | Branch | Issue | Started | Completed |
| --- | ---- | --------------------- | ----------- | ------------------------- | ------------------------ | ------- | --------- |
| 1 | MS18 | Theme & Widget System | not-started | per-task feature branches | #487,#488,#489,#490,#491 | — | — |
## Deployment
@@ -46,18 +47,16 @@
| Metric | Value |
| ------ | ----------------- |
| Budget | ~320K (estimated) |
| Budget | ~500K (estimated) |
| Used | 0 |
| Mode | normal |
## Session History
| 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) |
| 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 |
| Session | Runtime | Started | Duration | Ended Reason | Last Task |
| ------- | --------------- | ----------------- | -------- | ------------ | ------------------- |
| S1 | Claude Opus 4.6 | 2026-02-23T13:30Z | — | — | Planning (PLAN-001) |
## 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 |
| 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 |
| 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 |
| 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 |
@@ -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.
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.
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.
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| 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. |
| id | status | description | issue | repo | branch | depends_on | blocks | agent | started_at | completed_at | estimate | used | notes |
| ----------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ---- | ------ | ------------------------------------------------------ | ------------------------------------------- | ------------ | ---------- | ------------ | -------- | ---- | ----- |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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 | — | |
| 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
| Metric | Value |
| ------------- | ------------------------------ |
| Total tasks | 15 |
| Completed | 15 |
| In Progress | 0 |
| Remaining | 0 |
| PRs merged | #470-#484 (15 PRs) |
| Issues closed | #466, #467, #468, #469 |
| Milestone | MS16+MS17-PagesDataIntegration |
| Metric | Value |
| ------------- | ----------------- |
| Total tasks | 16 |
| Completed | 0 |
| In Progress | 1 (PLAN-001) |
| Remaining | 15 |
| PRs merged | — |
| Issues closed | — |
| 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)