@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-1

package/skills/teamclaw-setup/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: teamclaw-setup
+description: Install, configure, validate, or troubleshoot the TeamClaw OpenClaw plugin for virtual software-team workflows. Use when users want TeamClaw setup help, controller or worker config snippets, on-demand process/docker/kubernetes workers, external worker registration, or safe first-run validation steps.
+version: 1.0.0
+metadata:
+  openclaw:
+    author: TeamClaws
+    homepage: https://github.com/topcheer/teamclaw
+    links:
+      homepage: https://github.com/topcheer/teamclaw
+      repository: https://github.com/topcheer/teamclaw
+      documentation: https://github.com/topcheer/teamclaw/blob/main/INSTALL.md
+      changelog: https://github.com/topcheer/teamclaw/releases
+---
+
+# TeamClaw Setup
+
+Guide users to the smallest working TeamClaw installation first, then expand.
+
+## Default workflow
+
+1. Prefer the guided installer first:
+
+   ```bash
+   npx -y @teamclaws/teamclaw install
+   ```
+
+   The guided installer already applies `--dangerously-force-unsafe-install` for TeamClaw and defaults to an independent `teamclaw` agent/workspace.
+
+   Advanced compatibility only:
+
+   ```bash
+   npx -y @teamclaws/teamclaw install --agent-mode main
+   ```
+
+   Use that only when the user explicitly wants the legacy shared-`main` layout.
+
+2. Use manual plugin install only when the user wants direct control:
+
+   ```bash
+   openclaw plugins install --dangerously-force-unsafe-install @teamclaws/teamclaw
+   ```
+
+   If the user explicitly wants the ClawHub package path, use:
+
+   ```bash
+   openclaw plugins install --dangerously-force-unsafe-install clawhub:@teamclaws/teamclaw
+   ```
+
+3. Recommend `controller + process provisioning` for the first successful run unless the user explicitly needs external workers, Docker, or Kubernetes immediately.
+
+4. Read `references/install-modes.md` before generating config. Pick the smallest matching topology and reuse the provided snippets.
+
+5. Read `references/validation-checklist.md` before finishing. Always give the user:
+   - one health-check command
+   - one UI URL
+   - one tiny smoke-test requirement
+   - one or two likely failure checks for the chosen topology
+
+## Installation guidance
+
+- Start with a single host and `process` provisioning.
+- Keep TeamClaw `taskTimeoutMs` large for real model runs.
+- Keep OpenClaw `agents.defaults.timeoutSeconds` at least as large as the TeamClaw task window in seconds.
+- For `docker` or `kubernetes`, require a reachable `workerProvisioningControllerUrl`.
+- For `docker`, mention the published runtime image:
+
+  ```text
+  ghcr.io/topcheer/teamclaw-openclaw:latest
+  ```
+
+## What to produce
+
+When helping a user, produce:
+
+1. the exact install command
+2. the minimal config snippet for the chosen topology
+3. the startup command
+4. the validation commands and first smoke-test task
+
+Do not push users into distributed, Docker, or Kubernetes first unless they asked for it or already have the surrounding infrastructure ready.

package/skills/teamclaw-setup/references/install-modes.md

