added agendas studio

This commit is contained in:
2026-03-24 13:42:38 +00:00
parent 11ca697fa4
commit cb786c2663
12 changed files with 684 additions and 0 deletions
@@ -0,0 +1,76 @@
# Studio Shell, Workspace Navigation, and Layout Agenda
## Status
Open
## Purpose
Define the baseline Studio shell:
- main window layout,
- workspace navigation model,
- shell regions and panel hierarchy,
- default landing behavior,
- how future workspaces should fit into the frame.
## Domain Owner
`docs/studio`
## Current Code Context
Current `prometeu-studio` already provides:
- `MainView` as the root shell;
- `WorkspaceBar` as left-side workspace navigation;
- `EditorWorkspace` as the most concrete workspace;
- placeholder workspaces for `Assets` and `Device`;
- a `BuilderWorkspace` implementation artifact with logs and toolbar.
The shell exists, but it is still closer to a scaffold than a documented Studio UX contract.
## Core Questions
1. What is the long-lived shell structure of the Studio?
2. Is left-side workspace switching the correct baseline navigation model?
3. Which shell regions are global and which belong to each workspace?
4. How should the Assets workspace coexist with Editor, Device, and future shipping flows?
5. What should the default landing workspace be?
## Options
### Option A
Keep the current shell mostly intact and grow workspaces within it.
### Option B
Evolve toward a multi-panel shell with global activity and contextual side panels.
### Option C
Adopt a dock-heavy IDE-style shell from the start.
## Tradeoffs
- Option A is fast and consistent with current code, but may constrain richer workflows later.
- Option B preserves the current shell while creating room for Studio-grade interaction design.
- Option C is powerful, but likely too heavy for the current code and service maturity.
## Recommendation
Prefer Option B.
Recommended direction:
- keep workspace switching in the shell,
- formalize a stable frame with navigation, workspace body, and activity/progress region,
- let each workspace own its internal panels,
- avoid a fully dockable IDE model for the first Studio UI wave.
## Expected Follow-up
- a shell decision,
- a Studio shell spec,
- a PR/plan for `MainView`, `WorkspaceBar`, and workspace composition.
@@ -0,0 +1,74 @@
# Asset Workspace Information Architecture Agenda
## Status
Open
## Purpose
Define the baseline information architecture of the Assets workspace.
The goal is to decide which panels and data views the user needs in order to manage assets through Studio services rather than through ad hoc file inspection.
## Domain Owner
`docs/studio`
## Current Code Context
`WorkspaceId.ASSETS` is still backed by a placeholder workspace.
Meanwhile, the packer domain already defines:
- managed assets,
- diagnostics,
- preview/apply mutation flows,
- an asset event lane,
- structured service responses.
The Assets workspace must therefore be designed as a Studio view over those services, not as a file browser clone.
## Core Questions
1. Which panels are baseline for the Assets workspace?
2. What should the primary unit of navigation be: asset list, tree, or diagnostic inbox?
3. Which information should always be visible for the selected asset?
4. How should diagnostics, preload, and managed/orphan state surface in the workspace?
5. What belongs in the workspace body versus a global Studio activity region?
## Options
### Option A
List-first asset workspace with details panel and diagnostics section.
### Option B
File-tree-first asset workspace with asset details as a secondary mode.
### Option C
Dashboard-first asset workspace focused on diagnostics and actions.
## Tradeoffs
- Option A aligns best with the managed asset model already defined by the packer.
- Option B is familiar, but risks collapsing the Studio into a glorified file explorer.
- Option C is useful for operations, but weak as a day-to-day authoring workspace.
## Recommendation
Prefer Option A.
Recommended baseline:
- asset list or registry-aware browser on the left,
- asset details in the main panel,
- diagnostics and action surfaces attached to the selected asset,
- broader activity/progress outside the asset details body when possible.
## Expected Follow-up
- an information architecture decision,
- a workspace spec,
- a PR/plan for the first concrete `AssetsWorkspace`.
@@ -0,0 +1,50 @@
# Asset List, Filters, and Selection Model Agenda
## Status
Open
## Purpose
Define how users navigate and select assets inside the Assets workspace.
## Domain Owner
`docs/studio`
## Current Code Context
The Studio shell already has workspace switching, but no concrete Assets workspace.
The packer model already distinguishes:
- managed assets,
- orphan declarations,
- diagnostics,
- preload intent,
- stable `asset_id` and logical `asset_name`.
The list model should make those distinctions visible without forcing users into raw registry inspection.
## Core Questions
1. Should the main asset view be flat, grouped, or tree-based?
2. Which filters are baseline?
3. How should the current selection be preserved across refreshes and background events?
4. How should empty, loading, and error states appear?
5. How much of the filesystem path should be exposed in the primary list?
## Recommendation
Baseline direction:
- registry-aware flat or grouped asset list,
- lightweight filters for `managed`, `orphan`, `diagnostics`, and `preload`,
- selection preserved by stable identity when possible,
- path treated as supporting information, not primary identity.
## Expected Follow-up
- a decision on the asset list model,
- a UI state spec for selection and filtering,
- a plan for list rendering and refresh behavior.
@@ -0,0 +1,47 @@
# Asset Details, Diagnostics, and Action Surface Agenda
## Status
Open
## Purpose
Define what the selected asset view shows and which actions are directly available there.
## Domain Owner
`docs/studio`
## Current Code Context
The packer service model already expects:
- structured diagnostics,
- preview/apply mutation flows,
- operations such as `register_asset`, `adopt_asset`, `forget_asset`, `remove_asset`, `doctor`, and `build`.
The selected asset view should therefore be designed around explicit state and explicit actions.
## Core Questions
1. What summary information is always visible for the selected asset?
2. Which diagnostics belong inline versus in a separate panel?
3. Which actions should be primary, secondary, or hidden behind confirmation?
4. How should managed and orphan assets differ visually?
5. How should runtime-facing information such as preload and output format appear?
## Recommendation
Baseline direction:
- a summary card for identity and state,
- explicit diagnostics panel,
- explicit action group,
- clear differentiation between safe actions and sensitive mutations,
- no hidden automatic repair behavior.
## Expected Follow-up
- a decision on asset details composition,
- a spec for diagnostics and actions in the workspace,
- a plan for Studio service integration in the asset details view.
@@ -0,0 +1,55 @@
# Background Events, Progress, and Activity Feed Agenda
## Status
Open
## Purpose
Define how Studio surfaces background asset activity, progress, and logs coming from the packer event lane.
## Domain Owner
`docs/studio`
## Current Code Context
The packer already defines a Studio-facing asset event lane with events such as:
- `asset_discovered`
- `asset_changed`
- `diagnostics_updated`
- `build_started`
- `build_finished`
- `cache_hit`
- `cache_miss`
- `preview_ready`
- `action_applied`
- `action_failed`
- `progress_updated`
Current `BuilderWorkspace` already contains a logs area, which is a useful signal but not yet a coherent Studio-wide activity model.
## Core Questions
1. Should activity be global to the Studio shell or local to the Assets workspace?
2. How should progress, logs, and state changes be distinguished?
3. What should persist in history versus only appear transiently?
4. How noisy should automatic background reporting be?
5. How should action failures and blockers surface?
## Recommendation
Baseline direction:
- global activity region in the Studio shell,
- structured event rendering rather than raw log dumping,
- progress visible both inline and in the activity surface,
- recent actionable failures retained until acknowledged,
- normal background noise summarized rather than streamed endlessly.
## Expected Follow-up
- a decision on activity feed and progress UX,
- a shell or integration spec,
- a plan for event rendering and background updates.
@@ -0,0 +1,47 @@
# Preview, Confirm, and Apply Mutation Flows Agenda
## Status
Open
## Purpose
Define how Studio stages sensitive asset mutations before applying them.
## Domain Owner
`docs/studio`
## Current Code Context
The packer model already requires:
- preview/apply for sensitive mutations,
- explicit consent for destructive or relocational changes,
- structured responses with blockers, proposed actions, and applied actions.
The Studio must turn that into clear interaction flows instead of accidental one-click mutations.
## Core Questions
1. Which actions require preview by default?
2. What should a preview surface show before confirmation?
3. How should blockers, warnings, and safe fixes be separated?
4. When does the user see a modal confirmation versus an inline staged action panel?
5. How should batch operations differ from single-asset mutations?
## Recommendation
Baseline direction:
- use preview-first flows for sensitive mutations,
- show proposed actions and blockers explicitly,
- keep safe fixes distinct from destructive actions,
- favor inline staged review where possible,
- reserve modal confirmation for high-risk commits such as delete or relocation.
## Expected Follow-up
- a mutation-flow decision,
- a Studio interaction spec,
- a plan for preview/apply service integration.
+61
View File
@@ -0,0 +1,61 @@
# Studio Agendas
This directory contains active Studio discussion agendas.
## Active Agendas
The initial Studio UI planning wave is:
1. [`01.0. Studio Shell, Workspace Navigation, and Layout Agenda.md`](./01.0.%20Studio%20Shell,%20Workspace%20Navigation,%20and%20Layout%20Agenda.md)
2. [`01.1. Asset Workspace Information Architecture Agenda.md`](./01.1.%20Asset%20Workspace%20Information%20Architecture%20Agenda.md)
3. [`01.2. Asset List, Filters, and Selection Model Agenda.md`](./01.2.%20Asset%20List,%20Filters,%20and%20Selection%20Model%20Agenda.md)
4. [`01.3. Asset Details, Diagnostics, and Action Surface Agenda.md`](./01.3.%20Asset%20Details,%20Diagnostics,%20and%20Action%20Surface%20Agenda.md)
5. [`01.4. Background Events, Progress, and Activity Feed Agenda.md`](./01.4.%20Background%20Events,%20Progress,%20and%20Activity%20Feed%20Agenda.md)
6. [`01.5. Preview, Confirm, and Apply Mutation Flows Agenda.md`](./01.5.%20Preview,%20Confirm,%20and%20Apply%20Mutation%20Flows%20Agenda.md)
Recommended discussion order:
`01.0 -> 01.1 -> 01.2 -> 01.3 -> 01.4 -> 01.5`
That order closes the Studio shell first, then the asset workspace structure, then interaction details and mutation flows.
## Purpose
An agenda exists to drive a decision.
Use an agenda when:
- the Studio UI topic is still open,
- multiple interaction models are possible,
- the team still needs tradeoffs and a recommendation,
- implementation would otherwise guess shell or UX behavior.
## Expected Format
A Studio agenda should usually include:
1. Title
2. Status
3. Purpose
4. Domain Owner
5. Current Code Context
6. Options
7. Tradeoffs
8. Recommendation
9. Open Questions
10. Expected Follow-up
## Writing Rules
- Keep the document centered on unresolved Studio behavior.
- Anchor the discussion in the actual `prometeu-studio` shell and workspaces.
- Distinguish clearly between shell decisions, workspace decisions, and service-integration decisions.
- Prefer concrete interaction tradeoffs over generic design commentary.
## Exit Rule
An agenda should leave the active set when:
- the main UX tradeoffs are understood,
- a recommendation is ready to adopt,
- and the topic is ready to become a decision record.