@teamclaws/teamclaw 2026.3.21

package/src/controller/prompt-injector.ts

@@ -0,0 +1,116 @@
+import type { PluginConfig, TeamState } from "../types.js";
+import { ROLES } from "../roles.js";
+
+const TEAMCLAW_ROLE_IDS_TEXT = [
+  "pm",
+  "architect",
+  "developer",
+  "qa",
+  "release-engineer",
+  "infra-engineer",
+  "devops",
+  "security-engineer",
+  "designer",
+  "marketing",
+].join(", ");
+
+export type ControllerPromptDeps = {
+  config: PluginConfig;
+  getTeamState: () => TeamState | null;
+};
+
+export function createControllerPromptInjector(deps: ControllerPromptDeps) {
+  return () => {
+    const state = deps.getTeamState();
+    if (!state) return null;
+
+    const workers = Object.values(state.workers);
+    const tasks = Object.values(state.tasks);
+    const pendingTasks = tasks.filter((t) => t.status === "pending");
+    const activeTasks = tasks.filter((t) => t.status === "in_progress" || t.status === "assigned");
+    const blockedTasks = tasks.filter((t) => t.status === "blocked");
+    const completedTasks = tasks.filter((t) => t.status === "completed");
+    const pendingClarifications = Object.values(state.clarifications).filter((c) => c.status === "pending");
+
+    const parts: string[] = [
+      "## TeamClaw Controller Mode",
+      "You are the Team Controller and the first-pass requirements analyst for the human.",
+      "Treat human input as raw requirements unless it is already explicitly phrased as an execution-ready TeamClaw task.",
+      "",
+      "### Available Tools",
+      "- teamclaw_create_task: Create a new task with role assignment",
+      "- teamclaw_list_tasks: List all tasks with status filtering",
+      "- teamclaw_assign_task: Assign a task to a specific worker",
+      "- teamclaw_send_message: Send messages between team members",
+      "",
+      "### Current Team Status",
+    ];
+
+    if (workers.length === 0) {
+      parts.push("- No workers registered yet");
+    } else {
+      for (const w of workers) {
+        const roleDef = ROLES.find((r) => r.id === w.role);
+        const statusIcon = w.status === "idle" ? "[idle]" : w.status === "busy" ? "[busy]" : "[offline]";
+        const currentTask = w.currentTaskId ? ` (task: ${w.currentTaskId})` : "";
+        parts.push(`- ${roleDef?.icon ?? ""} ${w.label} (${w.id}) ${statusIcon}${currentTask}`);
+      }
+    }
+
+    parts.push("");
+    parts.push(`### Tasks Summary`);
+    parts.push(`- Pending: ${pendingTasks.length} | Active: ${activeTasks.length} | Blocked: ${blockedTasks.length} | Completed: ${completedTasks.length}`);
+
+    if (pendingClarifications.length > 0) {
+      parts.push("");
+      parts.push("Pending clarification requests:");
+      for (const clarification of pendingClarifications.slice(0, 10)) {
+        parts.push(`- Task ${clarification.taskId}: ${clarification.question}`);
+      }
+    }
+
+    if (pendingTasks.length > 0) {
+      parts.push("");
+      parts.push("Pending tasks:");
+      for (const t of pendingTasks.slice(0, 10)) {
+        parts.push(`- [${t.priority}] ${t.title} (role: ${t.assignedRole ?? "any"})`);
+      }
+    }
+
+    parts.push("");
+    parts.push("### Available Roles");
+    for (const role of ROLES) {
+      parts.push(`- ${role.icon} ${role.label}: ${role.description}`);
+    }
+
+    parts.push("");
+    parts.push("## Requirement Intake Rules");
+    parts.push("- Human messages are the initial requirement, not an already-decomposed task tree.");
+    parts.push("- First analyze the requirement: desired outcome, scope, constraints, acceptance signals, and missing decisions.");
+    parts.push("- If critical information is missing, ask the human a concrete clarification question before creating execution tasks.");
+    parts.push("- After the requirement is clear enough, translate it into the minimum explicit TeamClaw task packet needed for the team.");
+    parts.push("- 'Minimum task packet' means only tasks that can start immediately with the currently available information and already-satisfied prerequisites.");
+    parts.push("- If later phases depend on outputs that do not exist yet, describe them to the human as the plan, but do not create those TeamClaw tasks yet.");
+    parts.push("- Downstream QA/review/release/README/integration tasks must stay in the plan until the upstream code or artifacts already exist in the workspace.");
+    parts.push("- Do not dump raw user wording directly onto workers when the requirement still needs controller-side analysis.");
+    parts.push("- TeamClaw uses git as the default file collaboration mechanism. Do not invent ad-hoc file sharing flows when the workspace repo is available.");
+
+    parts.push("");
+    parts.push("## Controller Discipline");
+    parts.push("- Stay within the user's current requirement/request.");
+    parts.push("- Create tasks only after you have converted the raw requirement into an execution-ready packet.");
+    parts.push("- Never create backlog placeholder tasks or future-phase tasks with unmet prerequisites; TeamClaw tasks are live work items, not a passive roadmap.");
+    parts.push("- Never create a task whose own wording says it should happen after something else is completed, ready, validated, or merged.");
+    parts.push("- Bad example: creating a QA/integration task that says 'run after server and SDK are ready' before those outputs exist. Good example: mention that QA step in the plan now, then create it later when the repo already contains the server and SDK.");
+    parts.push("- Do not auto-spawn helper tasks, duplicate tasks, or parallel task trees.");
+    parts.push("- Do not let a worker task turn itself into a controller/coordinator workflow.");
+    parts.push("- If the correct role is busy, prefer waiting, messaging, or explicit reassignment over routing core work to an unrelated role.");
+    parts.push("- If a task is blocked by missing information, keep it in the clarification queue until the human answers; do not guess on the user's behalf.");
+    parts.push("- Use the controller itself for requirement analysis; use the PM role only for PM-owned deliverables after intake is clear.");
+    parts.push(`- Use exact TeamClaw role IDs only: ${TEAMCLAW_ROLE_IDS_TEXT}.`);
+
+    return {
+      prependSystemContext: parts.join("\n"),
+    };
+  };
+}

