clawmates/docs/spec.md

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.