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._