team-projects

What this skill does

# Team Projects 📋

Multi-agent project management for OpenClaw. Run agent teams that plan, assign, execute, and track work together. Includes a **Control UI plugin tab** for visual project tracking and a **right-edge Team Chat drawer** for live agent activity.

## Overview

This skill enables a **coordinator agent** to manage projects across multiple specialist agents:

```
User → Coordinator (Koda) → dispatches tasks via sessions_spawn
                            ├── @researcher → web research, data analysis
                            ├── @coder → writing code, building features
                            ├── @writer → copy, documentation, content
                            └── ... any configured agent
```

Each agent works independently with their own tools and workspace. The coordinator tracks progress, manages dependencies, and advances the project.

## UI Components

### 1. Projects Tab (sidebar)
A full project dashboard registered as a plugin tab in the Control sidebar under the "Control" group. Shows project cards, task boards with phase sections, team overview, and progress stats.

### 2. Team Chat Drawer (right edge)
A slide-out panel accessible from a vertical "Team" tab fixed to the right edge of the screen. Shows:
- Live agent activity feed (sub-agent sessions, messages)
- Project progress bar
- Task overview (collapsible)
- Quick message input to send commands

## Installation

### Step 1: Config Prerequisites

Add to `openclaw.json`:

```json
{
  "tools": {
    "agentToAgent": {
      "enabled": true,
      "allow": ["*"]
    }
  }
}
```

Add `subagents.allowAgents` to the **coordinator agent's list entry** (NOT on `agents.defaults`):

```json
{
  "agents": {
    "list": [
      {
        "id": "main",
        "default": true,
        "name": "Koda",
        "subagents": {
          "allowAgents": ["*"]
        }
      }
    ]
  }
}
```

> ⚠️ **Critical:** `allowAgents` must be on the agent's own entry in `agents.list`. Setting it on `agents.defaults.subagents` does NOT work. The code reads `resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents` which resolves the per-agent config, not defaults.

### Step 2: Gateway Plugin Installation (for Projects tab)

The Projects tab requires installing a gateway plugin. This involves 4 registration points in the OpenClaw source:

#### 2a. Plugin SDK entry

Create `src/plugin-sdk/team-projects.ts`:

```typescript
export { emptyPluginConfigSchema } from "../plugins/config-schema.js";
export type {
  OpenClawPluginApi,
  PluginViewRegistration,
} from "../plugins/types.js";
```

#### 2b. Plugin extension

Create `extensions/team-projects/openclaw.plugin.json`:

```json
{
  "id": "team-projects",
  "configSchema": {
    "type": "object",
    "additionalProperties": false,
    "properties": {}
  }
}
```

Create `extensions/team-projects/index.ts` — see `gateway-plugin/index.ts`.

#### 2c. Register in build pipeline (4 files)

**`tsdown.config.ts`** — Add `"team-projects"` to the `pluginSdkEntrypoints` array.

**`src/plugins/loader.ts`** — Add to the `pluginSdkScopedAliasEntries` array:
```typescript
{
  subpath: "team-projects",
  srcFile: "team-projects.ts",
  distFile: "team-projects.js",
},
```

**`scripts/write-plugin-sdk-entry-dts.ts`** — Add `"team-projects"` to the entrypoints array.

**`package.json`** — Add to the exports map:
```json
"./plugin-sdk/team-projects": {
  "types": "./dist/plugin-sdk/team-projects.d.ts",
  "default": "./dist/plugin-sdk/team-projects.js"
},
```

#### 2d. Enable in config

```json
{
  "plugins": {
    "allow": ["telegram", "discord", "team-projects"],
    "entries": {
      "team-projects": {
        "enabled": true
      }
    }
  }
}
```

### Step 3: UI View Installation

#### 3a. Team Projects view

Copy `gateway-plugin/team-projects-view.ts` to `ui/src/ui/views/team-projects.ts`.

#### 3b. Team Chat Drawer

Copy `gateway-plugin/team-chat-drawer.ts` to `ui/src/ui/views/team-chat-drawer.ts`.

