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:

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

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:

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

Example:

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:

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:

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:

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

Example:

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:

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:

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:

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

9. Activity design

Normalize events into concise statements:

Good:

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

Bad:

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:

check name
status
scope
candidate revision
evidence link
duration
failure summary

Statuses:

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:

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:

Open PR | Approve | Request changes | Answer blocker

Merge remains external/manual initially.

12. Result and learning UX

After delivery:

Expected
Actual
Evidence
Classification
Follow-ups

Learning proposals are reviewable cards:

Proposed update
reason/evidence
target document/Kit
diff
[Accept] [Edit] [Reject]

Never silently rewrite canonical knowledge.

13. Empty/loading/error states

Empty project

Describe what you want to accomplish.
Zopu will convert actionable intent into reviewable Work.

Processing

Use phase-specific state:

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:

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.