zopu-code/docs/PRODUCT.md

Zopu Work OS — Product Specification

Related: dev-loop.md defines delivery; slices.md defines product increments; evaluation.md defines quality measurement.

Status: Working source of truth
Audience: product, design, engineering, agents
Normative words: MUST = required, SHOULD = default, MAY = optional
Product boundary: this file defines what and why, not implementation details.

1. Thesis

Zopu is a completion system for durable units of work, not a chat wrapper and not a coding-agent launcher.

The product converts conversation and external events into verified outcomes:

Talk/events → Signals → Work → Definition → Design → Slices
→ Resolution → Verification → Delivery → Observation → Learning

The core promise:

Given an accepted unit of work, Zopu keeps advancing it until a verified outcome exists or a precise terminal blocker is recorded.

Agents may propose, plan, implement, review, and test. The system decides completion from evidence.

2. Initial customer and scope

ICP v0

Technical founders and small engineering teams working in one Git repository.

Supported v0 workflow

Project chat
→ actionable Signal
→ approved Work Definition
→ lightweight Design Packet
→ vertical slices
→ isolated coding run
→ independent verification
→ branch + pull request
→ human merge
→ result assessment

v0 constraints

• One user/organization/project/repository path first.
• Web interface only.
• One implementation harness first.
• One sandbox provider first.
• Manual merge.
• No autonomous production mutation.
• No arbitrary generated tools receiving immediate execution authority.
• No generic support for every founder workflow yet.

The domain must remain broader than Git, but the implementation should prove quality on software delivery first.

3. Product surfaces

The primary interface remains intentionally small:

1. Continuous project conversation
2. Work cards
3. Human attention queue

Continuous conversation

One project-level conversation is used to:

• discuss intent;
• create Signals;
• ask about Work;
• add evidence or constraints;
• change priorities;
• respond to agent questions.

Conversation is not the system of record for execution state.

Work cards

A Work card is the durable, inspectable representation of one desired outcome. It exposes definition, design, execution, evidence, delivery, and result without forcing the user to inspect raw agent transcripts.

Attention queue

All decisions requiring a human are first-class objects:

• clarify intent;
• approve definition/design;
• grant permission;
• select an alternative;
• review a slice;
• approve merge/release;
• accept risk.

4. Canonical domain

Signal

Evidence that may require attention.

Signal
├── exact source/provenance
├── extracted meaning
├── project context
├── confidence
├── related signals
└── candidate Work links

A Signal MUST preserve the original source. A model summary never replaces evidence.

Work

A durable desired outcome, not a message, issue, session, branch, or PR.

Work
├── objective
├── reason/user impact
├── source Signals
├── Work Definition
├── Design Packet
├── slices/steps
├── runs/attempts
├── questions/decisions
├── artifacts/evidence
├── delivery
└── result

Work Definition

A testable contract before implementation:

• problem;
• desired outcome;
• affected users;
• in/out of scope;
• acceptance criteria;
• constraints;
• assumptions;
• unresolved questions;
• risk class;
• required artifacts;
• rollout/rollback requirements when applicable.

Design Packet

A reviewable implementation intent:

• impact map;
• architecture summary/sequence;
• file-tree diff;
• call-flow diff;
• key types/interfaces;
• invariants;
• migration/security/operational concerns;
• vertical slice plan;
• explicit trade-offs and deviations.

Vertical Slice

A bounded unit of implementation that produces observable, independently verifiable progress.

A valid slice answers:

• what behavior becomes observable;
• what code boundaries change;
• what artifacts must exist;
• what evidence proves completion;
• what review is required before continuation.

Kit

A versioned executable configuration for resolving a class of Work:

• roles/agent definitions;
• tools and grants;
• skills/instructions;
• context policy;
• runtime requirements;
• harness policy;
• budgets;
• output contracts;
• verification recipes;
• escalation policy.

A Kit is not an agent and not a run. v0 uses one static Coding Kit; dynamic Kit Builder comes after the loop is reliable.

Run and Attempt

A Run coordinates execution for Work or a slice. An Attempt is one bounded execution by one harness in one environment.

Attempt terminal classifications:

Succeeded | RetryableFailure | NeedsInput | Blocked
| VerificationFailed | BudgetExhausted | Cancelled | PermanentFailure

“Agent working” is not a durable outcome.

Artifact and Evidence

Examples:

