Skip to content

docs: automated documentation updates 2026-04-02 #1331

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
jcllobet wants to merge 1 commit into from
+62 −263
Closed

docs: automated documentation updates 2026-04-02 #1331

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
290 changes: 45 additions & 245 deletions PRODUCT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,261 +1,61 @@
# OpenWork Product
## Product

## Target Users
OpenWork helps individual create, consume, and maintain their agentic workflows.

> Bob the IT guy.
> Bob might already use opencode, he can setup agents and workflows and share them with his team. The only thing he needs is a way to share this. The way he does is by using OpenWork and creating "workpaces".
OpenWork helps companies share their agentic workflows and provision their entire team.

> Susan in accounting
The chat interfaces is where people consume the workflows.

Susan in accounting doesn't use opencode. She certaintly doesn't paly aorund to create workflow create agents. She wants something that works.
Openwork should be given to give her a good taste of what she can do.
We should also eventually guide ther to:
Interfaces for consuming workflows:
- Desktop app
- Slack
- Telegram

- creating her own skills
- adding custom MCP / login into mcp oauth servers through ui)
- adding skills from a list of skills
- adding plugins from a list of plugins
- create her own commands
What is a "agentic workflow":
- LLM providers
- Skills
- MCP
- Agents
- Plugins
- Tools
- Background Agents

