@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-2

package/src/controller/prompt-injector.ts

@@ -1,19 +1,19 @@
 import type { PluginConfig, TeamState } from "../types.js";
 import { ROLES } from "../roles.js";
+import {
+  buildControllerCompletionRules,
+  buildControllerDisciplineRules,
+  buildControllerEvidenceMemoryRules,
+  buildControllerIntakeRules,
+  buildControllerStructuredContractRules,
+  buildControllerToolRules,
+  buildControllerWorkflowRules,
+  composePrompt,
+} from "../prompt-policy.js";
 import { hasOnDemandWorkerProvisioning, shouldBlockControllerWithoutWorkers } from "./controller-capacity.js";
-
-const TEAMCLAW_ROLE_IDS_TEXT = [
-  "pm",
-  "architect",
-  "developer",
-  "qa",
-  "release-engineer",
-  "infra-engineer",
-  "devops",
-  "security-engineer",
-  "designer",
-  "marketing",
-].join(", ");
+import { resolveTeamClawWorkspaceDir } from "../workspace-browser.js";
+import fs from "node:fs";
+import path from "node:path";
 
 export type ControllerPromptDeps = {
   config: PluginConfig;
@@ -30,18 +30,13 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
     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 canProvisionWithoutWorkers = hasOnDemandWorkerProvisioning(deps.config);
 
     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_submit_manifest: Submit the required structured orchestration manifest for this intake run",
-      "- 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",
+      ...buildControllerToolRules(),
       "",
       "### Current Team Status",
     ];
@@ -95,62 +90,116 @@ export function createControllerPromptInjector(deps: ControllerPromptDeps) {
       parts.push(`- ${role.icon} ${role.label}: ${role.description}.${skillLine}`);
     }
 
+    // List existing projects so the controller can distinguish new vs. existing
+    parts.push("");
+    parts.push("### Existing Projects in Workspace");
+    const existingProjects = listExistingProjects(state);
+    if (existingProjects.length === 0) {
+      parts.push("- No existing projects yet.");
+    } else {
+      for (const proj of existingProjects) {
+        parts.push(`- 📂 ${proj.dir}: ${proj.summary}`);
+      }
+    }
+
     parts.push("");
-    parts.push("## Controller Workflow");
-    parts.push("- First determine which TeamClaw roles are needed for the human requirement.");
-    parts.push("- Then translate the requirement into the minimum execution-ready TeamClaw tasks owned by those roles.");
-    parts.push("- TeamClaw workers, not the controller, do the specialist work in the shared repo/workspace.");
-    parts.push("- After workers report progress, results, or handoffs, create only the next tasks whose prerequisites are now satisfied.");
-    parts.push("- A completed upstream task with a structured result contract, concrete deliverables, or an explicit handoff is strong evidence that its dependent downstream work can now be created.");
+    parts.push("## New vs. Existing Project Detection");
+    parts.push("- Before creating tasks, determine if the user's request relates to an existing project listed above.");
+    parts.push("- If the request mentions a technology, feature, or project name that matches an existing project, treat it as an enhancement/bugfix for that project — reuse the same projectDir.");
+    parts.push("- If the request is clearly a new, unrelated requirement, create a fresh projectDir with a new projectName.");
+    parts.push("- When enhancing an existing project, include context about what already exists so the worker can extend rather than rebuild.");
+    parts.push("- NEVER let a worker's deliverables reference files from a different project. Each task's deliverables must be scoped to its own projectDir.");
+
+    parts.push(...buildControllerWorkflowRules());
 
     parts.push("");
