Skip to content
Skills Library
AI & agents · Planning

team-projects

/team-projects

Multi-agent project management with task boards, @-mention routing, WBS, and orchestrated team collaboration. Includes a Control UI plugin tab with project dashboard and a right-edge Team Chat drawer for live activity. Enables a coordinator agent to plan projects, break down work into phases and tasks, assign to specialist agents, dispatch via sessions_spawn, and track progress to completion. Use when: (1) managing work across multiple OpenClaw agents, (2) creating project plans with work breakdown structures, (3) assigning and tracking tasks across agents, (4) coordinating multi-agent workflo

Licence
MIT
Last repository change
20.07.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
20
Scripts
12
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 20.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 12 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: gateway-plugin/app-gateway-patch.ts, gateway-plugin/app-render-patch.ts, gateway-plugin/index.ts, gateway-plugin/plugin-sdk-entry.ts, gateway-plugin/team-chat-drawer.ts, gateway-plugin/team-projects-view.ts, scripts/gateway-handlers.js, scripts/orchestrator.js

What it does and when to use it

Multi-agent project management with task boards, @-mention routing, WBS, and orchestrated team collaboration. Includes a Control UI plugin tab with project dashboard and a right-edge Team Chat drawer for live activity. Enables a coordinator agent to plan projects, break down work into phases and tasks, assign to specialist agents, dispatch via sessions_spawn, and track progress to completion. Use when: (1) managing work across multiple OpenClaw agents, (2) creating project plans with work breakdown structures, (3) assigning and tracking tasks across agents, (4) coordinating multi-agent workflo

Original author description

Multi-agent project management with task boards, @-mention routing, WBS, and orchestrated team collaboration. Includes a Control UI plugin tab with project dashboard and a right-edge Team Chat drawer for live activity. Enables a coordinator agent to plan projects, break down work into phases and tasks, assign to specialist agents, dispatch via sessions_spawn, and track progress to completion. Use when: (1) managing work across multiple OpenClaw agents, (2) creating project plans with work breakdown structures, (3) assigning and tracking tasks across agents, (4) coordinating multi-agent workflo

How it works

  1. Overview
  2. UI Components
  3. Installation
  4. Usage
  5. Data Model
  6. Architecture
  7. Coordinator Prompt Template
  8. Known Issues & Gotchas
  9. Limitations
  10. Future Enhancements
Original SKILL.md headings · 460 lines, 2,093 words
SKILL.md preview
---
name: team-projects
description: "Multi-agent project management with task boards, @-mention routing, WBS, and orchestrated team collaboration. Includes a Control UI plugin tab with project dashboard and a right-edge Team Chat drawer for live activity. Enables a coordinator agent to plan projects, break down work into phases and tasks, assign to specialist agents, dispatch via sessions_spawn, and track progress to completion. Use when: (1) managing work across multiple OpenClaw agents, (2) creating project plans with work breakdown structures, (3) assigning and tracking tasks across agents, (4) coordinating multi-agent workflows with dependencies, (5) running team-based projects with progress tracking."
metadata:
  {
    "openclaw": {
      "emoji": "📋",
      "requires": {
        "config": {
          "tools.agentToAgent.enabled": true,
          "agents.list": "at least 2 agents configured"
        }
      }
    }
  }
---

# 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 project stats
node {{SKILL_DIR}}/scripts/project-store.js stats --id PROJECT_ID

# View work breakdown structure
node {{SKILL_DIR}}/scripts/project-store.js wbs --id PROJECT_ID

# Check and advance completed phases
node {{SKILL_DIR}}/scripts/orchestrator.js advance PROJECT_ID
```

### Updating Tasks

```bash
# Mark task in progress
node {{SKILL_DIR}}/scripts/project-store.js update-task \
  --project PROJECT_ID --id TASK_ID --status in_progress

# Mark task done
node {{SKILL_DIR}}/scripts/project-store.js update-task \
  --project PROJECT_ID --id TASK_ID --status done

# Add a comment
node {{SKILL_DIR}}/scripts/project-store.js add-comment \
  --project PROJECT_ID --task TASK_ID \
  --author main --text "Looks good, merging now"
```

## Data Model

### Project
```
project
├── id, name, slug, description
├── status: planning | active | paused | completed | archived
├── coordinator: agentId
├── agents: [agentId, ...]
└── phases[]
    ├── id, name, description, order
    ├── status: pending | active | completed
    └── tasks[]
        ├── id, title, description
        ├── assignee: agentId
        ├── priority: critical | high | medium | low
        ├── status: todo | in_progress | blocked | review | done
        ├── dependsOn: [taskId, ...]
        ├── sessionKey: (set when dispatched)
        ├── artifacts: [paths/URLs]
        └── comments[]
