@teamclaws/teamclaw 2026.4.2-3 → 2026.4.2-4

package/README.md

@@ -71,6 +71,15 @@ For maintainers, TeamClaw now uses two release paths:
 1. **npm package** — published by GitHub Actions via `.github/workflows/teamclaw-plugin-npm-release.yml`
 2. **ClawHub code plugin + bundled skills** — published manually from the CLI
 
+The npm publish workflow runs automatically when:
+
+- a tag matching `v*` is pushed
+- or relevant package files change on `main` (`src/**`, `.github/workflows/teamclaw-plugin-npm-release.yml`, `scripts/sync-teamclaw-plugin-manifest.mjs`, `scripts/teamclaw-package-check.mjs`, `scripts/teamclaw-npm-publish.sh`)
+
+It also supports `workflow_dispatch` for a specific commit SHA on `main`.
+
+Before the first real npm publish, GitHub must already be configured for npm trusted publishing with the `npm-release` environment and this workflow file.
+
 Before either release path, sync and validate the generated plugin manifest:
 
 ```bash
@@ -101,7 +110,7 @@ For a first-time setup, the safest path is:
 2. Validate the workflow with a small smoke-test task
 3. Expand to external workers, Docker, or Kubernetes after the basics are working
 
-When on-demand provisioning is enabled, TeamClaw now treats controller startup as a readiness phase, not just a process-up check. During that warm-up, `/api/v1/health` returns a non-OK status until the controller has verified writable runtime paths and successfully brought the configured startup worker roles online.
+When on-demand provisioning is enabled, TeamClaw now treats controller startup as a readiness phase, not just a process-up check. During that warm-up, `/api/v1/health` returns a non-OK status until the controller has verified writable runtime paths and successfully brought the configured startup worker roles online. If `workerProvisioningRoles` is empty, startup readiness defaults to waiting for a warm `developer` worker.
 
 ## Documentation
 

package/cli.mjs

@@ -64,7 +64,7 @@ const INSTALL_MODE_OPTIONS = [
   {
     value: "controller-manual",
     label: "Local controller + default on-demand workers",
-    hint: "Lean same-host setup; TeamClaw launches local worker processes on demand with controller-decided defaults.",
+    hint: "Lean same-host setup; writes workerProvisioningRoles=[] and workerProvisioningMaxPerRole=1.",
   },
   {
     value: "controller-docker",
@@ -1363,7 +1363,7 @@ async function collectInstallChoices(configPath, config, prompter, options) {
 
   const provisioningRoles = await promptOptionalRoleList(
     prompter,
-    "Preferred on-demand roles (comma-separated, leave empty for controller-decided defaults)",
+    "Preferred on-demand roles (comma-separated, leave empty to keep workerProvisioningRoles empty and let startup readiness default to a warm developer worker)",
     resolveDefaultProvisioningRoles(existingTeamClaw),
   );
   const maxPerRole = await prompter.number({
@@ -1371,7 +1371,7 @@ async function collectInstallChoices(configPath, config, prompter, options) {
     defaultValue:
       typeof existingTeamClaw.workerProvisioningMaxPerRole === "number" && existingTeamClaw.workerProvisioningMaxPerRole >= 1
         ? existingTeamClaw.workerProvisioningMaxPerRole
-        : 2,
+        : 10,
     min: 1,
     max: 50,
   });
@@ -1677,7 +1677,7 @@ function applyInstallerChoices(config, choices, configPath) {
     teamclawConfig.workerProvisioningDisabled = true;
     teamclawConfig.workerProvisioningControllerUrl = "";
     teamclawConfig.workerProvisioningRoles = [];
-    teamclawConfig.workerProvisioningMaxPerRole = 1;
+    teamclawConfig.workerProvisioningMaxPerRole = 10;
     teamclawConfig.workerProvisioningImage = "";
     teamclawConfig.workerProvisioningPassEnv = [];
     teamclawConfig.workerProvisioningExtraEnv = {};
@@ -1697,7 +1697,7 @@ function applyInstallerChoices(config, choices, configPath) {
       teamclawConfig.workerProvisioningDisabled = false;
       teamclawConfig.workerProvisioningControllerUrl = "";
       teamclawConfig.workerProvisioningRoles = [];
-      teamclawConfig.workerProvisioningMaxPerRole = 1;
+      teamclawConfig.workerProvisioningMaxPerRole = 10;
       teamclawConfig.workerProvisioningImage = "";
       teamclawConfig.workerProvisioningPassEnv = [];
       teamclawConfig.workerProvisioningExtraEnv = {};

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "teamclaw",
   "name": "TeamClaw",
   "description": "Virtual team collaboration - multiple OpenClaw instances form a virtual software company with role-based task routing.",
-  "version": "2026.4.2-3",
+  "version": "2026.4.2-4",
   "skills": [
     "./skills"
   ],
@@ -260,7 +260,7 @@
       "workerProvisioningRoles": {
         "type": "array",
         "default": [],
-        "description": "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
+        "description": "Preferred on-demand roles; task-required roles can still launch automatically. Empty means no preferred startup role list, so startup readiness falls back to a warm developer worker",
         "items": {
           "type": "string",
           "enum": [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@teamclaws/teamclaw",
-  "version": "2026.4.2-3",
+  "version": "2026.4.2-4",
   "description": "OpenClaw virtual software team orchestration plugin",
   "private": false,
   "keywords": [

package/skills/teamclaw/references/api-quick-ref.md

@@ -10,7 +10,7 @@ Default: `http://127.0.0.1:9527`
 
 | Method | Path | Description |
 |--------|------|-------------|