• plan/design;
• diff;
• test report;
• screenshot/video;
• commit;
• PR;
• preview;
• deployment;
• runtime logs;
• performance/security reports.

Every artifact SHOULD include producer, Work/slice/run, source revision, environment, provenance, and verification status.

Result

Delivery is not necessarily outcome. Result compares intended and actual impact:

Achieved | PartiallyAchieved | NotAchieved | Regressed | Inconclusive

Learning

Post-work observations that may propose updates to:

• project knowledge;
• architecture decisions;
• test recipes;
• skills;
• tools;
• Kit definitions;
• planning heuristics.

Canonical knowledge updates require review.

5. Quality doctrine

High-quality software is evaluated across:

Dimension	Required question
Correctness	Does behavior satisfy the accepted criteria?
Regression safety	Did existing behavior remain valid?
Maintainability	Does the change preserve understandable boundaries?
Security	Are permissions, secrets, data, and dependencies safe?
Reliability	Are failures and edge cases handled?
Operability	Can it be deployed, observed, debugged, and rolled back?
Performance	Are expected resource limits preserved?
UX	Does the actual user path work?
Traceability	Can claims be tied to evidence and revisions?
Reversibility	Can risk be disabled or rolled back?

Completion rule

Work is complete only when:

1. accepted behavior is implemented on a known revision;
2. required checks pass in a known environment;
3. design deviations are visible;
4. required human gates are satisfied;
5. delivery artifacts exist;
6. post-release observation is completed when required.

A passing test suite is necessary but not sufficient for medium/high-risk work.

Builder-verifier separation

The implementation worker MUST NOT be the sole authority on completion.

Builder → candidate output
Verifier → independent evidence
Resolver → completion decision
Human → policy-defined approvals

Risk lanes

Fast

Copy, docs, isolated styling, deterministic mechanical changes.

short contract → implement → verify → PR

Standard

Normal features, APIs, workflows, changes spanning a few modules.

definition → combined design → 1–3 slices → verify → review → PR

Critical

Auth, billing, permissions, migrations, shared infrastructure, destructive operations.

definition approval → architecture approval → program-design approval
→ one slice at a time → staged release → observation/rollback gate

6. Resolver contract

The Work Resolver is the central product engine.

It MUST continuously answer:

• What remains incomplete?
• What is executable now?
• What capability can perform it?
• What evidence is missing?
• Should it retry, repair, replan, escalate, or stop?
• Has the Work reached a valid terminal state?

Resolver outcomes:

VerifiedOutcomeDelivered
VerifiedPRReady
HumanDecisionRequired
ExternalDependencyBlocked
BudgetExhaustedWithEvidence
PermanentlyFailedWithDiagnosis
Cancelled

The Resolver MUST:

• operate from durable state;
• execute bounded attempts;
• enforce budgets and permissions;
• preserve provenance;
• recover after process failure;
• avoid duplicate side effects;
• require evidence before transitions;
• surface precise blockers;
• never silently stall.

7. Human operating model

Humans should spend attention on high-leverage decisions, not supervise tool calls.

Preferred gates:

• Work Definition approval;
• Design Packet approval for standard/critical work;
• slice review when risk requires it;
• merge/release approval;
• resolution of ambiguity or policy exceptions.

A human request must include:

decision needed
why it is needed
recommended action
alternatives
consequences
urgency
affected Work/slice

8. External collaboration

Buzz, Slack-like systems, Git forges, monitoring, support, and analytics are interfaces and Signal sources.

They MAY:

• create Signals;
• carry status updates;
• present questions;
• receive review/preview links;
• report incidents and results.

They MUST NOT own canonical Work, Resolver, verification, or completion state.

9. Product success metrics

Primary:

• verified outcomes per unit of human attention;
• median time from accepted Work to verified PR/outcome;
• percentage of Work reaching an explicit terminal state;
• verification escape rate;
• post-merge rework rate;
• design-review-to-implementation deviation rate.

Secondary:

• retry count;
• human interruption count;
• stale Work count;
• duplicate Signal/Work rate;
• average review-package comprehension time;
• Kit/version performance by work type.

Avoid optimizing token volume, agent count, or code generated.

10. Non-goals for early versions

• Fully autonomous company operation.
• Lights-off merging/deployment.
• Universal dynamic tool creation.
• Large unbounded fleets.
• Replacing Git or CI.
• Encoding all product truth in chat.
• Making one model/harness part of the product domain.
• Automating maintainability judgment without human policy.