```

### Storage
- **Projects:** `~/.openclaw/workspace/team-projects/projects.json`
- **Chat logs:** `~/.openclaw/workspace/team-projects/chat_PROJECT_ID.jsonl`
- **Orchestrator state:** `~/.openclaw/workspace/team-projects/orchestrator-state.json`

## Architecture

### How It Works

```
┌─────────────┐     sessions_spawn      ┌──────────────┐
│ Coordinator  │ ──────────────────────→ │  Worker Agent │
│   (Koda)     │                         │  (researcher) │
│              │ ←── push completion ──── │              │
│  project-    │                         └──────────────┘
│  store.js    │     sessions_spawn      ┌──────────────┐
│              │ ──────────────────────→ │  Worker Agent │
│  orchestr-   │                         │   (coder)     │
│  ator.js     │ ←── push completion ──── │              │
│              │                         └──────────────┘
│  UI plugin   │     sessions_send       ┌──────────────┐
│  tab         │ ←────────────────────── │  Worker Agent │
└─────────────┘     (inter-agent msg)    │   (writer)    │
                                         └──────────────┘
```

### Key Design Decisions

1. **Push-based completion** — No polling. OpenClaw's `subagent-announce` system delivers completion events automatically.
2. **Dependency gates** — The orchestrator only dispatches tasks whose `dependsOn` are all `done`.
3. **Tool isolation** — Each agent gets only the tools they need. A researcher can't exec arbitrary code; a coder can't send messages to external channels.
4. **File-based persistence** — Simple JSON storage. No database required. Works on any OpenClaw instance.
5. **CLI-first** — All operations available via CLI. The UI is optional.
6. **Agent-native** — Uses OpenClaw's existing `sessions_spawn`, `sessions_send`, and `agents_list` tools. No custom transport.
7. **Plugin architecture** — Projects tab registered via OpenClaw's `uiPluginRegistry` (client-side). Team Chat drawer uses inline `<style>` tags for CSS (no Shadow DOM).
8. **Client-side plugin registration** — Since the gateway plugin view registration pipeline isn't fully wired end-to-end, the Projects tab is registered client-side in `app-gateway.ts` during `onHello`. This is reliable and avoids depending on gateway-side plugin infrastructure.

### Plugin Registration Points (4 required for gateway plugin)

When adding a new gateway plugin to OpenClaw, you must register it in 4 places:

| File | What to add |
|------|-------------|
| `src/plugin-sdk/<id>.ts` | SDK type entry (exports `OpenClawPluginApi` etc.) |
| `src/plugins/loader.ts` → `pluginSdkScopedAliasEntries` | Jiti alias so runtime can resolve `openclaw/plugin-sdk/<id>` |
| `tsdown.config.ts` → `pluginSdkEntrypoints` | Build entry so `dist/plugin-sdk/<id>.js` gets generated |
| `scripts/write-plugin-sdk-entry-dts.ts` | DTS entry generator |
| `package.json` → exports → `./plugin-sdk/<id>` | Package subpath export |

Missing any one of these causes `Cannot find module` errors at runtime.

### CSS Gotcha: No Shadow DOM

OpenClaw's `OpenClawApp` uses `createRenderRoot() { return this; }` — it renders directly to the DOM without Shadow DOM. This means:

- Lit `css` tagged templates (used with `static styles`) are **never applied**
- All styles must be embedded as `<style>` tags in the HTML returned by render functions
- The `teamChatDrawerStyles` export was originally dead code until fixed to use inline styles

## Coordinator Prompt Template

The coordinator agent should include `templates/coordinator-prompt.md` in its system prompt (or SOUL.md). This gives it the commands and workflow for managing projects.

Worker agents should include `templates/worker-prompt.md` for task completion protocols.

## Known Issues & Gotchas

### `allowAgents` must be per-agent
Setting `agents.defaults.subagents.allowAgents: ["*"]` does NOT work. The code at `agents-list-tool.ts:49` reads:
```typescript
const allowAgents = resolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgents ?? [];
```
This resolves the per-agent config entry, not defaults. You must add it to the agent's entry in `agents.list`.

### `dependsOn` normalization
The CLI passes `--dependsOn task_abc` as a string, not an array. The project store and orchestrator both normalize with `Array.isArray()` checks. If you create tasks programmatically, always pass an array.

### UI requires hard refresh
After rebuilding the UI (`pnpm ui:build`) and restarting the gateway, browsers may cache the old JS bundle. Always hard-refresh (Ctrl+Shift+R) after UI changes.

### Icon availability
The icon used for the Projects tab must exist in `ui/src/ui/icons.ts`. Available icons include: `fileText`, `folder`, `barChart`, `zap`, `brain`, `settings`, `plug`, etc. Custom icon names like `clipboard-list` won't work — use `fileText` instead.

## Limitations

- **No real-time UI sync** — The UI reads from JSON files; updates appear on refresh, not live push.
- **No native gateway RPC** — The project board is managed via CLI tools, not gateway RPC methods (yet).
- **Single coordinator** — One agent coordinates per project (though you could have different coordinators for different projects).
- **No cost tracking** — Task cost/token tracking depends on OpenClaw's session usage system.
- **Client-side plugin registration** — The gateway-side plugin view registration pipeline (`registerView` → hello snapshot → `loadFromGateway`) is scaffolded but not fully wired. Plugin tabs are registered client-side instead.

## Future Enhancements

- [ ] Gateway RPC plugin for live UI updates via WebSocket
- [ ] Kanban drag-and-drop in the sidebar
- [ ] Gantt chart / timeline view
- [ ] Automated task creation from GitHub issues
- [ ] Cost/token budget per task
- [ ] Agent capability auto-detection from tools config
- [ ] Cron-based project health checks
- [ ] Gateway-side plugin view registration (when pipeline is complete)

## Files

```
team-projects/
├── SKILL.md                              # This file
├── scripts/
│   ├── project-store.js                  # CRUD for projects, phases, tasks, comments
│   ├── orchestrator.js                   # Dispatch planning, dependency gates, phase advancement
│   ├── task-router.js                    # @-mention parsing and dispatch planning
│   └── gateway-handlers.js              # HTTP API adapter (optional)
├── ui/
│   ├── project-sidebar.js               # Sidebar panel component (standalone)
│   └── team-chat.js                     # Multi-agent chat component (standalone)
├── gateway-plugin/
│   ├── index.ts                         # Gateway plugin source (extensions/team-projects/)
│   ├── openclaw.plugin.json             # Plugin manifest
│   ├── plugin-sdk-entry.ts              # SDK type entry (src/plugin-sdk/team-projects.ts)
│   ├── team-projects-view.ts            # UI view renderer (ui/src/ui/views/team-projects.ts)
│   ├── team-chat-drawer.ts              # Team Chat drawer + edge tab (ui/src/ui/views/team-chat-drawer.ts)
│   ├── app-render-patch.ts              # Patch for app-render.ts (plugin tab catch-all + drawer)
│   ├── app-gateway-patch.ts             # Patch for app-gateway.ts (renderer registration)
│   └── BUILD_REGISTRATION.md            # Build pipeline registration checklist
├── templates/
│   ├── coordinator-prompt.md            # System prompt for coordinator agent
│   └── worker-prompt.md                 # System prompt fragment for worker agents
└── references/
    ├── example-config.json              # Example openclaw.json for team setup
    └── walkthrough.md                   # Step-by-step usage guide
