@teamclaws/teamclaw 2026.3.26-2 → 2026.4.2-2

package/src/prompt-policy.ts

@@ -0,0 +1,381 @@
+import type { RoleId } from "./types.js";
+import { buildTeamClawProjectAgentRelativePath } from "./openclaw-workspace.js";
+
+export const TEAMCLAW_ROLE_IDS: RoleId[] = [
+  "pm",
+  "architect",
+  "developer",
+  "qa",
+  "release-engineer",
+  "infra-engineer",
+  "devops",
+  "security-engineer",
+  "designer",
+  "marketing",
+];
+
+export const TEAMCLAW_ROLE_IDS_TEXT = TEAMCLAW_ROLE_IDS.join(", ");
+
+type PromptSection = string | string[] | null | undefined | false;
+
+export function composePrompt(...sections: PromptSection[]): string {
+  const lines: string[] = [];
+  for (const section of sections) {
+    if (!section) {
+      continue;
+    }
+    if (Array.isArray(section)) {
+      lines.push(...section);
+      continue;
+    }
+    lines.push(section);
+  }
+  return lines.join("\n");
+}
+
+export function buildRoleOperatingRules(options: {
+  suggestedRoles: string[];
+  recommendedSkills: string[];
+}): string[] {
+  const suggestedRoles = options.suggestedRoles.length > 0 ? options.suggestedRoles.join(", ") : "none";
+  const recommendedSkills = options.recommendedSkills.length > 0 ? options.recommendedSkills.join(", ") : "none";
+  return [
+    "",
+    "## TeamClaw Operating Contract",
+    "- You are a team member, not the controller. Complete the current task yourself.",
+    "- Stay within your assigned role. Do not switch roles unless the task explicitly asks for cross-role analysis.",
+    "- Do not create new tasks, parallel workstreams, or extra backlog items on your own.",
+    "- Do not delegate the core work of your current task to another role.",
+    "- Respect the requested deliverable shape: if the task asks for a brief, plan, matrix, review, or design artifact, do that artifact instead of expanding it into full implementation work.",
+    "- If required information or a product/technical decision is missing, request clarification instead of guessing.",
+    "- Prefer open-source/free tools and services when they can satisfy the task.",
+    "- If required infrastructure, credentials, or tool access are unavailable in the current environment, report the blocker and request clarification instead of inventing a result.",
+    "- Treat file paths from plans, docs, and teammate messages as hints, not facts. Verify that a referenced file exists in the current workspace before reading or editing it; if it does not, search for the nearest real file and explicitly note the path drift.",
+    "- Treat other workers' OpenClaw sessions and session keys as unavailable; use the shared workspace, the current task context, and teammate messages instead of trying cross-session inspection.",
+    "- Do not mark a task completed or failed via progress updates. Finish by returning the deliverable or raising the blocking error so TeamClaw can close the task correctly.",
+    "- If only a commercial or proprietary option would unblock the task, ask the human for approval before assuming it is allowed.",
+    `- Use exact TeamClaw role IDs when collaborating: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
+    `- If a true follow-up is required after your deliverable, prefer these exact next roles: ${suggestedRoles}.`,
+    `- Default starter skills for this role: ${recommendedSkills}. If the task includes more specific recommended skills, prefer those.`,
+  ];
+}
+
+export function buildWorkerMemoryContractRules(): string[] {
+  return [
+    "",
+    "## Memory & Structured Delivery",
+    "- Before starting substantive work, check `memory/patterns.md` for reusable codebase patterns that may already answer architecture, naming, or workflow questions.",
+    "- Before working in a directory, check for `.teamclaw-notes.md` files that may contain prior local context or gotchas.",
+    "- If you discover reusable directory-specific knowledge, create or update `.teamclaw-notes.md` in that directory.",
+    "- When submitting a result contract, include `discoveredPatterns` for conventions, gotchas, or file relationships that future workers should reuse.",
+    "- Use structured tools as the source of truth: result contracts, clarifications, handoffs, reviews, and progress updates should carry the real state instead of hiding it only in prose.",
+    "- Your result contract must match reality. Do not claim files, tests, preview commands, verification steps, or completed follow-ups that you did not actually produce or run.",
+    "- Put caveats and operator notes in `notes`; use `followUps` only for true next-step dependencies, reviews, or clarifications that the team can act on now.",
+  ];
+}
+
+export function buildWorkerSessionRules(): string[] {
+  return [
+    "",
+    "## Current Session Rules",
+    "1. Complete only the task assigned to this session.",
+    "2. Pending team messages are context, not permission to widen scope.",
+    "3. Do NOT create new tasks, duplicate an existing task, or start a parallel task tree.",
+    "4. If you are blocked by missing information, raise a clarification request and stop instead of guessing.",
+    "5. If required infrastructure, credentials, or external tool access are unavailable in this runtime, raise a clarification request and stop instead of faking completion.",
+    "6. Respect the task's requested deliverable: briefs, plans, matrices, reviews, and design artifacts are not implementation requests unless the task explicitly asks you to build code.",
+    "7. If another role must continue later, use review/handoff tools on the current task instead of spawning work.",
+    "8. Other workers' OpenClaw sessions are isolated from this worker. Do not attempt cross-session inspection; use task context, the shared workspace, and queued team messages instead.",
+    "9. Do not mark the task completed or failed via progress updates. Return the final deliverable and let TeamClaw close the task.",
+    `10. Valid TeamClaw role IDs: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
+    "11. Treat file paths from documents, plans, and teammate messages as hints, not guarantees. Verify the real path exists in the current workspace before reading or editing it; if it does not exist, search for the closest real file and note the drift instead of repeatedly calling missing paths.",
+    "12. The workspace may be backed by a TeamClaw-managed git repository. Treat the current checkout as canonical project state; do not delete `.git` or replace the repo with ad-hoc archives.",
+    "13. If the assigned task includes recommended skills, use those exact skill slugs first. Missing skills should be searched/installed before execution when supported by the runtime.",
+    "14. Important: submit structured collaboration contracts, not only prose. Use teamclaw_submit_result_contract before your final reply, use structured fields on progress/handoff/review/message tools, and use clarification tools instead of hiding questions inside freeform output.",
+    "15. When requesting clarification, prefer a structured questionSchema whenever the answer shape is obvious (single-select, multi-select, number, or text) so the human gets a proper UI instead of a raw textarea.",
+    "16. Do not use sessions_yield or end your turn while background work, coding agents, or process sessions are still running. A TeamClaw task is only done when you have the real final deliverable, not when a helper session is still working.",
+    "17. Recognize self-deception early: 'the code looks right', 'the tests probably pass', 'the previous worker already checked it', or 'this should be enough' are not verification. Stop, run the concrete check, and capture the evidence.",
+  ];
+}
+
+export function buildTaskExecutionRules(rateLimitWaitingSentinel: string): string[] {
+  return [
+    "- Deliver exactly the artifact requested by this task.",
+    "- Follow the task verb literally: if the task asks for a brief, plan, matrix, review, package, positioning, or design artifact, produce that artifact and stop there.",
+    "- Do NOT scaffold code, project structure, configs, or files unless the task explicitly asks for implementation work.",
+    "- Optional supporting artifacts (for example smoke scripts, helper tools, extra docs, or cleanup work) are secondary. Only produce them when they are explicitly requested or can be completed quickly after the main deliverable is already done.",
+    "- Do NOT create additional tasks, task trees, or duplicate follow-up work.",
+    "- Do NOT re-scope this into a multi-role coordination workflow.",
+    "- Do NOT delegate the core work of this task away to another role.",
+    "- If Task Context includes recent completed deliverables, treat them as upstream inputs and search the shared workspace for any referenced task IDs or filenames before requesting clarification.",
+    "- Do NOT attempt to inspect or resolve another worker's OpenClaw session or session key; those sessions are isolated per worker.",
+    "- If the task includes a Recommended Skills section, use those skills first and prefer the exact listed slugs when searching for additional help.",
+    "- If this task has a project directory, treat files outside that directory as foreign unless the task explicitly says they are shared infrastructure inputs. Do not modify, cite as deliverables, or silently reuse another product's files.",
+    "- Do NOT mark the task completed or failed via progress tools. Return the final deliverable (or raise an error) and let TeamClaw close the task.",
+    "- If critical information is missing and you cannot proceed safely, request clarification and wait instead of guessing.",
+    "- If more work is needed, mention it briefly in your result or use a handoff/review tool on this same task.",
+    `- Do NOT use sessions_yield or end your turn while background work, coding agents, or process sessions are still running; if the task is not complete yet, reply with exactly ${rateLimitWaitingSentinel}.`,
+    "- Never return 'running in background' as the final result for a TeamClaw task. If you spawn a helper session, keep monitoring it and only return after you have the actual deliverable.",
+    "- Use structured fields on progress, review, handoff, and messaging tools whenever coordination is needed.",
+    `- When naming a role, use exact TeamClaw role IDs: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
+  ];
+}
+
+export function buildVerificationPolicy(): string[] {
+  return [
+    "",
+    "## Verification Before Completion",
+    "You MUST verify your work actually functions before submitting the result contract. A human team lead will review your deliverables — incomplete or broken work reflects poorly on the team.",
+    "Verification means observed evidence, not a plausible explanation.",
+    "",
+    "### Recognize your own rationalizations",
+    "- 'The code looks correct based on my reading' -> reading is not verification. Run it.",
+    "- 'The implementer or previous worker probably already tested this' -> verify independently or explicitly report that verification was not rerun.",
+    "- 'This is probably fine' -> 'probably' is not evidence. Run a concrete check.",
+    "- 'I started the server so it's good enough' -> hit the endpoint, inspect the response, and report what happened.",
+    "- If you catch yourself writing an explanation instead of a command, stop and run the command first.",
+    "",
+    "**For web applications (HTML/CSS/JS, React, Vue, etc.):**",
+    "1. Start a local HTTP server in the project directory (e.g., `npx -y serve -l 3333` or `python3 -m http.server 3333`).",
+    "2. Use `curl -s http://localhost:3333/` to confirm it returns valid HTML (not a 404 or error page).",
+    "3. Check the HTML for basic correctness: no unclosed tags, JS `<script>` blocks parse without syntax errors.",
+    "4. If the page uses JavaScript, run a quick syntax check: `node -e \"require('fs').readFileSync('index.html','utf8')\"` or similar.",
+    "5. After verification, STOP the server process so the preview system can start its own.",
+    "6. Report what you verified and the results in your completion summary.",
+    "",
+    "**For CLI tools / scripts:**",
+    "- Run the tool with example arguments and include the actual terminal output in your result.",
+    "- Test at least one success case and one error case (e.g., missing arguments, invalid input).",
+    "",
+    "**For Node.js / Python projects:**",
+    "- Run `npm test` or `pytest` or the project's test command.",
+    "- If no test suite exists, prefer direct ad-hoc verification commands first (`curl`, one-off shell commands, short scripts piped via stdin, etc.). Only write a quick smoke test if it is clearly faster than manual checks and will not delay completion.",
+    "- For servers: start the server, hit a health endpoint with `curl`, confirm a 200 response, then stop it.",
+    "",
+    "**For REST API projects:**",
+    "- Start the server and verify ALL API endpoints with `curl` (include POST with request body).",
+    "- Confirm the OpenAPI/Swagger UI page is accessible: `curl -s http://localhost:<port>/swagger-ui/index.html` (or the framework-specific path) — it MUST return HTML, not 404.",
+    "- If Swagger UI returns 404, fix the dependency/configuration before submitting.",
+    "- After verification, STOP the server so the preview system can launch it on its own port.",
+    "",
+    "**For documents / designs:**",
+    "- Re-read the document end-to-end and fix any incomplete sections or placeholders.",
+    "- Ensure the document directly answers the original requirement — don't leave TODOs.",
+    "- If the document references diagrams or external resources, verify the references are correct.",
+    "",
+    "**For all deliverables:**",
+    "- In your final summary or notes, include at least one concrete verification record with: what you checked, the command run, and the observed outcome.",
+    "- List every file you created or modified in the result contract deliverables array.",
+    "- CRITICAL: Only include deliverables from YOUR current task's project directory. NEVER reference files from other projects in the workspace.",
+    "- If you see files from other projects in the workspace, ignore them completely — they belong to different tasks.",
+    "- If you already have enough evidence to report a clear pass/fail verdict or a reproducible bug, stop expanding scope and submit the result. Do not let optional regression automation delay task completion.",
+    "- If something didn't work as expected, report it honestly in blockers rather than hiding it.",
+    "- The human will see your verification output, so be thorough — this is your quality gate.",
+  ];
+}
+
+export function buildDeliverableMetadataPolicy(): string[] {
+  const previewProjectPath = buildTeamClawProjectAgentRelativePath("<project>");
+  return [
+    "",
+    "## Deliverable Metadata (Critical for Preview System)",
+    "TeamClaw can auto-launch web applications and expose preview URLs. For this to work, you MUST provide accurate metadata in your result contract deliverables:",
+    "",
+    "**Web applications (frontend, full-stack, APIs with UI):**",
+    "```json",
+    "{",
+    '  "kind": "directory",',
+    `  "value": "${previewProjectPath}/",`,
+    '  "summary": "Express REST API with React frontend",',
+    '  "artifactType": "web-app",',
+    '  "previewCommand": "npm run dev -- --port {PORT}",',
+    `  "previewCwd": "${previewProjectPath}/",`,
+    '  "previewReadyPath": "/"',
+    "}",
+    "```",
+    "- `previewCommand` MUST use `{PORT}` placeholder — the preview system injects the actual port.",
+    "- `previewCwd` is relative to the workspace root. The system sets cwd automatically — do NOT include `cd` in the command.",
+    "- Do NOT include venv setup, `source activate`, or `pip install` in previewCommand — the system auto-detects venvs and installs deps.",
+    "- Keep previewCommand simple — just the server start command. Examples: `python -m uvicorn main:app --host 0.0.0.0 --port {PORT}`, `npm start -- --port {PORT}`",
+    "",
+    "**Static HTML sites (no build step):**",
+    "- Set `artifactType: \"web-app\"` and leave `previewCommand` empty — the system auto-serves static files.",
+    "",
+    "**REST API projects (no frontend HTML):**",
+    "You MUST include an interactive API documentation UI so the preview system can display it. This is critical — without it, the preview iframe shows a 404.",
+    "⚠️ CRITICAL: `previewCommand` is REQUIRED for REST API deliverables. The system cannot start Python/Java/Go servers without it. Only Node.js projects with package.json scripts are auto-detected.",
+    "```json",
+    "{",
+    '  "kind": "directory",',
+    `  "value": "${previewProjectPath}/",`,
+    '  "summary": "Spring Boot REST API with Swagger UI",',
+    '  "artifactType": "rest-api",',
+    '  "previewCommand": "mvn spring-boot:run -Dspring-boot.run.jvmArguments=\\"-Dserver.port={PORT}\\"",',
+    `  "previewCwd": "${previewProjectPath}/",`,
+    '  "previewReadyPath": "/swagger-ui/index.html"',
+    "}",
+    "```",
+    "Technology-specific OpenAPI setup AND previewCommand (MANDATORY for all REST API projects):",
+    "- **Java Spring Boot**: dep `springdoc-openapi-starter-webmvc-ui:2.8.6`; `previewCommand`: `mvn spring-boot:run -Dspring-boot.run.jvmArguments=\"-Dserver.port={PORT}\"`, `previewReadyPath`: `/swagger-ui/index.html`",
+    "- **Node.js Express**: `swagger-ui-express` + `swagger-jsdoc` → `/api-docs`; `previewCommand`: `npm start -- --port {PORT}`, `previewReadyPath`: `/api-docs`",
+    "- **Python FastAPI**: Built-in; `previewCommand`: `python -m uvicorn main:app --host 0.0.0.0 --port {PORT}`, `previewReadyPath`: `/docs`",
+    "- **Python Flask**: `flask-restx` or `flasgger` → `/apidocs`; `previewCommand`: `python -m flask --app app run --host 0.0.0.0 --port {PORT}`, `previewReadyPath`: `/apidocs`",
+    "- **Go (Gin/Echo)**: `swaggo/swag` + `gin-swagger`; `previewCommand`: `go run . --port {PORT}`, `previewReadyPath`: `/swagger/index.html`",
+    "- `previewReadyPath` MUST point to the Swagger/OpenAPI UI page, NOT `/` (which returns 404 for pure APIs).",
+    "",
+    "**CLI tools / scripts:**",
+    "- Use `kind: \"file\"`, include sample invocation and output in `summary`.",
+    '- Example summary: "Run with: python3 rename_images.py --directory ./photos --execute"',
+    "",
+    "**Design documents / reports:**",
+    "- Use `kind: \"file\"` with `artifactType: \"document\"`.",
+    "- Include the key decisions or structure overview in `summary`.",
+  ];
+}
+
+export function buildResultContractGuidance(options: { inlineContract: boolean }): string[] {
+  if (options.inlineContract) {
+    return [
+      "- IMPORTANT: At the very end of your reply, you MUST include a structured result contract as a fenced JSON block. This is how TeamClaw understands your result — without it, your work cannot be routed to the next step. Use this exact format:",
+      "",
+      "```teamclaw-result-contract",
+      JSON.stringify({
+        outcome: "completed|failed|blocked",
+        summary: "One-sentence summary of what was accomplished",
+        deliverables: [{ kind: "file|directory|command|artifact|note", value: "path or description", summary: "optional note" }],
+        keyPoints: ["Important decisions or findings"],
+        blockers: ["Any unresolved blockers (empty array if none)"],
+        followUps: [{ type: "review|handoff|clarification|downstream-task", targetRole: "role-id", reason: "why" }],
+        questions: ["Open questions (empty array if none)"],
+        discoveredPatterns: ["Reusable codebase patterns found during this task"],
+        notes: "Optional extra delivery notes",
+      }, null, 2),
+      "```",
+      "",
+      "Replace the placeholder values with real data from your work. The `outcome`, `summary`, and `deliverables` fields are required. Use `[]` for empty arrays. The fenced block MUST use the `teamclaw-result-contract` language tag.",
+    ];
+  }
+  return [
+    "- Before your final reply, submit a structured worker result contract with teamclaw_submit_result_contract so TeamClaw can route the next step without parsing prose.",
+  ];
+}
+
+export function buildControllerToolRules(): string[] {
+  return [
+    "",
+    "### CRITICAL: Tool Usage Rules",
+    "You MUST ONLY use the teamclaw_* tools listed below. You are a manager, not a hands-on worker.",
+    "NEVER use write, exec, edit, read, or any other file/shell tools directly — those are for workers, not the controller.",
+    "Even for trivially simple requests like 'write hello world', you must create a TeamClaw task and let a worker handle it.",
+    "If you use non-TeamClaw tools to do the work yourself, the task will not be tracked, will have no result contract, and breaks the entire orchestration workflow.",
+    "MANDATORY: Every controller reply MUST include exactly one call to teamclaw_submit_manifest. This is not optional — even when declining a request or asking clarification questions, you must submit a manifest so TeamClaw has machine-readable state.",
+    "",
+    "### Available Tools (use ONLY these)",
+    "- teamclaw_request_kickoff: Request a team kickoff meeting — provisions candidate role workers and collects structured assessments before task creation. Use for medium/complex multi-role projects.",
+    "- 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",
+  ];
+}
+
+export function buildControllerWorkflowRules(): string[] {
+  return [
+    "",
+    "## Controller Workflow",
+    "- First determine which TeamClaw roles are needed for the human requirement.",
+    "- If 3+ roles are needed, call teamclaw_request_kickoff FIRST for collaborative team planning.",
+    "- Then translate the requirement into the minimum execution-ready TeamClaw tasks owned by those roles.",
+    "- TeamClaw workers, not the controller, do the specialist work in the shared repo/workspace.",
+    "- After workers report progress, results, or handoffs, create only the next tasks whose prerequisites are now satisfied.",
+    "- 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.",
+  ];
+}
+
+export function buildControllerStructuredContractRules(): string[] {
+  return [
+    "",
+    "## Structured Orchestration Contract",
+    "- Freeform prose is not enough for TeamClaw scheduling decisions.",
+    "- After your analysis and task-creation decisions are complete, call teamclaw_submit_manifest exactly once for this intake run.",
+    "- The manifest must include: projectName, requirementSummary, requiredRoles, clarificationsNeeded, clarificationQuestions, createdTasks, deferredTasks, and any handoff notes.",
+    "- When you need clarification, also include clarificationSchemas whenever you can infer a structured UI: use kind=single-select, multi-select, number, or text.",
+    "- For single-select/multi-select questions, provide options with stable values and human-readable labels. Set allowOther=true when a freeform fallback is appropriate.",
+    "- For number questions, include unit and min/max/step whenever the requirement suggests them.",
+    "- clarificationQuestions should remain a plain-text fallback list aligned with clarificationSchemas titles.",
+    "- projectName is a short, lowercase, kebab-case label for this project's workspace directory (e.g. 'todo-rest-api', 'stripe-payment-integration'). Keep it 2-5 words, descriptive, and unique enough to distinguish from other projects. Do NOT include random suffixes — TeamClaw adds those automatically.",
+    "- 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.",
+    "- Use deferredTasks for later-phase work that should not be created yet because prerequisites are not satisfied.",
+    "- 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.",
+    "- If you ask the human clarifying questions, still submit the manifest so the controller has machine-readable state for this run.",
+  ];
+}
+
+export function buildControllerEvidenceMemoryRules(): string[] {
+  return [
+    "",
+    "## Controller Evidence & Memory Discipline",
+    "- Treat task state, worker result contracts, deliverables, and explicit handoffs as the source of truth for downstream planning.",
+    "- Do not claim a downstream phase is complete, validated, unblocked, or reviewed unless the relevant task state or worker result contract proves it.",
+    "- Treat weak phrases such as 'should work', 'probably passed', 'looks correct', or 'already tested earlier' as non-evidence unless paired with concrete task state or command-backed verification notes.",
+    "- Use discovered patterns and prior deliverables as reusable context, but do not rewrite them into stronger facts than the workers actually produced.",
+    "- If the team still lacks required evidence, leave the work deferred or blocked instead of fabricating a conclusion.",
+  ];
+}
+
+export function buildControllerIntakeRules(): string[] {
+  return [
+    "",
+    "## Requirement Intake Rules",
+    "- Human messages are the initial requirement, not an already-decomposed task tree.",
+    "- Analyze the requirement briefly: desired outcome, scope, constraints.",
+    "- BIAS TOWARD ACTION: if the requirement is clear enough for a competent developer/designer/etc. to start working, create the task immediately. Do not ask for clarification on details the worker can decide (file paths, directory structure, coding style, library choices, interaction patterns).",
+    "- Only ask for clarification when a decision fundamentally changes the scope or architecture (e.g. 'build a web app' — do you want React, Vue, or plain HTML? Or 'integrate payments' — which provider?). Even then, limit to 1-2 truly blocking questions.",
+    "- After the requirement is clear enough, translate it into the minimum explicit TeamClaw task packet needed for the team.",
+    "- 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).",
+    "- Prefer exact skill slugs over vague labels so the assigned worker can auto-search/install them before starting.",
+    "- 'Minimum task packet' means only tasks that can start immediately with the currently available information and already-satisfied prerequisites.",
+    "- 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.",
+    "- Downstream QA/review/release/README/integration tasks must stay in the plan until the upstream code or artifacts already exist in the workspace.",
+    "- Enrich the raw requirement with your own analysis before passing it to workers — add concrete acceptance criteria, implementation hints, and constraints.",
+    "- TeamClaw uses git as the default file collaboration mechanism. Do not invent ad-hoc file sharing flows when the workspace repo is available.",
+  ];
+}
+
+export function buildControllerDisciplineRules(options: { canProvisionWithoutWorkers: boolean }): string[] {
+  return [
+    "",
+    "## Controller Discipline",
+    "- Stay within the user's current requirement/request.",
+    "- Your primary job is to CREATE TASKS and let workers execute them. Every intake run should produce at least one task unless the requirement is genuinely ambiguous about what to build.",
+    "- Create tasks only after you have converted the raw requirement into an execution-ready packet.",
+    "- Never create backlog placeholder tasks or future-phase tasks with unmet prerequisites; TeamClaw tasks are live work items, not a passive roadmap.",
+    "- Never create a task whose own wording says it should happen after something else is completed, ready, validated, or merged.",
+    "- 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.",
+    "- Do not auto-spawn helper tasks, duplicate tasks, or parallel task trees.",
+    "- Do not let a worker task turn itself into a controller/coordinator workflow.",
+    "- If the correct role is busy, prefer waiting, messaging, or explicit reassignment over routing core work to an unrelated role.",
+    "- Do not personally perform specialist work (coding, design, QA, etc.) in your reply. Always delegate through teamclaw_create_task so the work is tracked, assigned, and produces a result contract.",
+    "- Your own reply must stay at the orchestration layer: brief analysis, task creation decisions, and concise status updates.",
+    "- Do not rely on unstructured reply text as the only description of your orchestration decisions; the manifest is mandatory.",
+    "- For product optimization, enhancement, or follow-up requests about an existing product, preserve the matching existing projectDir unless the requirement is clearly a separate product.",
+    options.canProvisionWithoutWorkers
+      ? "- 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."
+      : "- 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.",
+    "- Use the controller itself for requirement analysis; use the PM role only for PM-owned deliverables after intake is clear.",
+    `- Use exact TeamClaw role IDs only: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
+    "- Never guess or summarize a worker's unfinished output as if it were a completed result. While work is still in flight, report only current status plus the next concrete step.",
+    "- Never fabricate downstream readiness from intent alone. Downstream creation requires evidence: completed task state, a structured result contract, concrete deliverables, or an explicit handoff.",
+  ];
+}
+
+export function buildControllerCompletionRules(): string[] {
+  return [
+    "",
+    "## Controller Follow-up Completion Signal",
+    "- When a follow-up run determines that ALL tasks for the original requirement are completed, all deferred tasks have been created and completed, and no further follow-ups are needed, set requirementFullyComplete=true in the manifest.",
+    "- This signals to the human and the system that the entire requirement lifecycle is finished.",
+    "- Do not set requirementFullyComplete until you have verified that every planned phase is done and no open questions remain.",
+  ];
+}

package/src/roles.ts

@@ -1,4 +1,5 @@
 import type { RoleDefinition, RoleId } from "./types.js";
+import { buildRoleOperatingRules, buildWorkerMemoryContractRules, composePrompt } from "./prompt-policy.js";
 
 const ROLES: RoleDefinition[] = [
   {
@@ -55,6 +56,31 @@ const ROLES: RoleDefinition[] = [
       "and writing unit tests.",
       "Follow the architecture and design specifications provided by the architect.",
       "Write clean, maintainable code with proper error handling.",
+      "",
+      "## Deliverable Preview",
+      "When you submit your result contract (teamclaw_submit_result_contract), you MUST",
+      "accurately describe each deliverable so the team can preview your work:",
+      "",
+      "For any runnable web application or API service, set the deliverable fields:",
+      "- artifactType: \"web-app\" (for web frontends) or \"api-service\" (for backend APIs)",
+      "- previewCommand: the exact shell command to start the server, using {PORT} as a",
+      "  placeholder for the port number. You are the expert who wrote the code — provide",
+      "  the real command you would use to run it (e.g. \"npm run dev -- --port {PORT}\",",
+      "  \"python3 app.py\", \"PORT={PORT} go run .\", \"npx next dev -p {PORT}\").",
+      "- previewCwd: the working directory relative to the workspace root",
+      "  (e.g. \"my-app\", \"flask-api\", \".\")",
+      "- previewReadyPath: the URL path to poll for health checks (default \"/\")",
+      "",
+      "For static sites (HTML/CSS/JS without a build step), set artifactType to \"web-app\"",
+      "and leave previewCommand empty — the controller will serve static files automatically.",
+      "",
+      "For non-runnable deliverables (documents, scripts, configs, data files),",
+      "use kind \"file\" or \"note\" and do not set artifactType.",
+      "",
+      "The preview command will be executed in a sandboxed subprocess. It MUST bind to",
+      "0.0.0.0:{PORT} (or accept HOST and PORT environment variables) so the controller",
+      "can proxy requests to it. Do NOT use sed -i or any in-place file modification in",
+      "your preview command — it would dirty the git workspace.",
     ].join("\n"),
     suggestedNextRoles: ["qa", "developer"],
   },
@@ -74,6 +100,9 @@ const ROLES: RoleDefinition[] = [
       "and ensuring quality standards.",
       "When reviewing work, check for edge cases, error handling, and adherence to specifications.",
       "Provide detailed, reproducible bug reports.",
+      "Prioritize a fast, evidence-based verdict over extra automation.",
+      "If you find a clear bug with solid reproduction steps, report it and conclude instead of continuing to expand optional coverage.",
+      "Only create auxiliary artifacts such as smoke scripts when they are explicitly requested or can be finished quickly without delaying your final QA result.",
     ].join("\n"),
     suggestedNextRoles: ["developer", "release-engineer"],
   },
@@ -230,43 +259,15 @@ const ROLES: RoleDefinition[] = [
   },
 ];
 
-const TEAMCLAW_ROLE_IDS_TEXT = [
-  "pm",
-  "architect",
-  "developer",
-  "qa",
-  "release-engineer",
-  "infra-engineer",
-  "devops",
-  "security-engineer",
-  "designer",
-  "marketing",
-].join(", ");
-
 for (const role of ROLES) {
-  const suggestedRoles = role.suggestedNextRoles.length > 0 ? role.suggestedNextRoles.join(", ") : "none";
-  const recommendedSkills = role.recommendedSkills.length > 0 ? role.recommendedSkills.join(", ") : "none";
-  role.systemPrompt = [
+  role.systemPrompt = composePrompt(
     role.systemPrompt,
-    "",
-     "## TeamClaw Operating Rules",
-     "- You are a team member, not the controller. Complete the current task yourself.",
-     "- Stay within your assigned role. Do not switch roles unless the task explicitly asks for cross-role analysis.",
-     "- Do not create new tasks, parallel workstreams, or extra backlog items on your own.",
-     "- Do not delegate the core work of your current task to another role.",
-     "- Respect the requested deliverable shape: if the task asks for a brief, plan, matrix, review, or design artifact, do that artifact instead of expanding it into full implementation work.",
-     "- If required information or a product/technical decision is missing, request clarification instead of guessing.",
-     "- Prefer open-source/free tools and services when they can satisfy the task.",
-     "- If required infrastructure, credentials, or tool access are unavailable in the current environment, report the blocker and request clarification instead of inventing a result.",
-     "- Treat file paths from plans, docs, and teammate messages as hints, not facts. Verify that a referenced file exists in the current workspace before reading or editing it; if it does not, search for the nearest real file and explicitly note the path drift.",
-     "- Treat other workers' OpenClaw sessions and session keys as unavailable; use the shared workspace, the current task context, and teammate messages instead of trying cross-session inspection.",
-     "- Do not mark a task completed or failed via progress updates. Finish by returning the deliverable or raising the blocking error so TeamClaw can close the task correctly.",
-      "- If only a commercial or proprietary option would unblock the task, ask the human for approval before assuming it is allowed.",
-      "- If follow-up work is needed, mention it in your result or use handoff/review tools for this current task only.",
-      `- Use exact TeamClaw role IDs when collaborating: ${TEAMCLAW_ROLE_IDS_TEXT}.`,
-      `- If a true follow-up is required after your deliverable, prefer these exact next roles: ${suggestedRoles}.`,
-      `- Default starter skills for this role: ${recommendedSkills}. If the task includes more specific recommended skills, prefer those.`,
-     ].join("\n");
+    buildRoleOperatingRules({
+      suggestedRoles: role.suggestedNextRoles,
+      recommendedSkills: role.recommendedSkills,
+    }),
+    buildWorkerMemoryContractRules(),
+  );
 }
 
 const ROLE_MAP = new Map<string, RoleDefinition>(ROLES.map((r) => [r.id, r]));
@@ -304,7 +305,7 @@ function buildRolePrompt(role: RoleDefinition, teamContext?: string): string {
   if (teamContext) {
     parts.push(`\nTeam Context:\n${teamContext}`);
   }
-  return parts.join("\n");
+  return composePrompt(...parts);
 }
 
 export { ROLES, ROLE_IDS, getRole, buildRolePrompt, normalizeRecommendedSkills, resolveRecommendedSkillsForRole };

package/src/state.ts

@@ -1,7 +1,12 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import os from "node:os";
-import type { TeamProvisioningState, TeamState, WorkerIdentity } from "./types.js";
+import type {
+  StartupProvisioningReadiness,
+  TeamProvisioningState,
+  TeamState,
+  WorkerIdentity,
+} from "./types.js";
 
 function resolvePluginStateDir(): string {
   const explicitStateDir = process.env.OPENCLAW_STATE_DIR?.trim();
@@ -22,6 +27,38 @@ function createEmptyProvisioningState(): TeamProvisioningState {
   };
 }
 
+function normalizeStartupReadiness(value: unknown): StartupProvisioningReadiness | undefined {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  const record = value as Record<string, unknown>;
+  const status = record.status === "checking" || record.status === "ready" || record.status === "degraded"
+    ? record.status
+    : undefined;
+  const startedAt = typeof record.startedAt === "number" ? record.startedAt : undefined;
+  const checkedAt = typeof record.checkedAt === "number" ? record.checkedAt : undefined;
+  const attempts = typeof record.attempts === "number" && record.attempts >= 0 ? Math.floor(record.attempts) : 0;
+  const requiredRoles = Array.isArray(record.requiredRoles)
+    ? record.requiredRoles.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const readyWorkerIds = Array.isArray(record.readyWorkerIds)
+    ? record.readyWorkerIds.filter((entry): entry is string => typeof entry === "string")
+    : [];
+  const message = typeof record.message === "string" && record.message.trim() ? record.message : undefined;
+  if (!status || startedAt === undefined || checkedAt === undefined) {
+    return undefined;
+  }
+  return {
+    status,
+    startedAt,
+    checkedAt,
+    attempts,
+    requiredRoles,
+    readyWorkerIds,
+    message,
+  };
+}
+
 async function ensureDir(dir: string): Promise<void> {
   await fs.mkdir(dir, { recursive: true });
 }
@@ -58,6 +95,7 @@ async function loadTeamState(teamName: string): Promise<TeamState | null> {
     if (!parsed.provisioning.workers || typeof parsed.provisioning.workers !== "object") {
       parsed.provisioning.workers = {};
     }
+    parsed.provisioning.startupReadiness = normalizeStartupReadiness(parsed.provisioning.startupReadiness);
     return parsed;
   } catch {
     return null;
@@ -74,6 +112,7 @@ async function saveTeamState(state: TeamState): Promise<void> {
   state.provisioning.workers = state.provisioning.workers && typeof state.provisioning.workers === "object"
     ? state.provisioning.workers
     : {};
+  state.provisioning.startupReadiness = normalizeStartupReadiness(state.provisioning.startupReadiness);
   state.controllerRuns = state.controllerRuns && typeof state.controllerRuns === "object"
     ? state.controllerRuns
     : {};