@@ -0,0 +1,136 @@
+# TeamClaw install modes
+
+## 1. Guided install
+
+Use this when the user already has OpenClaw working and wants the shortest path:
+
+```bash
+npx -y @teamclaws/teamclaw install
+```
+
+The guided installer already applies `--dangerously-force-unsafe-install` for TeamClaw.
+
+What it helps with:
+
+- installs or updates the TeamClaw plugin
+- locates `openclaw.json`
+- lets the user choose a topology
+- reuses existing OpenClaw model definitions
+- prompts for workspace placement
+
+## 2. Manual plugin install
+
+Use this when the user wants direct control over plugin installation:
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install @teamclaws/teamclaw
+```
+
+If the user explicitly wants the ClawHub source:
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install clawhub:@teamclaws/teamclaw
+```
+
+## 3. Recommended first topology: controller + process provisioning
+
+Minimal TeamClaw plugin block:
+
+```json
+{
+  "mode": "controller",
+  "processModel": "multi",
+  "port": 9527,
+  "teamName": "my-team",
+  "taskTimeoutMs": 1800000,
+  "gitEnabled": true,
+  "gitDefaultBranch": "main",
+  "workerProvisioningType": "process",
+  "workerProvisioningRoles": [],
+  "workerProvisioningMinPerRole": 0,
+  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningIdleTtlMs": 120000,
+  "workerProvisioningStartupTimeoutMs": 120000
+}
+```
+
+Use this first because it avoids multi-machine networking while still exercising the real controller, provisioned workers, UI, messages, clarifications, and git-backed workspace flow.
+
+## 4. Worker-only topology
+
+Use this only when a controller already exists elsewhere:
+
+```json
+{
+  "mode": "worker",
+  "port": 9528,
+  "role": "developer",
+  "controllerUrl": "http://controller-host:9527",
+  "taskTimeoutMs": 1800000,
+  "gitEnabled": true,
+  "gitDefaultBranch": "main"
+}
+```
+
+## 5. On-demand process workers
+
+Use this when the controller should launch same-machine workers only as needed:
+
+```json
+{
+  "mode": "controller",
+  "port": 9527,
+  "teamName": "my-team",
+  "workerProvisioningType": "process",
+  "workerProvisioningMinPerRole": 0,
+  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningIdleTtlMs": 120000,
+  "workerProvisioningStartupTimeoutMs": 120000
+}
+```
+
+## 6. On-demand Docker workers
+
+Use this when the user already has Docker and wants containerized workers:
+
+```json
+{
+  "mode": "controller",
+  "port": 9527,
+  "teamName": "my-team",
+  "workerProvisioningType": "docker",
+  "workerProvisioningControllerUrl": "http://host.docker.internal:9527",
+  "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
+  "workerProvisioningWorkspaceRoot": "/workspace-root",
+  "workerProvisioningDockerWorkspaceVolume": "teamclaw-workspaces",
+  "workerProvisioningMaxPerRole": 3
+}
+```
+
+Important notes:
+
+- `workerProvisioningControllerUrl` must be reachable from the worker container.
+- If persistent workspaces matter, keep `workerProvisioningDockerWorkspaceVolume`.
+
+## 7. On-demand Kubernetes workers
+
+Use this only when the user already runs the controller in or behind a reachable cluster address:
+
+```json
+{
+  "mode": "controller",
+  "port": 9527,
+  "teamName": "my-team",
+  "workerProvisioningType": "kubernetes",
+  "workerProvisioningControllerUrl": "http://teamclaw-controller.default.svc.cluster.local:9527",
+  "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
+  "workerProvisioningWorkspaceRoot": "/workspace-root",
+  "workerProvisioningKubernetesWorkspacePersistentVolumeClaim": "teamclaw-workspace",
+  "workerProvisioningMaxPerRole": 2
+}
+```
+
+Important notes:
+
+- `kubectl` must be available where the controller runs.
+- The controller URL must be reachable from pods.

package/skills/teamclaw-setup/references/validation-checklist.md

@@ -0,0 +1,73 @@
+# TeamClaw validation checklist
+
+## Startup checks
+
+After startup, always give the user:
+
+```bash
+curl http://127.0.0.1:9527/api/v1/health
+```
+
+Expected shape:
+
+```json
+{"status":"ok","mode":"controller", ...}
+```
+
+Also point them to:
+
+```text
+http://127.0.0.1:9527/ui
+```
+
+## First smoke-test task
+
+Recommend a tiny requirement before any large SDLC workflow:
+
+```text
+Create a minimal static site in the workspace with README.md, index.html, and style.css.
+```
+
+This checks controller intake, task routing, worker execution, workspace writes, and UI visibility with minimal risk.
+
+## Timeout guidance
+
+For real model runs:
+
+- TeamClaw: `taskTimeoutMs = 1800000`
+- OpenClaw: `agents.defaults.timeoutSeconds >= 2400`
+
+If OpenClaw times out first, users often think TeamClaw is broken when the real issue is the inner agent deadline.
+
+## Common failure checks
+
+### process provisioning
+
+- confirm the chosen model already works in plain OpenClaw
+- confirm `agents.defaults.workspace` points to a writable path
+
+### distributed worker
+
+- confirm `controllerUrl` is reachable from the worker machine
+- confirm the worker role matches the intended role
+
+### Docker
+
+- confirm `workerProvisioningControllerUrl` is reachable from containers
+- confirm the controller can access Docker
+- confirm the runtime image is `ghcr.io/topcheer/teamclaw-openclaw:latest`
+
+### Kubernetes
+
+- confirm pods can reach `workerProvisioningControllerUrl`
+- confirm the controller environment has `kubectl`
+- confirm any workspace PVC actually exists
+
+## Done criteria
+
+Treat the install as successful only when:
+
+1. controller health is `ok`
+2. expected workers appear in the UI or status view
+3. the smoke-test task completes
+4. files appear in the workspace

package/src/config.ts