-    parts.push("## Structured Orchestration Contract");
-    parts.push("- Freeform prose is not enough for TeamClaw scheduling decisions.");
-    parts.push("- After your analysis and task-creation decisions are complete, call teamclaw_submit_manifest exactly once for this intake run.");
-    parts.push("- The manifest must include: requirementSummary, requiredRoles, clarificationsNeeded, clarificationQuestions, createdTasks, deferredTasks, and any handoff notes.");
-    parts.push("- Use createdTasks for execution-ready tasks that this run activated now, including a deliberately reused existing TeamClaw task when you chose not to duplicate it.");
-    parts.push("- Use deferredTasks for later-phase work that should not be created yet because prerequisites are not satisfied.");
-    parts.push("- If the run is blocked and no tasks should be created yet, submit a manifest with createdTasks=[] and explain the blocker in clarificationQuestions and/or deferredTasks.");
-    parts.push("- If you ask the human clarifying questions, still submit the manifest so the controller has machine-readable state for this run.");
+    parts.push("## Team Kickoff Meeting (Collaborative Planning)");
+    parts.push("- **IMPORTANT**: When the requirement involves 3 or more roles, you MUST call teamclaw_request_kickoff as your FIRST tool call, BEFORE creating any tasks.");
+    parts.push("- The kickoff provisions candidate role workers and asks each for a structured assessment from their professional perspective.");
+    parts.push("- Each role evaluates: whether they're needed, their scope of work, suggested tasks, dependencies on other roles, risks, and open questions.");
+    parts.push("- Use the team's assessments to make informed decisions about which roles to actually involve and how to structure the task pipeline.");
+    parts.push("- Roles that assessed themselves as not needed will be automatically reclaimed after their idle timeout.");
+    parts.push("- Adaptive kickoff rules:");
+    parts.push("  - **Simple** (single clear task, 1 role): Skip kickoff, create task directly.");
+    parts.push("  - **Medium** (2-3 roles likely): Call kickoff with the 2-3 most relevant roles.");
+    parts.push("  - **Complex** (4+ potential roles, multi-domain, unclear scope): ALWAYS call kickoff with all candidate roles. Do NOT skip.");
+    parts.push("- For task_follow_up runs (triggered by completed tasks), do NOT call kickoff again — the team plan was already established.");
+    parts.push("- Example: 'Build an e-commerce platform' → complex (architect+developer+designer+qa+security) → MUST call teamclaw_request_kickoff first");
 
     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("- When creating a task, include a recommendedSkills array whenever you know a useful OpenClaw/ClawHub skill slug (or a short search query if you do not know the exact slug).");
-    parts.push("- Prefer exact skill slugs over vague labels so the assigned worker can auto-search/install them before starting.");
-    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("## Out-of-Scope Requests");
+    parts.push("- TeamClaw is a software development team. You handle: coding, architecture, design, testing, deployment, documentation, security review, and related technical work.");
+    parts.push("- If the human asks for something clearly non-technical (cooking, weather, personal advice, general knowledge, creative writing unrelated to software), politely decline in your reply text AND still call teamclaw_submit_manifest with createdTasks=[], requiredRoles=[], and requirementSummary explaining why you declined.");
+    parts.push("- If the request is borderline (e.g. 'write a blog post about our API'), lean toward accepting it and assigning to the appropriate role (marketing, pm).");
+    parts.push("- REMEMBER: You must ALWAYS call teamclaw_submit_manifest, even when declining. The system cannot record your decision without it.");
 
     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("- You are never a substitute worker. Do not personally perform architecture, implementation, QA, release, infra, design, marketing, research, or other specialist work.");
