13ef123026
Move doc/specs/ui.md to doc/spec/ui.md. Move plans/module-system.md to doc/plans/. Add doc/spec/agents-runtime.md and docs/ reference specs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
50 KiB
Paperclip UI Spec
Status: Draft Date: 2026-02-17
1. Design Philosophy
Paperclip's UI is a professional-grade control plane, not a toy dashboard. It should feel like the kind of tool you live in all day — fast, keyboard-driven, information-dense without being cluttered, dark-themed by default. Every pixel should earn its place.
Design principles:
- Dense but scannable. Show maximum information without requiring clicks to reveal it. Use whitespace to separate, not to pad.
- Keyboard-first. Global shortcuts for search (Cmd+K), new issue (C), navigation. Power users should rarely touch the mouse.
- Contextual, not modal. Inline editing over dialog boxes. Dropdowns over page navigations. The user's mental context should never be broken unnecessarily.
- Dark theme default. Neutral grays, not pure black. Accent colors used sparingly for status and priority. Text is the primary visual element.
Color System
- Background:
hsl(220, 13%, 10%)(dark charcoal, not pure black) - Surface/Card:
hsl(220, 13%, 13%) - Border:
hsl(220, 10%, 18%) - Text primary:
hsl(220, 10%, 90%) - Text secondary:
hsl(220, 10%, 55%) - Accent (interactive):
hsl(220, 80%, 60%)(muted blue)
Status colors (consistent across all entities):
- Backlog: gray
hsl(220, 10%, 45%) - Todo: gray-blue
hsl(220, 20%, 55%) - In Progress: yellow
hsl(45, 90%, 55%) - In Review: violet
hsl(270, 60%, 60%) - Done: green
hsl(140, 60%, 50%) - Cancelled: gray
hsl(220, 10%, 40%) - Blocked: amber
hsl(25, 90%, 55%)
Priority indicators:
- Critical: red circle, filled
- High: orange circle, half-filled
- Medium: yellow circle, outline
- Low: gray circle, outline, dashed
Typography
- Font: System font stack (Inter if loaded, else
-apple-system, BlinkMacSystemFont, 'Segoe UI') - Body: 13px / 1.5 line-height
- Labels/metadata: 11px / uppercase tracking
- Headings: 14-18px / semi-bold, never all-caps
Icons
Use lucide-react throughout. Every sidebar item, every status indicator, every action button should have an icon. Icons are 16px in nav, 14px inline.
2. Application Shell
The app is a three-zone layout:
┌──────────┬────────────────────────────────────────────────┐
│ │ Breadcrumb bar │
│ Sidebar ├──────────────────────────┬─────────────────────┤
│ (240px) │ Main content │ Properties panel │
│ │ (flex-1) │ (320px, optional) │
│ │ │ │
└──────────┴──────────────────────────┴─────────────────────┘
- Sidebar: Fixed left, 240px. Collapsible to icon-only (48px) via toggle or keyboard shortcut.
- Breadcrumb bar: Spans the full width above main+properties. Shows navigation path, entity actions, and view controls.
- Main content: Scrollable. Contains the primary view (list, detail, chart, etc).
- Properties panel: Right side, 320px. Shown on detail views (issue detail, project detail, agent detail). Hidden on list views and dashboard. Resizable.
The properties panel slides in when you click into a detail view and slides out when you go back to a list. It is NOT a sidebar — it's contextual to the selected entity.
3. Sidebar
The sidebar is the primary navigation. It is grouped into logical sections with collapsible headers.
3.1 Company Header
Top of sidebar. Always visible.
┌─────────────────────────┐
│ [icon] Acme Corp ▼ │ ← Company switcher dropdown
├─────────────────────────┤
│ [🔍] [✏️] │ ← Search + New Issue
└─────────────────────────┘
Company switcher is a dropdown button that occupies the full width of the sidebar header. It shows:
- Company icon (first letter avatar with company color, or uploaded icon)
- Company name (truncated with ellipsis if long)
- Chevron-down icon
Clicking opens a dropdown with:
- List of all companies (with status dot: green=active, yellow=paused, gray=archived)
- Search field at top of dropdown (for users with many companies)
- Divider
+ Create companyaction at the bottom
Below the company name, a row of icon buttons:
- Search (magnifying glass icon) — opens Cmd+K search modal
- New Issue (pencil/square-pen icon) — opens new issue modal in the current company context
3.2 Personal Section
No section header — these are always at the top, below the company header.
Inbox 3
My Issues
- Inbox — items requiring the board operator's attention. Badge count on the right. Includes: pending approvals, stale tasks, budget alerts, failed heartbeats. The number is the total unread/unresolved count.
- My Issues — issues created by or assigned to the board operator.
3.3 Work Section
Section header: Work (collapsible, with a chevron toggle)
Work ▼
Issues
Projects
Goals
Views
- Issues — main task list for the selected company. This is the workhorse view.
- Projects — project list. Projects group issues and link to goals.
- Goals — company goal hierarchy.
- Views — saved filter/sort configurations (e.g., "Critical bugs", "Unassigned tasks", "CEO's tasks"). Users can create, name, and pin custom views here.
3.4 Company Section
Section header: Company (collapsible)
Company ▼
Dashboard
Org Chart
Agents
Costs
Activity
- Dashboard — company health overview: agent statuses, task velocity, cost burn, pending approvals count.
- Org Chart — interactive tree visualization of the agent reporting hierarchy.
- Agents — flat list of all agents with status, role, last heartbeat, spend.
- Costs — cost dashboard with breakdowns by agent, project, model, time.
- Activity — audit log of all system events.
Note: Approvals do not have a top-level sidebar entry. They are surfaced through the Inbox (primary interaction point), Dashboard (pending count metric), and inline on entity pages (e.g., an agent detail page shows the approval that authorized its hire). The /approvals route still exists and is reachable via "See all approvals" links in Inbox and Dashboard, but it is not in the sidebar navigation.
3.5 Section Behavior
- Each section header is clickable to collapse/expand its children.
- Collapsed state persists in localStorage.
- Active nav item is highlighted with a left-border accent and background tint.
- Hovering a nav item shows a subtle background highlight.
- Badge counts are right-aligned, rendered as small pills (e.g.,
3in a rounded rect). - Icons are 16px, left-aligned, with 8px gap to label text.
3.6 Sidebar Icons
Each nav item has a distinctive icon (lucide-react):
| Item | Icon |
|---|---|
| Inbox | Inbox |
| My Issues | CircleUser |
| Issues | CircleDot |
| Projects | Hexagon |
| Goals | Target |
| Views | LayoutList |
| Dashboard | LayoutDashboard |
| Org Chart | GitBranch |
| Agents | Bot |
| Costs | DollarSign |
| Activity | History |
4. Breadcrumb Bar
The breadcrumb bar sits above the main content and properties panel. It serves as both navigation and context indicator.
4.1 Structure
┌─────────────────────────────────────────────────────────────────────┐
│ Projects › Paperclip › Issues › CLIP-42 [⭐] [···] [🔔] [⬜] │
└─────────────────────────────────────────────────────────────────────┘
Left side:
- Breadcrumb segments, separated by
›chevrons. - Each segment is clickable to navigate to that level.
- Current segment is non-clickable, slightly bolder text.
- Star icon to favorite/pin the current entity.
- Three-dot menu for entity actions (delete, archive, duplicate, copy link, etc.)
Right side:
- Notification bell (if in a detail view — subscribe to changes on this entity)
- Panel toggle (show/hide the right properties panel)
4.2 View-Specific Tabs
On certain detail pages, the breadcrumb bar also contains a tab row below the breadcrumbs:
Project detail:
Overview Updates Issues Settings
Agent detail:
Overview Heartbeats Issues Costs
Tabs are rendered as pill-shaped buttons. Active tab has a subtle background fill.
5. Issues (Task Management)
Issues are the core work unit. This section details the full issue experience.
5.1 Issue List View
The issue list is the default view when clicking "Issues" in the sidebar.
Layout:
┌─────────────────────────────────────────────────────────────────┐
│ [All Issues] [Active] [Backlog] [⚙ Settings] [≡ Filter] [Display ▼] │
├─────────────────────────────────────────────────────────────────┤
│ ▼ Todo 3 [+] │
│ ☐ --- CLIP-5 ○ Implement user auth @CTO Feb 16 │
│ ☐ --- CLIP-3 ○ Set up CI pipeline @DevOps Feb 16 │
│ ☐ --- CLIP-8 ○ Write API documentation @Writer Feb 17 │
│ │
│ ▼ In Progress 2 [+] │
│ ☐ !!! CLIP-1 ◐ Build landing page @FE Feb 15 │
│ ☐ --- CLIP-4 ◐ Database schema design @CTO Feb 14 │
│ │
│ ▼ Backlog 5 [+] │
│ ☐ --- CLIP-9 ◌ Research competitors Feb 17 │
│ ... │
└─────────────────────────────────────────────────────────────────┘
Top toolbar:
- Status tabs:
All Issues,Active(todo + in_progress + in_review + blocked),Backlog. Each tab shows a status icon and count. Active tab is filled, others outlined. - Settings gear: Configure issue display defaults, custom fields.
- Filter button: Opens a filter bar below the toolbar.
- Display dropdown: Toggle between grouping modes (by status, by priority, by assignee, by project, none) and layout modes (list, board/kanban).
Grouping:
- Issues are grouped by status by default (matching the reference screenshots).
- Each group header shows: collapse chevron, status icon, status name, count, and a
+button to create a new issue in that status. - Groups are collapsible. Collapsed groups show just the header with count.
Issue rows: Each row contains, left to right:
- Checkbox — for bulk selection. Hidden by default, appears on hover (left of priority).
- Priority indicator — icon representing critical/high/medium/low (see Color System above). Always visible.
- Issue key — e.g.,
CLIP-5. Monospace, muted color. The prefix is derived from the project (or company if no project). - Status circle — clickable to open status change dropdown (same as reference screenshot). The circle's fill/color reflects current status.
- Title — primary text, truncated with ellipsis if too long.
- Assignee — avatar (agent icon) + agent name, right-aligned. If unassigned, shows a dashed circle placeholder.
- Date — creation date or target date, muted text, far right.
Row interactions:
- Click row → navigate to issue detail view.
- Click status circle → opens inline status dropdown (Backlog, Todo, In Progress, In Review, Done, Cancelled) with keyboard numbers as shortcuts (1-6).
- Click checkbox → selects for bulk actions. When any checkbox is selected, a bulk action bar appears at the bottom of the list.
- Hover → shows checkbox, and row gets subtle background highlight.
- Right-click → context menu (same actions as three-dot menu).
Bulk action bar: When one or more issues are selected, a floating bar appears at the bottom:
┌─────────────────────────────────────────────────────────┐
│ 3 selected [Status ▼] [Priority ▼] [Assignee ▼] [Project ▼] [🗑 Delete] [✕ Cancel] │
└─────────────────────────────────────────────────────────┘
5.2 Issue Filter Bar
Clicking "Filter" reveals a filter bar below the toolbar:
┌─────────────────────────────────────────────────────────┐
│ [+ Add filter] Status is Todo, In Progress [×] │
│ Priority is Critical, High [×] │
│ Assignee is CTO-Agent [×] │
└─────────────────────────────────────────────────────────┘
- Each filter is a chip showing
field operator value. - Click a chip to edit it.
×removes the filter.+ Add filteropens a dropdown of available fields: Status, Priority, Assignee, Project, Goal, Created date, Labels, Creator.- Filters are AND-composed.
- Active filters persist in the URL query string so they're shareable/bookmarkable.
5.3 Issue Detail View (Three-Pane)
Clicking an issue opens the detail view. The main content area splits into two zones, with the sidebar still visible on the left.
┌──────────┬────────────────────────────────┬──────────────────────┐
│ │ Issues › CLIP-42 │ │
│ Sidebar │ │ Properties [+] │
│ │ Fix user authentication bug │ │
│ │ Implement proper token... │ Status In Progress │
│ │ │ Priority High │
│ │ ┌──────────────────────────┐ │ Assignee CTO │
│ │ │ Properties bar (inline) │ │ Project Auth │
│ │ │ In Progress · High · │ │ Goal Security │
│ │ │ CTO · Auth project · ... │ │ Labels bug, auth│
│ │ └──────────────────────────┘ │ Start Feb 15 │
│ │ │ Target Feb 20 │
│ │ Description │ Created Feb 14 │
│ │ ───────────────── │ │
│ │ The current authentication │ ───────────────── │
│ │ system has a token refresh... │ Activity │
│ │ │ CTO commented 2h │
│ │ Comments │ Status → In Prog │
│ │ ───────────────── │ Created by Board │
│ │ [avatar] CTO · 2 hours ago │ │
│ │ I've identified the root... │ │
│ │ │ │
│ │ [avatar] DevOps · 1 hour ago │ │
│ │ The CI is set up to run... │ │
│ │ │ │
│ │ ┌──────────────────────────┐ │ │
│ │ │ Write a comment... │ │ │
│ │ └──────────────────────────┘ │ │
└──────────┴────────────────────────────────┴──────────────────────┘
Middle Pane (Main Content)
Header area:
- Issue title, large (18px, semi-bold), editable on click (inline editing).
- Subtitle: issue key
CLIP-42in muted text. - Below the title: inline properties bar showing key properties as clickable chips (same pattern as reference screenshots):
[○ In Progress] [!!! High] [👤 CTO] [📅 Target date] [📁 Auth] [···]. Each chip is clickable to change that property inline.
Description:
- Markdown-rendered description.
- Click to edit — opens a markdown editor in-place.
- Support for headings, lists, code blocks, links, images.
Subtasks (if any):
- Listed below description as a collapsible section.
- Each subtask is a mini issue row (status circle + title + assignee).
+ Add subtaskbutton at the bottom.
Comments:
- Chronological list of comments.
- Each comment shows: author avatar/icon, author name, timestamp, body (markdown rendered).
- Comment input at the bottom — a text area with markdown support and a "Comment" button.
- Comments from agents show a bot icon; comments from the board show a user icon.
Right Pane (Properties Panel)
Header: "Properties" label with a + button to add a custom field.
Property list: Each property is a row with label on the left and editable value on the right.
| Property | Control |
|---|---|
| Status | Dropdown with status options + colored dot |
| Priority | Dropdown with priority options + icon |
| Assignee | Agent picker dropdown with search |
| Project | Project picker dropdown |
| Goal | Goal picker dropdown |
| Labels | Multi-select tag input |
| Lead | Agent picker |
| Members | Multi-select agent picker |
| Start date | Date picker |
| Target date | Date picker |
| Created by | Read-only text |
| Created | Read-only timestamp |
| Billing code | Text input |
Below properties, a divider, then:
Activity section:
- "Activity" header with "See all" link.
- Compact timeline of recent events: status changes, assignment changes, comments, etc.
- Each entry: icon + description + relative timestamp.
5.4 New Issue Modal
Triggered by the sidebar pencil icon, keyboard shortcut C, or the + buttons in the issue list.
┌─────────────────────────────────────────────────────────┐
│ [📁 CLIP] › New issue [Save as draft] [↗] [×] │
├─────────────────────────────────────────────────────────┤
│ │
│ Issue title │
│ ___________________________________________________ │
│ │
│ Add a description... │
│ │
│ │
│ │
│ │
├─────────────────────────────────────────────────────────┤
│ [○ Todo] [--- Priority] [👤 Assignee] [📁 Project] │
│ [🏷 Labels] [···] │
├─────────────────────────────────────────────────────────┤
│ [📎] [◻ Create more] [Create issue] │
└─────────────────────────────────────────────────────────┘
Top bar:
- Breadcrumb showing context: project key (or company key)
›"New issue". - "Save as draft" button.
- Expand icon (open as full page instead of modal).
- Close
×.
Body:
- Title field: large input, placeholder "Issue title". Auto-focused on open.
- Description: markdown editor below, placeholder "Add a description...". Expandable.
Property chips (bottom bar):
- Compact row of property buttons. Each opens a dropdown to set that property.
- Default chips shown: Status (defaults to Todo), Priority, Assignee, Project, Labels.
···more button reveals: Goal, Start date, Target date, Billing code, Parent issue.
Footer:
- Attachment button (paperclip icon).
- "Create more" toggle — when on, creating an issue clears the form and stays open for rapid entry.
- "Create issue" primary button.
Behavior:
Cmd+Entersubmits the form.- If opened from within a project context, the project is pre-filled.
- If opened from a specific status group's
+button, that status is pre-filled. - The slug/key is auto-generated from the project prefix + incrementing number (shown in breadcrumb).
5.5 Issue Board View (Kanban)
Accessible via Display dropdown → Board layout.
Columns represent statuses: Backlog | Todo | In Progress | In Review | Done
Each card shows:
- Issue key (muted)
- Title (primary text)
- Priority icon (bottom-left)
- Assignee avatar (bottom-right)
Cards are draggable between columns. Dragging a card to a new column changes its status (with transition validation — invalid transitions show an error toast).
Each column header has a + button to create a new issue in that status.
6. Projects
6.1 Project List View
Similar to the issue list but for projects.
┌─────────────────────────────────────────────────────────┐
│ Projects [+ New project] │
├─────────────────────────────────────────────────────────┤
│ [icon] Paperclip Auth Backlog CTO Feb 20 │
│ [icon] Marketing Site In Progress CMO Mar 01 │
│ [icon] API v2 Planned CTO Mar 15 │
└─────────────────────────────────────────────────────────┘
Each row: project icon (colored hexagon), name, status badge, lead agent, target date.
6.2 Project Detail View (Three-Pane)
Uses the same three-pane layout as issue detail.
Breadcrumb tabs: Overview | Updates | Issues | Settings
Overview tab (middle pane):
- Project icon + name (editable)
- Description (markdown, editable)
- Inline properties bar:
[◌ Backlog] [--- No priority] [👤 Lead] [📅 Target date] [🏢 Team] [···] - "Resources" section: linked documents, URLs
- "Write first project update" CTA (for project updates/status posts)
- Description (markdown body)
- Milestones section (collapsible): list of milestone markers with date and status
Issues tab: filtered issue list showing only issues in this project. Same controls as the main issues view.
Right pane (properties): Status, Priority, Lead, Members, Start date, Target date, Teams, Labels, Goal link.
Activity section: at the bottom of the properties panel.
7. Goals
7.1 Goal List View
Goals are displayed as a hierarchical tree, since goals have parent-child relationships.
┌─────────────────────────────────────────────────────────┐
│ Goals [+ New goal] │
├─────────────────────────────────────────────────────────┤
│ ▼ 🎯 Build the #1 AI note-taking app Company Active│
│ ▼ 🎯 Grow signups to 10k Team Active│
│ 🎯 Launch marketing campaign Agent Planned │
│ 🎯 Optimize onboarding funnel Agent Planned │
│ ▼ 🎯 Ship v2.0 with AI features Team Active│
│ 🎯 Implement smart search Task Planned │
│ 🎯 Build auto-summarization Task Planned │
└─────────────────────────────────────────────────────────┘
Each row: expand chevron (if has children), target icon, title, level badge (Company/Team/Agent/Task), status badge.
Indentation reflects hierarchy. Clicking a goal opens its detail view.
7.2 Goal Detail View
Three-pane layout. Middle pane shows title, description, child goals, and linked projects. Right pane shows properties (level, status, owner agent, parent goal) and activity.
8. Dashboard
The dashboard is the company health overview. Shown when clicking "Dashboard" in the Company section.
8.1 Layout
┌──────────┬──────────────────────────────────────────────┐
│ │ Dashboard │
│ Sidebar │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌──────┐│
│ │ │ Agents │ │ Tasks │ │ Costs │ │Apprvl││
│ │ │ 12 total │ │ 47 open │ │ $234.50 │ │ 3 ││
│ │ │ 8 active │ │ 12 prog │ │ 67% bud │ │pending│
│ │ │ 2 paused │ │ 3 block │ │ │ │ ││
│ │ │ 1 error │ │ 28 done │ │ │ │ ││
│ │ └─────────┘ └─────────┘ └─────────┘ └──────┘│
│ │ │
│ │ ┌────────────────────┐ ┌─────────────────────┐│
│ │ │ Recent Activity │ │ Stale Tasks ││
│ │ │ ... │ │ ... ││
│ │ └────────────────────┘ └─────────────────────┘│
└──────────┴──────────────────────────────────────────────┘
Top row: Metric cards (4 across)
- Agents — total, active, running, paused, error counts. Each with colored dots.
- Tasks — open, in progress, blocked, done counts.
- Costs — month-to-date spend in dollars, budget utilization percentage with a mini progress bar.
- Approvals — pending count (clickable to navigate to Inbox, which is the primary approval interaction point).
Bottom row: Detail panels (2 across) 5. Recent Activity — last ~10 activity log entries, compact timeline format. 6. Stale Tasks — tasks that have been in progress for too long without updates. Each shows issue key, title, assignee, time since last activity.
All cards and panels are clickable to navigate to their respective full pages.
9. Org Chart
Interactive visualization of the agent reporting hierarchy.
9.1 Tree View
┌─────────┐
│ CEO │
│ running │
└────┬────┘
┌────────────┼────────────┐
┌────┴────┐ ┌────┴────┐ ┌───┴─────┐
│ CTO │ │ CMO │ │ CFO │
│ active │ │ idle │ │ paused │
└────┬────┘ └────┬────┘ └─────────┘
┌────┴────┐ ┌────┴────┐
│ Dev-1 │ │ Mktg-1 │
│ running │ │ idle │
└─────────┘ └─────────┘
Each node shows:
- Agent name
- Role/title (smaller text)
- Status dot (colored by agent status)
- Agent avatar (bot icon with unique color per agent)
Nodes are clickable to navigate to agent detail.
9.2 Interactions
- Zoom/pan with mouse wheel and drag.
- Click a node to select it — shows a brief tooltip with key info (last heartbeat, current task, spend).
- Double-click a node to navigate to agent detail page.
- Right-click node for context menu: View, Pause, Resume, Invoke heartbeat, Edit.
10. Agents
10.1 Agent List View
┌─────────────────────────────────────────────────────────────────┐
│ Agents [+ New agent] │
├─────────────────────────────────────────────────────────────────┤
│ [🤖] CEO ceo ● Running $45.20/$100 2m ago │
│ [🤖] CTO cto ● Active $23.10/$100 5m ago │
│ [🤖] Dev-1 engineer ○ Idle $12.40/$50 15m ago │
│ [🤖] CMO marketing ○ Idle $8.30/$50 30m ago │
│ [🤖] DevOps devops ⚠ Paused $31.00/$50 1h ago │
└─────────────────────────────────────────────────────────────────┘
Columns: Avatar/icon, Name, Role, Status (with colored dot), Cost (spent/budget this month), Last Heartbeat (relative time).
Clicking a row navigates to agent detail.
10.2 Agent Detail View (Three-Pane)
Breadcrumb tabs: Overview | Heartbeats | Issues | Costs
Overview (middle pane):
- Agent name + role
- Capabilities description
- Adapter type + config summary
- Current task (if any)
- Reports to: [clickable agent name]
- Direct reports: list of agents
Heartbeats tab: table of heartbeat runs — time, source (manual/scheduler), status, duration, error (if any). Invoke button at top.
Issues tab: issues assigned to this agent.
Costs tab: cost breakdown for this agent — by model, by time period, with budget progress bar.
Right pane properties: Status, Role, Title, Reports To, Adapter Type, Context Mode, Budget (monthly), Spent (monthly), Last Heartbeat.
Quick actions in breadcrumb bar: [Pause] [Resume] [Invoke Heartbeat] [···]
11. Approvals (Contextual, Not Standalone)
Approvals are governance gates — decisions the board must make (hire an agent, approve a CEO strategy). They are NOT work items. Their data model stays separate from issues (different status machine, side-effect triggers, unstructured payload). But they don't need their own top-level nav entry.
11.1 Where Approvals Surface
1. Inbox (primary). Pending approvals are the highest-priority inbox items. The board operator sees them front and center with inline approve/reject actions (see Section 14).
2. Dashboard metric card. The "Pending Approvals" card shows the count and links to the full approvals list.
3. Inline on entity pages. When an entity was created via an approval, the detail page shows a contextual banner:
- Agent detail page:
"Hired via approval — requested by CEO on Feb 15"with a link to the approval record. - An agent in
pendingstatus (not yet created) could show:"Pending approval — requested by CEO"with approve/reject actions inline.
4. Activity log. Approval events (created, approved, rejected) appear in the activity timeline like any other event.
11.2 Approvals List Page (/approvals)
This page still exists — it's the "See all" destination from Inbox and Dashboard. But it's not in the sidebar.
┌─────────────────────────────────────────────────────────┐
│ Approvals [Pending] [Approved] [Rejected] [All] │
├─────────────────────────────────────────────────────────┤
│ 🟡 Hire Agent: "Marketing Analyst" CEO 2h ago │
│ 🟡 CEO Strategy: "Q2 Growth Plan" CEO 4h ago │
│ 🟢 Hire Agent: "DevOps Engineer" CTO 1d ago │
└─────────────────────────────────────────────────────────┘
Status tabs filter by approval status. Each row: status dot, type, title/summary (from payload), requester, relative time.
11.3 Approval Detail View
Three-pane layout. Middle pane renders the approval payload nicely based on type:
hire_agent type: Shows proposed agent name, role, title, reports-to, capabilities, adapter config, budget. Essentially a preview of the agent that will be created.
approve_ceo_strategy type: Shows the strategy text, proposed goal breakdown, initial task structure.
For pending approvals, prominent action buttons at the top of the middle pane:
┌─────────────────────────────────────────────────────────┐
│ ┌─────────────────────────────────────────────────────┐ │
│ │ Decision note (optional): _________________________ │ │
│ │ [✕ Reject] [✓ Approve] │ │
│ └─────────────────────────────────────────────────────┘ │
│ │
│ Hire Agent Request │
│ ───────────────── │
│ Name: Marketing Analyst │
│ Role: marketing │
│ Reports to: CMO │
│ Budget: $100/month │
│ ... │
└─────────────────────────────────────────────────────────┘
Right pane: Type, Status, Requested by, Requested at, Decided by, Decided at, Decision note. Activity timeline below.
12. Costs
12.1 Cost Dashboard
┌─────────────────────────────────────────────────────────┐
│ Costs Feb 2026 │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────┐│
│ │ Month-to-date: $234.50 / $500.00 [====-------] 47% ││
│ └──────────────────────────────────────────────────────┘│
│ │
│ By Agent By Project │
│ ┌──────────────────────┐ ┌──────────────────────┐ │
│ │ CEO $45.20 │ │ Auth $67.30 │ │
│ │ CTO $23.10 │ │ Marketing $34.50 │ │
│ │ Dev-1 $12.40 │ │ API v2 $12.00 │ │
│ │ ... │ │ ... │ │
│ └──────────────────────┘ └──────────────────────┘ │
│ │
│ Recent Cost Events │
│ ┌──────────────────────────────────────────────────────┐│
│ │ CEO openai/gpt-5 1,234 in / 567 out $0.89 2m ago│
│ │ ... │
│ └──────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────┘
Top: company-wide budget progress bar (large, prominent).
Two side-by-side tables: breakdown by agent and by project. Each row shows entity name and spend amount.
Bottom: recent cost events table with agent, provider/model, token counts, cost, and timestamp.
13. Activity Log
A chronological, filterable audit trail.
┌─────────────────────────────────────────────────────────┐
│ Activity [Filter by type ▼] │
├─────────────────────────────────────────────────────────┤
│ 🤖 CEO created issue CLIP-12 "Fix auth" 2 min ago │
│ 👤 Board approved hire "Marketing Analyst" 5 min ago │
│ 🤖 CTO changed CLIP-8 status → In Progress 10 min ago │
│ ⚙ System paused agent DevOps (budget limit) 15 min ago│
│ 🤖 Dev-1 commented on CLIP-5 30 min ago │
│ ... │
└─────────────────────────────────────────────────────────┘
Each entry: actor icon (bot for agent, user for board, gear for system), actor name, action description with entity links, relative timestamp.
Filterable by: actor type (agent/user/system), entity type (issue/agent/project/etc), action type, time range.
Infinite scroll with "Load more" fallback.
14. Inbox
The inbox is the board operator's primary action center. It aggregates everything that needs human attention, with approvals as the highest-priority category.
14.1 Inbox List View
┌─────────────────────────────────────────────────────────┐
│ Inbox [Mark all read] │
├─────────────────────────────────────────────────────────┤
│ APPROVALS See all approvals → │
│ ● 🛡 Hire Agent: "Marketing Analyst" │
│ │ Requested by CEO · 2h ago │
│ │ Role: marketing · Reports to: CMO · Budget: $100/mo │
│ │ [✕ Reject] [✓ Approve] │
│ │ │
│ ● 🛡 CEO Strategy: "Q2 Growth Plan" │
│ │ Requested by CEO · 4h ago │
│ │ [View details →] │
│ │
│ ALERTS │
│ ● 🔴 Agent Error: DevOps heartbeat failed 1h ago │
│ ● ⚠ Budget Alert: CEO at 80% monthly budget 3h ago │
│ │
│ STALE WORK │
│ ⏰ CLIP-3 "Set up CI pipeline" — no update in 24h │
│ ⏰ CLIP-7 "Write tests" — no update in 36h │
└─────────────────────────────────────────────────────────┘
14.2 Inbox Categories
Items are grouped by category, with the most actionable items first:
Approvals pending (top priority). Each approval item shows:
- Shield icon + approval type + title
- Requester + relative timestamp
- Key payload summary (1 line — agent name/role for hires, plan title for strategies)
- Inline [Approve] and [Reject] buttons for simple approvals (hire_agent). Clicking Approve/Reject shows a brief confirmation with an optional decision note field.
- [View details →] link for complex approvals (approve_ceo_strategy) that need full review before deciding.
- "See all approvals →" link in the category header navigates to
/approvals.
Alerts. Agent errors (failed heartbeats, error status) and budget alerts (agents or company approaching 80% or 100% limits). Each links to the relevant agent or cost page.
Stale work. Tasks in in_progress or todo with no activity (no comments, no status changes) beyond a configurable threshold (default: 24h). Each shows issue key, title, and time since last activity. Clicking navigates to the issue.
14.3 Inbox Behavior
- Unread items have a filled blue dot indicator on the left.
- Clicking an item marks it as read.
- Approvals disappear from the inbox once approved/rejected (they move to the resolved state).
- Alerts disappear when the underlying condition is resolved (agent resumed, budget increased).
- The sidebar badge count reflects total unresolved inbox items.
- Inbox is computed from live data (pending approvals query + alert conditions), not a separate notification table. This keeps it simple for V1.
15. Search (Cmd+K Modal)
Global search accessible via Cmd+K or the sidebar search icon.
┌─────────────────────────────────────────────────────────┐
│ 🔍 Search issues, agents, projects... │
├─────────────────────────────────────────────────────────┤
│ Recent │
│ 📋 CLIP-42 Fix user authentication bug │
│ 🤖 CEO │
│ 📁 Auth project │
├─────────────────────────────────────────────────────────┤
│ Actions │
│ ✏️ Create new issue C │
│ 🤖 Create new agent │
│ 📁 Create new project │
└─────────────────────────────────────────────────────────┘
- Type-ahead search across all entity types (issues, agents, projects, goals).
- Results grouped by type with icons.
- Recent items shown when input is empty.
- Quick actions section at the bottom.
- Arrow keys to navigate, Enter to select, Escape to close.
16. Keyboard Shortcuts
| Shortcut | Action |
|---|---|
Cmd+K |
Open search |
C |
Create new issue |
Cmd+Enter |
Submit form (in modals) |
Escape |
Close modal / deselect |
[ |
Toggle sidebar collapsed |
] |
Toggle properties panel |
J / K |
Navigate up/down in lists |
Enter |
Open selected item |
Backspace |
Go back |
S |
Toggle status on selected issue |
X |
Toggle checkbox selection |
Cmd+A |
Select all (in list context) |
17. Responsive Behavior
- >1400px: Full three-pane layout (sidebar + main + properties).
- 1024-1400px: Sidebar collapses to icons. Properties panel available via toggle.
- <1024px: Sidebar hidden (hamburger menu). Properties panel hidden (toggle or tab).
The properties panel is always dismissible — it should never block the main content.
18. Empty States
Every list view should have a thoughtful empty state:
- No issues: "No issues yet. Create your first issue to start tracking work." with a
[Create issue]button. - No agents: "No agents in this company. Create an agent to start building your team." with a
[Create agent]button. - No company selected: "Select a company to get started." with a company switcher or
[Create company]button.
Empty states should use a muted illustration (simple line art, not cartoons) and a single call-to-action.
19. Loading and Error States
- Loading: Skeleton placeholders matching the layout of the expected content (not spinners). Skeleton blocks animate with a subtle shimmer.
- Error: Inline error message with a retry button. Never a full-page error unless the app itself is broken.
- Conflict (409): Toast notification: "This issue was updated by another user. Refresh to see changes." with a [Refresh] action.
- Optimistic updates: Status changes and property edits should update immediately in the UI, with rollback on failure.
20. Component Library
Build on top of shadcn/ui components with these customizations:
| Component | Base | Customization |
|---|---|---|
| StatusBadge | Badge | Colored dot + label, entity-specific palettes |
| PriorityIcon | custom | SVG circles with fills matching priority |
| EntityRow | custom | Standardized list row with hover/select states |
| PropertyEditor | custom | Label + inline-editable value with dropdown |
| CommentThread | custom | Avatar + author + timestamp + markdown body |
| BreadcrumbBar | Breadcrumb | Integrated with router, tabs, and entity actions |
| CommandPalette | Dialog | Cmd+K search with type-ahead and actions |
| FilterBar | custom | Composable filter chips with add/remove |
| SidebarNav | custom | Grouped, collapsible, badge-supporting nav |
21. URL Structure
All routes are company-scoped after company selection (company context stored in React context, not URL):
/ → redirects to /dashboard
/dashboard → company dashboard
/inbox → inbox / attention items
/my-issues → board operator's issues
/issues → issue list
/issues/:issueId → issue detail
/projects → project list
/projects/:projectId → project detail (overview tab)
/projects/:projectId/issues → project issues
/goals → goal hierarchy
/goals/:goalId → goal detail
/org → org chart
/agents → agent list
/agents/:agentId → agent detail
/approvals → approval list
/approvals/:approvalId → approval detail
/costs → cost dashboard
/activity → activity log
/companies → company management (list/create)
/settings → company settings
22. Implementation Priority
Phase 1: Shell and Navigation
- Sidebar redesign (grouped sections, icons, company switcher, badges)
- Breadcrumb bar component
- Three-pane layout system
- Cmd+K search modal
- Install
lucide-react
Phase 2: Issue Management (Core)
- Issue list view with grouping, filtering, status circles
- Issue detail view (three-pane with properties panel)
- New issue modal
- Issue comments
- Bulk selection and actions
- Kanban board view
Phase 3: Entity Detail Views
- Project list + detail view
- Goal hierarchy view
- Agent list + detail view
Phase 4: Company-Level Views
- Inbox with inline approval actions (primary approval UX)
- Dashboard redesign with metric cards
- Org chart interactive visualization
- Cost dashboard
- Activity log with filtering
- Approvals list page (accessed via Inbox "See all", not sidebar)
Phase 5: Polish
- Keyboard shortcuts
- Responsive behavior
- Empty states and loading skeletons
- Error handling and toasts
- Saved views (custom filters)