zopu-code/docs/DESIGN.md

# Zopu Work OS — Product Design

> **Related:** `product.md` defines the domain; `dev-loop.md` defines phases/gates; `slices.md` defines UI rollout.

> **Status:** Working interaction specification  
> **Audience:** frontend, product, agents generating UI  
> **Constraint:** simple interface; complexity is revealed only when useful.

## 1. Experience principle

The user should experience:

```text
Talk naturally
→ see durable Work emerge
→ approve what matters
→ watch meaningful progress
→ answer precise questions
→ inspect evidence
→ receive a reviewable result
```

The UI MUST optimize **confidence per minute of human attention**, not display every agent action.

## 2. Information architecture

```text
Project
├── Conversation
├── Work cards
├── Attention
├── Artifacts/search
└── Project knowledge/settings
```

v0 may render Conversation and Work in one workspace with a side/detail panel.

## 3. Project conversation

One continuous project conversation, not session/thread-centric navigation.

Message types:

- user;
- Zopu response;
- Signal notice;
- Work created/updated;
- human decision;
- important artifact/result.

Conversation actions:

- send message;
- attach context;
- reference Work;
- create/modify priority;
- answer a question;
- ask for status/explanation.

When a message creates Work, render a compact inline link/card. Preserve a link from Work back to exact source message.

## 4. Work card

### Collapsed

Display only decision-relevant information:

```text
Title
phase/status
latest meaningful update
blocker/question
next action
slice progress
artifact count
```

Example:

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

Do not expose internal state-machine names unless in diagnostics.

## 6. Attention objects

A question/approval is a structured card:

```text
Decision title
exact question
why it matters
recommendation
alternatives
consequences
affected Work/slice
primary action
reply action
```

Example:

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

Answering MUST resume the same Work. Never create a disconnected chat thread.

Attention inbox ordering:

1. production/security blockers;
2. decisions blocking active Work;
3. review/approval requests;
4. informational updates.

## 7. Definition and design review

Use diffable structured documents, not long prose blobs.

### Work Definition editor

Editable fields:

- problem;
- outcome;
- scope/non-goals;
- acceptance criteria;
- assumptions;
- questions;
- risk.

Actions:

```text
Approve | Request revision | Edit directly
```

### Design Packet review

Show:

- one architecture diagram;
- expected file-tree changes;
- expected call flow;
- key types/contracts;
- slices;
- risks/trade-offs.

Highlight changes between versions. Approval records actor/user, version, timestamp, and optional comment.

## 8. Slice presentation

Each slice shows:

```text
objective
observable behavior
planned code changes
required checks
dependencies
status
attempt count
artifacts
review requirement
```

A timeline is useful, but the primary representation is a dependency-aware list.

Slice statuses:

```text
Pending | Ready | Running | Verifying | Review | Passed | Failed | Blocked
```

## 9. Activity design

Normalize events into concise statements:

Good:

```text
Implemented build metadata provider
Focused tests passed
Verifier found response schema mismatch
Repair attempt started with failure evidence
```

Bad:

```text
Tool call: bash
Read 42 files
Generated 7,932 tokens
Actor wake event
```

Provide an expandable diagnostics/log panel for experts.

## 10. Verification UX

Checklist rows contain:

```text
check name
status
scope
candidate revision
evidence link
duration
failure summary
```

Statuses:

```text
Queued | Running | Passed | Failed | Skipped | Inconclusive
```

Failures should include:

- exact assertion/exit code;
- relevant output;
- expected vs actual;
- repair action;
- retry count.

Design-conformance findings are labeled:

```text
Conforms | Intentional deviation | Concern | Unknown
```

Metrics never masquerade as truth; human review may accept justified deviations.

## 11. Review package

The delivery screen should narrate the change in review order:

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.

Primary actions:

```text
Open PR | Approve | Request changes | Answer blocker
```

Merge remains external/manual initially.

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