Team Projects

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.

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.

Installation

Step 1: Config Prerequisites

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: 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 UI tab)

The UI 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:

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:

{
  "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;

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:

{
  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"
},

2d. Enable in config

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

Step 3: UI View Renderer (for Control dashboard)

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:

1. Add import: import { uiPluginRegistry } from "./plugins/registry.ts";
2. Add import: import { isPluginTab, getPluginViewInfo } from "./navigation.ts";
3. Before </main>, add: ${renderPluginTabContent(state)}
4. Add the renderPluginTabContent() function (see gateway-plugin/app-render-patch.ts)

ui/src/ui/app-gateway.ts:

1. Add import: import { renderTeamProjects } from "./views/team-projects.ts";
2. After uiPluginRegistry.loadFromGateway(data), call registerPluginViewRenderers(host)
3. Add the registerPluginViewRenderers() function (see gateway-plugin/app-gateway-patch.ts)

Step 4: Build & Restart

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:

# 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):

# 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

# 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

# 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 — UI tab registered via OpenClaw's registerView() plugin API. Requires the plugin-architecture skill to be installed.

Plugin Registration Points (4 required)

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

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

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:

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.

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.

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

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)
│   ├── 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