-    parts.push("- Your own reply must stay at the orchestration layer: clarification, role selection, task decomposition, assignment decisions, and concise status updates.");
-    parts.push("- Do not rely on unstructured reply text as the only description of your orchestration decisions; the manifest is mandatory.");
-    if (hasOnDemandWorkerProvisioning(deps.config)) {
-      parts.push("- If no workers are currently registered but on-demand provisioning is enabled, you may still create execution-ready tasks so the required roles can be provisioned.");
-    } else {
-      parts.push("- If no workers are registered, you may mention which roles would be needed, but stop there and report the worker-capacity block to the human.");
-    }
-    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}.`);
+    parts.push("## Clarification & Follow-up Awareness");
+    parts.push("- If this session has prior messages where you asked clarification questions, the human's new message is likely a response to those questions.");
+    parts.push("- Do NOT treat a follow-up human message as a brand-new requirement if there are pending clarification questions in this session. Instead, interpret the message as an answer and proceed with task creation.");
+    parts.push("- If the human's follow-up is clearly irrelevant to the pending questions (e.g. random chitchat), acknowledge it briefly and re-state the pending questions so the human knows what you still need.");
+    parts.push("- For automatic task_follow_up runs (triggered by task completion), focus on advancing the pipeline — do not re-ask questions already answered.");
+
+    parts.push("");
+    parts.push("## Deliverable Presentation");
+    parts.push("- When a task completes with a result contract, review the deliverables and present a clear, actionable summary to the human.");
+    parts.push("- For web applications: include the preview URL if available (deliverable.liveUrl). The human should be able to click and verify.");
+    parts.push("- For CLI tools: include the command to run with example arguments.");
+    parts.push("- For documents: highlight the key decisions or structure.");
+    parts.push("- When ALL tasks for the requirement are complete (requirementFullyComplete=true), provide a final delivery summary:");
+    parts.push("  - What was built (1-2 sentence overview)");
+    parts.push("  - How to access/run it (URLs, commands)");
+    parts.push("  - File locations (project directory)");
+    parts.push("  - Any caveats or next steps");
+
+    parts.push(...buildControllerStructuredContractRules());
+    parts.push(...buildControllerEvidenceMemoryRules());
+    parts.push(...buildControllerIntakeRules());
+    parts.push(...buildControllerDisciplineRules({ canProvisionWithoutWorkers }));
+    parts.push(...buildControllerCompletionRules());
 
     return {
-      prependSystemContext: parts.join("\n"),
+      prependSystemContext: composePrompt(parts),
     };
   };
 }
+
+type ExistingProjectInfo = { dir: string; summary: string };
+
+function listExistingProjects(state: TeamState | null): ExistingProjectInfo[] {
+  const projects: ExistingProjectInfo[] = [];
+
+  // Gather from completed tasks with projectDir
+  const seenDirs = new Set<string>();
+  if (state) {
+    for (const task of Object.values(state.tasks)) {
+      if (task.projectDir && !seenDirs.has(task.projectDir)) {
+        seenDirs.add(task.projectDir);
+        const summary = task.resultContract?.summary ?? task.title;
+        projects.push({ dir: task.projectDir, summary });
+      }
+    }
+  }
+
+  // Also scan the filesystem for project directories not tracked in state
+  try {
+    const workspaceDir = resolveTeamClawWorkspaceDir();
+    const projectsRoot = path.join(workspaceDir, "projects");
+    if (fs.existsSync(projectsRoot)) {
+      const entries = fs.readdirSync(projectsRoot, { withFileTypes: true });
+      for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith(".")) {
+          const fullDir = `projects/${entry.name}`;
+          if (!seenDirs.has(entry.name) && !seenDirs.has(fullDir)) {
+            seenDirs.add(fullDir);
+            projects.push({ dir: fullDir, summary: "(discovered on filesystem)" });
+          }
+        }
+      }
+    }
+  } catch {
+    // Workspace not available — skip filesystem scan
+  }
+
+  return projects.slice(0, 20);
+}

package/src/controller/role-inference.ts

@@ -0,0 +1,41 @@
+import { ROLES } from "../roles.js";
+import type { RoleId, TaskInfo } from "../types.js";
+
+/**
+ * Infer the most appropriate role for a task based on text analysis.
+ *
+ * If `task.assignedRole` is already set, returns it directly.
+ * Otherwise, tokenizes the task title + description and scores each known
+ * role by overlap with its id, label, and capabilities.
+ */
+export function inferTaskRole(task: Pick<TaskInfo, "assignedRole" | "title" | "description">): RoleId | null {
+  if (task.assignedRole) {
+    return task.assignedRole;
+  }
+
+  const text = `${task.title} ${task.description}`.toLowerCase();
+  let bestRole: RoleId | null = null;
+  let bestScore = 0;
+
+  for (const role of ROLES) {
+    const roleTokens = [
+      role.id,
+      role.label,
+      ...role.capabilities,
+    ].flatMap((entry) => entry.toLowerCase().split(/[^a-z0-9]+/).filter((token) => token.length > 2));
+    const uniqueTokens = [...new Set(roleTokens)];
+    const score = uniqueTokens.reduce((count, token) => count + (text.includes(token) ? 1 : 0), 0);
+    if (score > bestScore) {
+      bestScore = score;
+      bestRole = role.id;
+    }
+  }
+
+  return bestScore > 0 ? bestRole : null;
+}
+
+/**
+ * Fallback role when inference produces no match.
+ * The developer role is the most versatile generalist.
+ */
+export const FALLBACK_ROLE: RoleId = "developer";

package/src/controller/websocket.ts

@@ -12,7 +12,9 @@ export type WsEvent =
   | { type: "task:execution"; data: unknown }
   | { type: "message:new"; data: unknown }
   | { type: "clarification:requested"; data: unknown }
-  | { type: "clarification:answered"; data: unknown };
+  | { type: "clarification:answered"; data: unknown }
+  | { type: "requirement:complete"; data: unknown }
+  | { type: "report:ready"; data: unknown };
 
 export class TeamWebSocketServer {
   private wss: WebSocketServer | null = null;