# AI Coworker Platform — Build Spec, PRD & Roadmap _Internal working name: **Clawmates** (replace with your brand). Original specification authored from product research. Art assets (avatars, wallpapers, logo) are generated separately and intentionally excluded._ --- ## Table of Contents 1. Product Overview 2. Design System & Tokens 3. Motion / Animation Spec 4. Global App Shell & Layout 5. Agent Chat Workspace 6. Sessions Column 7. The "Computer" Slide-out Panel (full spec) 8. Global Pages (Skills, Apps, Team, Credits) 9. Agent Creation Wizard 10. Dialogs & Overlays 11. Component Inventory 12. Routing & URL State Model 13. API Contract 14. Data Model 15. Agent Runtime & Safety Layer 16. PRD Summary 17. Delivery Roadmap --- ## 1. Product Overview An enterprise platform of customizable, collaborative AI agents ("claws"). Each agent has a persistent identity, a configurable system prompt, its own tool/app connections, files, scheduled routines, an inter-agent inbox, and a sandboxed runtime ("Computer") surfaced through a chat-first UI. A human-in-the-loop approval layer gates every sensitive or irreversible action. **Personas:** Owner/Admin (provisioning, billing, access policy), Builder (creates/tunes agents), Operator (chats, approves gated actions), Agent (first-class actor with identity, inbox, routines, files, runtime). --- ## 2. Design System & Tokens Dark-first. Coral brand accent. | Token | Value | |---|---| | --background | #0a0a0a | | --foreground | #fafafa | | --card / --popover | #0a0a0a | | --border / --input / --muted / --secondary | #262626 | | --muted-foreground | #a3a3a3 | | --subtle / --surface-warm | #141414 | | --surface-warm-muted | #1f1f1f | | --accent (coral) | #f96565 | | --coral-light / --coral-dark | #fa7575 / #e85555 | | --destructive | #7f1d1d | | --primary | #fafafa | | --radius (base) | 0.5rem | | --radius-button (pill) | 9999px | | app sidebar width | 176px | **Type:** Geist (UI) + Geist Mono (code). Reserved: Satoshi, Familjen Grotesk, Ranade, Inter. Scale: xxs 10px → base 16px → xxxl 36px. **Shadows:** bubble, button, card, dialog, popover, dock-tile, cta. **Texture:** inline SVG feTurbulence fractal-noise grain layered over wallpaper PNGs. --- ## 3. Motion / Animation Spec - Primary easing: `--ease-app: cubic-bezier(.32,.72,0,1)` - Secondary easing: `--ease-out: cubic-bezier(.16,1,.3,1)` - Durations: fast .15s / normal .25s / slow .4s - **Slide-out panels animate WIDTH, not transform:** `transition: width .25s var(--ease-app), border-color .5s var(--ease-out)` collapsing 0 ↔ target (176 / 208 / 448px). This makes panels "push" layout rather than overlay. - Keyframes to implement: slide-in-right, sheet-in, slide-up-in, scale-in, fade-in/out, fade-up, collapsible-expand/collapse, route-fade-in, shimmer, ripple, gradient-shift, caret-blink, shake, spin, ping, pulse, toolSlideIn, toolAccentPulse. - Provisioning (new-agent spin-up): avatar-breathe, photo-rotate, photo-bob, tip-slide, tip-fade. --- ## 4. Global App Shell & Layout Three persistent zones; up to three columns visible in chat at full width. ``` +--------+-----------------------------+--------------------------+ | LEFT | MAIN (chat / page) | COMPUTER PANEL (slide) | | RAIL | | (right, ~448px) | | 176px | header (h-14 / lg:h-20) | ?device=full|tablet| | | | | phone | | logo | ...content... | | | [agent]| | | | [agent]| | | | [agent]| | | | ( + ) | | | | | | | | Skills | | | | Apps | | | | Team | | | | Credits| | | | [user] | | | +--------+-----------------------------+--------------------------+ ``` Left rail: logo (top), agent roster (avatar + name + green online dot), add-agent (+), then nav: Skills / Apps / Team / Credits, current user pinned bottom. Active item uses coral. Rail width animates on collapse. --- ## 5. Agent Chat Workspace Route: `/claws/{clawId}/chat/{sessionKey}` ### 5a. Empty / Welcome state ``` +---------------------------------------------+ | (avatar) | | Hi, I'm {Name}. What can I | | help with? | | {Role} · Shared with your team | | +-------------------------------------+ | | | Message {Name}... [clip][skill]| | | +-------------------------------------+ | | [Create a daily briefing] [Write a report] | | [Make a presentation] [What can it do?]| +---------------------------------------------+ ``` ### 5b. Active transcript ``` HEADER: (avatar) {Name} / {Role} [slack][sessions][new] ------------------------------------------------------------ [ user bubble (right) ] (avatar) agent message (left) > N steps (collapsible tool/reasoning trace) inline `code chip` coral action link [Copy] [Helpful] [Not helpful] ------------------------------------------------------------ COMPOSER: [ Type your message... ] [clip] [skill] ``` - User bubbles right-aligned; agent messages left with avatar. - "N steps" expands to show tool calls (toolSlideIn / toolAccentPulse). - Gated actions render as coral "Review and approve" links → approvals queue. --- ## 6. Sessions Column Toggle: `?sessions=1`. Slides in on the LEFT of the chat (separate from Computer panel), narrowing the chat column. ``` +------------------+ | [ Search ] | +------------------+ | Session title | | 4h ago (•)| <- active = coral left border | Session title | | 1d ago | +------------------+ [ + New session ] ``` Each row: title + relative timestamp. Backed by session-history retrieval; sessions are resumable. --- ## 7. The "Computer" Slide-out Panel (FULL SPEC) Right-hand slide-out, themed per-agent via wallpaper. Size toggles top-right: **Full** (expand to side nav) / **Tablet** (chat beside it) / **Phone**. Plus close (×). State via `?device=` and `?app=`. ### 7.0 Home screen (dock + app grid) ``` ● {Name}'s Computer +------------------------------------------+ | [Browser] [Slack] [Claw Chat] [+ Add] | <- app grid | | | (wallpaper area) | | | | +------------------------------------+ | | | [Skills] [Files] [Routines][Settings] | <- dock (glassy) | +------------------------------------+ | +------------------------------------------+ ``` Every app is a routable sub-view (`?app=...`) with header (title + close, optional back/tabs) and an empty state. Each sub-view title appears top-left; close (×) top-right. ### 7.1 Browser (live agent web browser) ``` [<] [>] ( address: newtab ) [⟳] [+] [×] +------------------------------------------+ | web viewport | +------------------------------------------+ ``` Full browser chrome: back/forward, address bar, reload, new-tab, close. Renders the agent's actual browsing session (CDP-backed). Handle profile-load error state ("Some features may be unavailable" + OK). ### 7.2 Claw Chat (inter-agent inbox) — `?app=chat` ``` Claw Chat [×] [ Search ] +------------------------------------------+ | (av) {Agent} 2h | | {Thread subject} | | {last message preview…} | +------------------------------------------+ ``` Thread list → conversation detail. Threads may be flagged "sensitive." This is the surface governed by the "Other Claws" access toggle. ### 7.3 Slack (tabbed integration) — `?app=slack` ``` Slack [×] [ Overview ] [ Channels ] [ Connection ] +------------------------------------------+ | (Slack glyph) | | Bring this claw into Slack | | Connect Slack to respond on @mention | | [ Connect Slack ] | +------------------------------------------+ ``` Pre-connect: all tabs show connect gate. Post-connect: Channels (pick channels), Connection (manage auth). Agent replies on @mention; outbound posts are gated. ### 7.4 Files — `?app=files` ``` Files [×] +------------------------------------------+ | 📁 My Documents > | | 📁 Received Files > | | 📁 Shared ClawDrive (team) > | +------------------------------------------+ ``` Three drives; Shared drive is team-visible. Backed by openclaw/files + shared-drive/files. ### 7.5 Skills (per-agent installed) — `?app=skills` ``` Skills [×] +------------------------------------------+ | (lightning) | | {Name}'s Skills | | Add workflows you want {Name} to do | | | | [ Add Skill ] | +------------------------------------------+ ``` Installed subset of the global Skill Library. Empty state + Add Skill. ### 7.6 Routines (scheduled tasks) — `?app=routines` (→ scheduled) ``` Routines [⟳][×] +------------------------------------------+ | (bell) | | No routines yet | | Ask your claw to set up a routine — | | daily digest, newsletter, calendar block| | [ Schedule a task ] | +------------------------------------------+ ``` Routines are agent-created (interval/cron). List + refresh + create. ### 7.7 Settings — `?app=settings` (push/pop nav stack) **Main:** ``` Settings [×] (avatar) {Name} {Role subtitle} +------------------------------------------+ | Slack handle ⚠ @handle (disconnected)| | Managed by {Owner} | | Edit profile > | +------------------------------------------+ WHO ELSE HAS ACCESS +------------------------------------------+ | (av) Other people [ON] | | ◉ Entire team — anyone at {Org} | | ○ Specific people — pick teammates | +------------------------------------------+ | (av) Other Claws [ON] | | ◉ Any Claw on the team | | ○ Specific claws — pick claws | +------------------------------------------+ [ Need help? support@… ] ``` **Edit profile (drill-in, ‹ back):** ``` ‹ Edit profile (avatar) [Change photo] +------------------------------------------+ | Name {Name} | | Job Title {Role} | +------------------------------------------+ JOB DESCRIPTION [ Describe how this claw should think... ] "becomes part of its system prompt" PERSONALIZATION | Wallpaper {Theme} > | +------------------------------------------+ [ 🗑 Delete claw ] (destructive) ``` Key: the Job Description textarea IS the system prompt. Wallpaper drives panel theming. Delete is destructive (gated/confirmed). ### 7.8 Add Apps (connect directory) — `?app=apps` ``` Add Apps [×] [ Search apps ] +------------------------------------------+ | (icon) Gmail [+] | | (icon) Google Calendar [+] | | (icon) Notion / Linear / GitHub … [+] | +------------------------------------------+ [ + Add custom app ] ``` Per-row [+] starts OAuth. "Add custom app" → auth-method dialog (see §10). --- ## 8. Global Pages ### 8.1 Skill Library — `/skills` ``` Skill Library [ Create v ] Browse skills published by your team and the catalog. [ Search skills ] [ All categories v ] +------------------+ +------------------+ | {Skill} [+] | | {Skill} [+] | | by {author} | | by {author} | | {description} | | {description} | | N installs | | N installs | +------------------+ +------------------+ ``` Two-column cards: title, author, description, install count, install (+). ### 8.2 Apps — `/apps` ``` Apps [ + Add Custom App ] [ Find an App ] [ Category v ] Browse All Apps — connect via OAuth +------------------+ +------------------+ |(logo){App} [+] | |(logo){App} [+] | | {description} | | {description} | +------------------+ +------------------+ ``` Infinite scroll. Includes Gmail, Calendar, Drive, Notion, Linear, GitHub, Figma, Zoom, Stripe, HubSpot, Sheets, Telegram, HTTP/Webhook, Schedule, Supabase, MySQL, Postgres, AWS, SendGrid, SES, … ### 8.3 Team — `/team` ``` {Workspace} ✎ [ Invite ] N members in your workspace [ Members ] [ Claw org chart ] [ Leaderboard ] +------------------------------------------+ | Name Email Joined | | (NM) {User} [Owner] {email} {date} | +------------------------------------------+ ``` ### 8.4 Credits — `/credits` ``` Credits — manage balance, subscriptions, usage +------------------------------------------+ | AVAILABLE CREDITS {N} [Buy credits][Activity]| | Plans from $/mo · save yearly | | CREDIT LOTS · all credits never expire | | USAGE · LAST 7 DAYS [▓▓▓▓▓▓░] ~2 days | +------------------------------------------+ | Promo code [ PROMOCODE ] [ Redeem ] | +------------------------------------------+ | Scaling beyond self-serve? [ Talk to sales ]| +------------------------------------------+ ``` --- ## 9. Agent Creation Wizard — `/claws/new` (?step=identity|access|slack) ``` [▬▬▬▬] [ ] [ ] (3-step progress) Create your Claw Claws help get your work done. (< avatar carousel >) Name * ● ● ● ● [+] (accent swatches) [ {name} ] (⟳) Job title [ {role} ] [ Continue → ] ``` Step 1 identity (avatar carousel + accent/wallpaper swatches + name w/ randomizer + job title), Step 2 access (same scopes as Settings), Step 3 Slack (optional). Provisioning shows animated spin-up states. **Note:** completing creates a live agent — confirm before submit. --- ## 10. Dialogs & Overlays ### Add Custom App (centered modal) ``` (icon) Add Custom App [×] Pick how this app authenticates +------------------------------------------+ | 🔑 Keys — secret keys / API key / token | | 🛡 Username & Password — HTTP basic auth | | 🖥 MCP Server with OAuth — remote MCP | +------------------------------------------+ [ Cancel ] ``` ### Approval card (safety layer) ``` Review & approve This claw wants to: {action summary} PREVIEW: {exact payload / diff of what executes} Source: {agent / thread} ⚠ {sensitive/unverified} [ Reject ] [ Approve ] ``` --- ## 11. Component Inventory **Shell:** LeftRail, AgentRosterItem, AddAgentButton, GlobalNavItem, UserMenu. **Chat:** ChatHeader, WelcomeState, SuggestedPromptChip, MessageList, UserBubble, AgentMessage, StepTrace, CodeChip, GatedActionLink, MessageActions, Composer. **Sessions:** SessionsColumn, SessionSearch, SessionRow, NewSessionButton. **Computer panel:** DevicePanel (resizable), DeviceSizeToggle, PanelHeader, AppGrid, AppTile, Dock, DockTile; modules: BrowserApp, ClawChatApp (ThreadList/ThreadRow/ThreadDetail), SlackApp (Tabs/ConnectGate), FilesApp (FolderRow), SkillsApp, RoutinesApp, SettingsApp (IdentityHeader/SettingRow/AccessToggleGroup/EditProfileForm/WallpaperPicker/DeleteAgent), AddAppsApp. **Global:** SkillCard, AppCard, AddCustomAppDialog, MembersTable, CreditsCard, UsageMeter, PromoRedeem. **Wizard:** StepProgress, AvatarCarousel, AccentSwatchRow, ProvisioningState. **Safety:** ApprovalCard, ApprovalQueue, ActionPreview, AuditLogEntry, UntrustedContentBadge. --- ## 12. Routing & URL State Model - Global: `/skills`, `/apps`, `/team`, `/credits`, `/claws/new` - Agent: `/claws/{clawId}/chat/{sessionKey}` where sessionKey = `agent:{agentId}-claw-{shard}:session:{sessionId}:{messageId}` - Overlays via query: `?app=browser|slack|chat|skills|files|routines(→scheduled)|settings|apps`, `?sessions=1`, `?device=full|tablet|phone`, `?step=identity|access|slack` - All panel/overlay state is deep-linkable & shareable. --- ## 13. API Contract (REST, JSON, same-origin /api/, keyed by clawId) **Observed:** - Identity/team: `GET /user/me`, `GET /team/permissions`, `GET /team/credits`, `GET /team/claws` - Per-agent: `GET /claws/{id}/health`, `GET /claws/settings/full?clawId=`, `GET /claws/{id}/custom-photos`, `GET /claws/{id}/slack-channels`, `GET /claws/{id}/apps/available` - Sessions: `GET /sessions?clawId=`, `GET /sessions/active?clawId=`, `GET /sessions/history?sessionKey=&tools=true&clawId=` - Apps/skills/slack: `GET /apps?clawId=`, `GET /skills?clawId=`, `GET /slack/me`, `GET /apps/slack/setup` - Files: `GET /openclaw/files?clawId=`, `GET /shared-drive/files?clawId=` - Runtime bridge: `POST /gateway?clawId=` (streaming) **Designed (confirm during build):** - `POST /claws`, `PATCH /claws/{id}`, `DELETE /claws/{id}`, `POST /sessions`, `POST /skills/install`, `POST /apps/connect` - Approvals: `GET /approvals`, `GET /approvals/{id}`, `POST /approvals/{id}/approve`, `POST /approvals/{id}/reject` Health/active are polled; auth uses provider session heartbeat. --- ## 14. Data Model Workspace/Team(name, plan, credits) · User(id, role Owner|Member, email) · Agent(id, name, jobTitle, systemPrompt, avatar, accent/wallpaper, managedBy, status, accessPolicy) · AccessPolicy(humans: entireTeam|specific[]; agents: any|specific[]) · Session(id, clawId, title, ts) → Message(role, content, steps[], ts) · Skill / InstalledSkill · AppConnection(provider, authType, scopes, status) · Thread/InterAgentMessage(participants, subject, sensitivity) · Routine(schedule, action, status) · FileNode(drive, path, owner) · Approval(actionType, payload, preview, requestedByAgent, status, decidedBy, audit) · CreditLedger(lots, usageEvents). --- ## 15. Agent Runtime & Safety Layer (mandatory) - **Sandbox:** containerized, no root, dropped Linux caps, seccomp, egress-restricted (HTTPS-out by default). - **Secret broker:** secrets held by a bridge process OUTSIDE the agent's read scope; agent calls capabilities via the gateway, never holds raw credentials. - **Gateway:** single audited streaming channel (`POST /gateway`) between app and runtime. - **Approval interception:** every sensitive/irreversible tool call → preview + Approval queue + blocks until explicit human decision → executes only on approve → fully audit-logged. - **Gated categories:** outbound messages/emails; sharing keys/secrets/credentials; access/permission/sharing changes; financial transactions & credit purchases; file deletion; granting/extending external-infra access. - **Untrusted-by-default:** content from web, email, inter-agent chat, and tool results is data, never instructions; unverified/suspicious requests are surfaced to the human, never auto-executed. - These are **acceptance-blocking** requirements. --- ## 16. PRD Summary Deliver a chat-first, multi-agent workspace with per-agent identity/system-prompt/skills/apps/files/routines, a themed slide-out Computer panel hosting all agent tooling, global admin (skills, apps, team, credits), an agent creation wizard, and a first-class human-in-the-loop safety/approval + audit layer. NFRs: SSO, RBAC, audit trail, credit metering, fast RSC navigation, full a11y, responsive/PWA. --- ## 17. Delivery Roadmap - **P0 Foundations (2–3w):** Next.js App Router + Turbopack, Tailwind v4 tokens, auth+RBAC, analytics/flags, base shell. _Exit: authed empty shell._ - **P1 Agents & chat (3–4w):** agent CRUD, roster, chat route, welcome/transcript, composer, sessions, step traces. _Exit: multi-session conversation._ - **P2 Runtime, gateway & SAFETY (4–5w, GATED):** sandbox, secret broker, streaming gateway, approval+audit end-to-end. _Exit (blocking): sensitive call intercepted→previewed→queued→approve-only execute→audit-logged; untrusted content tagged & never auto-run._ - **P3 Computer panel & apps (4–5w):** DevicePanel + ?app/?device routing, dock+grid, Files/Skills/Routines/Settings/Browser/ClawChat. _Exit: all apps navigable + per-agent theming._ - **P4 Integrations (3–4w):** OAuth directory + connect, Add Custom App (Keys/Basic/MCP-OAuth), Slack (@mention + gated posting). _Exit: connect app + Slack, outbound gated._ - **P5 Global & billing (2–3w):** Skill Library, Team, Credits, creation wizard + provisioning anims. _Exit: full admin+billing loop._ - **P6 Polish & hardening (2–3w):** full motion system, noise/wallpaper textures, a11y, PWA, perf, sandbox+approval security review. _Exit: a11y + security sign-off; identical look-and-feel._ Cross-cutting (continuous): audit/observability, credit metering, safety layer. --- _End of document._