@teamclaws/teamclaw 2026.3.21 → 2026.3.25

package/index.ts

@@ -1,4 +1,4 @@
-import type { OpenClawPluginApi } from "./api.js";
+import { definePluginEntry, type OpenClawPluginApi } from "./api.js";
 import { parsePluginConfig } from "./src/types.js";
 import type { TaskExecutionEventInput, WorkerIdentity } from "./src/types.js";
 import { buildConfigSchema } from "./src/config.js";
@@ -13,16 +13,16 @@ import { LocalWorkerManager } from "./src/controller/local-worker-manager.js";
 import { createControllerPromptInjector } from "./src/controller/prompt-injector.js";
 import { createControllerTools } from "./src/controller/controller-tools.js";
 import { publishWorkerRepo, syncWorkerRepo } from "./src/git-collaboration.js";
+import { installRecommendedSkills } from "./src/worker/skill-installer.js";
 
-const plugin = {
+export default definePluginEntry({
   id: "teamclaw",
   name: "TeamClaw",
   description:
     "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
-  configSchema: buildConfigSchema(),
+  configSchema: buildConfigSchema,
   register(api: OpenClawPluginApi) {
     const config = parsePluginConfig(api.pluginConfig as Record<string, unknown>);
-    const logger = api.logger;
 
     if (config.mode === "controller") {
       registerController(api, config);
@@ -30,9 +30,7 @@ const plugin = {
       registerWorker(api, config);
     }
   },
-};
-
-export default plugin;
+});
 
 function registerController(api: OpenClawPluginApi, config: ReturnType<typeof parsePluginConfig>) {
   const logger = api.logger;
@@ -146,6 +144,25 @@ function registerWorker(api: OpenClawPluginApi, config: ReturnType<typeof parseP
         currentWorkerId = identity.workerId;
       },
       prepareTaskAssignment: async (assignment) => {
+        if (assignment.recommendedSkills?.length) {
+          try {
+            const skillInstall = await installRecommendedSkills(assignment, logger);
+            for (const event of skillInstall.events) {
+              await reportExecutionEvent(assignment.taskId, event);
+            }
+          } catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await reportExecutionEvent(assignment.taskId, {
+              type: "error",
+              phase: "skills_preflight_failed",
+              source: "worker",
+              status: "running",
+              message,
+            });
+            logger.warn(`Worker: skill preflight failed for ${assignment.taskId}: ${message}`);
+          }
+        }
+
         if (!assignment.repo?.enabled || !currentControllerUrl) {
           return;
         }

package/openclaw.plugin.json

@@ -1,13 +1,151 @@
 {
   "id": "teamclaw",
   "name": "TeamClaw",
-  "description": "Virtual team collaboration plugin - multiple OpenClaw instances form a virtual software company with role-based task routing.",
+  "description": "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
+  "version": "2026.3.25",
+  "uiHints": {
+    "mode": {
+      "label": "Mode",
+      "help": "controller manages the team, worker executes tasks"
+    },
+    "port": {
+      "label": "Port",
+      "help": "HTTP server port for this instance"
+    },
+    "role": {
+      "label": "Role",
+      "help": "Worker role (worker mode only)"
+    },
+    "controllerUrl": {
+      "label": "Controller URL",
+      "help": "Manual fallback if mDNS discovery fails"
+    },
+    "teamName": {
+      "label": "Team Name",
+      "help": "Team identifier for mDNS"
+    },
+    "heartbeatIntervalMs": {
+      "label": "Heartbeat Interval",
+      "help": "In milliseconds, minimum 1000"
+    },
+    "taskTimeoutMs": {
+      "label": "Task Timeout",
+      "help": "Maximum time to wait for a role task to finish before marking it failed (in milliseconds)"
+    },
+    "gitEnabled": {
+      "label": "Git Collaboration",
+      "help": "Enable automatic git-backed workspace bootstrapping and worker repo sync"
+    },
+    "gitRemoteUrl": {
+      "label": "Git Remote URL",
+      "help": "Optional remote repository URL; when empty, distributed workers use controller-hosted git bundles"
+    },
+    "gitDefaultBranch": {
+      "label": "Git Default Branch",
+      "help": "Default branch name for the TeamClaw workspace repository"
+    },
+    "gitAuthorName": {
+      "label": "Git Author Name",
+      "help": "Author name for TeamClaw-managed workspace commits"
+    },
+    "gitAuthorEmail": {
+      "label": "Git Author Email",
+      "help": "Author email for TeamClaw-managed workspace commits"
+    },
+    "localRoles": {
+      "label": "Local Roles",
+      "help": "Controller mode only: run these roles as local virtual workers inside the same OpenClaw instance"
+    },
+    "workerProvisioningType": {
+      "label": "On-demand Worker Provider",
+      "help": "Launch missing workers on demand using process, Docker, or Kubernetes"
+    },
+    "workerProvisioningControllerUrl": {
+      "label": "Provisioned Worker Controller URL",
+      "help": "URL that launched workers use to call back into the controller"
+    },
+    "workerProvisioningRoles": {
+      "label": "Provisioned Roles",
+      "help": "Only launch these roles on demand; leave empty for all roles"
+    },
+    "workerProvisioningMinPerRole": {
+      "label": "Warm Workers Per Role",
+      "help": "Minimum idle workers to keep warm per role"
+    },
+    "workerProvisioningMaxPerRole": {
+      "label": "Max Workers Per Role",
+      "help": "Maximum concurrent on-demand workers per role"
+    },
+    "workerProvisioningIdleTtlMs": {
+      "label": "Idle TTL",
+      "help": "Terminate an idle provisioned worker after this many milliseconds"
+    },
+    "workerProvisioningStartupTimeoutMs": {
+      "label": "Startup Timeout",
+      "help": "Fail a launch if the worker does not register in time"
+    },
+    "workerProvisioningImage": {
+      "label": "Provisioning Image",
+      "help": "Container image for docker/kubernetes provisioners"
+    },
+    "workerProvisioningPassEnv": {
+      "label": "Pass-through Env",
+      "help": "Environment variable names copied from controller to provisioned workers"
+    },
+    "workerProvisioningExtraEnv": {
+      "label": "Extra Env",
+      "help": "Static environment variables injected into provisioned workers"
+    },
+    "workerProvisioningDockerNetwork": {
+      "label": "Docker Network",
+      "help": "Optional Docker network for launched worker containers"
+    },
+    "workerProvisioningDockerMounts": {
+      "label": "Docker Mounts",
+      "help": "Optional Docker bind mounts for launched worker containers"
+    },
+    "workerProvisioningWorkspaceRoot": {
+      "label": "Workspace Root",
+      "help": "Optional persistent workspace root path inside docker/kubernetes workers; defaults to /workspace-root when persistence is configured"
+    },
+    "workerProvisioningDockerWorkspaceVolume": {
+      "label": "Docker Workspace Volume",
+      "help": "Optional Docker named volume or host path mounted as the persistent workspace root"
+    },
+    "workerProvisioningKubernetesNamespace": {
+      "label": "Kubernetes Namespace",
+      "help": "Namespace for launched worker pods"
+    },
+    "workerProvisioningKubernetesContext": {
+      "label": "Kubernetes Context",
+      "help": "Optional kubectl context for the Kubernetes provider"
+    },
+    "workerProvisioningKubernetesServiceAccount": {
+      "label": "Kubernetes Service Account",
+      "help": "Optional service account for launched worker pods"
+    },
+    "workerProvisioningKubernetesWorkspacePersistentVolumeClaim": {
+      "label": "Kubernetes Workspace PVC",
+      "help": "Optional PVC mounted as the persistent workspace root for launched worker pods"
+    },
+    "workerProvisioningKubernetesLabels": {
+      "label": "Kubernetes Labels",
+      "help": "Extra labels applied to launched worker pods"
+    },
+    "workerProvisioningKubernetesAnnotations": {
+      "label": "Kubernetes Annotations",
+      "help": "Extra annotations applied to launched worker pods"
+    }
+  },
   "configSchema": {
     "type": "object",
     "properties": {
       "mode": {
         "type": "string",
-        "enum": ["controller", "worker"],
+        "enum": [
+          "controller",
+          "worker"
+        ],
         "default": "worker",
         "description": "Plugin mode: controller manages the team, worker executes tasks"
       },
@@ -35,6 +173,192 @@
         "type": "number",
         "default": 10000,
         "description": "Heartbeat interval in milliseconds"
+      },
+      "taskTimeoutMs": {
+        "type": "number",
+        "default": 1800000,
+        "description": "Maximum time in milliseconds to wait for a role task to finish"
+      },
+      "gitEnabled": {
+        "type": "boolean",
+        "default": true,
+        "description": "Enable TeamClaw git-backed workspace collaboration"
+      },
+      "gitRemoteUrl": {
+        "type": "string",
+        "default": "",
+        "description": "Optional remote repository URL for distributed worker clone/pull/push"
+      },
+      "gitDefaultBranch": {
+        "type": "string",
+        "default": "main",
+        "description": "Default branch name for the shared TeamClaw workspace repository"
+      },
+      "gitAuthorName": {
+        "type": "string",
+        "default": "TeamClaw",
+        "description": "Git author name used for TeamClaw-managed workspace commits"
+      },
+      "gitAuthorEmail": {
+        "type": "string",
+        "default": "teamclaw@local",
+        "description": "Git author email used for TeamClaw-managed workspace commits"
+      },
+      "localRoles": {
+        "type": "array",
+        "default": [],
+        "description": "Controller-local roles executed in this same OpenClaw instance",
+        "items": {
+          "type": "string",
+          "enum": [
+            "pm",
+            "architect",
+            "developer",
+            "qa",
+            "release-engineer",
+            "infra-engineer",
+            "devops",
+            "security-engineer",
+            "designer",
+            "marketing"
+          ]
+        }
+      },
+      "workerProvisioningType": {
+        "type": "string",
+        "enum": [
+          "none",
+          "process",
+          "docker",
+          "kubernetes"
+        ],
+        "default": "none",
+        "description": "Controller-only on-demand worker launch backend"
+      },
+      "workerProvisioningControllerUrl": {
+        "type": "string",
+        "default": "",
+        "description": "Controller URL injected into provisioned workers; required for docker/kubernetes"
+      },
+      "workerProvisioningRoles": {
+        "type": "array",
+        "default": [],
+        "description": "Restrict on-demand launches to specific roles; empty means all roles",
+        "items": {
+          "type": "string",
+          "enum": [
+            "pm",
+            "architect",
+            "developer",
+            "qa",
+            "release-engineer",
+            "infra-engineer",
+            "devops",
+            "security-engineer",
+            "designer",
+            "marketing"
+          ]
+        }
+      },
+      "workerProvisioningMinPerRole": {
+        "type": "number",
+        "default": 0,
+        "description": "Minimum number of ready workers to keep warm per role"
+      },
+      "workerProvisioningMaxPerRole": {
+        "type": "number",
+        "default": 1,
+        "description": "Maximum on-demand workers to launch per role"
+      },
+      "workerProvisioningIdleTtlMs": {
+        "type": "number",
+        "default": 120000,
+        "description": "Terminate provisioned idle workers after this many milliseconds"
+      },
+      "workerProvisioningStartupTimeoutMs": {
+        "type": "number",
+        "default": 120000,
+        "description": "Fail a launch if the worker does not register within this many milliseconds"
+      },
+      "workerProvisioningImage": {
+        "type": "string",
+        "default": "ghcr.io/topcheer/teamclaw-openclaw:latest",
+        "description": "Container image used by docker/kubernetes provisioners"
+      },
+      "workerProvisioningPassEnv": {
+        "type": "array",
+        "default": [],
+        "description": "Environment variable names copied from the controller into provisioned workers",
+        "items": {
+          "type": "string"
+        }
+      },
+      "workerProvisioningExtraEnv": {
+        "type": "object",
+        "default": {},
+        "description": "Extra environment variables injected into provisioned workers",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "workerProvisioningDockerNetwork": {
+        "type": "string",
+        "default": "",
+        "description": "Optional Docker network name for launched worker containers"
+      },
+      "workerProvisioningDockerMounts": {
+        "type": "array",
+        "default": [],
+        "description": "Optional Docker bind mounts for launched worker containers",
+        "items": {
+          "type": "string"
+        }
+      },
+      "workerProvisioningWorkspaceRoot": {
+        "type": "string",
+        "default": "",
+        "description": "Optional persistent workspace root path inside docker/kubernetes workers; defaults to /workspace-root when a Docker volume or PVC is configured"
+      },
+      "workerProvisioningDockerWorkspaceVolume": {
+        "type": "string",
+        "default": "",
+        "description": "Optional Docker named volume or host path mounted as the persistent workspace root"
+      },
+      "workerProvisioningKubernetesNamespace": {
+        "type": "string",
+        "default": "default",
+        "description": "Kubernetes namespace for launched worker pods"
+      },
+      "workerProvisioningKubernetesContext": {
+        "type": "string",
+        "default": "",
+        "description": "Optional kubectl context used by the Kubernetes provisioner"
+      },
+      "workerProvisioningKubernetesServiceAccount": {
+        "type": "string",
+        "default": "",
+        "description": "Optional service account name for launched worker pods"
+      },
+      "workerProvisioningKubernetesWorkspacePersistentVolumeClaim": {
+        "type": "string",
+        "default": "",
+        "description": "Optional PVC mounted as the persistent workspace root for launched worker pods"
+      },
+      "workerProvisioningKubernetesLabels": {
+        "type": "object",
+        "default": {},
+        "description": "Extra labels applied to launched worker pods",
+        "additionalProperties": {
+          "type": "string"
+        }
+      },
+      "workerProvisioningKubernetesAnnotations": {
+        "type": "object",
+        "default": {},
+        "description": "Extra annotations applied to launched worker pods",
+        "additionalProperties": {
+          "type": "string"
+        }
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamclaws/teamclaw",
-  "version": "2026.3.21",
+  "version": "2026.3.25",
   "description": "OpenClaw virtual software team orchestration plugin",
   "private": false,
   "keywords": [
@@ -20,9 +20,13 @@
     "directory": "src"
   },
   "type": "module",
+  "bin": {
+    "teamclaw": "./cli.mjs"
+  },
   "files": [
     "README.md",
     "api.ts",
+    "cli.mjs",
     "index.ts",
     "openclaw.plugin.json",
     "src/",
@@ -36,19 +40,12 @@
     "@sinclair/typebox": "0.34.48",
     "bonjour-service": "^1.3.0",
     "json5": "^2.2.3",
+    "openclaw": "2026.3.23-2",
     "ws": "^8.19.0"
   },
   "devDependencies": {
     "typescript": "^5.9.0"
   },
-  "peerDependencies": {
-    "openclaw": ">=2026.3.14"
-  },
-  "peerDependenciesMeta": {
-    "openclaw": {
-      "optional": true
-    }
-  },
   "publishConfig": {
     "access": "public"
   },

package/src/config.ts

@@ -1,6 +1,7 @@
 import type { PluginConfig } from "./types.js";
 import { parsePluginConfig } from "./types.js";
 import { ROLE_IDS } from "./roles.js";
+import { TEAMCLAW_PUBLISHED_RUNTIME_IMAGE } from "./install-defaults.js";
 
 function buildConfigSchema() {
   return {
@@ -119,7 +120,7 @@ function buildConfigSchema() {
         },
         workerProvisioningImage: {
           type: "string" as const,
-          default: "",
+          default: TEAMCLAW_PUBLISHED_RUNTIME_IMAGE,
           description: "Container image used by docker/kubernetes provisioners",
         },
         workerProvisioningPassEnv: {
@@ -151,6 +152,16 @@ function buildConfigSchema() {
             type: "string" as const,
           },
         },
+        workerProvisioningWorkspaceRoot: {
+          type: "string" as const,
+          default: "",
+          description: "Optional persistent workspace root path inside docker/kubernetes workers; defaults to /workspace-root when a Docker volume or PVC is configured",
+        },
+        workerProvisioningDockerWorkspaceVolume: {
+          type: "string" as const,
+          default: "",
+          description: "Optional Docker named volume or host path mounted as the persistent workspace root",
+        },
         workerProvisioningKubernetesNamespace: {
           type: "string" as const,
           default: "default",
@@ -166,6 +177,11 @@ function buildConfigSchema() {
           default: "",
           description: "Optional service account name for launched worker pods",
         },
+        workerProvisioningKubernetesWorkspacePersistentVolumeClaim: {
+          type: "string" as const,
+          default: "",
+          description: "Optional PVC mounted as the persistent workspace root for launched worker pods",
+        },
         workerProvisioningKubernetesLabels: {
           type: "object" as const,
           default: {},
@@ -267,6 +283,14 @@ function buildConfigSchema() {
         label: "Docker Mounts",
         help: "Optional Docker bind mounts for launched worker containers",
       },
+      workerProvisioningWorkspaceRoot: {
+        label: "Workspace Root",
+        help: "Optional persistent workspace root path inside docker/kubernetes workers; defaults to /workspace-root when persistence is configured",
+      },
+      workerProvisioningDockerWorkspaceVolume: {
+        label: "Docker Workspace Volume",
+        help: "Optional Docker named volume or host path mounted as the persistent workspace root",
+      },
       workerProvisioningKubernetesNamespace: {
         label: "Kubernetes Namespace",
         help: "Namespace for launched worker pods",
@@ -279,6 +303,10 @@ function buildConfigSchema() {
         label: "Kubernetes Service Account",
         help: "Optional service account for launched worker pods",
       },
+      workerProvisioningKubernetesWorkspacePersistentVolumeClaim: {
+        label: "Kubernetes Workspace PVC",
+        help: "Optional PVC mounted as the persistent workspace root for launched worker pods",
+      },
       workerProvisioningKubernetesLabels: {
         label: "Kubernetes Labels",
         help: "Extra labels applied to launched worker pods",

package/src/controller/controller-service.ts

@@ -46,6 +46,7 @@ export function createControllerService(deps: ControllerServiceDeps): OpenClawPl
           teamName: config.teamName,
           workers: {},
           tasks: {},
+          controllerRuns: {},
           messages: [],
           clarifications: {},
           repo: repoState ?? undefined,

package/src/controller/controller-tools.ts

@@ -31,6 +31,13 @@ export function createControllerTools(deps: ControllerToolsDeps) {
         description: Type.String({ description: "Execution-ready task description with scope, expected deliverable, constraints, resolved clarifications, and no unmet predecessor dependency" }),
         priority: Type.Optional(Type.String({ description: "Priority: low, medium, high, critical" })),
         assignedRole: Type.Optional(Type.String({ description: "Exact target role ID (pm, architect, developer, qa, release-engineer, infra-engineer, devops, security-engineer, designer, marketing)" })),
+        recommendedSkills: Type.Optional(
+          Type.Array(
+            Type.String({
+              description: "Exact OpenClaw/ClawHub skill slug when known; otherwise a short skill-discovery query",
+            }),
+          ),
+        ),
       }),
       async execute(_id: string, params: Record<string, unknown>) {
         const title = String(params.title ?? "");
@@ -58,6 +65,7 @@ export function createControllerTools(deps: ControllerToolsDeps) {
               description,
               priority: params.priority ?? "medium",
               assignedRole: params.assignedRole ?? undefined,
+              recommendedSkills: Array.isArray(params.recommendedSkills) ? params.recommendedSkills : undefined,
               createdBy: "controller",
             }),
           });
@@ -74,11 +82,14 @@ export function createControllerTools(deps: ControllerToolsDeps) {
             : task.status === "pending"
               ? " (pending - no available worker)"
               : "";
+          const recommended = Array.isArray(task.recommendedSkills) && task.recommendedSkills.length > 0
+            ? ` | skills: ${task.recommendedSkills.join(", ")}`
+            : "";
 
           return {
             content: [{
               type: "text" as const,
-              text: `Task created: ${task.title} [${task.id}] [${task.priority}]${assigned}`,
+              text: `Task created: ${task.title} [${task.id}] [${task.priority}]${assigned}${recommended}`,
             }],
           };
         } catch (err) {