```
Files in this package (20)
  • SKILL.md 18 KB
  • _meta.json 1 KB
  • gateway-plugin/BUILD_REGISTRATION.md 1 KB
  • gateway-plugin/app-gateway-patch.ts 1 KB
  • gateway-plugin/app-render-patch.ts 2 KB
  • gateway-plugin/index.ts 1 KB
  • gateway-plugin/openclaw.plugin.json 1 KB
  • gateway-plugin/plugin-sdk-entry.ts 1 KB
  • gateway-plugin/team-chat-drawer.ts 24 KB
  • gateway-plugin/team-projects-view.ts 19 KB
  • references/example-config.json 2 KB
  • references/walkthrough.md 3 KB
  • scripts/gateway-handlers.js 5 KB
  • scripts/orchestrator.js 9 KB
  • scripts/project-store.js 14 KB
  • scripts/task-router.js 6 KB
  • templates/coordinator-prompt.md 3 KB
  • templates/worker-prompt.md 1 KB
  • ui/project-sidebar.js 22 KB
  • ui/team-chat.js 8 KB

Versions

The database has no other skills named team-projects.

Database snapshot: 13.11.2026 · package version 29a60732afa5 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100task-system
    Manage shared task lists for agent teams including creating tasks, setting dependencies, claiming work, and tracking progress. Use when creating work items, building task pipelines, coordinating task ownership, or managing task dependencies.
  • 95agent-team-builder
    Guide users through building a custom multi-agent team on OpenClaw — from role design to workspace files, routing bindings, channel configuration, and collaboration rules. Use this skill whenever the user mentions building an AI team, multi-agent setup, multi-agent…
  • 100oh-my-claudecode
    Orchestrate multi-agent Claude Code teams — assign roles, coordinate parallel tasks, share context between agents, and manage team workflows. Use when: running multiple Claude Code agents simultaneously, building team-based AI development workflows, coordinating complex multi-agent coding projects.
  • 100team-lead
    (forwward) Orchestrates multi-agent engineering and business teams by analyzing tasks, selecting team shapes, assigning specialist roles, and coordinating parallel agent work with skill dispatch. Triggers on tasks needing 2+ agents, feature dev with frontend + backend, quality…
  • 100project-manager
    Project Manager role skill. Use when you need to break down tasks, define a WBS, manage dependencies, control delivery pace, or translate confirmed requirements and architecture into an executable task plan. Keywords: task breakdown, WBS, milestones, dependency management,…
  • 100team-planner
    Use when a task is too large or multi-domain for a single agent — assemble a specialist team, assign work via SQL tracking, dispatch with /fleet or task tool, and synthesize results

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.