feat: Slice 1 polish - MiMo V2.5 model, visible reasoning, image attachments, mobile keyboard fix
- Switch conversation agent to xiaomi/mimo-v2.5 (multimodal: text + image) - Render native reasoning parts as live 'Thinking trace' (streaming open, collapsed after completion); inline <think> extraction for streaming models - Image attachments: picker (up to 4, 10MB each), base64 to Flue AgentPromptImage, authenticated blob-URL replay for historical images - Mobile keyboard viewport fix: visual-viewport hook, fixed shell, interactive-widget=resizes-content, header pinned, composer follows keyboard - Conversation to Signal to proposed Work: Convex persistence, Effect validation in @code/work-os, Work cards with exact source provenance - Streamdown markdown + Mermaid chart rendering in chat messages - Flue tool turns hidden, reasoning-containing turns remain visible - Frontend regression tests: keyboard viewport, responsive shell, attachment overflow, authenticated images, reasoning traces, transforms - .env.example updated to xiaomi/mimo-v2.5 config
This commit is contained in:
-Puter
650
docs/DESIGN.md
650
docs/DESIGN.md
@@ -1,367 +1,469 @@
|
||||
# Zopu Work OS — Product Design
|
||||
|
||||
> **Status:** canonical working interaction/interface specification · **Audience:** product design, frontend/product engineering, agent experience · **Scope:** information architecture, screens, cards, interaction patterns, states, actions, principles · **Excludes:** backend and low-level infrastructure
|
||||
> **Related:** `product.md` defines the domain; `dev-loop.md` defines phases/gates; `slices.md` defines UI rollout.
|
||||
|
||||
## 1. Objective and governing model
|
||||
> **Status:** Working interaction specification
|
||||
> **Audience:** frontend, product, agents generating UI
|
||||
> **Constraint:** simple interface; complexity is revealed only when useful.
|
||||
|
||||
Design one calm, persistent workspace for supervising many active work units across organizations, products, projects, teams, and contexts—without making users manage chat threads, model settings, or agent sessions. It must make an autonomous system understandable and controllable by showing the minimum needed to answer: **what matters; what is happening; what is blocked; what needs human action; what happens next; why the system believes it.**
|
||||
## 1. Experience principle
|
||||
|
||||
> **The conversation is the command surface; the work unit is the persistent product object.**
|
||||
|
||||
## 2. Experience principles
|
||||
|
||||
| Principle | Requirement |
|
||||
| --- | --- |
|
||||
| One continuous workspace | Do not organize around chat history, sessions, or thread lists. Keep one workspace and a composer that works globally or within a selected unit. |
|
||||
| Work first, machinery second | Show outcomes, blockers, decisions, artifacts, results. Hide agent names, model choices, runtime and infrastructure unless they explain progress/debug failure. |
|
||||
| Progressive disclosure | Collapsed cards scan quickly; expanded cards become working surfaces; evidence/raw events/technical detail are on demand. |
|
||||
| Calm density | Support dense operational information without an enterprise-dashboard feel; use hierarchy, spacing, typography, grouping—not excessive borders, color, or permanent panels. |
|
||||
| Human attention is scarce | Centralize approvals, blockers, unanswered questions, and other requests; users must not hunt through cards. |
|
||||
| Visible context | Always show organization; project/portfolio scope; global vs work-specific composer; selected unit; whether an action affects external/production systems. |
|
||||
| Nearby provenance | Important claims, decisions, and recommendations expose source indicators; evidence is one interaction away, not buried in an audit app. |
|
||||
|
||||
## 3. Product language
|
||||
|
||||
| Term | Meaning |
|
||||
| --- | --- |
|
||||
| **Organization** | Company, client, or hard context boundary. |
|
||||
| **Project** | Product, application, repository-backed system, or durable operating context. |
|
||||
| **Goal** | Measurable business/product objective. |
|
||||
| **Signal** | New information that may matter. |
|
||||
| **Candidate** | Proposed work unit awaiting confirmation. |
|
||||
| **Work unit** | Persistent outcome the system is responsible for progressing. |
|
||||
| **Run** | One execution attempt inside a work unit. |
|
||||
| **Artifact** | Produced/collected output: PR, preview, report, design, document, etc. |
|
||||
| **Attention item** | Decision, approval, question, blocker, review, or risk requiring human action. |
|
||||
|
||||
Do not expose **agent thread, model context window, harness session, VM, sandbox lifecycle, actor wake state** except in technical/debug views.
|
||||
|
||||
## 4. Global information architecture
|
||||
|
||||
Desktop uses three regions plus a persistent composer:
|
||||
The user should experience:
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Header │
|
||||
├───────────────┬───────────────────────────────────┬─────────────────┤
|
||||
│ Work index │ Primary workspace │ Context panel │
|
||||
│ │ cards / expanded work / chat │ evidence, │
|
||||
│ │ │ artifacts, │
|
||||
│ │ │ preview, tools │
|
||||
├───────────────┴───────────────────────────────────┴─────────────────┤
|
||||
│ Persistent composer │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
Talk naturally
|
||||
→ see durable Work emerge
|
||||
→ approve what matters
|
||||
→ watch meaningful progress
|
||||
→ answer precise questions
|
||||
→ inspect evidence
|
||||
→ receive a reviewable result
|
||||
```
|
||||
|
||||
The layout collapses gracefully on smaller screens.
|
||||
The UI MUST optimize **confidence per minute of human attention**, not display every agent action.
|
||||
|
||||
### Header
|
||||
|
||||
Global orientation/light controls: current organization switcher; current project or portfolio scope; search/command trigger; attention count; activity indicator; user menu. Do **not** fill it with model controls, agent selectors, or environment settings.
|
||||
|
||||
### Left work index
|
||||
|
||||
This is operational navigation, not chat history: **Now, Attention, Discovery, Active work, Waiting, Review, Monitoring, Recently completed, Goals, Projects, Knowledge, Activity**. Show compact counts/status indicators. A project section may show name, health, active-unit count, attention count, current goal/release.
|
||||
|
||||
### Primary workspace
|
||||
|
||||
Show portfolio/project overview, project overview, work-card feed, expanded work unit, global conversation moments, candidate review, attention workflow, results/learning.
|
||||
|
||||
### Context panel
|
||||
|
||||
Change with the selected object; show only when relevant (otherwise hide/collapse). Possible content: evidence, sources, files, PR, code changes, preview, test results, research, agent activity, decisions, dependencies, analytics, customer feedback, version history.
|
||||
|
||||
### Persistent composer
|
||||
|
||||
Available everywhere; scope is visibly lightweight:
|
||||
## 2. Information architecture
|
||||
|
||||
```text
|
||||
Global workspace
|
||||
Working in: Fix Safari OAuth callback failures
|
||||
Project
|
||||
├── Conversation
|
||||
├── Work cards
|
||||
├── Attention
|
||||
├── Artifacts/search
|
||||
└── Project knowledge/settings
|
||||
```
|
||||
|
||||
Accept text, files, images, voice, links, source/work-unit/project mentions, and natural-language commands. Users never select a model, agent, or thinking mode.
|
||||
v0 may render Conversation and Work in one workspace with a side/detail panel.
|
||||
|
||||
## 5. Primary screens
|
||||
## 3. Project conversation
|
||||
|
||||
### 5.1 Command Center (default)
|
||||
One continuous project conversation, not session/thread-centric navigation.
|
||||
|
||||
An operational briefing—not a wall of metrics—answering portfolio-level orientation, autonomous progress, meaningful changes, and required actions:
|
||||
Message types:
|
||||
|
||||
- **Today:** highest-value active work; upcoming deadlines; work likely to block; recently unblocked work.
|
||||
- **Needs attention:** approvals, decisions, questions, reviews, risks.
|
||||
- **Autonomous progress:** work advanced since last visit; new artifacts; completed verification; follow-up candidates.
|
||||
- **Project health:** current goal, active count, blocker count, recent result, risk/health signal per relevant project.
|
||||
- **Recent outcomes:** completed work, measured effects, captured learnings.
|
||||
- user;
|
||||
- Zopu response;
|
||||
- Signal notice;
|
||||
- Work created/updated;
|
||||
- human decision;
|
||||
- important artifact/result.
|
||||
|
||||
### 5.2 Discovery Inbox
|
||||
Conversation actions:
|
||||
|
||||
Separate raw information from proposed interpretation. Views: new signals; candidate work; possible duplicates; suggested links to existing work; low-confidence observations. Actions: **Accept, Edit, Attach to existing work, Merge, Defer, Dismiss, Save as knowledge, Ask why**. Batch obvious duplicates/low-value signals when useful; important candidate creation remains inspectable.
|
||||
- send message;
|
||||
- attach context;
|
||||
- reference Work;
|
||||
- create/modify priority;
|
||||
- answer a question;
|
||||
- ask for status/explanation.
|
||||
|
||||
### 5.3 Project Overview
|
||||
When a message creates Work, render a compact inline link/card. Preserve a link from Work back to exact source message.
|
||||
|
||||
One product/application context: project identity/health; current goals; active work; waiting/blocked work; recent releases/outcomes; connected sources; important context documents; team/responsibility; autonomous activity. It answers: what is the project trying to achieve, what is moving/blocked, what changed, and what requires the user?
|
||||
## 4. Work card
|
||||
|
||||
### 5.4 Work Unit Workspace
|
||||
### Collapsed
|
||||
|
||||
Expanded selected card; structure:
|
||||
|
||||
| Section | Contents |
|
||||
| --- | --- |
|
||||
| Work header | Outcome title; organization/project; type; phase; status; priority; owner/responsible party; last meaningful change; autonomy state. |
|
||||
| Objective | Desired outcome; why now; linked goal; success criteria; scope/non-goals. |
|
||||
| Current understanding | Concise generated summary split into **Known, Inferred, Uncertain, Conflicting**. |
|
||||
| Plan | Current approach; steps; completed actions; next action; alternative path when relevant. |
|
||||
| Blockers/dependencies | For each: what is blocked, why, who/what resolves it, impact of waiting, requested human action. |
|
||||
| Activity | Compressed chronology of user instructions, system/agent progress, state changes, decisions, artifacts, external actions, verification. |
|
||||
| Artifacts | Previews/links for PRs, commits, documents, screenshots, previews, test reports, designs, research. |
|
||||
| Results | After publication/completion: expected and actual result, measurement window, evidence, unexpected effects, follow-up recommendation. |
|
||||
| Contextual composer | Fixed at bottom and clearly scoped to this unit. |
|
||||
|
||||
### 5.5 Attention Queue
|
||||
|
||||
Central human-in-the-loop surface; categories: **Decisions, Approvals, Questions, Blockers, Reviews, Access requests, Risk alerts**. Every item answers what/why is needed; recommendation and supporting evidence; what follows approval; consequence of no action; urgency; reversibility. Enable quick review without opening the full workspace unless deeper context is needed.
|
||||
|
||||
### 5.6 Activity Stream
|
||||
|
||||
Show meaningful autonomous events: work discovered/updated; run started; plan prepared; code changed; verification completed; artifact created; blocker detected; approval requested; work completed; result measured. Do not fill it with every tool call; events can expand for technical detail/provenance.
|
||||
|
||||
### 5.7 Results and Learning
|
||||
|
||||
A feedback system, not an archive. Views: recently completed; monitoring; successful outcomes; unexpected regressions; follow-up opportunities; reusable learnings. Each result links to original objective and evidence.
|
||||
|
||||
### 5.8 Knowledge
|
||||
|
||||
Expose durable organization/project understanding across **Product, Business, Customers, Design, Technical context, Decisions, Known constraints, Reusable learnings**. Mark each item **Canonical, Inferred, Pending review, Outdated, or Conflicting**.
|
||||
|
||||
## 6. Card system
|
||||
|
||||
A card is a visual projection of a durable product object. The same work unit may appear as a compact/expanded card, attention item, embedded conversation object, timeline event, or result card; never create separate task systems per surface.
|
||||
|
||||
| Type | Purpose and collapsed anatomy | Actions |
|
||||
| --- | --- | --- |
|
||||
| **Signal** | Newly detected information: source icon/name; observation; project/organization; time; suggested relationship; confidence. | Create work; attach to existing work; save as knowledge; dismiss. |
|
||||
| **Candidate** | Proposed durable unit: proposed outcome; why it matters; project; linked goal; supporting-source count; confidence; duplicate warning when relevant. | Accept; edit; merge; defer; dismiss; ask why. |
|
||||
| **Active work** | Operational state. Must answer what it is, why it matters, current state, blocker, and next step. Anatomy below. | Use status-appropriate actions. |
|
||||
| **Waiting/blocked** | Visually distinct without alarmism: exact blocker; responsible party; time waiting; impact; next resolution action. | Review/resolve requested action. |
|
||||
| **Approval** | Safe bounded decision: exact action; why; recommendation; alternatives; risk; impact; evidence; reversibility. | Approve; modify; reject; ask for more evidence; delegate. |
|
||||
| **Review** | Evaluate artifact/completed run: what changed; acceptance criteria; verification summary; open concerns; preview/diff access; recommended decision. | Accept; request changes; continue discussion; compare alternative; stop work. |
|
||||
| **Result** | Connect completed work to outcome: intended outcome; shipped work; expected impact; actual result; measurement period; unexpected effects; follow-up. | Accept result; continue monitoring; create follow-up; reopen; roll back where applicable. |
|
||||
| **Parent initiative** | Larger outcome composed of child units: initiative outcome; child progress; critical path; blockers; next milestone; active/completed child counts. Do not duplicate every child detail. | Use child/initiative actions as applicable. |
|
||||
|
||||
### Card examples/anatomy
|
||||
Display only decision-relevant information:
|
||||
|
||||
```text
|
||||
Support · Acme Corp · 18m ago
|
||||
Three users could not finish OAuth setup in Safari.
|
||||
Possible match: Fix Safari callback failures · Confidence: High
|
||||
[Attach] [Create separate work] [Dismiss]
|
||||
Title
|
||||
phase/status
|
||||
latest meaningful update
|
||||
blocker/question
|
||||
next action
|
||||
slice progress
|
||||
artifact count
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```text
|
||||
[Type] [Organization / Project] [Status]
|
||||
Fix Safari OAuth callback failures
|
||||
Supports: Improve onboarding reliability · 42% complete
|
||||
Blocked: Need production Safari logs
|
||||
Latest: Agent reproduced the issue · 18m ago
|
||||
Next: Approve temporary logging deployment
|
||||
3 artifacts · 5 sources · 2 runs
|
||||
Add build-aware health endpoint
|
||||
Verifying slice 2 of 3
|
||||
HTTP behavior passed; design check pending
|
||||
Next: complete verifier review
|
||||
2 signals · 4 artifacts
|
||||
```
|
||||
|
||||
Avoid raw tokens, wakeups, grep calls, and internal actor noise.
|
||||
|
||||
### Expanded
|
||||
|
||||
Use six sections:
|
||||
|
||||
```text
|
||||
Waiting · Approval required
|
||||
Fix Safari OAuth callback failures
|
||||
Need: Approve 30-minute diagnostic logging
|
||||
Impact: Investigation cannot continue without production evidence
|
||||
[Review request]
|
||||
1. Outcome
|
||||
2. Design
|
||||
3. Build
|
||||
4. Evidence
|
||||
5. Delivery
|
||||
6. Result
|
||||
```
|
||||
|
||||
#### Outcome
|
||||
|
||||
- objective/user impact;
|
||||
- source Signals;
|
||||
- scope/non-goals;
|
||||
- acceptance criteria;
|
||||
- risk;
|
||||
- assumptions/questions;
|
||||
- definition approval.
|
||||
|
||||
#### Design
|
||||
|
||||
- impact map;
|
||||
- architecture/sequence;
|
||||
- file-tree delta;
|
||||
- call-flow delta;
|
||||
- key interfaces/invariants;
|
||||
- vertical slices;
|
||||
- design approval/revisions.
|
||||
|
||||
#### Build
|
||||
|
||||
- slice graph/progress;
|
||||
- current attempt;
|
||||
- meaningful activity;
|
||||
- questions/decisions;
|
||||
- retry/replan history;
|
||||
- contextual composer.
|
||||
|
||||
#### Evidence
|
||||
|
||||
- verification checklist;
|
||||
- command/test results;
|
||||
- browser/API results;
|
||||
- screenshots/video;
|
||||
- design-conformance report;
|
||||
- maintainability/security evidence;
|
||||
- exact candidate SHA/environment.
|
||||
|
||||
#### Delivery
|
||||
|
||||
- commit/branch/PR;
|
||||
- review package;
|
||||
- preview/staging;
|
||||
- merge/release approvals;
|
||||
- rollout/rollback state.
|
||||
|
||||
#### Result
|
||||
|
||||
- expected vs actual outcome;
|
||||
- post-release health;
|
||||
- final classification;
|
||||
- follow-up Signals;
|
||||
- learning proposals.
|
||||
|
||||
## 5. Phase language
|
||||
|
||||
Use user-meaningful phases:
|
||||
|
||||
```text
|
||||
Approval required — Merge PR #184
|
||||
Why: All automated verification passed; no blocking review issues remain.
|
||||
Impact: Changes OAuth callback validation; no database migration.
|
||||
Evidence: 14 unit tests; 6 browser tests; preview reviewed; automated code review attached.
|
||||
[Review changes] [Request changes] [Merge]
|
||||
Defining outcome
|
||||
Awaiting definition approval
|
||||
Designing
|
||||
Awaiting design approval
|
||||
Ready
|
||||
Building slice N of M
|
||||
Verifying slice N
|
||||
Slice review required
|
||||
Integrating
|
||||
Ready for merge
|
||||
Releasing
|
||||
Observing result
|
||||
Completed
|
||||
Blocked
|
||||
Needs input
|
||||
Failed
|
||||
Cancelled
|
||||
```
|
||||
|
||||
## 7. Card expansion
|
||||
Do not expose internal state-machine names unless in diagnostics.
|
||||
|
||||
Selecting a work card expands it in place in the primary workspace. On desktop, only one primary card is expanded; surrounding feed remains visible where practical; right panel follows selected section/artifact; composer scope becomes that unit; collapse retains card position; deep links open directly to a unit. Expansion must feel like entering a workspace, not a disconnected detail page. Mobile may use a full-screen sheet/route while preserving the model.
|
||||
## 6. Attention objects
|
||||
|
||||
## 8. Global/contextual chat
|
||||
|
||||
**Global mode** coordinates work across active organization/portfolio and may embed work cards/attention items. Example prompts: “What needs my attention today?”; “Create work for the repeated OAuth complaints.”; “Compare onboarding issues across my projects.”; “What is blocked for the release?”; “Move the pricing experiment behind the reliability work.”; “Summarize what progressed overnight.”
|
||||
|
||||
**Context mode** focuses one work unit: “Add Safari 17 to the acceptance criteria.”; “Explain the current hypothesis.”; “Show me the failing test.”; “Try a solution without changing the data model.”; “Prepare a smaller pull request.”; “Ask the customer for the missing information.” Header shows scope and easy return to global.
|
||||
|
||||
When work is described, the system may update an existing unit, create a candidate, create accepted work when intent is explicit and policy permits, ask a clarifying question, or save knowledge. Briefly state the outcome:
|
||||
A question/approval is a structured card:
|
||||
|
||||
```text
|
||||
Created candidate work: Improve OAuth diagnostics
|
||||
Linked to: Restore OAuth reliability · Sources attached: 3
|
||||
Decision title
|
||||
exact question
|
||||
why it matters
|
||||
recommendation
|
||||
alternatives
|
||||
consequences
|
||||
affected Work/slice
|
||||
primary action
|
||||
reply action
|
||||
```
|
||||
|
||||
Mentions insert structured references (without copying IDs/links) to a work unit, project, goal, artifact, source, or person.
|
||||
|
||||
## 9. Status design
|
||||
|
||||
Use these user-facing statuses and explicit primary actions:
|
||||
|
||||
| Status | Meaning | Primary actions |
|
||||
| --- | --- | --- |
|
||||
| **Proposed** | Suggested, not started. | Accept; edit; merge; dismiss. |
|
||||
| **Clarifying** | Outcome/requirements incomplete. | Answer question; add context; accept assumption. |
|
||||
| **Ready** | Defined enough to begin. | Start; review plan; change priority. |
|
||||
| **Active** | Progressing. | Inspect; steer; pause; add context. |
|
||||
| **Waiting** | Depends on person, dependency, approval, or external event. | Resolve blocker; grant access; make decision; continue waiting. |
|
||||
| **Review** | Artifact/result needs evaluation. | Approve; request changes; continue discussion. |
|
||||
| **Monitoring** | Shipped; outcome is being watched. | Inspect result; extend monitoring; create follow-up; roll back. |
|
||||
| **Done** | Completed or intentionally stopped. | View result; reopen; create follow-up; archive. |
|
||||
|
||||
Modifiers: **Blocked, Approval required, Waiting on user, Waiting on dependency, Running autonomously, Scheduled, At risk**. Always pair color with text and iconography.
|
||||
|
||||
## 10. Activity language
|
||||
|
||||
Activity is meaningful product language, not raw agent noise.
|
||||
|
||||
- **Prefer:** Investigated authentication flow; identified likely state-validation bug; added regression tests; verification passed; PR created; waiting for merge approval.
|
||||
- **Hide from primary UI (technical drawer only):** called grep; ran shell command; read 34 files; model generated 2,600 tokens; actor woke.
|
||||
|
||||
Group related events into sessions:
|
||||
Example:
|
||||
|
||||
```text
|
||||
Implementation run · 24 minutes
|
||||
• Inspected callback handler • Added state validation
|
||||
• Added regression tests • 14 tests passed
|
||||
• Created PR #184
|
||||
Should /health be public?
|
||||
|
||||
Recommendation
|
||||
Expose basic status publicly; protect detailed diagnostics.
|
||||
|
||||
Why
|
||||
Public uptime checks need access, but build metadata may reveal deployment data.
|
||||
|
||||
[Use recommendation] [Reply]
|
||||
```
|
||||
|
||||
## 11. Provenance
|
||||
Answering MUST resume the same Work. Never create a disconnected chat thread.
|
||||
|
||||
Four progressively disclosed levels:
|
||||
Attention inbox ordering:
|
||||
|
||||
1. **Source chips (on cards):** Git, Support, Analytics, Conversation, System inference, Human decision.
|
||||
2. **Evidence panel:** sources supporting current understanding/recommendation.
|
||||
3. **Raw source:** original message, issue, log, file, or event.
|
||||
4. **Derivation detail (high-impact claims):** conclusion; evidence; assumptions; confidence; conflicting evidence; last updated; producing agent/process.
|
||||
1. production/security blockers;
|
||||
2. decisions blocking active Work;
|
||||
3. review/approval requests;
|
||||
4. informational updates.
|
||||
|
||||
Labels: **Verified, Reported, Inferred, Assumed, Conflicting, Outdated**. Do not force derivation detail during normal operation.
|
||||
## 7. Definition and design review
|
||||
|
||||
## 12. Organization/project/portfolio scope
|
||||
Use diffable structured documents, not long prose blobs.
|
||||
|
||||
Users may manage several organizations/projects. The active organization is always visible; switching organization changes the full scope; never blend private context across organizations. Portfolio views may aggregate counts/summaries only with explicit labels. Composer indicates portfolio, organization, project, or work-unit scope.
|
||||
### Work Definition editor
|
||||
|
||||
Editable fields:
|
||||
|
||||
- problem;
|
||||
- outcome;
|
||||
- scope/non-goals;
|
||||
- acceptance criteria;
|
||||
- assumptions;
|
||||
- questions;
|
||||
- risk.
|
||||
|
||||
Actions:
|
||||
|
||||
```text
|
||||
Portfolio
|
||||
├── Company A
|
||||
│ ├── Product Alpha
|
||||
│ └── Internal Platform
|
||||
└── Client B
|
||||
└── Customer Portal
|
||||
Approve | Request revision | Edit directly
|
||||
```
|
||||
|
||||
Do not require deep-tree navigation for every action: provide search, recent projects, and scope-aware commands.
|
||||
### Design Packet review
|
||||
|
||||
## 13. Project onboarding
|
||||
Show:
|
||||
|
||||
Onboarding prepares a capable working environment, not a long settings form.
|
||||
- one architecture diagram;
|
||||
- expected file-tree changes;
|
||||
- expected call flow;
|
||||
- key types/contracts;
|
||||
- slices;
|
||||
- risks/trade-offs.
|
||||
|
||||
- **Entry:** start from template; connect existing repository; import repository; create empty project.
|
||||
- **Initial templates:** React, Hono, Express, full-stack web application, API service, Expo application, monorepo. Each card states inclusions, fit, expected setup time, and included verification.
|
||||
- **Context setup:** concise sections for Product, Business, Design, Technical conventions, Agent instructions. System may draft from repository/conversation; user reviews/confirms. Allow progressive completion; clearly mark missing context; do not require complete documents before starting.
|
||||
- **Readiness:** Repository ready; Dependencies prepared; Context confirmed; Verification passed; Preview available; Agent ready. Describe infrastructure in plain operational language, not raw logs.
|
||||
Highlight changes between versions. Approval records actor/user, version, timestamp, and optional comment.
|
||||
|
||||
## 14. Artifacts
|
||||
## 8. Slice presentation
|
||||
|
||||
Artifacts are first-class in the work unit. Present as PR summary, code diff, preview frame, test report, screenshot gallery, research document, design proposal, generated file, or release note. Each shows **name, type, producer, time, related run, verification state, review state, source/destination**. Open in the right panel or focused viewer without breaking work-unit context.
|
||||
|
||||
## 15. Human actions
|
||||
|
||||
Use explicit actions, never vague “continue”: **Approve plan; answer question; grant temporary access; review preview; review changes; request revision; approve branch push; approve PR; approve merge; approve deployment; send message; pause autonomous work; cancel run; reopen work.** Every sensitive action shows scope and consequence:
|
||||
Each slice shows:
|
||||
|
||||
```text
|
||||
Deploy preview
|
||||
Project: Zopu Web · Branch: work/W-103/team-invitations
|
||||
Environment: Temporary preview · External impact: None
|
||||
Expected duration: 20 minutes
|
||||
[Deploy preview]
|
||||
objective
|
||||
observable behavior
|
||||
planned code changes
|
||||
required checks
|
||||
dependencies
|
||||
status
|
||||
attempt count
|
||||
artifacts
|
||||
review requirement
|
||||
```
|
||||
|
||||
## 16. Autonomy controls
|
||||
A timeline is useful, but the primary representation is a dependency-aware list.
|
||||
|
||||
Do not expose a complex agent-control panel by default. States: **Manual; Ask before actions; Autonomous within policy; Paused**. Project/organization policy can set defaults. Example unit indicators:
|
||||
Slice statuses:
|
||||
|
||||
```text
|
||||
Autonomous within policy · No action required
|
||||
Paused after repeated verification failure · Review required
|
||||
Pending | Ready | Running | Verifying | Review | Passed | Failed | Blocked
|
||||
```
|
||||
|
||||
Advanced settings may expose policy detail; everyday use stays simple.
|
||||
## 9. Activity design
|
||||
|
||||
## 17. Empty, loading, failure, conflict
|
||||
Normalize events into concise statements:
|
||||
|
||||
| State | Required behavior |
|
||||
| --- | --- |
|
||||
| Empty workspace | Never show a blank dashboard; offer Create project, Connect repository, Describe what you are working on, Import existing issues, Start from a template. |
|
||||
| No active work | Show recent outcomes and suggested candidates; never invent busywork. |
|
||||
| Run provisioning | Use “Preparing workspace”, “Loading project context”, “Starting implementation”; expose infrastructure terms only when delayed/failed. |
|
||||
| Failure | Explain what failed; preserved work; retry safety; recommendation; whether human action is required. Example: “Verification failed. The implementation is saved, but 2 browser tests are failing. The system recommends another repair attempt.” Actions: Review failures / Retry repair / Stop work. |
|
||||
| Conflicting evidence | Show conflict, never silently choose: “Support reports OAuth failures increased; Analytics currently shows no significant change.” Actions: Inspect sources / Continue monitoring / Start investigation. |
|
||||
Good:
|
||||
|
||||
## 18. Responsive behavior
|
||||
```text
|
||||
Implemented build metadata provider
|
||||
Focused tests passed
|
||||
Verifier found response schema mismatch
|
||||
Repair attempt started with failure evidence
|
||||
```
|
||||
|
||||
| View | Layout/behavior |
|
||||
| --- | --- |
|
||||
| Desktop | Three columns; one expanded unit; right contextual panel; persistent bottom composer. |
|
||||
| Tablet | Collapsible left index; primary workspace; right panel as overlay or resizable drawer. |
|
||||
| Mobile | Bottom navigation **Now, Attention, Work, Projects**; vertical card feed; expanded work full-screen route/sheet; composer fixed above navigation; context content in tabs/sheets. Prioritize supervision, review, approval over full code inspection. |
|
||||
Bad:
|
||||
|
||||
## 19. Visual language
|
||||
```text
|
||||
Tool call: bash
|
||||
Read 42 files
|
||||
Generated 7,932 tokens
|
||||
Actor wake event
|
||||
```
|
||||
|
||||
Direction: **calm, precise, premium, spacious, highly legible, modern without looking experimental**. Use warm white or restrained dark backgrounds; soft neutral surfaces; thin separators; large rounded corners; subtle depth; strong type hierarchy; restrained accent; selective pastel category/phase states; smooth expansion/scope transitions.
|
||||
Provide an expandable diagnostics/log panel for experts.
|
||||
|
||||
Avoid dense enterprise dashboards; excessive gradients; permanent borders around every item; bright status colors everywhere; model/agent-control clutter; chat bubbles dominating; Kanban as default mental model; gamification. It should feel like a focused operating environment, not AI widgets.
|
||||
## 10. Verification UX
|
||||
|
||||
## 20. Motion
|
||||
Checklist rows contain:
|
||||
|
||||
Motion reinforces state/continuity: card→workspace expansion; composer-scope change; candidate→accepted work; approval resolving/work resuming; new artifact; blocker clearing. Avoid decorative distraction; the system feels alive because work meaningfully changes, not because it constantly animates.
|
||||
```text
|
||||
check name
|
||||
status
|
||||
scope
|
||||
candidate revision
|
||||
evidence link
|
||||
duration
|
||||
failure summary
|
||||
```
|
||||
|
||||
## 21. Accessibility
|
||||
Statuses:
|
||||
|
||||
Require full keyboard navigation; clear focus states; screen-reader labels for statuses/actions; status never color-only; sufficient light/dark contrast; reduced-motion support; predictable card expansion; confirmations for destructive/external effects; human-readable relative timestamps with exact-time access.
|
||||
```text
|
||||
Queued | Running | Passed | Failed | Skipped | Inconclusive
|
||||
```
|
||||
|
||||
## 22. MVP
|
||||
Failures should include:
|
||||
|
||||
### Screens
|
||||
- exact assertion/exit code;
|
||||
- relevant output;
|
||||
- expected vs actual;
|
||||
- repair action;
|
||||
- retry count.
|
||||
|
||||
1. **Active Work:** work-card feed; project/status filters; expanded work unit.
|
||||
2. **Discovery Inbox:** signals; candidate work; merge/attach.
|
||||
3. **Attention Queue:** decisions; approvals; questions; reviews.
|
||||
4. **Project Overview:** goals; active work; project context; artifacts/recent outcomes.
|
||||
Design-conformance findings are labeled:
|
||||
|
||||
All four persist: header; work index; global/contextual composer; realtime activity.
|
||||
```text
|
||||
Conforms | Intentional deviation | Concern | Unknown
|
||||
```
|
||||
|
||||
### Cards
|
||||
Metrics never masquerade as truth; human review may accept justified deviations.
|
||||
|
||||
Signal; Candidate; Active work; Waiting/blocker; Approval; Review; Result. Do not create one card type per technical event; use sections/modifiers in the core system.
|
||||
## 11. Review package
|
||||
|
||||
## 23. Success criteria
|
||||
The delivery screen should narrate the change in review order:
|
||||
|
||||
Within seconds, users can answer: **What should I focus on? What progressed without me? What is blocked? What requires my decision? Why is this happening? What evidence supports current understanding? What happens next? What changed in the project? What result did completed work produce?** They can start, steer, review, or stop work without understanding internal agent/infrastructure architecture.
|
||||
1. original intent;
|
||||
2. accepted behavior;
|
||||
3. architecture/program-design summary;
|
||||
4. slice-by-slice implementation;
|
||||
5. screenshots/video/API examples;
|
||||
6. important diffs;
|
||||
7. verification evidence;
|
||||
8. deviations and risks;
|
||||
9. exact commit and PR actions.
|
||||
|
||||
## 24. Shipping checklist
|
||||
Primary actions:
|
||||
|
||||
- Primary object is a work unit, not a chat session.
|
||||
- Organization/project scope is clear.
|
||||
- Next human action is obvious.
|
||||
- Machine actions and human decisions are separated.
|
||||
- Provenance is available.
|
||||
- Uncertainty is represented honestly.
|
||||
- Detail is progressively disclosed.
|
||||
- Technical internals are hidden unless useful.
|
||||
- Composer preserves continuity.
|
||||
- Experience reduces coordination rather than creating more.
|
||||
```text
|
||||
Open PR | Approve | Request changes | Answer blocker
|
||||
```
|
||||
|
||||
## 25. Core experience statement
|
||||
Merge remains external/manual initially.
|
||||
|
||||
Zopu should feel like supervising a capable operating system, not operating a collection of agents: one workspace shows meaningful work; the user resolves the few things requiring judgment and continues conversation where needed; the system handles context, execution, progress tracking, and knowledge retention beneath a calm surface organized around persistent outcomes.
|
||||
## 12. Result and learning UX
|
||||
|
||||
After delivery:
|
||||
|
||||
```text
|
||||
Expected
|
||||
Actual
|
||||
Evidence
|
||||
Classification
|
||||
Follow-ups
|
||||
```
|
||||
|
||||
Learning proposals are reviewable cards:
|
||||
|
||||
```text
|
||||
Proposed update
|
||||
reason/evidence
|
||||
target document/Kit
|
||||
diff
|
||||
[Accept] [Edit] [Reject]
|
||||
```
|
||||
|
||||
Never silently rewrite canonical knowledge.
|
||||
|
||||
## 13. Empty/loading/error states
|
||||
|
||||
### Empty project
|
||||
|
||||
```text
|
||||
Describe what you want to accomplish.
|
||||
Zopu will convert actionable intent into reviewable Work.
|
||||
```
|
||||
|
||||
### Processing
|
||||
|
||||
Use phase-specific state:
|
||||
|
||||
```text
|
||||
Extracting actionable intent…
|
||||
Drafting Work Definition…
|
||||
Preparing Design Packet…
|
||||
```
|
||||
|
||||
### Failure
|
||||
|
||||
Always show:
|
||||
|
||||
- failed phase;
|
||||
- durable status;
|
||||
- retained evidence;
|
||||
- recommended next action;
|
||||
- retry/replan/cancel controls.
|
||||
|
||||
Never show an endless generic spinner.
|
||||
|
||||
## 14. Responsive behavior
|
||||
|
||||
Mobile:
|
||||
|
||||
- Conversation is primary.
|
||||
- Work cards appear inline and in a drawer.
|
||||
- Attention cards pin above composer.
|
||||
- Expanded Work uses stacked sections.
|
||||
- Diagnostics remain secondary.
|
||||
|
||||
Desktop:
|
||||
|
||||
- Conversation left/main.
|
||||
- Work list/detail right or split panel.
|
||||
- Attention queue accessible globally.
|
||||
|
||||
## 15. Accessibility and interaction rules
|
||||
|
||||
- All status meaning has text, not color alone.
|
||||
- Streaming updates preserve focus.
|
||||
- Approvals require explicit controls.
|
||||
- Destructive actions show scope and consequence.
|
||||
- Keyboard navigation covers cards, sections, actions.
|
||||
- Long logs are virtualized/collapsed.
|
||||
- Timestamps and actor identity are available in audit detail.
|
||||
|
||||
## 16. v0 screens
|
||||
|
||||
Only build:
|
||||
|
||||
```text
|
||||
Project workspace
|
||||
Work detail
|
||||
Attention state inside Work
|
||||
Verification/review package inside Work
|
||||
```
|
||||
|
||||
Do not build a separate dashboard for every backend module.
|
||||
|
||||
## 17. Design acceptance
|
||||
|
||||
The experience is successful when a technical founder can:
|
||||
|
||||
1. state intent in chat;
|
||||
2. see exact intent become a Work card;
|
||||
3. approve a testable definition/design;
|
||||
4. understand current progress in under a minute;
|
||||
5. answer a blocker without finding an agent session;
|
||||
6. inspect verification evidence;
|
||||
7. reach the exact verified PR;
|
||||
8. understand why Zopu considers the Work ready.
|
||||
|
||||
Reference in New Issue
Block a user