@@ -31,7 +31,7 @@ function buildConfigSchema() {
         },
         teamName: {
           type: "string" as const,
-          default: "default",
+          default: "TeamClaw",
           description: "Team name for mDNS identification",
         },
         heartbeatIntervalMs: {
@@ -42,7 +42,7 @@ function buildConfigSchema() {
         taskTimeoutMs: {
           type: "number" as const,
           default: 1800000,
-          description: "Maximum time in milliseconds to wait for a role task to finish",
+          description: "Inactivity threshold in milliseconds before TeamClaw probes a stalled role task instead of failing it",
         },
         gitEnabled: {
           type: "boolean" as const,
@@ -69,14 +69,17 @@ function buildConfigSchema() {
           default: "teamclaw@local",
           description: "Git author email used for TeamClaw-managed workspace commits",
         },
-        localRoles: {
-          type: "array" as const,
-          default: [],
-          description: "Controller-local roles executed in this same OpenClaw instance",
-          items: {
-            type: "string" as const,
-            enum: ROLE_IDS,
-          },
+        agentIsolationMode: {
+          type: "string" as const,
+          enum: ["independent", "main"],
+          default: "independent",
+          description: "Runtime isolation mode: dedicated TeamClaw agent/workspace, or legacy main-agent shared mode",
+        },
+        processModel: {
+          type: "string" as const,
+          enum: ["multi"],
+          default: "multi",
+          description: "Worker execution model: TeamClaw runs workers as separate gateway processes",
         },
         workerProvisioningType: {
           type: "string" as const,
@@ -84,6 +87,11 @@ function buildConfigSchema() {
           default: "none",
           description: "Controller-only on-demand worker launch backend",
         },
+        workerProvisioningDisabled: {
+          type: "boolean" as const,
+          default: false,
+          description: "Explicitly disable controller-managed on-demand workers even when TeamClaw would normally default to same-host process provisioning",
+        },
         workerProvisioningControllerUrl: {
           type: "string" as const,
           default: "",
@@ -105,7 +113,7 @@ function buildConfigSchema() {
         },
         workerProvisioningMaxPerRole: {
           type: "number" as const,
-          default: 1,
+          default: 3,
           description: "Maximum on-demand workers to launch per role",
         },
         workerProvisioningIdleTtlMs: {
@@ -177,6 +185,14 @@ function buildConfigSchema() {
           default: "",
           description: "Optional service account name for launched worker pods",
         },
+        workerProvisioningKubernetesImagePullSecrets: {
+          type: "array" as const,
+          default: [],
+          description: "Optional image pull secret names added to launched worker pods",
+          items: {
+            type: "string" as const,
+          },
+        },
         workerProvisioningKubernetesWorkspacePersistentVolumeClaim: {
           type: "string" as const,
           default: "",
@@ -208,8 +224,8 @@ function buildConfigSchema() {
       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)",
+        label: "Task Stall Threshold",
+        help: "In milliseconds, how long TeamClaw waits without visible progress before probing the task instead of failing it",
       },
       gitEnabled: {
         label: "Git Collaboration",
@@ -231,14 +247,22 @@ function buildConfigSchema() {
         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",
+      agentIsolationMode: {
+        label: "Agent Isolation Mode",
+        help: "Use a dedicated TeamClaw agent/workspace by default, or the legacy shared main-agent mode",
+      },
+      processModel: {
+        label: "Process Model",
+        help: "TeamClaw runs workers as separate gateway processes",
       },
       workerProvisioningType: {
         label: "On-demand Worker Provider",
         help: "Launch missing workers on demand using process, Docker, or Kubernetes",
       },
+      workerProvisioningDisabled: {
+        label: "Disable On-demand Workers",
+        help: "Force TeamClaw to keep worker provisioning off even for same-host local controllers",
+      },
       workerProvisioningControllerUrl: {
         label: "Provisioned Worker Controller URL",
         help: "URL that launched workers use to call back into the controller",
@@ -303,6 +327,10 @@ function buildConfigSchema() {
         label: "Kubernetes Service Account",
         help: "Optional service account for launched worker pods",
       },
+      workerProvisioningKubernetesImagePullSecrets: {
+        label: "Kubernetes Image Pull Secrets",
+        help: "Optional secret names added to launched worker pods so they can pull private images",
+      },
       workerProvisioningKubernetesWorkspacePersistentVolumeClaim: {
         label: "Kubernetes Workspace PVC",
         help: "Optional PVC mounted as the persistent workspace root for launched worker pods",

package/src/controller/controller-capacity.ts

@@ -1,13 +1,13 @@
 import type { PluginConfig, TeamState } from "../types.js";
 
 export function hasOnDemandWorkerProvisioning(
-  config: Pick<PluginConfig, "workerProvisioningType">,
+  config: Pick<PluginConfig, "workerProvisioningType" | "processModel">,
 ): boolean {
   return config.workerProvisioningType !== "none";
 }
 
 export function shouldBlockControllerWithoutWorkers(
-  config: Pick<PluginConfig, "workerProvisioningType">,
+  config: Pick<PluginConfig, "workerProvisioningType" | "processModel">,
   state: TeamState | null,
 ): boolean {
   return !!state && Object.keys(state.workers).length === 0 && !hasOnDemandWorkerProvisioning(config);