package/src/controller/task-router.ts

@@ -0,0 +1,97 @@
+import type { PluginLogger } from "../../api.js";
+import type { TaskInfo, WorkerInfo } from "../types.js";
+import { getRole } from "../roles.js";
+
+export class TaskRouter {
+  private logger: PluginLogger;
+
+  constructor(logger: PluginLogger) {
+    this.logger = logger;
+  }
+
+  routeTask(
+    task: TaskInfo,
+    workers: Record<string, WorkerInfo>,
+  ): WorkerInfo | null {
+    // First try exact role match with idle workers
+    if (task.assignedRole) {
+      const candidates = Object.values(workers).filter(
+        (w) => w.role === task.assignedRole && w.status === "idle",
+      );
+      if (candidates.length > 0) {
+        return candidates[0]!;
+      }
+
+      this.logger.info(
+        `TaskRouter: no idle worker for explicitly assigned role ${task.assignedRole} on task ${task.id}; keeping task pending`,
+      );
+      return null;
+    }
+
+    // Try keyword matching on capabilities
+    const keywords = this.extractKeywords(task.description + " " + task.title);
+    const scored = Object.values(workers)
+      .filter((w) => w.status === "idle")
+      .map((w) => {
+        const roleDef = getRole(w.role);
+        const capabilities = roleDef?.capabilities ?? [];
+        const matchCount = keywords.filter((k) =>
+          capabilities.some((c) => c.includes(k) || k.includes(c)),
+        ).length;
+        return { worker: w, score: matchCount };
+      })
+      .filter((s) => s.score > 0)
+      .sort((a, b) => b.score - a.score);
+
+    if (scored.length > 0) {
+      return scored[0]!.worker;
+    }
+
+    // Fallback: any idle worker
+    const anyIdle = Object.values(workers).find((w) => w.status === "idle");
+    if (anyIdle) {
+      return anyIdle;
+    }
+
+    return null;
+  }
+
+  autoAssignPendingTasks(
+    tasks: Record<string, TaskInfo>,
+    workers: Record<string, WorkerInfo>,
+  ): Array<{ task: TaskInfo; worker: WorkerInfo }> {
+    const pendingTasks = Object.values(tasks).filter(
+      (t) => t.status === "pending" || t.status === "assigned",
+    );
+
+    const assignments: Array<{ task: TaskInfo; worker: WorkerInfo }> = [];
+
+    for (const task of pendingTasks) {
+      if (task.assignedWorkerId && workers[task.assignedWorkerId]) {
+        continue; // Already assigned to a valid worker
+      }
+
+      const worker = this.routeTask(task, workers);
+      if (worker) {
+        assignments.push({ task, worker });
+      }
+    }
+
+    return assignments;
+  }
+
+  private extractKeywords(text: string): string[] {
+    const common = new Set([
+      "the", "a", "an", "and", "or", "but", "in", "on", "at", "to", "for",
+      "of", "with", "by", "is", "are", "was", "were", "be", "been", "being",
+      "have", "has", "had", "do", "does", "did", "will", "would", "could",
+      "should", "may", "might", "must", "shall", "can", "this", "that",
+      "these", "those", "it", "its", "we", "our", "you", "your", "they",
+      "their", "create", "implement", "build", "make", "add", "update", "fix",
+    ]);
+    return text
+      .toLowerCase()
+      .split(/[^a-z0-9]+/)
+      .filter((w) => w.length > 2 && !common.has(w));
+  }
+}

