# 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

## 1. Objective and governing model

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.**

> **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:

```text
┌─────────────────────────────────────────────────────────────────────┐
│ Header                                                              │
├───────────────┬───────────────────────────────────┬─────────────────┤
│ Work index    │ Primary workspace                 │ Context panel   │
│               │ cards / expanded work / chat      │ evidence,       │
│               │                                   │ artifacts,      │
│               │                                   │ preview, tools  │
├───────────────┴───────────────────────────────────┴─────────────────┤
│ Persistent composer                                                 │
└─────────────────────────────────────────────────────────────────────┘
```

The layout collapses gracefully on smaller screens.

### 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:

```text
Global workspace
Working in: Fix Safari OAuth callback failures
```

Accept text, files, images, voice, links, source/work-unit/project mentions, and natural-language commands. Users never select a model, agent, or thinking mode.

## 5. Primary screens

### 5.1 Command Center (default)

An operational briefing—not a wall of metrics—answering portfolio-level orientation, autonomous progress, meaningful changes, and required actions:

- **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.

### 5.2 Discovery Inbox

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.

### 5.3 Project Overview

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?

### 5.4 Work Unit Workspace

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

```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]
```

```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
```

```text
Waiting · Approval required
Fix Safari OAuth callback failures
Need: Approve 30-minute diagnostic logging
Impact: Investigation cannot continue without production evidence
[Review request]
```

```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]
```

## 7. Card expansion

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.

## 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:

```text
Created candidate work: Improve OAuth diagnostics
Linked to: Restore OAuth reliability · Sources attached: 3
```

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:

```text
Implementation run · 24 minutes
• Inspected callback handler  • Added state validation
• Added regression tests      • 14 tests passed
• Created PR #184
```

## 11. Provenance

Four progressively disclosed levels:

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.

Labels: **Verified, Reported, Inferred, Assumed, Conflicting, Outdated**. Do not force derivation detail during normal operation.

## 12. Organization/project/portfolio scope

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.

```text
Portfolio
├── Company A
│   ├── Product Alpha
│   └── Internal Platform
└── Client B
    └── Customer Portal
```

Do not require deep-tree navigation for every action: provide search, recent projects, and scope-aware commands.

## 13. Project onboarding

Onboarding prepares a capable working environment, not a long settings form.

- **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.

## 14. Artifacts

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:

```text
Deploy preview
Project: Zopu Web · Branch: work/W-103/team-invitations
Environment: Temporary preview · External impact: None
Expected duration: 20 minutes
[Deploy preview]
```

## 16. Autonomy controls

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:

```text
Autonomous within policy · No action required
Paused after repeated verification failure · Review required
```

Advanced settings may expose policy detail; everyday use stays simple.

## 17. Empty, loading, failure, conflict

| 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. |

## 18. Responsive behavior

| 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. |

## 19. Visual language

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.

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.

## 20. Motion

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.

## 21. Accessibility

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.

## 22. MVP

### Screens

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.

All four persist: header; work index; global/contextual composer; realtime activity.

### Cards

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.

## 23. Success criteria

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.

## 24. Shipping checklist

- 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.

## 25. Core experience statement

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.