> ⚠️ **Critical: No Shadow DOM** — The OpenClaw app uses `createRenderRoot() { return this; }`, so Lit `css` tagged templates are NOT applied. All styles must be embedded as inline `<style>` tags in the rendered HTML. The team-chat-drawer uses an inline `<style>` block inside `renderTeamChatEdgeTab()` so styles are present even when the drawer is closed.

#### 3c. Wire into app-render.ts

See `gateway-plugin/app-render-patch.ts` for the integration points:

1. Import `renderTeamChatDrawer` and `renderTeamChatEdgeTab` from `./views/team-chat-drawer.ts`
2. Before `</main>`, add `${renderPluginTabContent(state)}`
3. After `</main>`, add the edge tab and drawer renders
4. Add the `renderPluginTabContent()` function

#### 3d. Wire into app-gateway.ts

See `gateway-plugin/app-gateway-patch.ts` for the integration points:

1. Import `uiPluginRegistry` from `./plugins/registry.ts`
2. Import `renderTeamProjects` from `./views/team-projects.ts`
3. In `onHello`, after `applySnapshot()`, call `registerTeamProjectsPlugin()`
4. Add the `registerTeamProjectsPlugin()` function

#### 3e. Add view state fields

In `ui/src/ui/app-view-state.ts`, add to `AppViewState`:

```typescript
teamChatOpen: boolean;
teamChatProject: unknown;
teamChatSessions: unknown[];
teamChatActivity: unknown[];
teamChatLoading: boolean;
teamChatInput: string;
teamChatTasksCollapsed: boolean;
```

In `ui/src/ui/app-settings.ts`, add `teamChatOpen?: boolean` to `SettingsHost` type, and add defensive cleanup in `applyTabSelection()`:

```typescript
} else if (host.teamChatOpen) {
  host.teamChatOpen = false;
}
```

### Step 4: Build & Restart

```bash
cd ~/openclaw
pnpm build        # Backend (gateway + plugin SDK)
pnpm ui:build     # Control UI
openclaw gateway restart
```

Hard-refresh the browser (Ctrl+Shift+R) to load the new UI assets.

## Usage

### Creating a Project

Tell the coordinator agent what you want to build. It will:
1. Create the project with appropriate phases
2. Break down work into tasks
3. Assign tasks to agents based on capabilities
4. Dispatch ready tasks

**Example prompt:**
> "Create a team project to redesign our company website. @researcher should analyze competitors, @writer should draft copy, and @coder should build it in React. Priority: launch in 2 weeks."

### The Coordinator's Workflow

The coordinator uses CLI tools to manage the project board:

```bash
# Create a project
node {{SKILL_DIR}}/scripts/project-store.js create-project \
  --name "Website Redesign" \
  --description "Full redesign of company website" \
  --coordinator main \
  --agents "researcher,writer,coder"

# Add phases (ordered)
node {{SKILL_DIR}}/scripts/project-store.js add-phase \
  --project PROJECT_ID --name "Research" --description "Competitive analysis"

# Add tasks with assignments and dependencies
node {{SKILL_DIR}}/scripts/project-store.js add-task \
  --project PROJECT_ID --phase PHASE_ID \
  --title "Analyze top 5 competitors" \
  --description "Research competitor websites..." \
  --assignee researcher --priority high

node {{SKILL_DIR}}/scripts/project-store.js add-task \
  --project PROJECT_ID --phase PHASE_ID \
  --title "Write homepage hero copy" \
  --assignee writer --priority high \
  --dependsOn "task_abc123"
```

### Dispatching Tasks

The orchestrator identifies ready tasks (dependencies met, not yet dispatched):

```bash
# See what's ready to dispatch
node {{SKILL_DIR}}/scripts/orchestrator.js plan PROJECT_ID
```

Then dispatch via OpenClaw's native `sessions_spawn`:

```
sessions_spawn(
  agentId: "researcher",
  task: "Research the top 5 competitors in the AI SaaS space...",
  label: "task_abc123"
)
```

### Agent Communication

Agents can communicate using @-mentions:

- **@agentId** — Direct message to an agent (routed via `sessions_send`)
- **@all** / **@team** — Broadcast to all project agents
- **#task_id** — Reference a task
- **TASK_COMPLETE: #task_id** — Signal task completion
- **TASK_BLOCKED: #task_id** — Signal a blocker

### Tracking Progress

```bash
# View projec