-| GET | `/api/v1/health` | Health check → `{"status":"ok"}` |
+| GET | `/api/v1/health` | Health/readiness check; may report a non-OK startup readiness state until required warm workers are online |
 | GET | `/api/v1/team/status` | Full team snapshot (workers, tasks, runs, clarifications) |
 | GET | `/api/v1/roles` | List all available roles |
 

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

@@ -48,7 +48,7 @@ Minimal TeamClaw plugin block:
   "workerProvisioningType": "process",
   "workerProvisioningRoles": [],
   "workerProvisioningMinPerRole": 0,
-  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningMaxPerRole": 10,
   "workerProvisioningIdleTtlMs": 120000,
   "workerProvisioningStartupTimeoutMs": 120000
 }
@@ -56,6 +56,12 @@ Minimal TeamClaw plugin block:
 
 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.
 
+If the user is specifically choosing install modes through the guided installer, remember the resulting config differs by mode:
+
+- `controller-manual` writes `workerProvisioningType: "process"` and `workerProvisioningRoles: []`, so startup readiness falls back to a warm `developer` worker
+- `controller-process` writes `workerProvisioningType: "process"` and uses the chosen roles/max-per-role
+- `worker` disables provisioning on that node
+
 ## 4. Worker-only topology
 
 Use this only when a controller already exists elsewhere:
@@ -83,7 +89,7 @@ Use this when the controller should launch same-machine workers only as needed:
   "teamName": "my-team",
   "workerProvisioningType": "process",
   "workerProvisioningMinPerRole": 0,
-  "workerProvisioningMaxPerRole": 2,
+  "workerProvisioningMaxPerRole": 10,
   "workerProvisioningIdleTtlMs": 120000,
   "workerProvisioningStartupTimeoutMs": 120000
 }
@@ -103,7 +109,7 @@ Use this when the user already has Docker and wants containerized workers:
   "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
   "workerProvisioningWorkspaceRoot": "/workspace-root",
   "workerProvisioningDockerWorkspaceVolume": "teamclaw-workspaces",
-  "workerProvisioningMaxPerRole": 3
+  "workerProvisioningMaxPerRole": 10
 }
 ```
 
@@ -126,7 +132,7 @@ Use this only when the user already runs the controller in or behind a reachable
   "workerProvisioningImage": "ghcr.io/topcheer/teamclaw-openclaw:latest",
   "workerProvisioningWorkspaceRoot": "/workspace-root",
   "workerProvisioningKubernetesWorkspacePersistentVolumeClaim": "teamclaw-workspace",
-  "workerProvisioningMaxPerRole": 2
+  "workerProvisioningMaxPerRole": 10
 }
 ```
 

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

@@ -14,6 +14,8 @@ Expected shape:
 {"status":"ok","mode":"controller", ...}
 ```
 
+If on-demand provisioning is enabled, `/api/v1/health` can temporarily return a non-OK readiness state during warm-up. When `workerProvisioningRoles` is empty, readiness defaults to waiting for a warm `developer` worker.
+
 Also point them to:
 
 ```text
@@ -67,7 +69,7 @@ If OpenClaw times out first, users often think TeamClaw is broken when the real
 
 Treat the install as successful only when:
 
-1. controller health is `ok`
+1. controller health is `ok` after startup readiness finishes
 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

@@ -100,7 +100,7 @@ function buildConfigSchema() {
         workerProvisioningRoles: {
           type: "array" as const,
           default: [],
-          description: "Preferred on-demand roles; task-required roles can still launch automatically. Empty means controller-decided defaults across all roles",
+          description: "Preferred on-demand roles; task-required roles can still launch automatically. Empty means no preferred startup role list, so startup readiness falls back to a warm developer worker",
           items: {
             type: "string" as const,
             enum: ROLE_IDS,

package/src/controller/worker-provisioning.ts

@@ -1416,7 +1416,7 @@ function buildProvisionedWorkerConfig(
   teamclawConfig.workerProvisioningControllerUrl = "";
   teamclawConfig.workerProvisioningRoles = [];
   teamclawConfig.workerProvisioningMinPerRole = 0;
-  teamclawConfig.workerProvisioningMaxPerRole = 1;
+  teamclawConfig.workerProvisioningMaxPerRole = 10;
   teamclawConfig.workerProvisioningIdleTtlMs = controllerConfig.workerProvisioningIdleTtlMs;
   teamclawConfig.workerProvisioningStartupTimeoutMs = controllerConfig.workerProvisioningStartupTimeoutMs;
   teamclawConfig.workerProvisioningImage = "";