mosaicstack/stack
25
0 Fork 1
Code Issues 403 Pull Requests 13 Packages Projects Releases 15 Wiki Activity

docs: record unified workspace direction and PRD 1.20 draft (#1873)

Browse Source
This commit was merged in pull request #1874.
This commit is contained in:
jason.woltje committed 2026-11-09 11:55:44 -06:00
1 parent 3c2d8631e5
commit 00ef0bd301
3 files changed
+376
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

BUILD-LOG.md
+2
View File
@@ -6337,3 +6337,5 @@ R5 quote fallback room (#797 D3, 2026-11-06, MVP3 lead): r4 review P2 found that
2026-11-07 UTC | Organizations S1 — implementation phase | Before: ui-dev c8d6d12fe used the instance root for one bus and the Console had no scoped lifecycle commands. The S1 stream charter and boundaries are in /mnt/storage/scratch/mosaic-lead/uidev/org-release/PLAN.md. The queue refused this linked worktree; canonical checkout access was excluded. Verification and unresolved integration boundaries follow in the stream report.
2026-11-07 UTC | Organizations S1 — implementation evidence | Organization-root bus and launcher paths, guarded lifecycle and Console launch/stop were implemented locally. Focused Node 26 tests and host regressions passed; the fresh-organization notifier choice, shared-proxy S2 integration, and remaining instance-root consumers are not complete. Exact commands, inventory, failures and boundaries: /mnt/storage/scratch/mosaic-lead/uidev/org-release/report-s1.md. No push or deployment. Gitea issue creation was excluded by the no-network and no-external-communication limits.
2026-11-09 UTC | Unified workspace (#1873) — direction recorded | Before: the 11-07 rulings had one Console switch between organizations from Settings, tasks only in each org queue, and an agent bound to one organization (REQ-USER-1). After: Jason's 11-09 direction and answers recorded in docs/plans/2026-11-09_unified-workspace-owner-direction.md (all orgs visible at once, per-org task stores with a Vikunja option and an aggregated Kanban, root/org/project agents with one cross-org assistant, system type plug-ins, self-service restart and model switch). PRD 1.20 draft 1 written for his exact-text approval; the PRD itself is unchanged. The unpushed 11-07 rulings record (ad8140065) lands with it.
docs/plans/2026-11-09_prd-1-20-draft.md
+136
View File
@@ -0,0 +1,136 @@
# PRD version 1.20, draft 1: unified workspace
- Status: draft, not approved. Jason approves the exact text before it
enters `docs/prd/mosaic-stack.md` as version 1.20.
- Source: `docs/plans/2026-11-09_unified-workspace-owner-direction.md`,
Jason's direction and answers of 2026-11-09.
- Drafted by Mos (lead).
Version 1.20 adds the unified workspace: every organization visible at once,
cross-organization views, three levels of agent configuration, per-org task
stores behind the task tracker kind, system type plug-ins and self-service
operation. It amends REQ-ASSIST-1, REQ-USER-1, REQ-TASK-1 and REQ-WEB-3.
## Amended requirements
Each entry gives the 1.19 text that changes and its 1.20 replacement.
### REQ-ASSIST-1
1.19: "Each user has one assistant role per organization."
1.20: Each user has one assistant across all of the organizations they
belong to. It knows the user's organizations, projects and sessions and
keeps one shared memory. It talks with the user and passes each
organization's work to that organization's chief of staff. It doesn't
direct other agents, create or assign tasks, or launch sessions. (The rest
of REQ-ASSIST-1 stands.)
### REQ-USER-1
1.19: "An agent belongs to one organization and reaches only its allowed
projects and threads."
1.20: Users and role-based access control exist at install and
organization level. An agent other than the assistant works in one
organization at a time. Its memory, files and credentials are scoped to that
organization, even when its definition comes from the user's root
configuration. It reaches only that organization's allowed projects and
threads. The assistant is the exception in REQ-ASSIST-1, and it reaches only
organizations its user belongs to.
### REQ-TASK-1
1.19: "Tasks live in Vikunja..."
1.20: Each organization stores its own tasks, through the task tracker
plug-in kind (REQ-PLUG-1). The default module is a store built into Mosaic
Stack. Vikunja is an optional module, and when an organization selects it
the 1.19 rules for Vikunja (bot tokens per role, one writing role per field,
REQ-TASK-2 polling) apply to that organization. Every task tracker module
supports create, read, update, archive and delete, ordering and grouping.
Archiving or removing an organization removes its tasks without touching
another organization's.
### REQ-WEB-3
1.19: "The Console has controls to restart the bus and to reload the
organization file."
1.20: The Console has controls to restart itself, to restart an
organization's bus, to reload the organization file, and to change the model
an agent instance runs on and apply it. Each control is a gated, trailed
action that a human takes. No agent can take it. A reload applies
`launch.instances` changes to running sessions without a manual
`systemctl restart`. On a dev instance (`--dev-local-owner`) the controls
need no sign-in.
## New requirements
### Workspace
- **REQ-WS-1.** The WebUI shows every organization the user belongs to at
all times. A collapsible Organizations item in the sidebar lists them.
There is no organization switcher.
- **REQ-WS-2.** The Console reads across the buses of the user's
organizations to build shared views. Each organization keeps its own bus
as the tenant boundary (REQ-ORG-1). A shared view shows only
organizations the user belongs to.
- **REQ-WS-3.** The main dashboard sums activity, work and metrics across
all of the user's organizations and projects.
- **REQ-WS-4.** Each organization has a dashboard with its docs, every
configurable setting, its KPIs and metrics, and its active agent
sessions.
- **REQ-WS-5.** The projects list covers every organization. It sorts and
filters by organization, status, name and activity. Each project shows
its owning organization by icon, color and avatar.
- **REQ-WS-6.** One inbox holds every item that needs the user, from every
organization, project and session.
- **REQ-WS-7.** One view shows activity across all organizations and
projects. Organizations and projects can be open side by side.
- **REQ-WS-8.** The tasks view aggregates every organization's tasks, with
Kanban and list layouts, filtered by organization and project. It works
the same for every task tracker module.
### Agent levels
- **REQ-AGENT-1.** Agents are configured at three levels: the user's root,
the organization and the project. A project's available agents are the
union of the three.
- **REQ-AGENT-2.** The user can see and change the configuration of agents,
organizations, projects and sessions, and can override any setting at any
time, through the write path (REQ-ROLE-3).
- **REQ-AGENT-3.** The chief of staff hires and fires agents at the
organization and project levels under REQ-COS-3. Root-level agents change
only by the user.
### System types
- **REQ-SYS-1.** System types are a plug-in kind. Its modules include
coding, creative writing, marketing, Mosaic Montage (the OpenMontage
fork) and business management. An organization enables a list of them.
- **REQ-SYS-2.** A project may use any system type its organization
enables, and none is required. An agent working in a project gets the
toolsets of the system types that project uses.
### Accounts
- **REQ-ACCT-1.** A deployed system requires user sign-in (OIDC, Q203). A
user creates organizations and belongs to any number of them.
- **REQ-ACCT-2.** An organization's owner invites another user into it.
The invited user joins with the grant the owner chose (REQ-USER-3).
### Setup
- **REQ-SETUP-1.** Quick Setup leaves its project with its records
initialized.
- **REQ-SETUP-2.** After Quick Setup, the assistant offers an onboarding
interview. It asks for the project's outcome and limits and drafts the
north star and a first PRD. The user approves each through the existing
approval path.
## Open questions for the approval
1. The final name for the Mosaic Montage module.
2. REQ-AGENT-3 keeps root-level agents user-only. Should the chief of staff
also be able to propose root-level hires for the user to approve?
docs/plans/2026-11-09_unified-workspace-owner-direction.md
+238
View File
@@ -0,0 +1,238 @@
# Unified workspace: owner direction, 2026-11-09
Recorded by Mos (lead) from Jason's T3 message of 2026-11-09, around 17:50Z,
and his answers to four clarifying questions at about 18:00Z. It binds the
next phase of the organizations work. Corrections go in a new dated file, not
edits here.
## What prompted it
Jason ran Quick Setup on the dragon-lin dev instance (uiorg) to create the
`test3` organization. Two things went wrong:
- The new project showed "This project has no records yet" with an
"Initialize project records" button. Quick Setup should have done that.
The setup receipts show the org, checkout, project repository and bus
steps at 17:19:20Z. The records repository first appears at 17:21:13Z,
from the button press. The fix round reproduces it.
- After he pressed the button, the overview showed the north star template
as raw text: `# North star Describe the outcome this project should
achieve...`. The overview prints the markdown source instead of rendering
it.
He also named a standing problem with how the dev instance is operated.
## Owner text, verbatim
> The Quick Setup should auto-initialize since this didn't ask any
> questions. An onboarding interview to determine the north star and PRD
> would be beneficial here.
>
> I've noticed that we have a perennial issue with needing to restart the
> console, or requiring a sign-in (model proxy), and other limiting behaviors
> that don't seem to make sense for the operating method. We are running
> this as a test instance on my dev workstation (dragon-lin), auth is not
> required for this local testing env., and we need to be capable of rapid
> iteration without undue manual intervention by the user. I also don't see
> where we can trigger any type of restart or relaunch with the available
> config from within the webui. The user should be able to change the
> running model and restart the service from within the system.
>
> Here is what I want:
> - Mosaic Stack system runs
> - Allows user to log in
> - User can create orgs, and be invited to join another user's org
> - User belongs to N organizations
> - All orgs are visible in the interface for the user to see the org,
> project, sessions within each
> - Tasks are overarching for all projects; a central store of tasks
> - Agents can be configured at the root, org, and project level
> - The user is able to see all happenings in the system from one pane
> - Projects are sortable and filterable by org, status, name, activity
> - Inbox contains all items needing the user; all orgs/projects/sessions
> with needs surface here
> - System allows for side-by-side operation of orgs and projects all
> visible in single pane
> - Rather than selecting an organization with a switch or in the settings
> menu, the user sees all orgs at all times.
> - Sidebar collapsible item for Organizations; user clicks to see all info
> about the organzation
> - The Docs are available on the org dashboard
> - All configurables are visible on the org dashboard
> - Org dashboard features KPIs/Metrics for the org
> - Active agent sessions visible on the org dashboard
> - Projects sidebar list indicates the organization owning the project via
> iconography, color, and "avatar" for org
> - Main dashboard for user surfaces sum and cumulative data for all
> orgs/projects, not just one
> - The system is configured to use plugins/modules to allow for various
> system types like coding, creative writing, Mosaic Montage (fork of
> OpenMontage) for social media production, business management
> - Each Project within an org is capable of using multiple system types
> - Example: Org. Distinctly Digital
> - enabled plugins: coding, creative writing, marketing, Mosaic
> Montage/Mosaic Studio (whatever we name this...), business management,
> - Each project within "Distinctly Digital" has access to the plugins,
> but is not required to use all of them
> - Agents configured for the user's root config are available
> - Org agents are available
> - Project agents are available
> - Agents use the toolsets for the plugin/module appropriately
> - Configuration for the agents, orgs, projects, sessions are all
> available for the user to tweak as needed
> - Chief of Staff can hire and fire agents to meet the user's system
> needs
> - User can override settings at any time via the configuration
>
> I'm thinking this information needs to be recorded for durability and we
> need to work toward this implementation.
## Answers to the clarifying questions
1. **Task store.** Verbatim: "We need to keep the tasks separated at an org
level. This allows for archive, instant removal of org tasks without
violating the other orgs. I'd like to see a basic config use per-org,
aggregated store with the option to use Vikunja. Not all users will use
Vikunja. Either way, we need a way to store, retrieve, archive, maintain,
organize, and view all the tasks. If we use Vikunja or a custom-rolled
solution within Mosaic Stack, they all need to surface with Kanban, etc.
for the user to see properly."
2. **Agent scope across orgs.** Verbatim: "The user's main interaction agent
needs to be aware of all orgs, projects, etc. That one interaction agent
uses a shared memory. The other agents are isolated per org."
3. **Multi-user.** Design sign-in, membership and invites now. Build them
in the second phase, after the single-user unified pane.
4. **Order.** Remove the operating friction first, then build the unified
pane.
## Rulings that follow
1. **All orgs at once.** The WebUI shows every organization the user
belongs to at all times. A collapsible Organizations item in the sidebar
lists them, and selecting one opens its dashboard. There is no
organization switcher, in Settings or elsewhere.
2. **Per-org isolation stays.** Each organization keeps its own bus as the
tenant boundary (REQ-ORG-1). The Console reads across the buses of the
user's organizations to build the shared views. Removing or archiving an
organization removes its data, tasks included, without touching another.
3. **Tasks.** Each organization stores its own tasks. The default store is
built into Mosaic Stack. Vikunja is an optional alternative, selected per
organization through the task tracker plug-in kind (REQ-PLUG-1). Both
support store, retrieve, archive, maintain and organize. The WebUI
aggregates every organization's tasks into one view with Kanban and list
layouts, filterable by organization and project.
4. **Agents.** Agents are configured at three levels: the user's root,
the organization and the project. A project's agents are the union of
all three. The user's main interaction agent (the assistant) is the one
exception to isolation. It knows all of the user's organizations,
projects and sessions, and it keeps one shared memory. Every other agent
is isolated to the organization it works in: its memory, files and
credentials are scoped to that organization, even when its definition
comes from the root.
5. **One pane.** One screen shows activity across every organization and
project. Organizations and projects can be open side by side.
6. **Main dashboard.** It sums across all organizations and projects, not
only one.
7. **Org dashboard.** It shows the organization's docs, every configurable
setting, KPIs and metrics, and its active agent sessions.
8. **Projects list.** It sorts and filters by organization, status, name
and activity. Each project shows its owning organization by icon, color
and avatar.
9. **Inbox.** One inbox holds everything that needs the user, from every
organization, project and session.
10. **System types are plug-ins.** Coding, creative writing, marketing,
Mosaic Montage (the OpenMontage fork; final name open) and business
management are modules. An organization enables a set of them. Each of
its projects may use any of the enabled set, and none is required.
Agents get the toolsets of the modules their project uses.
11. **Configuration.** The user can see and change the configuration of
agents, organizations, projects and sessions, and can override any
setting at any time. The chief of staff hires and fires agents to meet
the user's needs, within the existing PRD rules (REQ-ROLE, version
1.7).
12. **Accounts.** The deployed system has user sign-in. Users create
organizations, belong to any number of them, and can be invited into
another user's organization. The dev instance keeps running with no
sign-in (ruling 5 of 2026-11-07).
13. **Operating the dev instance.** Routine operation needs no manual
intervention from the user. From the WebUI the user can restart the
Console and an organization's bus, and change the model an agent runs
on. Dev mode needs no sign-in, including for the model proxy. Agents
still cannot restart the Console; the user can, from the WebUI.
14. **Quick Setup.** Quick Setup leaves a project with its records
initialized. An onboarding interview then helps the user write the
north star and a first PRD.
## What this supersedes or amends
- **2026-11-07 ruling 2.** "One Console switches between them from
Settings" is superseded by ruling 1 above. The per-org bus in the same
ruling stands.
- **2026-11-07 ruling 9.** Each organization's queue lived only in its own
checkout. Ruling 3 above keeps tasks per organization, adds the Vikunja
option through the task tracker kind, and adds the aggregated view.
- **PRD 1.19, REQ-USER-1.** "An agent belongs to one organization" gains
the assistant exception in ruling 4. This needs a PRD version. The draft
is `docs/plans/2026-11-09_prd-1-20-draft.md`, and Jason approves the
exact text before it enters `docs/prd/mosaic-stack.md`.
## Delivery plan
Each phase follows the MVP rule: build, one review round, one fix round, an
agent E2E on a scratch instance, then a deploy to uiorg for Jason.
### Phase F: operating friction (now)
- **F1.** Quick Setup records: reproduce the `test3` gap on a scratch
instance and fix it, so a Quick Setup project opens with live Docs, Files
and north star. Render the north star as markdown on the project
overview.
- **F2.** Onboarding interview: after Quick Setup, the assistant opens a
conversation that asks for the outcome and limits, then drafts
`spec/north-star.md` and a first PRD. The user approves each through the
existing approval path.
- **F3.** Self-service operation: restart the Console and an org bus from
the WebUI, change an agent's model from Settings and apply it, and list
and remove every manual step the dev instance still needs, model proxy
sign-in included.
### Phase U: unified pane
- **U0.** Design samples first. Sample screens for the sidebar with all
orgs, the main dashboard, an org dashboard, the projects list, the inbox,
the task Kanban and side-by-side panes. Jason approves them before the
build (design samples are the acceptance target).
- **U1.** Cross-org read model in the Console: one API that reads every
organization's bus the user belongs to, for projects, sessions, inbox
items, tasks and metrics.
- **U2.** Sidebar and org dashboards. **U3.** Main dashboard, projects list
and inbox. **U4.** Task store: built-in per-org store behind the task
tracker kind, the Vikunja module, and the aggregated Kanban. **U5.**
Side-by-side panes.
### Phase A: agent levels
Root, organization and project agent configuration. The assistant spans
organizations with shared memory, and every other agent is isolated per
organization. The user can override settings, and the chief of staff hires
and fires at each level.
### Phase P: system type plug-ins
A plug-in kind for system types. Organizations enable modules, projects opt
in, and agents receive the modules' toolsets. First modules: coding (the
current behavior), creative writing, then Mosaic Montage, marketing and
business management.
### Phase M: accounts (design now, build second)
OIDC sign-in (OIDC-only per Q203), membership in N organizations, invites
into another user's organization, and access checks on the cross-org read
model. The design lands with Phase U so the read model has membership from
the start.
## Open items
- The final name for the Mosaic Montage module.
- Which "sign-in (model proxy)" step Jason hit. F3 inventories every manual
step on the dev instance and reports it.