From 5d1598a807ee83b070b0d8257968945a7be0e0de Mon Sep 17 00:00:00 2001 From: -Puter <22245429+puterhimself@users.noreply.github.com> Date: Thu, 23 Jul 2026 14:45:19 +0530 Subject: [PATCH] docs --- AGENTS.md | 2 +- docs/DESIGN.md | 1500 ++++++-------------------------------------- docs/PRODUCT.md | 933 ++++------------------------ docs/TECH.md | 1580 +++++------------------------------------------ 4 files changed, 458 insertions(+), 3557 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 09a43a7..d3811f5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1 +1 @@ -This Bun/TypeScript monorepo uses Bun/Vite+, Convex, Effect v4, and Flue; use `@code/*` exports, validate env in `packages/env`, never edit generated files or `repos/`, and keep UI presentational by moving UI state to reusable hooks and business/services/pure logic to dedicated modules. Before Flue work, MUST read `.agents/skills/flue/SKILL.md` and use installed-version `flue docs`; after every change, MUST run `bunx ultracite check` on every changed source, script, and agent file (apply `bunx ultracite fix` first when needed), run the affected package's `bun run check-types`, exercise the changed behavior with its targeted runtime or smoke test, then run root `bun run check` and report unrelated pre-existing failures separately; keep every `AGENTS.md` to 1–2 dense sentences by replacing stale guidance rather than appending. +This Bun/TypeScript monorepo uses Bun/Vite+, Convex, Effect v4, and Flue; use `@code/*` exports, validate env in `packages/env`, never edit generated files or `repos/`, and keep UI presentational by moving UI state to reusable hooks and business/services/pure logic to dedicated modules. Treat `docs/PRODUCT.md`, `docs/DESIGN.md`, and `docs/TECH.md` as the canonical product, experience, and architecture specifications; read the relevant files before decisions or changes in those domains. Before Flue work, MUST read `.agents/skills/flue/SKILL.md` and use installed-version `flue docs`; after every change, MUST run `bunx ultracite check` on every changed source, script, and agent file (apply `bunx ultracite fix` first when needed), run the affected package's `bun run check-types`, exercise the changed behavior with its targeted runtime or smoke test, then run root `bun run check` and report unrelated pre-existing failures separately. Keep each individual instruction in any `AGENTS.md` to 1–2 dense sentences, replacing stale guidance rather than appending; this limit applies per instruction, not to the whole file. diff --git a/docs/DESIGN.md b/docs/DESIGN.md index f03b948..a1e8d78 100644 --- a/docs/DESIGN.md +++ b/docs/DESIGN.md @@ -1,139 +1,51 @@ # Zopo Work OS — Product Design -> Status: working interaction and interface specification -> Audience: product design, frontend, product engineering, and agent experience teams -> Scope: information architecture, screens, cards, interaction patterns, states, actions, and design principles -> Excludes: backend implementation and low-level infrastructure details +> **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. Design objective +## 1. Objective and governing model -Design one calm, persistent interface in which users can supervise many active units of work across multiple organizations, products, projects, teams, and contexts without managing chat threads, model settings, or agent sessions. +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 interface should make a complex autonomous system feel understandable and controllable. - -The primary design challenge is not displaying everything the system knows. It is showing the smallest amount of information required for the user to understand: - -1. What matters. -2. What is happening. -3. What is blocked. -4. What requires human action. -5. What will happen next. -6. Why the system believes what it believes. - -The central interaction principle is: - -> The conversation is the command surface. The work unit is the persistent product object. - ---- +> **The conversation is the command surface; the work unit is the persistent product object.** ## 2. Experience principles -### 2.1 One continuous workspace - -Do not organize the product around chat history, sessions, or thread lists. - -The user should experience one persistent workspace with a composer that can operate globally or inside a selected work unit. - -### 2.2 Work first, machinery second - -The user should see outcomes, blockers, decisions, artifacts, and results. - -Agent names, model choices, runtime state, and infrastructure details should remain hidden unless they help explain progress or debug a failure. - -### 2.3 Progressive disclosure - -Collapsed cards should be scannable. Expanded cards should become rich working surfaces. Deep evidence, raw events, and technical details should be available on demand. - -### 2.4 Calm density - -The product should support dense operational information without feeling like a traditional enterprise dashboard. - -Use hierarchy, spacing, typography, and grouping rather than excessive borders, colors, or permanent panels. - -### 2.5 Human attention is a scarce resource - -The interface should centralize requests for human involvement. Users should not search through cards to discover approvals, blockers, or unanswered questions. - -### 2.6 Context must always be visible - -The user should always know: - -- Which organization they are viewing. -- Which project or portfolio scope is active. -- Whether the composer is global or work-specific. -- Which work unit is selected. -- Whether an action affects external or production systems. - -### 2.7 Provenance should be nearby - -Important claims, decisions, and recommendations should have accessible source indicators. Evidence should be one interaction away, not buried in a separate audit application. - ---- +| 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 -Use consistent language across the interface. +| 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. | -### Organization - -A company, client, or hard context boundary. - -### Project - -A product, application, repository-backed system, or durable operating context. - -### Goal - -A measurable business or product objective. - -### Signal - -A new piece of information that may matter. - -### Candidate - -A proposed unit of work awaiting confirmation. - -### Work unit - -A persistent outcome the system is responsible for progressing. - -### Run - -One execution attempt inside a work unit. - -### Artifact - -A produced or collected output such as a pull request, preview, report, design, or document. - -### Attention item - -A decision, approval, question, blocker, review, or risk that requires human action. - -Avoid exposing terms such as: - -- Agent thread. -- Model context window. -- Harness session. -- VM. -- Sandbox lifecycle. -- Actor wake state. - -These may appear only in technical details or debugging views. - ---- +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 -The primary desktop layout uses three regions. +Desktop uses three regions plus a persistent composer: ```text ┌─────────────────────────────────────────────────────────────────────┐ │ Header │ ├───────────────┬───────────────────────────────────┬─────────────────┤ │ Work index │ Primary workspace │ Context panel │ -│ │ │ │ -│ │ Cards / expanded work / chat │ Evidence, │ +│ │ cards / expanded work / chat │ evidence, │ │ │ │ artifacts, │ │ │ │ preview, tools │ ├───────────────┴───────────────────────────────────┴─────────────────┤ @@ -141,931 +53,203 @@ The primary desktop layout uses three regions. └─────────────────────────────────────────────────────────────────────┘ ``` -The layout should collapse gracefully on smaller screens. +The layout collapses gracefully on smaller screens. -### 4.1 Header +### Header -The header provides global orientation and lightweight controls. +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. -Recommended contents: +### Left work index -- Current organization switcher. -- Current project or portfolio scope. -- Search or command trigger. -- Attention count. -- Activity indicator. -- User menu. +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. -Avoid filling the header with model controls, agent selectors, or environment settings. +### Primary workspace -### 4.2 Left work index +Show portfolio/project overview, project overview, work-card feed, expanded work unit, global conversation moments, candidate review, attention workflow, results/learning. -The left region is not chat history. +### Context panel -It contains operational navigation such as: +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. -- Now. -- Attention. -- Discovery. -- Active work. -- Waiting. -- Review. -- Monitoring. -- Recently completed. -- Goals. -- Projects. -- Knowledge. -- Activity. +### Persistent composer -The index should show compact counts and status indicators. - -A project section may show: - -- Project name. -- Health. -- Number of active units. -- Number requiring attention. -- Current goal or release. - -### 4.3 Primary workspace - -The center is where work appears and expands. - -It can show: - -- Portfolio overview. -- Project overview. -- Work-card feed. -- Expanded work unit. -- Global conversation moments. -- Candidate review. -- Attention workflow. -- Results and learning. - -### 4.4 Context panel - -The right panel changes with the selected object. - -Possible contents: - -- Evidence. -- Sources. -- Files. -- Pull request. -- Code changes. -- Preview. -- Test results. -- Research. -- Agent activity. -- Decisions. -- Dependencies. -- Analytics. -- Customer feedback. -- Version history. - -The panel should be hidden or collapsed when there is no relevant content. - -### 4.5 Persistent composer - -The composer remains available across the product. - -It has two scopes: +Available everywhere; scope is visibly lightweight: ```text Global workspace -``` - -or: - -```text Working in: Fix Safari OAuth callback failures ``` -The active scope should be visually obvious but not heavy. - -The composer can accept: - -- Text. -- Files. -- Images. -- Voice. -- Links. -- Source mentions. -- Work-unit references. -- Project references. -- Commands through natural language. - -The user should not have to select a model, agent, or thinking mode. - ---- +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 +### 5.1 Command Center (default) -The Command Center is the default high-level screen. +An operational briefing—not a wall of metrics—answering portfolio-level orientation, autonomous progress, meaningful changes, and required actions: -Purpose: +- **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. -- Give the user an immediate understanding of the portfolio. -- Show what progressed autonomously. -- Surface only meaningful changes and required actions. +### 5.2 Discovery Inbox -Recommended sections: +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. -### Today +### 5.3 Project Overview -- Highest-value active work. -- Upcoming deadlines. -- Work likely to become blocked. -- Work recently unblocked. +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? -### Needs attention +### 5.4 Work Unit Workspace -- Approvals. -- Decisions. -- Questions. -- Reviews. -- Risks. +Expanded selected card; structure: -### Autonomous progress +| 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. | -- Work advanced since the last visit. -- Newly produced artifacts. -- Verification completed. -- Follow-up candidates. +### 5.5 Attention Queue -### Project health +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. -For each relevant project: +### 5.6 Activity Stream -- Current goal. -- Active work count. -- Blocker count. -- Recent result. -- Risk or health signal. +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. -### Recent outcomes +### 5.7 Results and Learning -- Completed work. -- Measured effects. -- Newly captured learnings. +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. -The Command Center should not become a wall of metrics. It should be an operational briefing. +### 5.8 Knowledge -## 5.2 Discovery Inbox - -The Discovery Inbox contains signals and candidate work. - -Each item should clearly distinguish raw information from proposed interpretation. - -Views: - -- New signals. -- Candidate work. -- Possible duplicates. -- Suggested links to existing work. -- Low-confidence observations. - -Primary actions: - -- Accept. -- Edit. -- Attach to existing work. -- Merge. -- Defer. -- Dismiss. -- Save as knowledge. -- Ask why. - -Batch actions may be useful for obvious duplicates or low-value signals, but important candidate creation should remain inspectable. - -## 5.3 Project Overview - -The Project Overview presents one product or application context. - -Sections: - -- Project identity and health. -- Current goals. -- Active work. -- Waiting and blocked work. -- Recent releases or outcomes. -- Connected sources. -- Important context documents. -- Team members and responsibility. -- Autonomous activity. - -The screen should answer: - -- What is this project trying to achieve? -- What is moving? -- What is blocked? -- What changed recently? -- What requires the user? - -## 5.4 Work Unit Workspace - -The Work Unit Workspace is the expanded state of a selected card. - -Recommended structure: - -### Work header - -- Outcome-oriented title. -- Organization and project. -- Work type. -- Phase. -- Status. -- Priority. -- Owner or responsible party. -- Last meaningful change. -- Autonomy state. - -### Objective - -- Desired outcome. -- Why now. -- Linked goal. -- Success criteria. -- Scope and non-goals. - -### Current understanding - -A concise system-generated summary separated into: - -- Known. -- Inferred. -- Uncertain. -- Conflicting. - -### Plan - -- Current approach. -- Steps. -- Completed actions. -- Next action. -- Alternative path when relevant. - -### Blockers and dependencies - -Each blocker shows: - -- What is blocked. -- Why. -- Who or what can resolve it. -- Impact of waiting. -- Requested human action. - -### Activity - -A chronological but compressed history of: - -- User instructions. -- Agent progress. -- State changes. -- Decisions. -- Artifacts. -- External actions. -- Verification. - -### Artifacts - -A collection of previews and links for: - -- Pull requests. -- Commits. -- Documents. -- Screenshots. -- Previews. -- Test reports. -- Designs. -- Research. - -### Results - -Visible after publication or completion: - -- Expected result. -- Actual result. -- Measurement window. -- Evidence. -- Unexpected effects. -- Follow-up recommendation. - -### Contextual composer - -The composer remains fixed at the bottom and clearly scoped to the selected work unit. - -## 5.5 Attention Queue - -The Attention Queue is the central human-in-the-loop surface. - -Categories: - -- Decisions. -- Approvals. -- Questions. -- Blockers. -- Reviews. -- Access requests. -- Risk alerts. - -Each item must answer: - -- What is needed? -- Why is it needed? -- What does the system recommend? -- What evidence supports that recommendation? -- What happens after approval? -- What happens if the user does nothing? -- How urgent is it? -- Is the action reversible? - -The queue should support quick review without forcing the user into the full work-unit workspace unless deeper context is needed. - -## 5.6 Activity Stream - -The Activity Stream shows what the autonomous system did. - -It should include meaningful events such as: - -- Work discovered. -- Work updated. -- Run started. -- Plan prepared. -- Code changed. -- Verification completed. -- Artifact created. -- Blocker detected. -- Approval requested. -- Work completed. -- Result measured. - -Avoid filling the stream with every low-level tool call. - -Users can expand an event to inspect technical detail and provenance. - -## 5.7 Results and Learning - -This screen shows completed work as a feedback system rather than an archive. - -Views: - -- Recently completed. -- Monitoring. -- Successful outcomes. -- Unexpected regressions. -- Follow-up opportunities. -- Reusable learnings. - -Each result should connect to the original objective and evidence. - -## 5.8 Knowledge - -The Knowledge screen exposes durable organization and project understanding. - -Categories: - -- Product. -- Business. -- Customers. -- Design. -- Technical context. -- Decisions. -- Known constraints. -- Reusable learnings. - -The user should be able to see whether knowledge is: - -- Canonical. -- Inferred. -- Pending review. -- Outdated. -- Conflicting. - ---- +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 -The card is a visual projection of a durable product object. +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. -The same underlying work unit may appear as: +| 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. | -- Compact card. -- Expanded card. -- Attention item. -- Embedded conversation object. -- Timeline event. -- Result card. - -Do not create separate task systems for each surface. - -## 6.1 Signal card - -Purpose: show newly detected information. - -Collapsed content: - -- Source icon and source name. -- Observation. -- Project or organization. -- Time. -- Suggested relationship. -- Confidence. - -Actions: - -- Create work. -- Attach to existing work. -- Save as knowledge. -- Dismiss. - -Example: +### 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 - +Possible match: Fix Safari callback failures · Confidence: High [Attach] [Create separate work] [Dismiss] ``` -## 6.2 Candidate card - -Purpose: propose a durable work unit. - -Collapsed content: - -- Proposed outcome. -- Why it matters. -- Project. -- Linked goal. -- Supporting source count. -- Confidence. -- Duplicate warning if relevant. - -Actions: - -- Accept. -- Edit. -- Merge. -- Defer. -- Dismiss. -- Ask why. - -## 6.3 Active work card - -Purpose: communicate current operational state. - -The collapsed card should answer five questions: - -1. What is this? -2. Why does it matter? -3. What state is it in? -4. Is anything blocked? -5. What happens next? - -Recommended anatomy: - ```text -[Type] [Organization / Project] [Status] - +[Type] [Organization / Project] [Status] Fix Safari OAuth callback failures - -Supports: Improve onboarding reliability - -42% complete +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 ``` -## 6.4 Waiting or blocked card - -Waiting should be visually distinct without becoming alarmist. - -Show: - -- Exact blocker. -- Responsible party. -- Time waiting. -- Impact. -- Next resolution action. - -Example: - ```text Waiting · Approval required - Fix Safari OAuth callback failures - Need: Approve 30-minute diagnostic logging Impact: Investigation cannot continue without production evidence - [Review request] ``` -## 6.5 Approval card - -Purpose: let the user make a bounded decision safely. - -Required content: - -- Exact action. -- Why it is requested. -- Recommendation. -- Alternatives. -- Risk. -- Impact. -- Evidence. -- Reversibility. - -Actions: - -- Approve. -- Modify. -- Reject. -- Ask for more evidence. -- Delegate. - -Example: - ```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 passed -• 6 browser tests passed -• Preview reviewed -• Automated code review attached - +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] ``` -## 6.6 Review card +## 7. Card expansion -Purpose: evaluate an artifact or completed run. +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. -Show: +## 8. Global/contextual chat -- What changed. -- Acceptance criteria. -- Verification summary. -- Open concerns. -- Preview or diff access. -- Recommended decision. +**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.” -Actions: +**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. -- Accept. -- Request changes. -- Continue discussion. -- Compare alternative. -- Stop work. - -## 6.7 Result card - -Purpose: connect completed work to actual outcomes. - -Show: - -- Intended outcome. -- What shipped. -- Expected impact. -- Actual result. -- Measurement period. -- Unexpected effects. -- Suggested follow-up. - -Actions: - -- Accept result. -- Continue monitoring. -- Create follow-up. -- Reopen. -- Roll back where applicable. - -## 6.8 Parent initiative card - -Purpose: summarize a larger outcome composed of several child work units. - -Show: - -- Initiative outcome. -- Progress across children. -- Critical path. -- Current blockers. -- Next milestone. -- Number of active and completed children. - -The parent card should not duplicate every child detail. - ---- - -## 7. Card expansion behavior - -Selecting a work card expands it in place in the primary workspace. - -Recommended behavior: - -- Only one primary card is expanded at a time on desktop. -- Other cards remain visible in the surrounding feed where practical. -- The right panel updates to the selected section or artifact. -- The composer scope changes to the selected work unit. -- The selected card retains its position when collapsed. -- Deep links can open directly to a work unit. - -Expanded work should feel like entering a workspace, not navigating to a disconnected detail page. - -On mobile, the expanded card may use a full-screen sheet or route while preserving the same conceptual model. - ---- - -## 8. Global and contextual chat - -## 8.1 Global mode - -Global mode can create and coordinate work across the active organization or portfolio. - -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. - -Global responses may include embedded work cards and attention items. - -## 8.2 Context mode - -Context mode focuses on one work unit. - -Example prompts: - -- 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. - -The composer header should show the active scope and provide an easy way to return to global mode. - -## 8.3 Creating work from chat - -When a user describes work, the system may: - -- Update an existing unit. -- Create a candidate. -- Create accepted work when intent is explicit and policy permits. -- Ask a clarifying question. -- Save the information as knowledge. - -The interface should briefly communicate what happened: +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 +Linked to: Restore OAuth reliability · Sources attached: 3 ``` -## 8.4 Mentioning work - -Users should be able to reference: - -- A work unit. -- A project. -- A goal. -- An artifact. -- A source. -- A person. - -Mentions should insert structured references without requiring the user to copy IDs or links. - ---- +Mentions insert structured references (without copying IDs/links) to a work unit, project, goal, artifact, source, or person. ## 9. Status design -Use a small set of user-facing statuses. +Use these user-facing statuses and explicit primary actions: -### Proposed +| 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. | -The system suggests work but has not started it. +Modifiers: **Blocked, Approval required, Waiting on user, Waiting on dependency, Running autonomously, Scheduled, At risk**. Always pair color with text and iconography. -Primary actions: +## 10. Activity language -- Accept. -- Edit. -- Merge. -- Dismiss. +Activity is meaningful product language, not raw agent noise. -### Clarifying +- **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. -The outcome or requirements are incomplete. - -Primary actions: - -- Answer question. -- Add context. -- Accept assumption. - -### Ready - -The work is sufficiently defined and can begin. - -Primary actions: - -- Start. -- Review plan. -- Change priority. - -### Active - -The work is progressing. - -Primary actions: - -- Inspect. -- Steer. -- Pause. -- Add context. - -### Waiting - -Progress depends on a person, dependency, approval, or external event. - -Primary actions: - -- Resolve blocker. -- Grant access. -- Make decision. -- Continue waiting. - -### Review - -An artifact or result needs evaluation. - -Primary actions: - -- Approve. -- Request changes. -- Continue discussion. - -### Monitoring - -The work has shipped and the system is watching the outcome. - -Primary actions: - -- Inspect result. -- Extend monitoring. -- Create follow-up. -- Roll back. - -### Done - -The work has reached a completed or intentionally stopped outcome. - -Primary actions: - -- View result. -- Reopen. -- Create follow-up. -- Archive. - -Modifiers: - -- Blocked. -- Approval required. -- Waiting on user. -- Waiting on dependency. -- Running autonomously. -- Scheduled. -- At risk. - -Use text and iconography in addition to color. - ---- - -## 10. Activity design - -Activity should show meaningful product events, not raw agent noise. - -### Primary activity language - -Good: - -- Investigated authentication flow. -- Identified likely state-validation bug. -- Added regression tests. -- Verification passed. -- Pull request created. -- Waiting for merge approval. - -Avoid as primary UI: - -- Called grep. -- Ran shell command. -- Read 34 files. -- Model generated 2,600 tokens. -- Actor woke. - -Low-level events should remain accessible in a technical details drawer. - -### Activity grouping - -Group related events into meaningful sessions: +Group related events into sessions: ```text Implementation run · 24 minutes - -• Inspected callback handler -• Added state validation -• Added regression tests -• 14 tests passed +• Inspected callback handler • Added state validation +• Added regression tests • 14 tests passed • Created PR #184 ``` ---- +## 11. Provenance -## 11. Provenance design +Four progressively disclosed levels: -Provenance has four 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. -### Level 1: Source chips +Labels: **Verified, Reported, Inferred, Assumed, Conflicting, Outdated**. Do not force derivation detail during normal operation. -Visible directly on cards: +## 12. Organization/project/portfolio scope -- Git. -- Support. -- Analytics. -- Conversation. -- System inference. -- Human decision. - -### Level 2: Evidence panel - -Shows sources supporting the current understanding or recommendation. - -### Level 3: Raw source - -Allows the user to inspect the original message, issue, log, file, or event. - -### Level 4: Derivation detail - -For high-impact claims, show: - -- Conclusion. -- Evidence used. -- Assumptions. -- Confidence. -- Conflicting evidence. -- Last updated time. -- Producing agent or process. - -Use labels such as: - -- Verified. -- Reported. -- Inferred. -- Assumed. -- Conflicting. -- Outdated. - -Do not force the user to read derivation detail during normal operation. - ---- - -## 12. Project and organization switching - -Users may manage several organizations and projects. - -Requirements: - -- The active organization must always be visible. -- Switching organizations changes the full product scope. -- The system must not show blended private context across organizations. -- Portfolio views may aggregate counts and summaries with explicit labels. -- The composer should show whether it is operating at portfolio, organization, project, or work-unit scope. - -A hierarchy may look like: +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 @@ -1076,422 +260,108 @@ Portfolio └── Customer Portal ``` -The interface should not require users to navigate a deep tree for every action. Search, recent projects, and scope-aware commands should provide fast movement. +Do not require deep-tree navigation for every action: provide search, recent projects, and scope-aware commands. ---- +## 13. Project onboarding -## 13. Project onboarding design +Onboarding prepares a capable working environment, not a long settings form. -Project onboarding should feel like preparing a capable working environment, not filling 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. -## 13.1 Entry choices +## 14. Artifacts -- Start from template. -- Connect existing repository. -- Import repository. -- Create an empty project. +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. -## 13.2 Template selection +## 15. Human actions -Initial templates may include: - -- React. -- Hono. -- Express. -- Full-stack web application. -- API service. -- Expo application. -- Monorepo. - -Each template card should explain: - -- What it includes. -- What it is suited for. -- Expected setup time. -- Included verification. - -## 13.3 Context setup - -Guide the user through concise sections for: - -- Product. -- Business. -- Design. -- Technical conventions. -- Agent instructions. - -The system may draft these from repository content or conversation. The user reviews and confirms. - -Avoid forcing users to write complete documents before starting. Allow progressive completion while clearly marking missing context. - -## 13.4 Readiness state - -Show project setup progress: - -- Repository ready. -- Dependencies prepared. -- Context confirmed. -- Verification passed. -- Preview available. -- Agent ready. - -Infrastructure details should appear as plain operational language rather than raw logs. - ---- - -## 14. Artifact experience - -Artifacts should feel first-class within the work unit. - -Supported artifact presentations: - -- Pull request summary. -- Code diff. -- Preview frame. -- Test report. -- Screenshot gallery. -- Research document. -- Design proposal. -- Generated file. -- Release note. - -Each artifact should show: - -- Name. -- Type. -- Producer. -- Time. -- Related run. -- Verification state. -- Review state. -- Source or destination. - -Artifacts should open in the right panel or a focused viewer without breaking the work-unit context. - ---- - -## 15. Human-in-the-loop actions - -The product should support explicit actions rather than vague “continue” buttons. - -Examples: - -- Approve plan. -- Answer question. -- Grant temporary access. -- Review preview. -- Review changes. -- Request revision. -- Approve branch push. -- Approve pull request. -- Approve merge. -- Approve deployment. -- Send message. -- Pause autonomous work. -- Cancel run. -- Reopen work. - -Every sensitive action should show scope and consequence. - -Example: +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: Zopo Web -Branch: work/W-103/team-invitations -Environment: Temporary preview -External impact: None +Project: Zopo 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. - -Use simple autonomy states: - -- Manual. -- Ask before actions. -- Autonomous within policy. -- Paused. - -Project or organization policy can define defaults. - -A work unit may show: +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 +Autonomous within policy · No action required +Paused after repeated verification failure · Review required ``` -or: +Advanced settings may expose policy detail; everyday use stays simple. -```text -Paused after repeated verification failure -Review required -``` +## 17. Empty, loading, failure, conflict -Advanced settings may expose policy detail, but everyday product use should remain simple. - ---- - -## 17. Empty, loading, and failure states - -## 17.1 Empty workspace - -Do not show a blank dashboard. - -Offer focused starting points: - -- Create project. -- Connect repository. -- Describe what you are working on. -- Import existing issues. -- Start from a template. - -## 17.2 No active work - -Show recent outcomes and suggested candidates rather than inventing busywork. - -## 17.3 Run provisioning - -Show simple language: - -- Preparing workspace. -- Loading project context. -- Starting implementation. - -Avoid exposing infrastructure terms unless the process is delayed or fails. - -## 17.4 Failure state - -A failure should explain: - -- What failed. -- Whether any work was preserved. -- Whether retry is safe. -- What the system recommends. -- Whether human action is required. - -Example: - -```text -Verification failed - -The implementation is saved, but 2 browser tests are failing. -The system recommends another repair attempt. - -[Review failures] [Retry repair] [Stop work] -``` - -## 17.5 Conflicting evidence - -Show conflict explicitly rather than silently choosing one source. - -```text -Conflicting evidence - -Support reports OAuth failures increased. -Analytics currently shows no significant change. - -[Inspect sources] [Continue monitoring] [Start investigation] -``` - ---- +| 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 -### Desktop - -- Three-column layout. -- One expanded work unit. -- Right contextual panel. -- Persistent bottom composer. - -### Tablet - -- Collapsible left index. -- Primary workspace. -- Right panel as overlay or resizable drawer. - -### Mobile - -- Bottom navigation for Now, Attention, Work, and Projects. -- Work cards in a vertical feed. -- Expanded work as a full-screen route or sheet. -- Composer fixed above navigation. -- Context panel content displayed as tabs or sheets. - -The mobile product should prioritize supervision, review, and approval rather than full code inspection. - ---- +| 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 -The visual direction should feel: +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. -- Calm. -- Precise. -- Premium. -- Spacious. -- Highly legible. -- Modern without looking experimental. +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. -Recommended characteristics: +## 20. Motion -- Warm white or restrained dark backgrounds. -- Soft neutral surfaces. -- Thin separators. -- Large rounded corners. -- Subtle depth. -- Strong typography hierarchy. -- Restrained accent color. -- Selective pastel states for work categories or phases. -- Smooth expansion and scope transitions. - -Avoid: - -- Dense enterprise dashboards. -- Excessive gradients. -- Permanent card borders around every item. -- Bright status colors everywhere. -- Model and agent control clutter. -- Chat bubbles dominating the product. -- Kanban as the default mental model. -- Gamification. - -The product should feel like a focused operating environment, not a collection of AI widgets. - ---- - -## 20. Motion and transitions - -Motion should reinforce state and continuity. - -Use motion for: - -- A card expanding into a workspace. -- Composer scope changing. -- A candidate becoming accepted work. -- An approval resolving and work resuming. -- A new artifact appearing. -- A blocker clearing. - -Avoid decorative motion that distracts from operational information. - -The system should feel alive because work changes meaningfully, not because the interface constantly animates. - ---- +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 -Requirements: +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. -- Full keyboard navigation. -- Clear focus states. -- Screen-reader labels for status and actions. -- Status not communicated by color alone. -- Sufficient contrast in light and dark modes. -- Reduced-motion support. -- Predictable card expansion. -- Action confirmations for destructive or external effects. -- Human-readable timestamps and relative times with exact-time access. +## 22. MVP ---- +### Screens -## 22. MVP screen set +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. -Build the first product around four primary screens: +All four persist: header; work index; global/contextual composer; realtime activity. -1. **Active Work** - - Work-card feed. - - Filters by project and status. - - Expanded work unit. +### Cards -2. **Discovery Inbox** - - Signals. - - Candidate work. - - Merge and attach actions. +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. -3. **Attention Queue** - - Decisions. - - Approvals. - - Questions. - - Reviews. +## 23. Success criteria -4. **Project Overview** - - Goals. - - Active work. - - Project context. - - Artifacts and recent outcomes. +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. -Persistent across all four: +## 24. Shipping checklist -- Header. -- Work index. -- Global or contextual composer. -- Realtime activity. +- 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 -## 23. MVP card set - -Initial card types: - -- Signal card. -- Candidate card. -- Active work card. -- Waiting or blocker card. -- Approval card. -- Review card. -- Result card. - -Avoid designing a separate card type for every technical event. Use sections and modifiers inside the core card system. - ---- - -## 24. Design success criteria - -The product experience is successful when a user can answer these questions within seconds: - -- What should I focus on? -- What progressed without me? -- What is blocked? -- What requires my decision? -- Why is this work happening? -- What evidence supports the current understanding? -- What will happen next? -- What changed in the project? -- What result did completed work produce? - -The product should also let the user start, steer, review, or stop work without understanding the internal agent or infrastructure architecture. - ---- - -## 25. Design principles checklist - -Before shipping a screen or feature, verify: - -- Is the primary object a work unit rather than a chat session? -- Is organization and project scope clear? -- Is the next human action obvious? -- Are machine actions separated from human decisions? -- Is provenance available? -- Is uncertainty represented honestly? -- Can detail be progressively disclosed? -- Are technical internals hidden unless useful? -- Does the composer preserve continuity? -- Does the experience reduce coordination rather than create more? - ---- - -## 26. Core experience statement - -Zopo should feel like supervising a capable operating system rather than operating a collection of agents. - -The user opens one workspace, sees the state of meaningful work, resolves the few things requiring judgment, and continues the conversation where needed. The system handles context, execution, progress tracking, and knowledge retention beneath a calm surface organized around persistent outcomes. +Zopo 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. diff --git a/docs/PRODUCT.md b/docs/PRODUCT.md index 2d1833b..79903d2 100644 --- a/docs/PRODUCT.md +++ b/docs/PRODUCT.md @@ -1,897 +1,228 @@ # Zopo Work OS — Product -> Status: working product specification -> Audience: product, design, operations, research, and agent teams -> Scope: product concepts, product boundaries, product behavior, and user value -> Excludes: implementation details, infrastructure, concrete technology choices, and low-level UI specifications +> Working spec · product/design/ops/research/agent teams · concepts, behavior, boundaries, value. Excludes implementation, infra, tech choices, low-level UI. -## 1. Product summary +## 1. Summary -Zopo Work OS is a persistent operating system for technical founders, product engineers, and small software teams who must manage the entire lifecycle of building and growing software across multiple products, companies, repositories, customers, and business functions. +Zopo Work OS is a persistent OS for technical founders, product engineers, and small teams managing the full lifecycle of building and growing software across products, companies, repos, customers, and functions. It replaces fragmented chats, trackers, docs, and manually coordinated AI agents with one coherent system organized around **units of work**. -It replaces fragmented chat sessions, disconnected task trackers, scattered documents, and manually coordinated AI agents with one coherent system organized around **units of work**. +One continuous workspace discovers work, builds understanding, coordinates execution, requests human judgment when needed, tracks outcomes, and retains knowledge. Not a better chat app or just another PM tool — it continuously converts company signals into structured, persistent, executable work. -The user interacts with one continuous workspace. From that workspace, the system discovers work, builds understanding, coordinates execution, requests human judgment when needed, tracks outcomes, and retains the resulting knowledge. +**Promise:** One workspace that understands the company, turns signals into work, progresses work autonomously, and brings the human in only when direction, judgment, permission, or taste is required. -The product is not a better chat application and not merely another project manager. It is a system that continuously converts company signals into structured, persistent, executable work. +## 2. Customer -The core promise is: +**Ideal:** technical founder/small team that operates 1+ software products across several companies/clients/repos; moves between engineering, product, support, sales, marketing, ops, strategy; uses many tools without a unified model; uses AI coding tools but finds session/thread fragmentation; needs more execution capacity without hiring per function; needs context continuity, reliable delegation, visibility into autonomous work. -> One workspace that understands the company, turns signals into work, progresses that work autonomously, and brings the human in only when direction, judgment, permission, or taste is required. +**Secondary:** product engineers (several initiatives), fractional CTOs, agencies/studios, solo founders, small product/eng teams, multi-internal-product operators. ---- +Technical-first because code is a clear execution domain (measurable artifacts, established workflows, strong familiarity). Broader direction: research, content, marketing, support, product ops, sales enablement, other knowledge/creative work. -## 2. Initial customer profile +## 3. Problem — work is fragmented three ways -The initial ideal customer is a technical founder or small technical team that: +| Fragmentation | Detail | +| --- | --- | +| **Across tools** | One problem spans support→analytics→tracker→browser→repo→PR→release notes→customer comms. Each tool stores a partial view; none owns the lifecycle. | +| **Across AI sessions** | Chat/thread-organized work forces repeated decisions: which conversation, what context to restate, which model/agent, where to store output, how it relates to existing work, what changed after shipping. Conversation becomes structure though conversations are temporary and work is persistent. | +| **Founders as coordination** | Small-team founders bridge every system/function: remember decisions, connect feedback to work, check blockers, move work between tools, review AI output, decide next steps. The founder becomes the human integration bus. | -- Operates one or more software products. -- Works across several companies, client organizations, or repositories. -- Moves constantly between engineering, product, customer support, sales, marketing, operations, and strategy. -- Uses many tools but lacks a single model of what the company is trying to accomplish. -- Already uses AI coding tools but finds their session- and thread-based workflows fragmented. -- Needs more execution capacity without hiring a full department for every function. -- Has a strong need for context continuity, reliable delegation, and visibility into autonomous work. +Zopo removes this burden by maintaining a persistent model of work, context, state, evidence, execution, and outcomes. -Secondary early users may include: +## 4. Thesis -- Product engineers managing several initiatives. -- Fractional CTOs. -- Technical agencies and studios. -- Solo software entrepreneurs. -- Small product and engineering teams. -- Operators responsible for multiple internal products or client environments. +- **Conversation is the interface, not the structure.** The durable structure is the **work unit**. Changing tasks must not require a new chat; the persistent conversation's scope moves between whole workspace and a specific work unit. +- **Work = outcomes, not activity.** Represent: _fix Safari OAuth failures; reduce onboarding abandonment; launch team invitations; resolve a billing escalation; rewrite the pricing page; validate a direction._ Do not promote every message/tool-call/agent action to a top-level task. +- **The product participates in work** — not just store/display: discover, understand, plan, execute, verify, publish, measure. +- **Autonomy reduces attention, not adds noise.** Successful when it makes correct progress, informs at the right level, asks only when necessary. +- **Knowledge compounds.** Every decision, result, failure, signal, artifact improves understanding and accelerates/future-proofs future work. -The initial product is technical-first because code is a clear execution domain with measurable artifacts, established workflows, and strong user familiarity. The broader product direction includes research, content, marketing, support, product operations, sales enablement, and other forms of knowledge and creative work. +## 5. Core objects ---- +Use a small set of durable concepts that stays stable across domains. -## 3. Problem statement +### Organization -Modern technical work is fragmented in three ways. +Hard business/permission/knowledge boundary. Represents a company, client, startup, internal BU, or personal portfolio. Owns its users, products, policies, integrations, knowledge, work, history. **Information never moves between organizations implicitly.** -### 3.1 Work is fragmented across tools +### Project / product -A single problem may begin in customer support, appear again in analytics, become an issue in a tracker, require research in a browser, turn into code in a repository, produce a pull request, and later require release notes and customer communication. +Durable operating context within an org: software product, repo-backed app, client engagement, internal platform, website/service, focused initiative. Contains goals, product knowledge, conventions, connected sources, relevant people, active work. Reduces context ambiguity without forcing manual folder structures. -Each tool stores a partial view. No tool owns the full lifecycle. +### Goal -### 3.2 AI work is fragmented across sessions +What the org/project is trying to achieve (e.g. reduce onboarding failure, reach a reliability target, launch enterprise support, improve trial→paid, close first ten enterprise customers). Distinguishes valuable work from merely possible. A work unit may support 1+ goals but every important unit has a clear reason. -Most AI products organize work around chats, threads, or isolated runs. The user must repeatedly decide: +### Signal -- Which conversation to open. -- What context to restate. -- Which model or agent to use. -- Where the result should be stored. -- How the output relates to existing work. -- What changed after the work shipped. +Raw info that may matter: support ticket, customer comment, error spike, deploy failure, sales objection, team-channel message, analytics change, founder thought. **Not automatically a task.** Fates: attach to existing work, convert to candidate, save as knowledge, dismiss, mark irrelevant/duplicate. -The conversation becomes the product structure even though conversations are temporary and work is persistent. +### Candidate work -### 3.3 Founders become the coordination layer +Proposed work unit not yet accepted as durable active work. Created when a signal/cluster seems actionable. Explains: proposed outcome, why it matters, supporting evidence, project/goal, system confidence, whether similar work exists. User can accept/edit/merge/defer/dismiss. -In small teams, the founder acts as the bridge between every system and function. They remember decisions, connect customer feedback to product work, check whether tasks are blocked, move work between tools, review AI outputs, and decide what happens next. +### Work unit -The founder becomes the human integration bus for the company. +Central object. Persistent, stateful representation of one meaningful outcome. Owns: objective, desired result, scope/non-goals, current understanding, requirements, success criteria, status, priority, dependencies, blockers, decisions, evidence, plan, human actions, agent activity, artifacts, results, learning. -Zopo Work OS removes this coordination burden by maintaining a persistent model of work, context, state, evidence, execution, and outcomes. +Persists across conversations, agent runs, people, tools, time. Not identical to (though may contain): a single prompt, chat thread, agent session, PR, checklist item, branch. ---- +### Step -## 4. Product thesis +Bounded action within a work unit: inspect logs, reproduce failure, draft plan, add tests, review preview, contact customers. Organizes execution but must not become another noisy task layer — visible when useful, hidden when only the outcome matters. -### 4.1 The conversation is not the product structure +### Run -Conversation is the interface through which the user thinks, directs, reviews, and makes decisions. +One agent/workflow attempt to progress a work unit: research root cause, implement, review, verify, prep release. A unit can have parallel/repeated runs. Subordinate to the work unit — never replaces it as the primary object. -The durable structure is the **work unit**. +### Artifact -A user should not have to create a new chat because they changed tasks. They should be able to move the scope of one persistent conversation between the whole workspace and a specific work unit. +Durable output/evidence: PR, commit, patch, design, spec, test report, screenshot, preview, research memo, customer-response draft, launch plan. Attached to the work unit, accessible from history and current state. -### 4.2 Work should be represented as outcomes, not activity +### Decision -The system should represent meaningful outcomes such as: +Records an important human/system choice + reasoning: approve plan, choose design direction, reject a migration, delay a feature, accept a limitation. Stays visible after the conversation so future agents don't repeat settled debates. -- Fix Safari OAuth callback failures. -- Reduce onboarding abandonment. -- Launch team invitations. -- Resolve an enterprise billing escalation. -- Rewrite the pricing page. -- Validate a new product direction. +### Approval -It should not promote every message, tool call, or agent action into a top-level task. +Specific human permission before a sensitive/consequential action: merge code, deploy prod, send customer message, access sensitive data, spend money, change business policy. Precise, inspectable, bounded — user knows exactly what happens after approval. -### 4.3 The product should participate in the work +### Result & learning -Traditional project-management products store and display work. Zopo should also help discover, understand, plan, execute, verify, publish, and measure it. - -### 4.4 Autonomy should reduce attention, not increase noise - -The product should optimize for useful progress with minimal required human attention. - -Autonomy is successful when the system makes correct progress, keeps the user informed at the right level, and asks for intervention only when it is necessary. - -### 4.5 Knowledge should compound - -Every decision, result, failed approach, customer signal, and artifact should improve the system’s understanding of the organization and make future work faster and more accurate. - ---- - -## 5. Core product objects - -The product should use a small set of durable concepts. These concepts should remain stable even as the product expands into new domains. - -## 5.1 Organization - -An organization is a hard business, permission, and knowledge boundary. - -An organization may represent: - -- A company. -- A client. -- A startup. -- An internal business unit. -- A personal software portfolio. - -An organization owns its users, products, policies, integrations, knowledge, work, and history. - -Information must never move between organizations implicitly. - -## 5.2 Product or project - -A product or project is a durable operating context within an organization. - -It may represent: - -- A software product. -- A repository-backed application. -- A client engagement. -- An internal platform. -- A website or service. -- A focused initiative with its own ongoing context. - -A project contains its goals, product knowledge, working conventions, connected sources, relevant people, and active work. - -Projects should reduce context ambiguity without forcing the user to manually maintain complex folder structures. - -## 5.3 Goal - -A goal states what the organization or project is trying to achieve. - -Examples: - -- Reduce onboarding failure. -- Reach a reliability target. -- Launch enterprise support. -- Improve trial-to-paid conversion. -- Close the first ten enterprise customers. - -Goals help the system distinguish valuable work from merely possible work. - -A work unit may support one or more goals, but every important work unit should have a clear reason for existing. - -## 5.4 Signal - -A signal is raw information that may matter. - -Examples: - -- A support ticket. -- A customer comment. -- An error spike. -- A deployment failure. -- A sales objection. -- A message in a team channel. -- An analytics change. -- A founder’s thought in the global conversation. - -A signal is not automatically a task. - -Signals can be: - -- Attached to existing work. -- Converted into candidate work. -- Saved as knowledge. -- Dismissed. -- Marked as irrelevant or duplicated. - -## 5.5 Candidate work - -Candidate work is a proposed work unit that has not yet been accepted as durable active work. - -The system creates candidates when it believes a signal or cluster of signals deserves action. - -A candidate should explain: - -- What outcome is proposed. -- Why it matters. -- Which evidence supports it. -- Which project and goal it belongs to. -- How confident the system is. -- Whether similar work already exists. - -The user can accept, edit, merge, defer, or dismiss it. - -## 5.6 Work unit - -A work unit is the central object of the product. - -It is a persistent, stateful representation of one meaningful outcome. - -A work unit owns: - -- Objective. -- Desired result. -- Scope and non-goals. -- Current understanding. -- Requirements. -- Success criteria. -- Status. -- Priority. -- Dependencies. -- Blockers. -- Decisions. -- Evidence. -- Plan. -- Human actions. -- Agent activity. -- Artifacts. -- Results. -- Learning. - -The work unit persists across multiple conversations, agent runs, people, tools, and time periods. - -A work unit is not identical to: - -- A single prompt. -- A chat thread. -- A single agent session. -- A pull request. -- A checklist item. -- A repository branch. - -Those may all exist inside or underneath a work unit. - -## 5.7 Step - -A step is a bounded action within a work unit. - -Examples: - -- Inspect relevant logs. -- Reproduce the failure. -- Draft an implementation plan. -- Add tests. -- Review a preview. -- Contact affected customers. - -Steps help organize execution, but they should not become another noisy task-management layer. They are visible when useful and hidden when the user only needs the higher-level outcome. - -## 5.8 Run - -A run is one attempt by an agent or workflow to progress a work unit. - -Examples: - -- Research the root cause. -- Implement a change. -- Review a proposed solution. -- Run verification. -- Prepare release material. - -A work unit can have several runs, including parallel or repeated attempts. - -Runs are subordinate to the work unit and should not replace it as the primary product object. - -## 5.9 Artifact - -An artifact is a durable output or piece of evidence produced or collected during work. - -Examples: - -- Pull request. -- Commit. -- Patch. -- Design. -- Specification. -- Test report. -- Screenshot. -- Preview. -- Research memo. -- Customer response draft. -- Launch plan. - -Artifacts should be attached to the work unit and accessible from its history and current state. - -## 5.10 Decision - -A decision records an important human or system choice and the reasoning behind it. - -Examples: - -- Approve a proposed plan. -- Choose one design direction. -- Reject a migration strategy. -- Delay a feature. -- Accept a known limitation. - -Decisions should remain visible after the immediate conversation is over so future agents do not repeat settled debates. - -## 5.11 Approval - -An approval is a specific human permission required before a sensitive or consequential action. - -Examples: - -- Merge code. -- Deploy to production. -- Send a customer message. -- Access sensitive data. -- Spend money. -- Change business policy. - -Approvals should be precise, inspectable, and bounded. The user should know exactly what will happen after approval. - -## 5.12 Result and learning - -A result records what happened after work was completed or published. - -It should compare: - -- Intended outcome. -- Expected impact. -- Actual outcome. -- Measurement period. -- Unexpected effects. -- Recommended follow-up. - -Learning is the reusable knowledge extracted from the work. It should improve future planning and execution across the relevant organization or project. - ---- +Result records post-completion reality, comparing: intended outcome, expected impact, actual outcome, measurement period, unexpected effects, recommended follow-up. Learning = reusable knowledge extracted to improve future planning/execution across the relevant org/project. ## 6. Work lifecycle -Work moves through four broad phases. These phases should remain conceptually consistent across engineering, product, marketing, support, and other domains. +Four conceptually consistent phases across all domains. -## 6.1 Discover +| Phase | The system… | Goal/output | +| --- | --- | --- | +| **Discover** | Extracts, groups, dedupes, connects signals; proposes candidate work; relates to goals/projects. | Identify meaningful work with sufficient evidence/relevance — _not_ the largest backlog. | +| **Understand** | Gathers context — research, code/system inspection, customer evidence, analytics, prior decisions, constraints, open questions, risks, success criteria. | Actionable understanding, not an endless report. | +| **Create & iterate** | Coordinates production — code, specs, designs, docs, tests, customer comms, launch assets, research, business recommendations. Produces intermediate artifacts, verifies, incorporates feedback without losing continuity. | Working solution. | +| **Publish & learn** | Releases/delivers/shares, then follows the outcome — deploy status, error rates, adoption, customer reactions, conversion, support volume, revenue impact, qualitative feedback. | Measured result. | -The system observes conversations and connected information sources to identify problems, opportunities, questions, risks, and requests. - -Discovery includes: - -- Extracting signals. -- Grouping related signals. -- Identifying duplicates. -- Connecting signals to existing work. -- Proposing candidate work. -- Relating work to goals and projects. - -The goal of discovery is not to create the largest possible backlog. It is to identify meaningful work with sufficient evidence and relevance. - -## 6.2 Understand - -The system gathers context and develops a shared model of the problem. - -Understanding may include: - -- Research. -- Code or system inspection. -- Customer evidence. -- Analytics. -- Existing decisions. -- Constraints. -- Open questions. -- Risks. -- Success criteria. - -The result should be an actionable understanding, not an endless research report. - -## 6.3 Create and iterate - -The system coordinates the production of a solution. - -Depending on the work, this can include: - -- Code. -- Product specifications. -- Designs. -- Documentation. -- Tests. -- Customer communication. -- Launch assets. -- Research outputs. -- Business recommendations. - -The system should produce intermediate artifacts, verify progress, and incorporate human feedback without losing the work unit’s continuity. - -## 6.4 Publish and learn - -The solution is released, delivered, shared, or otherwise put into use. - -The system then follows the outcome through: - -- Deployment status. -- Error rates. -- Adoption. -- Customer reactions. -- Conversion. -- Support volume. -- Revenue impact. -- Qualitative feedback. - -The lifecycle ends only when the work has either produced a result, been intentionally stopped, or been superseded by another decision. - ---- +Lifecycle ends only when work produces a result, is intentionally stopped, or is superseded. ## 7. Work-unit boundaries -The quality of the system depends heavily on how it divides work. +Quality depends on how work is divided. -## 7.1 A work unit should represent one independently meaningful outcome +**Good unit** = one independently meaningful outcome, summarizable in one clear sentence, reaches a recognizable result. Good: _fix Safari OAuth callback failures; decide SAML support this quarter; reduce onboarding time-to-first-value; prepare & launch team invitations._ Poor: _improve the product; marketing; work on onboarding; open the repo; read the logs_ (too broad or too granular). -A good work unit can be summarized in one clear sentence and can reach a recognizable result. +**Split when:** multiple independent outcomes; different owners/approval paths; different orgs/permission boundaries; different deadlines/success criteria; one part finishes while another stays active; hard to summarize/review; a child deserves its own lifecycle/result. -Good examples: +**Merge when:** two candidates describe the same outcome; different channels reported the same problem; one candidate is just evidence for an existing unit; neither can be completed independently. System may propose merges; uncertain merges stay reversible/user-reviewable. -- Fix Safari OAuth callback failures. -- Decide whether to support SAML this quarter. -- Reduce time-to-first-value during onboarding. -- Prepare and launch the team invitations feature. - -Poor examples: - -- Improve the product. -- Marketing. -- Work on onboarding. -- Open the repository. -- Read the logs. - -The first group is too broad. The second group is too granular. - -## 7.2 Split work when - -A work unit should be split when: - -- It contains multiple independent outcomes. -- Different parts have different owners or approval paths. -- The parts belong to different organizations or permission boundaries. -- They have different deadlines or success criteria. -- One part can finish while another remains active. -- The work has become difficult to summarize or review. -- A child outcome deserves its own lifecycle and result. - -## 7.3 Merge work when - -Work should be merged when: - -- Two candidates describe the same underlying outcome. -- Different channels produced duplicate reports of the same problem. -- One candidate is merely evidence for an existing unit. -- Neither item can be meaningfully completed independently. - -The system may propose a merge, but uncertain merges should remain reversible and user-reviewable. - -## 7.4 Parent and child work - -Large initiatives may contain child work units. - -A parent should represent a larger result, while each child still has an independently meaningful outcome. - -Example: - -**Parent initiative:** Restore OAuth reliability - -- Fix Safari callback failures. -- Improve OAuth setup diagnostics. -- Update documentation. -- Notify affected customers. -- Monitor setup completion after release. - -Parent units should summarize progress and dependencies without replacing the detail of their children. - ---- +**Parent/child:** large initiatives contain child units; parent = larger result, each child still independently meaningful. _Parent: Restore OAuth reliability → children: fix Safari callbacks, improve setup diagnostics, update docs, notify customers, monitor post-release completion._ Parent summarizes progress/dependencies without replacing child detail. ## 8. Conversation model -The product uses one persistent conversational surface with two scopes. +One persistent conversational surface, two scopes. -## 8.1 Global conversation +| Scope | Use | +| --- | --- | +| **Global** | Think/act across workspace: introduce ideas/problems, ask what needs attention, compare work across projects, reprioritize, create/modify work, request summaries, discuss dependencies, request research/execution. System auto-connects messages to relevant projects/units while preserving source. | +| **Contextual** | Same composer focused on one work unit: add requirements, answer questions, review progress, change direction, approve a plan, request another attempt, ask for explanation, continue from an artifact. Entering does **not** create a new thread — it changes the active scope. | -Global conversation is used to think and act across the workspace. - -The user can: - -- Introduce new ideas or problems. -- Ask what needs attention. -- Compare work across projects. -- Reprioritize. -- Create or modify work. -- Ask for summaries. -- Discuss dependencies. -- Request new research or execution. - -The system should automatically connect global messages to relevant projects and work units while preserving the original source. - -## 8.2 Contextual conversation - -Contextual conversation focuses the same composer and interaction model on one work unit. - -The user can: - -- Add requirements. -- Answer questions. -- Review progress. -- Change direction. -- Approve a plan. -- Request another attempt. -- Ask for explanation. -- Continue work from an artifact. - -Entering contextual conversation should not create a new thread. It changes the active scope of the persistent workspace. - -## 8.3 Conversation boundaries - -Conversation should not be the source of truth for work state. - -Important facts, decisions, requirements, approvals, artifacts, and results should be extracted into structured product objects while preserving links to their source conversation. - ---- +Conversation is not the source of truth. Important facts/decisions/requirements/approvals/artifacts/results are extracted into structured objects while preserving links to source conversation. ## 9. Autonomous behavior -The product should continuously observe, understand, organize, execute, escalate, and learn. +The system continuously observes, understands, organizes, executes, escalates, learns. -## 9.1 The system may autonomously +**May autonomously:** attach new evidence; update summaries/understanding; detect stale/blocked work; propose new work; run safe research; prepare plans/drafts; produce code/artifacts inside approved boundaries; run verification; suggest priorities; monitor completed work; create follow-up candidates; summarize activity. -- Attach new evidence to existing work. -- Update summaries and understanding. -- Detect stale or blocked work. -- Propose new work. -- Run safe research. -- Prepare plans and drafts. -- Produce code or other artifacts inside approved boundaries. -- Run verification. -- Suggest priorities. -- Monitor completed work. -- Create follow-up candidates. -- Summarize activity for the user. +**Request human for:** strategic direction; ambiguous product decisions; business tradeoffs; sensitive permissions; high-risk actions; external communication; production changes; priority conflicts; conflicting evidence; actions outside granted policy. -## 9.2 The system should request human involvement for +**Must not:** create speculative work without evidence; treat confidence as certainty; hide failures/uncertainty; silently cross org boundaries; reopen settled decisions without new evidence; perform irreversible actions without authority; optimize for activity over outcomes. -- Strategic direction. -- Ambiguous product decisions. -- Business tradeoffs. -- Sensitive permissions. -- High-risk actions. -- External communication. -- Production changes. -- Priority conflicts. -- Conflicting evidence. -- Actions outside previously granted policy. +## 10. Human-in-the-loop -## 9.3 The system should not +User must not inspect every unit to find what needs attention. Human requests centralize into an **Attention Queue**. Each request states: what's required, why, the recommendation, supporting evidence, what happens after approval, what happens if the user does nothing, urgency, reversibility. **Categories:** decision · approval · clarification · access request · review · blocker resolution · risk alert. -- Create large amounts of speculative work without evidence. -- Treat confidence as certainty. -- Hide failures or uncertainty. -- Silently cross organization boundaries. -- Reopen settled decisions without new evidence. -- Perform irreversible actions without appropriate authority. -- Optimize for activity instead of outcomes. +Minimize unnecessary approvals via explicit standing policies while preserving clear control over sensitive actions. ---- +## 11. Provenance & trust -## 10. Human-in-the-loop model - -The user should not have to inspect every work unit to find what requires attention. - -The product should centralize human requests into an **Attention Queue**. - -Each request should explain: - -- What is required. -- Why it is required. -- What the system recommends. -- What evidence supports the recommendation. -- What will happen after approval. -- What happens if the user does nothing. -- How urgent the request is. -- Whether the action is reversible. - -Human requests fall into several categories: - -- Decision. -- Approval. -- Clarification. -- Access request. -- Review. -- Blocker resolution. -- Risk alert. - -The product should minimize unnecessary approvals by supporting explicit standing policies, while preserving clear control over sensitive actions. - ---- - -## 11. Provenance and trust - -The user must be able to understand why the system believes something and what caused an action. - -Every important claim should carry provenance. - -Provenance may include: - -- Source message. -- Customer ticket. -- Repository change. -- Error report. -- Analytics event. -- Document. -- Agent observation. -- Human decision. - -Claims should be distinguishable as: - -- Verified. -- Reported. -- Inferred. -- Assumed. -- Conflicting. -- Outdated. - -The primary interface should remain readable, but deeper evidence and derivation should be available on demand. - -The system should never present an agent-generated summary as equivalent to primary evidence. - ---- +User must understand why the system believes something and what caused an action. **Every important claim carries provenance.** Sources: message, ticket, repo change, error report, analytics event, document, agent observation, human decision. Claim status distinguished as: verified · reported · inferred · assumed · conflicting · outdated. Primary interface stays readable; deeper evidence/derivation available on demand. **Never present an agent summary as equivalent to primary evidence.** ## 12. Knowledge model -Zopo should accumulate several kinds of organizational knowledge. +Accumulates several kinds; each retains its scope (personal prefs, project facts, org-wide truths never mixed blindly). -### 12.1 Canonical knowledge - -Durable, reviewed descriptions of: - -- Business. -- Product. -- Customers. -- Design principles. -- Architecture concepts. -- Working conventions. -- Policies. -- Goals. - -### 12.2 Operational knowledge - -Current structured state: - -- Active work. -- Priorities. -- Dependencies. -- Ownership. -- Blockers. -- Approvals. -- Results. - -### 12.3 Episodic knowledge - -What happened over time: - -- Conversations. -- Runs. -- Errors. -- Decisions. -- Reviews. -- Releases. -- Customer reactions. - -### 12.4 Learned patterns - -Reusable conclusions such as: - -- Common causes of failure. -- Customer preferences. -- Repeated objections. -- Effective launch patterns. -- Known limitations. -- Preferred technical and product approaches. - -Knowledge should always retain its scope. Personal preferences, project-specific facts, and organization-wide truths should not be mixed blindly. - ---- +| Kind | Content | +| --- | --- | +| **Canonical** | Reviewed descriptions: business, product, customers, design principles, architecture concepts, conventions, policies, goals. | +| **Operational** | Current structured state: active work, priorities, dependencies, ownership, blockers, approvals, results. | +| **Episodic** | History: conversations, runs, errors, decisions, reviews, releases, customer reactions. | +| **Learned patterns** | Reusable conclusions: common failure causes, customer prefs, repeated objections, effective launch patterns, known limitations, preferred technical/product approaches. | ## 13. Product boundaries -## 13.1 Zopo is the control layer, not the replacement for every specialist tool +| Boundary | Rule | +| --- | --- | +| **Control layer, not tool replacement** | Specialist systems (source control, support, comms, analytics, billing, deployment, docs) keep native records/actions. Zopo provides the unified model: what matters, its state, next step, whether outcome worked. | +| **Own the work graph** | Connects organizations→projects→goals→signals→work units→dependencies→decisions→runs→artifacts→results→learnings. Durable source of coordination/context. | +| **Execution is replaceable** | Execution is a capability beneath the work unit. Users shouldn't care which agent/model/harness ran unless inspection is useful. | +| **No unnecessary AI config** | Users shouldn't normally choose model, thinking level, agent framework, context-window strategy, execution runtime, tool routing. System chooses by task/risk/cost/policy. | -Specialist systems may continue to own their native records and actions. +## 14. Optimization -Examples include: +**Optimize for: maximum useful progress with minimum required human attention.** -- Source control. -- Customer support. -- Team communication. -- Analytics. -- Billing. -- Deployment. -- Documents. +Measures: correct extraction of meaningful work; low false-positive candidates; signal→understanding time; time to first useful action; accepted units reaching meaningful outcomes; reduced repeated context gathering; human attention per outcome; decision/output quality; trust/inspectability/reversibility; knowledge reuse; improvement from past results. -Zopo should provide the unified model of what matters, what state it is in, what should happen next, and whether the outcome worked. +**Don't primarily optimize:** chat count, time in interface, task count, agent-run count, notification count, raw model usage. -## 13.2 Zopo should own the work graph +A successful day: user opens briefly, resolves a few high-value decisions, sees many units progressed correctly without them. -The work graph connects: +## 15. Business value -- Organizations. -- Projects. -- Goals. -- Signals. -- Work units. -- Dependencies. -- Decisions. -- Runs. -- Artifacts. -- Results. -- Learnings. +| Form | Value | +| --- | --- | +| **Execution capacity** | Small team progresses more work without proportional headcount. | +| **Coordination reduction** | Handles repetitive context-gathering, state updates, linking, follow-ups, output prep. | +| **Continuity** | Work keeps context, history, decisions, artifacts across tools/time. | +| **Better opportunity capture** | Notices recurring problems, customer opportunities, operational risks, key relationships teams otherwise miss. | -This graph is the product’s durable source of coordination and context. +## 16. Initial scope — first product loop -## 13.3 Execution systems are replaceable +1. User starts/connects a software project. +2. Product establishes project context. +3. User describes desired work via global composer. +4. System creates/updates a work unit. +5. Unit is clarified and accepted. +6. System progresses work autonomously. +7. User reviews only necessary decisions/outputs. +8. System produces verified artifacts. +9. User approves publication/integration where required. +10. Product updates the unit and retains knowledge. -The product should present execution as a capability beneath the work unit. Users should not have to care which internal agent, model, or harness performed a run unless inspection is useful. +First version must prove persistent work units beat disposable agent chats. -## 13.4 The product should not expose unnecessary AI configuration +## 17. Long-term direction -Users should not normally need to choose: +Technical product is the starting point. The same work-unit model later supports: product research, marketing campaigns, content production, sales enablement, support operations, pricing work, business analysis, hiring, internal ops. Long-term: a general OS for creative/knowledge work. -- Model. -- Thinking level. -- Agent framework. -- Context-window strategy. -- Execution runtime. -- Tool routing. +**Enduring principles:** one persistent workspace · work units not chat sessions · outcome-oriented execution · invisible orchestration · explicit human authority · strong provenance · compounding organizational knowledge. -The system should choose automatically based on task, risk, cost, and policy. +## 18. Initial non-goals ---- +Not intended to be: a full external-tool replacement; a general social collaboration platform; a traditional kanban with AI decoration; a model playground; a prompt-management product; a marketplace of visible agents; a system that creates work faster than users can evaluate; a fully autonomous company with no human authority. -## 14. Product optimization +## 19. Principles -The product should optimize for: +1. Organize around work, not conversations. +2. Represent outcomes, not activity. +3. Keep the system calm while the machinery stays powerful. +4. Bring humans in for judgment, not clerical coordination. +5. Expose evidence and uncertainty. +6. Make important actions understandable and reversible. +7. Preserve organization and project boundaries. +8. Prefer one coherent model over many disconnected features. +9. Let knowledge compound across completed work. +10. Measure success by outcomes and reduced attention. -> Maximum useful progress with minimum required human attention. +## 20. Working statement -Key product measures include: - -- Correct extraction of meaningful work. -- Low false-positive candidate creation. -- Time from signal to structured understanding. -- Time to first useful action. -- Accepted work units reaching meaningful outcomes. -- Reduction in repeated context gathering. -- Human attention required per completed outcome. -- Quality of decisions and outputs. -- Trust, inspectability, and reversibility. -- Reuse of accumulated knowledge. -- Improvement in future work from past results. - -The product should not primarily optimize for: - -- Number of chats. -- Time spent in the interface. -- Number of tasks created. -- Number of agent runs. -- Number of notifications. -- Raw model usage. - -A successful day may involve the user opening the product briefly, resolving a few high-value decisions, and seeing that many other units progressed correctly without them. - ---- - -## 15. Business value delivered through the product - -Zopo provides four forms of value. - -### 15.1 Execution capacity - -A small team can progress more work without proportionally increasing headcount. - -### 15.2 Coordination reduction - -The product handles the repetitive work of gathering context, updating state, linking related information, following up, and preparing outputs. - -### 15.3 Continuity - -Work keeps its context, history, decisions, and artifacts across tools and time. - -### 15.4 Better opportunity capture - -The system notices recurring problems, customer opportunities, operational risks, and important relationships that the team may otherwise miss. - ---- - -## 16. Initial product scope - -The first strong product loop should be: - -1. The user starts or connects a software project. -2. The product establishes project context. -3. The user describes desired work through the global composer. -4. The system creates or updates a work unit. -5. The work unit is clarified and accepted. -6. The system progresses the work autonomously. -7. The user reviews only necessary decisions and outputs. -8. The system produces verified artifacts. -9. The user approves publication or integration where required. -10. The product updates the work unit and retains the resulting knowledge. - -The first version should prove that persistent work units are a better product structure than disposable agent chats. - ---- - -## 17. Long-term product direction - -The technical product is the starting point, not the final boundary. - -The same work-unit model can later support: - -- Product research. -- Marketing campaigns. -- Content production. -- Sales enablement. -- Customer support operations. -- Pricing work. -- Business analysis. -- Hiring. -- Internal operations. - -The long-term vision is a general operating system for creative and knowledge work. - -The enduring principles are: - -- One persistent workspace. -- Work units instead of chat sessions. -- Outcome-oriented execution. -- Invisible orchestration. -- Explicit human authority. -- Strong provenance. -- Compounding organizational knowledge. - ---- - -## 18. Non-goals for the initial product - -The initial product is not intended to be: - -- A full replacement for every external tool. -- A general-purpose social collaboration platform. -- A traditional kanban board with AI decoration. -- A model playground. -- A prompt-management product. -- A marketplace of visible agents. -- A system that creates work faster than users can evaluate it. -- A fully autonomous company with no human authority. - ---- - -## 19. Product principles - -1. **Organize around work, not conversations.** -2. **Represent outcomes, not activity.** -3. **Keep the system calm while the machinery remains powerful.** -4. **Bring humans in for judgment, not clerical coordination.** -5. **Expose evidence and uncertainty.** -6. **Make important actions understandable and reversible.** -7. **Preserve organization and project boundaries.** -8. **Prefer one coherent model over many disconnected features.** -9. **Let knowledge compound across completed work.** -10. **Measure success by outcomes and reduced attention.** - ---- - -## 20. Working product statement - -Zopo Work OS is an autonomous operating system for technical founders and small product teams. It observes work across the company, turns fragmented signals into persistent units of work, progresses those units using agents and tools, and brings the human in only when judgment, permission, or direction is required. - -It gives the user one continuous workspace for moving from idea or problem to verified, shipped, measurable outcome while preserving context and building a durable understanding of the company over time. +Zopo Work OS is an autonomous OS for technical founders and small product teams. It observes work across the company, turns fragmented signals into persistent units of work, progresses them via agents and tools, and brings the human in only when judgment, permission, or direction is required. One continuous workspace moves from idea/problem to verified, shipped, measurable outcome while preserving context and building durable understanding over time. diff --git a/docs/TECH.md b/docs/TECH.md index e10ec54..72a5e44 100644 --- a/docs/TECH.md +++ b/docs/TECH.md @@ -1,233 +1,48 @@ - # Zopo Work OS — Technical Architecture -> Status: working technical specification -> Audience: engineering, platform, infrastructure, security, and agent teams -> Scope: technical architecture, runtime boundaries, data flow, execution, security, scaling, and implementation decisions -> Assumption: the application begins from an existing Better-T-Stack monorepo with web and Expo applications plus shared packages +> Working spec · engineering/platform/infra/security/agent teams · starts from an existing Better-T-Stack monorepo (web + Expo + shared packages). -## 1. Technical objective +**Objective.** Multi-tenant Work OS: durable orgs/projects/goals/work units/runs/artifacts/outcomes; one global conversation + scoped work-unit conversations; continuous candidate-work extraction from conversation and connected systems; coding agents in isolated reproducible environments; autonomous execution with explicit human-approval boundaries; agent progress streamed into durable state; inspectable artifacts (commits, PRs, test reports, previews, docs, reviews); scales across orgs/repos/concurrent units/environments; harnesses and model providers replaceable. -Build a multi-tenant Work OS that: +**Central ownership rule.** Work OS owns intent + durable state · Flow agents own orchestration · AgentOS owns agent runtime coordination · Harnesses own individual agent loops · Sandboxes own full-system execution · Git owns source history · Artifact storage owns generated outputs. -- Maintains durable organizations, projects, goals, work units, runs, artifacts, and outcomes. -- Provides one global conversation and scoped work-unit conversations. -- Extracts candidate work continuously from conversation and connected systems. -- Runs coding agents inside isolated, reproducible environments. -- Supports autonomous execution while preserving explicit human approval boundaries. -- Streams agent progress into durable work-unit state. -- Produces inspectable artifacts such as commits, pull requests, test reports, previews, documents, and review notes. -- Scales across many organizations, repositories, concurrent work units, and execution environments. -- Keeps execution harnesses and model providers replaceable. +## 1. High-level architecture -The central architectural rule is: - -> Work OS owns intent and durable state. Flow agents own orchestration. AgentOS owns agent runtime coordination. Harnesses own individual agent loops. Sandboxes own full-system execution. Git owns source history. Artifact storage owns generated outputs. - ---- - -## 2. High-level architecture - -Separate the system into a **control plane** and an **execution plane**. +Control plane + execution plane. ```mermaid flowchart TB - User[User] - - subgraph Client[Client applications] - Web[Web application] - Mobile[Expo application] - end - - subgraph Edge[Application edge] - API[Application API] - Realtime[Realtime gateway] - end - - subgraph Control[Control plane] - Auth[Identity and tenancy] - WorkGraph[Work graph and relational state] - Conversation[Conversation service] - Flow[Zopo Flow Agent] - Context[Context assembler and memory] - Policy[Policy and approval engine] - Scheduler[Run scheduler and workflow engine] - Events[Event and provenance log] - Notifications[Attention and notification service] - end - - subgraph Shared[Shared services] - Git[Managed or connected Git] - Gateway[Model gateway] - Integrations[Executor / integration gateway] - Secrets[Secrets and workload identity broker] - Artifact[Artifact and object storage] - Search[Retrieval and indexing] - Preview[Preview routing gateway] - Observability[Logs metrics traces and billing] - end - - subgraph Execution[Execution plane] - Actor[AgentOS run actor] - Harness[OpenCode or other ACP harness] - Sandbox[Full Linux sandbox] - Runtime[Project services browsers tests builds] - end - - User --> Web - User --> Mobile - Web --> API - Mobile --> API - Web <--> Realtime - Mobile <--> Realtime - - API --> Auth - API --> WorkGraph - API --> Conversation - API --> Policy - - Conversation --> Flow - WorkGraph --> Flow - Flow --> Context - Flow --> Scheduler - Flow --> Policy - Flow --> Gateway - Flow --> Integrations - - Scheduler --> Actor - Actor <--> Harness - Actor <--> Sandbox - Harness --> Gateway - Harness --> Integrations - Sandbox --> Git - Sandbox --> Runtime - Runtime --> Preview - - Actor --> Events - Sandbox --> Events - Git --> Events - Events --> WorkGraph - Events --> Realtime - Events --> Observability - Artifact --> WorkGraph - Context --> Search - WorkGraph --> Search - Policy --> Notifications + User --> Web[Web] & Mobile[Expo] + Web & Mobile --> API[App API] & Realtime + API --> Auth[Identity/tenancy] & WorkGraph[Work graph] & Conversation & Policy + Conversation & WorkGraph --> Flow[Flow Agent] + Flow --> Context & Scheduler & Policy & Gateway[Model gateway] & Integrations & Secrets[Secrets/workload identity broker] + Scheduler --> Actor[AgentOS run actor] + Actor <--> Harness[OpenCode/ACP] & Sandbox[Full Linux sandbox] + Harness --> Gateway & Integrations + Sandbox --> Git & Runtime[Services/browsers/tests/builds] + Actor & Sandbox --> Secrets + Runtime --> Preview + Actor & Sandbox & Git --> Events[Event/provenance log] + Events --> WorkGraph & Realtime & Observability + Artifact[Object storage] --> WorkGraph + Context & WorkGraph --> Search + Policy --> Notifications ``` ---- +## 2. Components & ownership -## 3. System components and ownership +**Client apps (web, Expo)** — product surfaces only: render org/project/work-unit/run/artifact/attention state; send domain commands via app API; subscribe realtime; upload via signed/brokered flows. Never reach model providers, Git internals, harnesses, or sandboxes directly. Commands: create work unit, continue work, change composer scope, approve plan, resolve blocker, review artifact, request changes, pause/cancel run, approve merge, approve deployment. -## 3.1 Client applications +**Application API** — sole public backend: authz; org/project scoping; CRUD stable entities; command validation; conversation ingestion; attachment metadata; card/workspace/activity/attention queries; realtime-subscription authz; idempotency. Never expose internal runtime APIs. -The web and Expo applications are product surfaces only. +**Identity & tenancy** — one Work OS identity per user; organizations are hard tenant boundaries. Every durable/transient entity carries `organization_id` (+ `project_id`/`work_unit_id`/`run_id` where applicable). Deny-by-default authz on every command/query. Cross-org queries are explicit portfolio ops; never blend underlying knowledge/execution context. -They should: +**Secrets & workload-identity broker** — shared service owning short-lived run identities and scoped credential minting/injection for Git, model gateway, integrations, artifact storage, preview routing, and optional cloud access; secrets remain outside repositories/actor state, and broker decisions are policy-bound and auditable. -- Render organization, project, work-unit, run, artifact, and attention state. -- Send user commands through the application API. -- Subscribe to realtime updates. -- Upload attachments through signed or brokered flows. -- Never connect directly to model providers, Git internals, agent harnesses, or sandboxes. +**Work graph (canonical product DB)** — relational DB (authoritative) + event table (append-only provenance/replay) + materialized projections (cards, attention, portfolio, activity) + object storage (large artifacts) + search index. Entities: User, Organization, Membership, Project, Project source, Goal, Signal, Candidate, Work unit, Work-unit relation, Step, Run, Run attempt, Agent session, Blocker, Decision, Approval, Artifact, Source reference, Result, Learning, Conversation message, Composer scope, Integration connection, Policy, Workload identity. Work-unit record = structured fields + projections, **not** a big agent-authored JSON blob. -The frontend should issue domain commands such as: - -- Create work unit. -- Continue work. -- Change composer scope. -- Approve plan. -- Resolve blocker. -- Review artifact. -- Request changes. -- Pause run. -- Cancel run. -- Approve merge. -- Approve deployment. - -## 3.2 Application API - -The application API is the only public backend interface used by product clients. - -Responsibilities: - -- Authentication and authorization. -- Organization and project scoping. -- CRUD for stable domain entities. -- Domain command validation. -- Conversation ingestion. -- Attachment metadata. -- Query endpoints for cards, workspaces, activity, and attention. -- Realtime subscription authorization. -- Idempotency handling. - -Avoid exposing internal runtime APIs directly through the application surface. - -## 3.3 Identity and tenancy - -A user has one Work OS identity. - -Organizations are hard tenancy boundaries. - -Every durable and transient entity must include explicit tenant scope: - -- `organization_id` -- `project_id` where applicable -- `work_unit_id` where applicable -- `run_id` where applicable - -Authorization should be deny-by-default and evaluated on every command and query. - -Cross-organization queries must be explicit portfolio-level operations and must not blend underlying knowledge or execution context. - -## 3.4 Work graph and relational state - -The work graph is the canonical product database. - -Recommended initial implementation: - -- Relational database for authoritative state. -- Event table for append-only provenance and replay. -- Materialized projections for cards, attention, portfolio summaries, and activity feeds. -- Object storage for large artifacts. -- Search index for retrieval. - -Core entities: - -- User. -- Organization. -- Membership. -- Project. -- Project source. -- Goal. -- Signal. -- Candidate. -- Work unit. -- Work-unit relation. -- Step. -- Run. -- Run attempt. -- Agent session. -- Blocker. -- Decision. -- Approval. -- Artifact. -- Source reference. -- Result. -- Learning. -- Conversation message. -- Composer scope. -- Integration connection. -- Policy. -- Workload identity. - -The work-unit record should not be a large agent-authored JSON blob. Store meaningful structured fields and derive summaries through explicit projections. - -## 3.5 Event and provenance log - -All meaningful system changes should be represented as events. - -Example event envelope: +**Event & provenance log** — all meaningful changes are events. Envelope: ```json { @@ -250,1302 +65,187 @@ Example event envelope: } ``` -Requirements: +Requirements: monotonic sequence per run/actor stream; idempotent ingestion; immutable original payload; normalized derived state; trace card→events; distinguish raw evidence vs agent interpretation vs human decision. -- Monotonic sequence per run or actor stream. -- Idempotent ingestion. -- Immutable original payload. -- Normalized derived state. -- Traceability from card state to supporting events. -- Explicit distinction between raw evidence, agent interpretation, and human decision. +**Conversation service** — persistent conversation per user workspace, scoped. Message fields: org scope (+optional project/work-unit scope), author, content blocks, attachments, source references, extraction status, domain-event links. Persist exact user message; publish for extraction/orchestration; global + work-unit scope without new sessions; one message may reference several work units; preserve source links when structured state is extracted. -## 3.6 Conversation service +**Flow Agent (orchestration above specialist agents)** — interpret intent; extract signals/candidates; match new info to existing work; detect duplicates/relationships; build/update work briefs; decide whether a human question is required; select execution strategy; create runs; monitor run events; retry/fallback/escalate; summarize into work-unit state; create approval requests; propose follow-ups. Not the sole durable truth — outputs validated into commands/events. Does not directly mutate repos; coding is delegated to a harness in an isolated environment. -The system maintains a persistent conversation per user workspace with scoped context. +**Memory classes (four)** -Messages should contain: +- _Canonical project knowledge_ (versioned/reviewable, prefer in Git): `product.md`, `design.md`, `tech.md`, `business.md`, `AGENTS.md`, READMEs, decision records, repo-local conventions. +- _Structured operational memory_ (DB): goals, work-unit state, requirements, decisions, approvals, blockers, dependencies, results. +- _Episodic memory_ (events/transcripts): user messages, agent runs, tool calls, errors, reviews, deployments, human interventions. +- _Retrieval index_ (derived, non-authoritative → returns source refs): canonical docs, repo content, conversation, work-unit events, artifacts, connected external sources. -- Organization scope. -- Optional project scope. -- Optional work-unit scope. -- Author. -- Content blocks. -- Attachments. -- Source references. -- Extraction status. -- Relationship to domain events. +**Context assembly** — never inject all knowledge. Run context pack by precedence: (1) org policy (2) project goals + canonical context (3) repo conventions/instructions (4) work-unit objective/requirements/decisions (5) relevant evidence/artifacts (6) current run instructions (7) runtime + tool constraints. Each item retains source, scope, timestamp, confidence/verification status, revision id. Deterministic enough to audit/reproduce. -The conversation service should: +**Policy & approval engine** (above harness permissions + runtime capabilities) — per action: auto-allowed / allowed under standing policy / requires human approval / denied. Examples: create branch, push work branch, create PR → automatic; merge → approval; deploy preview → automatic; deploy production → approval; never send customer comms without review; never access prod data from a default coding run. Approval record = exact action, params, requested capability, evidence/rationale, risk level, expiration, user decision, resulting action event. -- Persist the exact user message. -- Publish it for extraction and orchestration. -- Support global and work-unit scope without creating new sessions. -- Allow one message to reference several work units. -- Preserve source links when structured state is extracted. +**Run scheduler / workflow engine** — converts accepted work → bounded runs. Owns queue, tenant quotas, priority, fairness, concurrency limits, run leasing, retry policy, budget allocation, cancellation, workflow checkpoints, waiting-for/resuming-after approvals. Run = idempotent steps; persist progress before waiting on human input. -## 3.7 Zopo Flow Agent +**AgentOS runtime** — durable supervisor/harness runtime per active run. One actor per active run or isolated workbox (never one giant actor per user/org); durable run-environment identity; harness session lifecycle; event streaming; permission requests; lightweight fs/process coordination; sleep/wake when safe. Actor key: `org:{orgId}:project:{projectId}:work:{workUnitId}:run:{runId}`. Durable work unit survives actor destruction/replacement. -The Flow Agent is the orchestration layer above specialist agents. +**Agent harness** — OpenCode is the initial coding harness (architecture supports other ACP-compatible/adapted harnesses later). Harness owns: model interaction loop, tool selection, repo inspection, file editing, shell requests, local reasoning state, session progress. Harness does **not** own: product work-unit state, org policy, billing, global memory, project permissions, long-term artifact retention. Drive OpenCode through AgentOS; never expose its standalone server to product clients. -Responsibilities: +**Full Linux sandbox** — compatibility/heavy-execution environment: repo checkout, writable branch/worktree, native binaries, package install, language runtimes, DBs, browser automation, dev servers, tests/builds, file watching, preview processes. AgentOS supervises via explicit adapters/bindings. Division: -- Interpret user intent. -- Extract signals and candidate work. -- Match new information to existing work. -- Detect duplicates and relationships. -- Build or update work briefs. -- Decide whether a human question is required. -- Select an execution strategy. -- Create runs. -- Monitor run events. -- Handle retry, fallback, or escalation decisions. -- Summarize results into work-unit state. -- Create approval requests. -- Propose follow-up work. - -The Flow Agent must not be the sole source of durable truth. Its outputs are validated into domain commands and events. - -It should not directly mutate repositories. Coding work is delegated to a harness running in an isolated execution environment. - -## 3.8 Context and memory layer - -Use four memory classes. - -### Canonical project knowledge - -Versioned, reviewable documents such as: - -- `product.md` -- `design.md` -- `tech.md` -- `business.md` -- `AGENTS.md` -- README files -- decision records -- repository-local conventions - -Prefer storing project-level canonical knowledge in Git alongside the project when practical. - -### Structured operational memory - -Stored in the database: - -- Goals. -- Work-unit state. -- Requirements. -- Decisions. -- Approvals. -- Blockers. -- Dependencies. -- Results. - -### Episodic memory - -Stored as events and transcripts: - -- User messages. -- Agent runs. -- Tool calls. -- Errors. -- Reviews. -- Deployments. -- Human interventions. - -### Retrieval index - -A derived index over: - -- Canonical documents. -- Repository content. -- Conversation. -- Work-unit events. -- Artifacts. -- Connected external sources. - -The retrieval index is not authoritative. It returns source references that are assembled into a run-specific context pack. - -## 3.9 Context assembly - -Do not inject all available knowledge into every run. - -Build a **run context pack** using explicit precedence: - -1. Organization policy. -2. Project goals and canonical context. -3. Repository conventions and instructions. -4. Work-unit objective, requirements, and decisions. -5. Relevant evidence and artifacts. -6. Current run instructions. -7. Runtime and tool constraints. - -Every context item should retain: - -- Source. -- Scope. -- Timestamp. -- Confidence or verification status. -- Revision identifier when applicable. - -Context assembly should be deterministic enough to audit and reproduce. - -## 3.10 Policy and approval engine - -The policy engine sits above harness permissions and runtime capabilities. - -It determines whether an action is: - -- Automatically allowed. -- Allowed under standing policy. -- Requires human approval. -- Denied. - -Policy examples: - -- Create branch automatically. -- Push work branch automatically. -- Create pull request automatically. -- Merge only with approval. -- Deploy preview automatically. -- Deploy production only with approval. -- Never send customer communication without review. -- Never access production data from a default coding run. - -Approval records must include: - -- Exact requested action. -- Parameters. -- Requested capability. -- Evidence and rationale. -- Risk level. -- Expiration. -- User decision. -- Resulting action event. - -## 3.11 Run scheduler and workflow engine - -The scheduler converts accepted work into bounded execution runs. - -Responsibilities: - -- Queue management. -- Tenant quotas. -- Priority. -- Fairness. -- Concurrency limits. -- Run leasing. -- Retry policy. -- Budget allocation. -- Cancellation. -- Workflow checkpoints. -- Waiting for approvals. -- Resuming after approval. - -Run lifecycle: - -```text -queued -→ provisioning -→ preparing -→ running -→ waiting_for_input | verifying | failed | cancelled -→ succeeded +``` +AgentOS: durable run identity, harness session, approvals, lightweight coordination +Sandbox: full repo fs, native commands, services, browser, tests, builds ``` -A run should use idempotent steps and persist progress before waiting on human input. +Known first-party templates may run in lighter env; imported arbitrary repos default to full sandbox. -## 3.12 AgentOS runtime +**Workbox** (product-neutral term for execution capsule beneath a run) — contains repo checkout, isolated branch, runtime recipe, harness config, project skills, temp credentials, running services, preview endpoints, test outputs. Ephemeral/replaceable; work unit is durable. Default isolation: **one writable checkout per active work unit / mutating run**. Parallel read-only runs may share immutable snapshots; parallel mutating runs use separate branches + separate Workboxes. -AgentOS is the durable supervisor and harness runtime for an active run. +**Git (managed/connected)** — source history. Creation modes: managed template, connect external, import+mirror, managed-first then add external remote. Identity: one Work OS user identity, internal service identities for automation, repo-scoped short-lived credentials, no second visible Git account for users. Branching: `main` + `work/{W-id}/{slug}`. Git may be hidden in product but user retains portability (export, clone, patch download, external remotes). -Recommended scope: +**Project templates** — React web, Hono, Express, full-stack, API-only, Expo, monorepo starter. Template defines: source files, runtime versions, install/test/verify/dev commands, service ports, preview behavior, project context prompts, default policies, agent skills. Generates a reusable base snapshot after successful setup+verification. -- One AgentOS actor per active run or isolated workbox. -- Durable identity for the run environment. -- Harness session lifecycle. -- Event streaming. -- Permission requests. -- Lightweight filesystem and process coordination. -- Sleep and wake when safe. +**Project config files** — repo structure: -Do not use one giant actor per user or organization. - -The actor key should include tenant and work scope, for example: - -```text -org:{orgId}:project:{projectId}:work:{workUnitId}:run:{runId} +``` +/ README.md, AGENTS.md, product.md, design.md, tech.md +/.zopo/ project.yaml, services.yaml, policies.yaml + lifecycle/{setup,resume,verify,preview} skills/{testing,reviewing,deploying}/SKILL.md +/apps/ ``` -The durable work unit must survive destruction or replacement of its execution actor. - -## 3.13 Agent harness - -OpenCode is the initial coding harness. - -The architecture should support other ACP-compatible or adapted harnesses later. - -The harness owns: - -- Model interaction loop. -- Tool selection. -- Repository inspection. -- File editing. -- Shell requests. -- Local reasoning state. -- Session-level progress. - -The harness does not own: - -- Product work-unit state. -- Organization policy. -- Billing. -- Global memory. -- Project permissions. -- Long-term artifact retention. - -Prefer controlling OpenCode through AgentOS rather than exposing its standalone server directly to product clients. - -## 3.14 Full Linux sandbox - -A full sandbox is the compatibility and heavy-execution environment. - -It provides: - -- Repository checkout. -- Writable branch or worktree. -- Native binaries. -- Package installation. -- Language runtimes. -- Databases. -- Browser automation. -- Dev servers. -- Tests and builds. -- File watching when required. -- Preview processes. - -AgentOS should supervise and communicate with the sandbox through explicit adapters or bindings. - -Recommended division: - -```text -AgentOS -- durable run identity -- harness session -- approvals -- lightweight coordination - -Sandbox -- full repository filesystem -- native commands -- services -- browser -- tests -- builds -``` - -For known first-party templates, some work may run directly in the lighter environment. Imported arbitrary repositories should default to a full sandbox. - -## 3.15 Workbox - -A Workbox is the product-neutral internal term for the execution capsule beneath a run. - -A Workbox contains: - -- Repository checkout. -- Isolated branch. -- Runtime recipe. -- Harness configuration. -- Project skills. -- Temporary credentials. -- Running services. -- Preview endpoints. -- Test outputs. - -A Workbox is ephemeral or replaceable. The work unit is durable. - -Default isolation rule: - -> One writable checkout per active work unit or mutating run. - -Parallel read-only runs may share immutable snapshots. Parallel mutating runs should use separate branches and separate Workboxes. - -## 3.16 Managed or connected Git - -Git is the source history layer. - -Project creation modes: - -- Create from a managed template repository. -- Connect an external repository. -- Import and mirror an existing repository. -- Start with managed Git and add an external remote later. - -Identity model: - -- One Work OS user identity. -- Internal service identities for automation. -- Repository-scoped, short-lived credentials. -- No requirement for users to manage a second visible Git account. - -Branching model: - -```text -main -├── work/W-102/oauth-fix -├── work/W-103/team-invitations -└── work/W-104/pricing-copy -``` - -Git may remain hidden in the product surface, but the user must retain portability through export, clone access, patch download, or external remotes. - -## 3.17 Project templates - -Initial templates may include: - -- React web application. -- Hono service. -- Express API. -- Full-stack application. -- API-only service. -- Expo application. -- Monorepo starter. - -A template should define: - -- Source files. -- Runtime versions. -- Install command. -- Test command. -- Verification command. -- Development command. -- Service ports. -- Preview behavior. -- Project context prompts. -- Default policies. -- Agent skills. - -Templates should generate a reusable base snapshot after successful setup and verification. - -## 3.18 Project configuration files - -Recommended repository structure: - -```text -/ -├── README.md -├── AGENTS.md -├── product.md -├── design.md -├── tech.md -│ -├── .zopo/ -│ ├── project.yaml -│ ├── services.yaml -│ ├── policies.yaml -│ ├── lifecycle/ -│ │ ├── setup -│ │ ├── resume -│ │ ├── verify -│ │ └── preview -│ └── skills/ -│ ├── testing/ -│ │ └── SKILL.md -│ ├── reviewing/ -│ │ └── SKILL.md -│ └── deploying/ -│ └── SKILL.md -└── apps/ -``` - -Example `project.yaml`: +`project.yaml`: ```yaml name: example-project -runtime: - template: react-hono - node: "24" - packageManager: pnpm - +runtime: { template: react-hono, node: "24", packageManager: pnpm } commands: - install: pnpm install --frozen-lockfile - test: pnpm test - verify: pnpm run verify - dev: pnpm dev - -services: - web: - port: 3000 - api: - port: 4000 - -changes: - workflow: pull_request - baseBranch: main - + { + install: pnpm install --frozen-lockfile, + test: pnpm test, + verify: pnpm run verify, + dev: pnpm dev, + } +services: { web: { port: 3000 }, api: { port: 4000 } } +changes: { workflow: pull_request, baseBranch: main } approvals: - pushBranch: automatic - createPullRequest: automatic - mergePullRequest: required - deployPreview: automatic - deployProduction: required + { + pushBranch: automatic, + createPullRequest: automatic, + mergePullRequest: required, + deployPreview: automatic, + deployProduction: required, + } ``` -## 3.19 Executor integration gateway +**Executor / integration gateway** — shared integration+tool gateway: GitHub, Slack, Linear, Intercom, analytics, CRM, cloud services, internal APIs, custom functions. Owns connection mgmt, tool catalog, scoped auth, tool-level policies, approval requirements, auditable invocation. Does **not** own: shell exec, repo fs ops, work-unit state, agent session state, sandbox lifecycle. Flow Agent may get broader org-level tools; OpenCode gets only project/run-scoped tools for the current task. -Executor acts as the shared integration and tool gateway for external systems. +**Model gateway** — all model calls route here. Provider credentials, auto routing, tenant attribution, cost accounting, budget enforcement, rate limits, retries/fallback, prompt/response logging under policy, redaction, run-scoped credentials. Don't expose model selection by default. Run token (short-lived, scoped): `{organization_id, project_id, work_unit_id, run_id, model_classes:["coding-standard","coding-fast"], budget_usd:8, expires_in_seconds:3600}`. -It may expose: +**Artifact storage** (object storage, not actor state/DB rows) — types: patch, commit bundle, test report, build log, screenshot, video, preview snapshot, research doc, review report, generated file. Metadata: tenant/work-unit/run scope, type, content hash, producer, source event, retention policy, access policy. -- GitHub APIs. -- Slack. -- Linear. -- Intercom. -- Analytics. -- CRM. -- Cloud services. -- Internal APIs. -- Custom functions. +**Preview gateway** — controlled exposure (not raw sandbox ports): authenticated access, project/run-scoped routing, short-lived URLs, service health, automatic shutdown, event on ready/fail, screenshot/browser verification integration. -Responsibilities: +**Observability & billing** — every path emits logs, metrics, traces, cost, token use, runtime duration, tool calls, network use, artifact size, retry count, user-intervention count. Correlation dims: `organization_id, project_id, work_unit_id, run_id, actor_id, session_id, sandbox_id, sequence, timestamp`. Cost per successful outcome, not per model request. -- Connection management. -- Tool catalog. -- Scoped authentication. -- Tool-level policies. -- Approval requirements. -- Auditable invocation. +## 3. Core execution flows -It should not own: +**Project onboarding.** User creates project → Project service creates/imports/connects repo → apply template (commit initial files) → Context service drafts context docs → user reviews/commits canonical docs → template runs setup+verify → Snapshot service creates sanitized base snapshot → project active. -- Shell execution. -- Repository filesystem operations. -- Work-unit state. -- Agent session state. -- Sandbox lifecycle. +**Prompt → candidate work.** User describes request → Conversation persists scoped message → publishes extraction job → Flow searches related work/sources → creates/updates signal → if existing work matches: attach signal + update understanding; else if new outcome: create candidate → Work graph publishes materialized update → realtime shows updated/new card. -The Flow Agent may receive broader organization-level tools. OpenCode should receive only the project- and run-scoped tools needed for the current task. +**Accepted work → verified PR.** User approves candidate → accept work unit → Flow persists objective + acceptance criteria → Scheduler creates implementation run → AgentOS provisions run actor → Workbox creates isolated sandbox → clone repo + create work branch → start OpenCode session → send run context pack. **Execution loop:** harness inspects/edits/executes, streams events/requests to AgentOS, which persists meaningful events → work card updates. On completion: run verification → upload reports/screenshots → commit/push branch → Flow creates PR + attaches artifacts + moves to Review → UI shows PR/preview/evidence/human action. -## 3.20 Model gateway +**Approval continuation.** Harness requests sensitive action → AgentOS → Policy evaluates action/scope: auto-allow · or → creates approval request to attention queue → user sees action/evidence/risk/impact → approve/modify/reject → policy persists decision → AgentOS resumes with bounded permission · or → deny with reason. -All model calls should route through a model gateway. +## 4. State machines -Responsibilities: +Keep product, run, and environment state separate. Frontend primarily exposes work-unit state; run state = operational detail; Workbox state hidden except debugging/delayed startup. -- Provider credentials. -- Automatic model routing. -- Tenant attribution. -- Cost accounting. -- Budget enforcement. -- Rate limits. -- Retries and fallback. -- Prompt and response logging under policy. -- Redaction. -- Run-scoped credentials. - -The product should not expose model selection by default. - -A run token should be short-lived and scoped: - -```json -{ - "organization_id": "org_01...", - "project_id": "prj_01...", - "work_unit_id": "wrk_01...", - "run_id": "run_01...", - "model_classes": ["coding-standard", "coding-fast"], - "budget_usd": 8, - "expires_in_seconds": 3600 -} +``` +Work unit: proposed → clarifying → ready → active → waiting|review|monitoring → done + modifiers: blocked, waiting_on_user, waiting_on_dependency, approval_required, autonomous, at_risk, scheduled +Run: queued → provisioning → preparing → running → waiting_for_input|verifying → succeeded|failed|cancelled +Workbox: creating → preparing → ready → busy → sleeping|waking → destroyed ``` -## 3.21 Artifact storage +## 5. Concurrency model -Large and durable outputs belong in object storage, not actor state or relational rows. +- One writable checkout per active mutating run; one branch per independently shippable work unit. +- Serialize mutating runs against same branch; permit parallel read-only analysis on immutable snapshots; permit parallel child work on separate branches; merge/integration = explicit controlled action. +- A work unit may use multiple runs: research → implementation → automated review → verification → human review. +- Never let agents share one writable working dir without deliberate coordination + conflict handling. -Artifact types include: +## 6. Persistence & recovery -- Patch. -- Commit bundle. -- Test report. -- Build log. -- Screenshot. -- Video. -- Preview snapshot. -- Research document. -- Review report. -- Generated file. +Durable truth lives outside transient agent processes. Persist after every meaningful step: work-unit state changes, decisions, approval requests, agent summaries, audit-relevant tool results, commit/patch checkpoints, artifact metadata, verification results. Don't rely on running shells, in-memory harness state, open sockets, or uncommitted working dirs surviving. Before waiting for human input: persist findings, commit relevant files, upload artifacts, record exact requested decision, store resumable workflow state. All workflow steps idempotent or safely repeatable. -Artifact metadata should include: +## 7. Security model -- Tenant scope. -- Work-unit scope. -- Run scope. -- Type. -- Content hash. -- Producer. -- Source event. -- Retention policy. -- Access policy. +**Trust boundaries** — untrusted: imported repos, repo instructions, external docs, customer messages, MCP tools, tool responses, generated code, agent-authored summaries. A model recommendation is **not** an authorization decision. -## 3.22 Preview gateway +**Layered authorization** — sensitive action requires ALL: `product policy AND harness permission AND runtime capability AND scoped credential`. Path: agent requests → harness permission check → Work OS policy eval → human approval when required → runtime capability check → credential minting → execution → provenance event. -Preview environments should be exposed through a controlled gateway rather than raw sandbox ports. +**Workload identity** — each run gets short-lived identity: org_id, project_id, work_unit_id, run_id, initiating principal, permitted capabilities, expiration. Workbox exchanges it for scoped Git/model-gateway/integration/artifact/preview/cloud access. Never inject long-lived org credentials into sandboxes. -Requirements: +**Network policy** — deny-by-default or allowlisted by run type (package registry during setup, repo host, model gateway, approved external APIs; no unrestricted prod network by default). -- Authenticated access. -- Project- and run-scoped routing. -- Short-lived URLs where appropriate. -- Service health. -- Automatic shutdown. -- Event emission when preview becomes ready or fails. -- Screenshot or browser verification integration. +**Secrets** — stored outside repos/actor state; org/project scoped; minted/injected only when required; short-lived; redacted from logs/transcripts; rotatable without rebuilding projects; audited on access. -## 3.23 Observability and billing +**Data isolation** — every query/event/artifact/context lookup/runtime token is tenant-scoped. Cross-org portfolio views may aggregate summaries but never give one org's raw context to another org's agent run. -Every execution path should emit: +**Human approvals** required for: prod deployment, merging protected branches, accessing sensitive prod data, external communications, billing/financial changes, data deletion, org-level policy changes. Action-specific; expire after use or time. -- Logs. -- Metrics. -- Traces. -- Cost. -- Token use. -- Runtime duration. -- Tool calls. -- Network use. -- Artifact size. -- Retry count. -- User intervention count. +**Auditability** — retain: who initiated, context provided, agent+model class, tools called, files changed, approvals requested/granted, artifacts produced, what was published/merged, outcome observed. -Required correlation dimensions: +## 8. Scaling model -```text -organization_id -project_id -work_unit_id -run_id -actor_id -session_id -sandbox_id -sequence -timestamp +Scale via many small isolated actors + queued runs (not long-lived per-user machines). + +**Tenant scheduler** enforces: max concurrent runs per org/project, priority classes, fair scheduling, subscription limits, model/sandbox budget, retry/runtime-duration limits. **Work queue** states: `accepted → queued → leased → running → completed`. Leases idempotent + recoverable (prevent duplicate expensive execution). **Resource limits** (hard + soft): tokens/run, cost/run, runtime duration, tool calls, file count + repo size, network bytes, process count, memory/CPU, artifact size, subagent depth, repeated-failure count. **Artifact offloading** — large logs/binaries → object storage; keep refs in work graph. **Snapshots** — sanitized reusable snapshots accelerate setup. Layers: base OS → language/toolchain → template → project deps. Never snapshot: long-lived creds, user secrets, active tokens, unreviewed prod data. **Multi-region** (not MVP unless demanded) — keep control-plane relational consistency explicit: org home region, region-local execution actors + artifact/cache placement, global routing to org's control plane, explicit data-residency restrictions. + +## 9. Better-T-Stack monorepo mapping + +``` +apps/ web, expo, api, worker, agent-runtime, preview-gateway +packages/ db, auth, domain, api-contract, events, realtime, work-graph, conversation, + flow-agent, context, policy, scheduler, integrations, model-gateway, git, + artifacts, sandbox, agentos, opencode, observability, billing, ui, config ``` -The system should calculate cost per successful outcome, not merely cost per model request. +Boundaries: **domain**=pure types + state transitions · **events**=envelopes/schemas/reducers/provenance · **work-graph**=work-entity queries + materialized views · **conversation**=message persistence/scopes/extraction jobs/source links · **flow-agent**=orchestration/planning/run coordination · **context**=canonical loading/retrieval/context-pack construction · **policy**=evaluation + approval workflows · **scheduler**=queues/leases/quotas/workflows/retries/cancellation · **agentos**=client/actor naming/session lifecycle/event translation · **opencode**=harness config/session prompts/tool policy/result normalization · **sandbox**=provider adapters/workspace lifecycle/commands/logs/previews · **git**=repo provisioning/branches/commits/pushes/PRs/mirrors · **integrations**=executor connection mgmt + tool scopes · **model-gateway**=provider routing/budgets/credentials/cost attribution. ---- +## 10. API & command design -## 4. Core execution flows +Prefer domain commands over generic entity mutation. Examples: `CreateProject, ImportRepository, CreateWorkUnit, AcceptCandidate, AttachSignal, MergeCandidates, StartWork, UpdateRequirements, ApprovePlan, ResolveBlocker, RequestChanges, PauseRun, CancelRun, ApproveAction, RejectAction, ApproveMerge, ApproveDeployment, ReopenWorkUnit`. Each command: validate tenant scope + current state; idempotent where practical; emit ≥1 domain event; no direct client control of infra details. -## 4.1 Project onboarding +## 11. Event translation (harness → product) -```mermaid -sequenceDiagram - actor User - participant UI as Work OS UI - participant Project as Project Service - participant Git as Git Service - participant Template as Template Builder - participant Context as Context Service - participant Snapshot as Snapshot Service +Preserve raw harness events for audit; translate to human-meaningful product events: - User->>UI: Create project - UI->>Project: Name, organization, template or repository - Project->>Git: Create, import, or connect repository - Git-->>Project: Repository identity - Project->>Template: Apply project template if selected - Template->>Git: Commit initial files - Project->>Context: Generate context-document drafts - Context-->>UI: Ask user to review product, design, and technical context - User->>UI: Confirm context - UI->>Git: Commit canonical project documents - Project->>Template: Run setup and verification - Template->>Snapshot: Create sanitized base snapshot - Snapshot-->>Project: Snapshot ready - Project-->>UI: Project active +``` +tool_call bash "pnpm test" → run.verification_started +tool_result exit_code=0 → run.test_suite_passed +permission_request git_push → approval.requested +file_edit src/auth/callback.ts → artifact.code_change_updated ``` -## 4.2 Prompt to candidate work +Primary UI hides raw transcripts unless user opens technical details. -```mermaid -sequenceDiagram - actor User - participant UI as Composer - participant Conversation as Conversation Service - participant Flow as Flow Agent - participant Work as Work Graph - participant Realtime as Realtime Gateway +## 12. Implementation sequence - User->>UI: Describe request or problem - UI->>Conversation: Persist message with scope - Conversation->>Flow: Publish extraction job - Flow->>Work: Search related work and sources - Flow->>Work: Create or update signal - alt Existing work matches - Flow->>Work: Attach signal and update understanding - else New outcome detected - Flow->>Work: Create candidate work - end - Work->>Realtime: Publish materialized update - Realtime-->>UI: Show updated or new card -``` +- **Phase 1 — Durable product model:** orgs, projects, work units, candidates, runs, artifacts, conversation scopes, event log, card projections. +- **Phase 2 — One complete coding loop:** one template project, managed Git, one sandbox provider, one AgentOS actor/run, OpenCode harness, model gateway, branch creation, tests, artifact upload, PR output, human approval. +- **Phase 3 — Context & memory:** canonical Markdown files, context-pack construction, retrieval index, decision memory, source provenance. +- **Phase 4 — Autonomous discovery:** continuous signal ingestion, candidate extraction, duplicate detection, existing-work matching, attention queue. +- **Phase 5 — Additional integrations/workflows:** external Git, support, team comms, issue trackers, analytics, deployment + monitoring. -## 4.3 Accepted work to verified pull request +## 13. MVP success criteria -```mermaid -sequenceDiagram - actor User - participant UI as Work OS UI - participant Flow as Flow Agent - participant State as Work Graph - participant Scheduler as Scheduler - participant AgentOS as AgentOS Actor - participant Harness as OpenCode - participant Box as Workbox Sandbox - participant Git as Git Service - participant Artifact as Artifact Store +Reliably demonstrate: `Prompt → candidate/work unit → clarified objective → isolated coding run → tested change → preview/evidence → pull request → human review → durable completed work card`. The work unit must remain understandable + resumable even if the harness session or Workbox is destroyed. - User->>UI: Approve candidate and start work - UI->>State: Accept work unit - State->>Flow: Work unit ready - Flow->>State: Persist objective and acceptance criteria - Flow->>Scheduler: Create implementation run - Scheduler->>AgentOS: Provision run actor - AgentOS->>Box: Create isolated sandbox - Box->>Git: Clone repository and create work branch - AgentOS->>Harness: Start OpenCode session - Flow->>Harness: Send run context pack +## 14. Non-goals (first release) - loop Execution - Harness->>Box: Inspect, edit, and execute - Harness-->>AgentOS: Stream events and requests - AgentOS->>State: Persist meaningful run events - State-->>UI: Update work card - end +Every harness; every sandbox provider; arbitrary multi-agent swarms; full replacement of external Git providers; multi-region active-active control plane; unlimited imported-repo compatibility; automatic prod deployment without approval; generic low-code workflow builder; exposing model selection + agent internals to users. - Harness->>Box: Run verification - Box->>Artifact: Upload reports and screenshots - Box->>Git: Commit and push branch - Flow->>Git: Create pull request - Flow->>State: Attach artifacts and move to Review - State-->>UI: Show PR, preview, evidence, and human action -``` +## 15. Architectural principles -## 4.4 Approval continuation - -```mermaid -sequenceDiagram - participant Harness as Agent Harness - participant AgentOS as AgentOS - participant Policy as Policy Engine - participant UI as Attention Queue - actor User - - Harness->>AgentOS: Request sensitive action - AgentOS->>Policy: Evaluate action and scope - alt Automatically allowed - Policy-->>AgentOS: Allow - else Requires human approval - Policy->>UI: Create approval request - UI-->>User: Show action, evidence, risk, and impact - User->>UI: Approve, modify, or reject - UI->>Policy: Persist decision - Policy-->>AgentOS: Resume with bounded permission - else Denied - Policy-->>AgentOS: Deny with reason - end -``` - ---- - -## 5. State machines - -Keep product, run, and environment state separate. - -## 5.1 Work-unit state - -```text -proposed -→ clarifying -→ ready -→ active -→ waiting | review | monitoring -→ done -``` - -Possible modifiers: - -- blocked. -- waiting_on_user. -- waiting_on_dependency. -- approval_required. -- autonomous. -- at_risk. -- scheduled. - -## 5.2 Run state - -```text -queued -→ provisioning -→ preparing -→ running -→ waiting_for_input | verifying -→ succeeded | failed | cancelled -``` - -## 5.3 Workbox state - -```text -creating -→ preparing -→ ready -→ busy -→ sleeping | waking -→ destroyed -``` - -The frontend should primarily expose work-unit state. Run state appears as operational detail. Workbox state is usually hidden except during debugging or delayed startup. - ---- - -## 6. Concurrency model - -Default rules: - -- One writable checkout per active mutating run. -- One branch per independently shippable work unit. -- Serialize mutating runs against the same branch. -- Permit parallel read-only analysis against immutable snapshots. -- Permit parallel child work on separate branches. -- Treat merge and integration as explicit controlled actions. - -Example: - -```text -Work Unit A → branch work/a → Workbox A -Work Unit B → branch work/b → Workbox B -Work Unit C → branch work/c → Workbox C -``` - -A work unit may use multiple runs: - -```text -research -→ implementation -→ automated review -→ verification -→ human review -``` - -Do not allow agents to share one writable working directory without deliberate coordination and conflict handling. - ---- - -## 7. Persistence and recovery - -The durable source of truth is outside transient agent processes. - -Persist after every meaningful step: - -- Work-unit state changes. -- Decisions. -- Approval requests. -- Agent summaries. -- Tool results required for audit. -- Repository commit or patch checkpoints. -- Artifact metadata. -- Verification results. - -Do not rely on: - -- A running shell process. -- In-memory harness state. -- Open sockets. -- An uncommitted working directory surviving indefinitely. - -Before waiting for human input: - -- Persist current findings. -- Save or commit relevant file changes. -- Upload important artifacts. -- Record the exact requested decision. -- Store resumable workflow state. - -All workflow steps should be idempotent or safely repeatable. - ---- - -## 8. Security model - -## 8.1 Trust boundaries - -Treat as untrusted: - -- Imported repositories. -- Repository instructions. -- External documents. -- Customer messages. -- MCP tools. -- Tool responses. -- Generated code. -- Agent-authored summaries. - -A model recommendation is not an authorization decision. - -## 8.2 Layered authorization - -A sensitive action requires all relevant layers to allow it: - -```text -Product policy -AND -Harness permission -AND -Runtime capability -AND -Scoped credential -``` - -The action path is: - -```text -Agent requests action -→ harness permission check -→ Work OS policy evaluation -→ human approval when required -→ runtime capability check -→ credential minting -→ action execution -→ provenance event -``` - -## 8.3 Workload identity - -Every run should receive a short-lived identity containing: - -- organization_id. -- project_id. -- work_unit_id. -- run_id. -- user or initiating principal. -- permitted capabilities. -- expiration. - -The Workbox exchanges this identity for scoped access to: - -- Git. -- Model gateway. -- Integration tools. -- Artifact storage. -- Preview gateway. -- Optional cloud environments. - -Avoid injecting long-lived organization credentials into sandboxes. - -## 8.4 Network policy - -Network access should be deny-by-default or allowlisted by run type. - -Examples: - -- Package registry access during setup. -- Repository host access. -- Model gateway access. -- Approved external APIs. -- No unrestricted production network access by default. - -## 8.5 Secrets - -Secrets should be: - -- Stored outside repositories and actor state. -- Scoped to organization and project. -- Minted or injected only when required. -- Short-lived where possible. -- Redacted from logs and transcripts. -- Rotatable without rebuilding projects. -- Audited when accessed. - -## 8.6 Data isolation - -Every storage query, event, artifact, context lookup, and runtime token must be tenant-scoped. - -Cross-organization portfolio views may aggregate summaries but must never provide one organization’s raw context to another organization’s agent run. - -## 8.7 Human approvals - -Approval should be required for actions such as: - -- Production deployment. -- Merging protected branches. -- Accessing sensitive production data. -- Sending external communications. -- Changing billing or financial state. -- Deleting data. -- Changing organization-level policy. - -Approval should be action-specific and expire after use or time. - -## 8.8 Auditability - -The system must retain: - -- Who initiated work. -- What context was provided. -- Which agent and model class performed the run. -- Which tools were called. -- What files changed. -- Which approvals were requested and granted. -- What artifacts were produced. -- What was published or merged. -- What outcome was observed. - ---- - -## 9. Scaling model - -Scale through many small, isolated actors and queued runs rather than long-lived per-user machines. - -## 9.1 Tenant scheduler - -Enforce: - -- Maximum concurrent runs per organization. -- Maximum concurrent runs per project. -- Priority classes. -- Fair scheduling. -- Subscription limits. -- Model budget. -- Sandbox budget. -- Retry limits. -- Runtime duration limits. - -## 9.2 Work queue - -Use explicit states: - -```text -accepted -→ queued -→ leased -→ running -→ completed -``` - -Leases should be idempotent and recoverable to prevent duplicate expensive execution. - -## 9.3 Resource limits - -Apply hard and soft limits for: - -- Tokens per run. -- Cost per run. -- Runtime duration. -- Tool calls. -- File count and repository size. -- Network bytes. -- Process count. -- Memory and CPU. -- Artifact size. -- Subagent depth. -- Repeated failure count. - -## 9.4 Artifact offloading - -Do not store large logs or binaries in actor state or database rows. Store them in object storage and retain references in the work graph. - -## 9.5 Snapshot strategy - -Use sanitized reusable snapshots for project setup acceleration. - -Snapshot layers may include: - -- Base operating environment. -- Language and toolchain layer. -- Template layer. -- Project dependency layer. - -Do not snapshot: - -- Long-lived credentials. -- User-specific secrets. -- Active tokens. -- Unreviewed production data. - -## 9.6 Multi-region considerations - -Keep control-plane relational consistency explicit. - -Potential strategy: - -- Organization home region. -- Region-local execution actors. -- Region-local artifact and cache placement. -- Global routing to the organization’s control plane. -- Explicit restrictions for data residency. - -Do not make multi-region execution an MVP requirement unless customer needs demand it. - ---- - -## 10. Better-T-Stack monorepo mapping - -Assuming an existing monorepo with `apps/web`, `apps/expo`, and shared packages, a possible structure is: - -```text -apps/ -├── web/ -├── expo/ -├── api/ -├── worker/ -├── agent-runtime/ -└── preview-gateway/ - -packages/ -├── db/ -├── auth/ -├── domain/ -├── api-contract/ -├── events/ -├── realtime/ -├── work-graph/ -├── conversation/ -├── flow-agent/ -├── context/ -├── policy/ -├── scheduler/ -├── integrations/ -├── model-gateway/ -├── git/ -├── artifacts/ -├── sandbox/ -├── agentos/ -├── opencode/ -├── observability/ -├── billing/ -├── ui/ -└── config/ -``` - -Suggested boundaries: - -### `packages/domain` - -Pure domain types and state transitions. - -### `packages/events` - -Event envelopes, schemas, reducers, and provenance utilities. - -### `packages/work-graph` - -Queries and commands for work entities and materialized views. - -### `packages/conversation` - -Message persistence, scopes, extraction jobs, and source links. - -### `packages/flow-agent` - -Orchestration logic, planning, and run coordination. - -### `packages/context` - -Canonical context loading, retrieval, and run context-pack construction. - -### `packages/policy` - -Policy evaluation and approval workflows. - -### `packages/scheduler` - -Queues, leases, quotas, workflows, retries, and cancellation. - -### `packages/agentos` - -AgentOS client, actor naming, session lifecycle, and event translation. - -### `packages/opencode` - -Harness configuration, session prompts, tool policy, and result normalization. - -### `packages/sandbox` - -Sandbox provider adapters, workspace lifecycle, commands, logs, and previews. - -### `packages/git` - -Repository provisioning, branches, commits, pushes, pull requests, and mirrors. - -### `packages/integrations` - -Executor connection management and tool scopes. - -### `packages/model-gateway` - -Provider routing, budgets, credentials, and cost attribution. - ---- - -## 11. API and command design - -Prefer domain commands over generic entity mutation. - -Examples: - -```text -CreateProject -ImportRepository -CreateWorkUnit -AcceptCandidate -AttachSignal -MergeCandidates -StartWork -UpdateRequirements -ApprovePlan -ResolveBlocker -RequestChanges -PauseRun -CancelRun -ApproveAction -RejectAction -ApproveMerge -ApproveDeployment -ReopenWorkUnit -``` - -Each command should: - -- Validate tenant scope. -- Validate current state. -- Be idempotent where practical. -- Emit one or more domain events. -- Avoid direct client control of infrastructure details. - ---- - -## 12. Event translation from harness to product - -Raw harness events should be preserved for audit but translated into human-meaningful product events. - -Examples: - -```text -Raw: tool_call bash "pnpm test" -Product: run.verification_started - -Raw: tool_result exit_code=0 -Product: run.test_suite_passed - -Raw: permission_request git_push -Product: approval.requested - -Raw: file_edit src/auth/callback.ts -Product: artifact.code_change_updated -``` - -The primary UI should not expose raw transcripts unless the user opens technical details. - ---- - -## 13. Initial implementation sequence - -## Phase 1: Durable product model - -- Organizations. -- Projects. -- Work units. -- Candidates. -- Runs. -- Artifacts. -- Conversation scopes. -- Event log. -- Card projections. - -## Phase 2: One complete coding loop - -- One template project. -- Managed Git. -- One sandbox provider. -- One AgentOS actor per run. -- OpenCode harness. -- Model gateway. -- Branch creation. -- Tests. -- Artifact upload. -- Pull request output. -- Human approval. - -## Phase 3: Context and memory - -- Canonical Markdown files. -- Context-pack construction. -- Retrieval index. -- Decision memory. -- Source provenance. - -## Phase 4: Autonomous discovery - -- Continuous signal ingestion. -- Candidate extraction. -- Duplicate detection. -- Existing work matching. -- Attention queue. - -## Phase 5: Additional integrations and workflows - -- External Git. -- Support. -- Team communication. -- Issue trackers. -- Analytics. -- Deployment and monitoring. - ---- - -## 14. MVP success criteria - -The first release should reliably demonstrate: - -```text -Prompt -→ candidate or work unit -→ clarified objective -→ isolated coding run -→ tested change -→ preview or evidence -→ pull request -→ human review -→ durable completed work card -``` - -The work unit must remain understandable and resumable even if the underlying harness session or Workbox is destroyed. - ---- - -## 15. Technical non-goals for the first release - -- Supporting every harness. -- Supporting every sandbox provider. -- Arbitrary multi-agent swarms. -- Full replacement of external Git providers. -- Multi-region active-active control plane. -- Unlimited imported repository compatibility. -- Automatic production deployment without approval. -- A generic low-code workflow builder. -- Exposing model selection and agent internals to users. - ---- - -## 16. Architectural principles - -1. **Durable work state must outlive execution environments.** -2. **Every execution path is tenant-scoped.** -3. **Use one writable checkout per mutating unit of work.** -4. **Persist events before projecting summaries.** -5. **Treat agent outputs as claims with provenance, not unquestioned truth.** -6. **Separate product policy, harness permission, and runtime capability.** -7. **Use short-lived credentials and explicit workload identity.** -8. **Keep harnesses, models, sandboxes, and Git providers replaceable.** -9. **Hide infrastructure state from the product surface unless actionable.** -10. **Measure successful outcomes and human attention, not merely agent activity.** +1. Durable work state outlives execution environments. 2. Every execution path is tenant-scoped. 3. One writable checkout per mutating unit of work. 4. Persist events before projecting summaries. 5. Treat agent outputs as claims with provenance, not unquestioned truth. 6. Separate product policy, harness permission, and runtime capability. 7. Short-lived credentials + explicit workload identity. 8. Keep harnesses, models, sandboxes, and Git providers replaceable. 9. Hide infrastructure state from the product surface unless actionable. 10. Measure successful outcomes and human attention, not merely agent activity.