osobh/clawmates
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6d087bf53757b0ea3361977734ae814bc91dc610
clawmates/docs/TeamClaw-Platform-Spec-PRD-Roadmap.md
T
Omar SobhandClaude Opus 4.8 48730abd78 docs: design specs + reference assets; move roadmap into docs/ 
Add the WorkClaw design-reference docs (specs, manifests, tokens, motion,
icon/asset references, gifs) under docs/, and move the platform
spec/PRD/roadmap from the repo root into docs/.

Co-Authored-By: Claude Opus 4.8 <[email protected]>
2026-06-12 22:55:57 -05:00

458 lines
21 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# AI Coworker Platform — Build Spec, PRD & Roadmap
_Internal working name: **TeamClaw** (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._
Reference in New Issue View Git Blame Copy Permalink