1. **knowledge worker**: "Do this for me" workflows with guardrails.
2. **Mobile-first user**: start/monitor tasks from phone.
3. **Power user**: wants UI parity + speed + inspection.
4. **Admin/host**: manages a shared machine + profiles.
Where are workflows created:
- Desktop app (using slash commands like `/create-skills`)
- Web App
- [We need better places for this to happen[

## Success Metrics
Where are workflows maintain:
- In OpenWork Cloud (internal name is Den).

- < 5 minutes to first successful task on fresh install.
- > 80% task success without terminal fallback.
- Permission prompts understood/accepted (low confusion + low deny-by-accident).
- UI performance: 60fps; <100ms interaction latency; no jank.
Where are workflow hosted:
- Local Machine
- Remote via a OpenWork Host (CLI or desktop)
- Remote on OpenWork Cloud (via Den sandbox workers)

## Product Primitives (What OpenWork Exposes)
## Current OpenWork Cloud flow

OpenWork must feel like "OpenCode, but for everyone."
- Users can sign in with the standard web auth providers or accept an org invite through the hosted join flow.
- Invite signup keeps the invited email fixed, verifies the user by email code, and then drops them into the org join path.
- Org creation can trigger checkout up front when billing is required, and launch attempts surface org limits when the current plan does not allow more workers or members.
- After a worker is ready, the user connects from the OpenWork app with `Add a worker` -> `Connect remote`, or opens the generated deep link directly.

### 1) Tasks
## Team distribution

- A Task = a user-described outcome.
- A Run = an OpenCode session + event stream.
- Organizations can publish shared skill hubs so members discover approved skills from one managed place instead of collecting local-only installs by hand.
- Org admins can now manage teams directly in the hosted dashboard and grant each skill hub to the exact teams that should inherit it.

### 2) Plans / Todo Lists
## Actors
Bob IT guy makes the config.
Susan the accountant consumes the config.

OpenWork provides a first-class plan UI:
Constraints:
- We use standards were possible
- We use opencode where possible
- We stay platform agnostic

- Plan is generated before execution (editable).
- Plan is updated during execution (step status + timestamps).
- Plan is stored as a structured artifact attached to the session (JSON) so it's reconstructable.

Implementation detail:

- The plan is represented in OpenCode as structured `parts` (or a dedicated "plan message") and mirrored in OpenWork.

### 3) Steps

- Each tool call becomes a step row with:
- tool name
- arguments summary
- permission state
- start/end time
- output preview

### 4) Artifacts

Artifacts are user-visible outputs:

- files created/modified
- generated documents/spreadsheets/presentations
- exported logs and summaries

OpenWork lists artifacts per run and supports open/share/download.

### 5) Audit Log

Every run provides an exportable audit log:

- prompts
- plan
- tool calls
- permission decisions
- outputs

## UI/UX Requirements (Slick as a Core Goal)

### Design Targets

- premium, calm, high-contrast
- subtle motion, springy transitions
- zero "developer vibes" in default mode

### Performance Targets

- 60fps animations
- <100ms input-to-feedback
- no blocking spinners (always show progress state)

### Mobile-first Interaction

- bottom navigation
- swipe gestures (dismiss, approve, cancel)
- haptics for major events
- adaptive layouts (phone/tablet)

### Accessibility

- WCAG 2.1 AA
- reduced motion mode
- screen-reader labels for steps + permissions

## Design Reference

use the design from ./design.ts that is your core reference for building the entire ui

## Functional Requirements

### Workspace Setup

- create a local workspace or connect a remote worker from the workspace shell
- provider/model setup
- authorized folders management from Settings when a workspace needs paths outside its root
- first-run task from the session surface

### Cloud Worker Onboarding (Current)

- Sign in (or sign up) on OpenWork cloud control surface.
- Launch worker with a human-readable name.
- If needed, complete checkout and return.
- Select launched worker from list/detail shell.
- Connect from OpenWork app via `Add a worker` -> `Connect remote`.
- Prefer one-click deep link when available; always provide manual URL + token fallback.

### Task Execution

- create task
- plan preview and edit
- run with streaming updates
- pause/resume/cancel
- show artifacts and summaries

### Permissions

- clear prompts with "why"
- allow once/session
- audit of decisions

### Commands

- save a task as a command
- arguments + quick run

### Scheduling (Future)

- schedule command runs
- notify on completion

## User Flow Map (Exhaustive)

### 0. Install & Launch

1. User installs OpenWork.
2. App launches into the workspace/settings shell.
3. User either creates a local workspace or chooses `Add a worker` -> `Connect remote`.
4. Local flow starts the host stack for the selected workspace.
5. Remote flow stores the worker URL + token and reconnects to that worker.

### 1. Local Workspace Setup

1. User picks or creates a workspace folder.
2. OpenWork starts the local host stack for that workspace.
3. User configures providers and model defaults.
4. If needed, user adds extra authorized folders from Settings.
5. User opens a session and runs the first task.

### 2. Remote Worker Connect

1. User chooses `Add a worker` -> `Connect remote`.
2. UI accepts a shared OpenWork worker URL and token (or deep link).
3. OpenWork verifies server health and available capabilities.
4. User lands in the same workspace/session shell used for local workers.
5. User can now list sessions and monitor runs.

### 3. Runtime Health & Recovery

1. UI pings `global.health()`.
2. If unhealthy:
- Host: attempt restart via `createOpencode()`.
- Client: show reconnect + diagnostics.

### 4. Quick Task Flow

1. User types goal.
2. OpenWork generates plan (structured).
3. User approves.
4. Create session: `session.create()`.
5. Send prompt: `session.prompt()`.
6. Subscribe to events: `event.subscribe()`.
7. Render streaming output + steps.
8. Show artifacts.

### 5. Guided Task Flow

1. Wizard collects goal, constraints, outputs.
2. Plan preview with "risky step" highlights.
3. Run execution with progress UI.

### 6. File-Driven Task Flow

1. User attaches files.
2. OpenWork injects context into session.
3. Execute prompt.

### 7. Permissions Flow (Any)

1. Event indicates permission request.
2. UI modal shows request.
3. User chooses allow/deny.
4. UI calls `client.permission.reply({ requestID, reply })`.
5. Run continues or fails gracefully.

### 8. Cancel / Abort

1. User clicks "Stop".
2. UI calls `client.session.abort({ sessionID })`.
3. UI marks run stopped.

### 9. Summarize

1. User taps "Summarize".
2. UI calls `client.session.summarize({ sessionID })`.
3. Summary displayed as an artifact.

### 10. Run History

1. UI calls `session.list()`.
2. Tap a session to load `session.messages()`.
3. UI reconstructs plan and steps.

### 11. File Explorer + Search

1. User searches: `find.text()`.
2. Open file: `file.read()`.
3. Show changed files: `file.status()`.

### 12. Commands

1. Save a plan + prompt as a command.
2. Re-run command creates a new session.

### 13. Multi-user (Future)

- separate profiles
- separate allowed folders
- separate providers/keys

### 14. Hosted Cloud Worker Connect Flow (Current)

1. User opens OpenWork cloud control page and authenticates.
2. User launches a worker (with optional checkout).
3. UI polls until worker is healthy.
4. UI resolves workspace-scoped connect URL (`/w/ws_*`) and access token.
5. User clicks `Open in OpenWork` or copies manual credentials.
6. In OpenWork app, user uses `Add a worker` -> `Connect remote` and starts working.
How to decide if OpenWork should do something:
- Does it help Bob share config more easily?
- Does it help Susan consume automations more easily?
- Is this something that is coding specific?
14 changes: 6 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
> OpenWork is the open source alternative to Claude Cowork/Codex (desktop app).


## Core Philosophy

- Local-first, cloud-ready: OpenWork runs on your machine in one click. Send a message instantly.
Expand All @@ -14,7 +15,6 @@
OpenWork is designed around the idea that you can easily ship your agentic workflows as a repeatable, productized process.

## Alternate UIs

- **OpenWork Orchestrator (CLI host)**: run OpenCode + OpenWork server without the desktop UI.
- install: `npm install -g openwork-orchestrator`
- run: `openwork start --workspace /path/to/workspace --approval auto`
Expand All @@ -26,7 +26,8 @@ Download the desktop app from [openworklabs.com/download](https://openworklabs.c

- macOS and Linux downloads are available directly.
- Windows access is currently handled through the paid support plan on [openworklabs.com/pricing#windows-support](https://openworklabs.com/pricing#windows-support).
- Hosted OpenWork Cloud workers are launched from the web app after checkout, then connected from the desktop app via `Add a worker` -> `Connect remote`.
- Hosted OpenWork Cloud workers are launched from the web app after org setup, including checkout when billing is required, then connected from the desktop app via `Add a worker` -> `Connect remote`.
- OpenWork Cloud org dashboards now include shared team management and skill hub management so admins can decide who can access each published skill library before workers are launched.

## Why

Expand All @@ -41,17 +42,14 @@ OpenWork is designed to be:

## What’s Included

- **Local host mode**: run OpenCode locally on your computer.
- **Remote connect**: attach to an OpenWork worker with a shared URL + token.
- **Workspaces**: create local workspaces or connect remote workers from the same workspace sidebar.
- **Host mode**: runs opencode locally on your computer
- **Client mode**: connect to an existing OpenCode server by URL.
- **Sessions**: create/select sessions and send prompts.
- **Live streaming**: SSE `/event` subscription for realtime updates.
- **Execution plan**: render OpenCode todos as a timeline.
- **Permissions**: surface permission requests and reply (allow once / always / deny).
- **Templates**: save and re-run common workflows (stored locally).
- **Debug exports**: copy or export the runtime debug report and developer log stream from Settings -> Debug when you need to file a bug.
- **Unified settings shell**: manage skills, extensions, automations, messaging, and appearance from one shell instead of separate dashboard tabs.
- **Authorized folders**: manage extra filesystem access from Settings when a workspace needs directories outside its root.
- **Skills manager**:
- list installed `.opencode/skills` folders
- import a local skill folder into `.opencode/skills/<skill-name>`
Expand Down Expand Up @@ -153,7 +151,7 @@ Capability permissions are defined in:

## OpenCode Plugins

Plugins are the **native** way to extend OpenCode. OpenWork now manages them from `Settings -> Extensions` by
Plugins are the **native** way to extend OpenCode. OpenWork now manages them from the Skills tab by
reading and writing `opencode.json`.

- **Project scope**: `<workspace>/opencode.json`
Expand Down
4 changes: 2 additions & 2 deletions ee/apps/den-api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,9 +19,9 @@ pnpm --filter @openwork-ee/den-api dev:local
- Better Auth mount at `/api/auth/*`
- desktop handoff routes under `/v1/auth/*`
- current user routes under `/v1/me*`
- organization routes under `/v1/orgs*`
- organization routes under `/v1/orgs*`, including org setup, invitations, members, roles, teams, and shared skill hub management
- admin routes under `/v1/admin*`
- worker lifecycle and billing routes under `/v1/workers*`
- worker lifecycle and billing routes under `/v1/workers*`, including checkout redirects and org limit enforcement

## Folder map

Expand Down
Loading
Loading