package/src/controller/websocket.ts

@@ -0,0 +1,63 @@
+import { WebSocketServer, WebSocket } from "ws";
+import type { Server } from "node:http";
+import type { PluginLogger } from "../../api.js";
+
+export type WsEvent =
+  | { type: "worker:online"; data: unknown }
+  | { type: "worker:offline"; data: unknown }
+  | { type: "task:created"; data: unknown }
+  | { type: "task:updated"; data: unknown }
+  | { type: "task:completed"; data: unknown }
+  | { type: "task:execution"; data: unknown }
+  | { type: "message:new"; data: unknown }
+  | { type: "clarification:requested"; data: unknown }
+  | { type: "clarification:answered"; data: unknown };
+
+export class TeamWebSocketServer {
+  private wss: WebSocketServer | null = null;
+  private logger: PluginLogger;
+
+  constructor(logger: PluginLogger) {
+    this.logger = logger;
+  }
+
+  attach(server: Server): void {
+    this.wss = new WebSocketServer({ server, path: "/ws" });
+
+    this.wss.on("connection", (ws) => {
+      this.logger.info("WebSocket: client connected");
+      ws.on("close", () => {
+        this.logger.info("WebSocket: client disconnected");
+      });
+    });
+
+    this.wss.on("error", (err) => {
+      this.logger.warn(`WebSocket: error: ${String(err)}`);
+    });
+  }
+
+  broadcastUpdate(event: WsEvent): void {
+    if (!this.wss) return;
+
+    const data = JSON.stringify(event);
+    for (const client of this.wss.clients) {
+      if (client.readyState === WebSocket.OPEN) {
+        client.send(data);
+      }
+    }
+  }
+
+  close(): void {
+    if (this.wss) {
+      for (const client of this.wss.clients) {
+        client.close();
+      }
+      this.wss.close();
+      this.wss = null;
+    }
+  }
+
+  getClientCount(): number {
+    return this.wss ? this.wss.clients.size : 0;
+  }
+}