Multi-agent project management with task boards, @-mention routing, WBS, and orchestrated team collaboration. Includes a Control UI plugin tab with project d...
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.
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.
Add to openclaw.json:
{
"tools": {
"agentToAgent": {
"enabled": true,
"allow": ["*"]
}
}
}
Add subagents.allowAgents to the coordinator agent's list entry (NOT on agents.defaults):
{
"agents": {
"list": [
{
"id": "main",
"default": true,
"name": "Koda",
"subagents": {
"allowAgents": ["*"]
}
}
]
}
}
⚠️ Critical:
allowAgentsmust be on the agent's own entry inagents.list. Setting it onagents.defaults.subagentsdoes NOT work. The code readsresolveAgentConfig(cfg, requesterAgentId)?.subagents?.allowAgentswhich resolves the per-agent config, not defaults.
The UI tab requires installing a gateway plugin. This involves 4 registration points in the OpenClaw source:
Create src/plugin-sdk/team-projects.ts:
export { emptyPluginConfigSchema } from "../plugins/config-schema.js";
export type {
OpenClawPluginApi,
PluginViewRegistration,
} from "../plugins/types.js";
Create extensions/team-projects/openclaw.plugin.json:
{
"id": "team-projects",
"configSchema": {
"type": "object",
"additionalProperties": false,
"properties": {}
}
}
Create extensions/team-projects/index.ts:
import type { OpenClawPluginApi } from "openclaw/plugin-sdk/team-projects";
import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/team-projects";
const plugin = {
id: "team-projects",
name: "Team Projects",
description: "Multi-agent project management with task boards and orchestrated collaboration.",
configSchema: emptyPluginConfigSchema(),
register(api: OpenClawPluginApi) {
if (typeof api.registerView === "function") {
api.registerView({
id: "team-projects",
label: "Projects",
subtitle: "Multi-agent team projects",
icon: "clipboard-list",
group: "Control",
position: 3,
});
}
},
};
export default plugin;
tsdown.config.ts — Add "team-projects" to the pluginSdkEntrypoints array.
src/plugins/loader.ts — Add to the pluginSdkScopedAliasEntries array:
{
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:
"./plugin-sdk/team-projects": {
"types": "./dist/plugin-sdk/team-projects.d.ts",
"default": "./dist/plugin-sdk/team-projects.js"
},
{
"plugins": {
"allow": ["telegram", "discord", "team-projects"],
"entries": {
"team-projects": {
"enabled": true
}
}
}
}
Copy gateway-plugin/team-projects-view.ts to ui/src/ui/views/team-projects.ts.
Then wire it into the app:
ui/src/ui/app-render.ts:
import { uiPluginRegistry } from "./plugins/registry.ts";import { isPluginTab, getPluginViewInfo } from "./navigation.ts";</main>, add: ${renderPluginTabContent(state)}renderPluginTabContent() function (see gateway-plugin/app-render-patch.ts)ui/src/ui/app-gateway.ts:
import { renderTeamProjects } from "./views/team-projects.ts";uiPluginRegistry.loadFromGateway(data), call registerPluginViewRenderers(host)registerPluginViewRenderers() function (see gateway-plugin/app-gateway-patch.ts)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.
Tell the coordinator agent what you want to build. It will:
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 uses CLI tools to manage the project board:
# 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"
The orchestrator identifies ready tasks (dependencies met, not yet dispatched):
# 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"
)
Agents can communicate using @-mentions:
sessions_send)# 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
# 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"
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[]
~/.openclaw/workspace/team-projects/projects.json~/.openclaw/workspace/team-projects/chat_PROJECT_ID.jsonl~/.openclaw/workspace/team-projects/orchestrator-state.json┌─────────────┐ 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) │
└──────────────┘
subagent-announce system delivers completion events automatically.dependsOn are all done.sessions_spawn, sessions_send, and agents_list tools. No custom transport.registerView() plugin API. Requires the plugin-architecture skill to be installed.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.
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.
allowAgents must be per-agentSetting agents.defaults.subagents.allowAgents: ["*"] does NOT work. The code at agents-list-tool.ts:49 reads:
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 normalizationThe 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.
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.
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)
│ ├── app-render-patch.ts # Patch for app-render.ts (plugin tab catch-all)
│ └── app-gateway-patch.ts # Patch for app-gateway.ts (renderer registration)
├── 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
ZIP package — ready to use