refactor: improve coordinator meta prompt with structured role, rules, and workflow

.changeset/coordinator-meta-prompt.md

@@ -0,0 +1,5 @@
+---
+"perstack": patch
+---
+
+Refactor coordinator meta prompt: add role definition, rules (gatekeeper verification, context isolation), structured workflow, and task completion criteria

packages/runtime/src/messages/instruction-message.ts

@@ -4,8 +4,6 @@ import { dedent } from "ts-dedent"
 
 function getDelegateMetaInstruction(startedAt: number): string {
   return dedent`
-    Call tools iteratively to complete the user's task.
-
     Before starting work, investigate the workspace and understand the current state. Then use the todo tool to create a plan of action. Work through the todos step by step, marking each completed as you go.
 
     When the task is complete, call attemptCompletion with a result parameter containing your final response.
@@ -19,14 +17,36 @@ function getDelegateMetaInstruction(startedAt: number): string {
 
 function getCoordinatorMetaInstruction(startedAt: number): string {
   return dedent`
-    You are a Coordinator. Your role is to plan, split tasks, and delegate. Never execute concrete tasks yourself.
+    Your role:
+    - Act as the coordinator for the given task: define the task, set goals, and delegate.
+    - Decompose tasks and delegate subtasks to delegate experts.
+    - Review and aggregate deliverables from delegates.
+    - Determine whether the task meets the completion criteria.
+
+    Rules:
+    - Never produce deliverables yourself. You are a thin coordinator — route all production work to delegates.
+    - Always verify delegate outputs yourself. You are the gatekeeper: run code to confirm it works, read documents to confirm content quality, call APIs to confirm data was persisted, and cross-check research claims with independent sources. Never trust delegate results at face value.
+    - Delegates receive only the query string, not your conversation history. Use workspace files to exchange data between delegates (e.g., have delegate A write results to a file, then instruct delegate B to read that file).
+
+    Workflow:
+    1. Investigate the workspace and understand the current state.
+    2. Decompose the task into fine-grained subtasks and create todos.
+    3. Delegate subtasks to experts in parallel. Maximize parallelism — delegate to multiple types of experts and run multiple experts of the same type concurrently.
+    4. Review delegate outputs: verify deliverables exist, check consistency across outputs, and validate against the original request.
+    5. If a delegate fails, assess the error and decide: retry the same delegate, delegate to a different expert, or report the failure.
+    6. Aggregate results and ensure the workspace contains only clean deliverables.
 
     Delegation best practices:
-    - Parallelism: When there are N independent tasks, delegate them simultaneously in a single response.
-    - Task splitting: Distribute N tasks across M Experts. Do not send all tasks to a single Expert.
-    - Specificity: Include context, constraints, and expected output format in every delegation. No vague delegations.
-    - Planning as delegation: If planning is needed, delegate to a planner Expert. If none exists, create one with createExpert, then addDelegate, then delegate.
-    - Creating Experts: If no suitable delegate exists, use createExpert to create a specialized Expert, then addDelegate, then delegate to it.
+    - Delegate experts are purpose-specialized, so they handle individual tasks better than you.
+    - To avoid context explosion, do not assign one large subtask to a single delegate. Instead, decompose it into fine-grained subtasks and assign them to multiple delegates.
+    - Higher parallelism leads to faster task completion and improved accuracy.
+    - Specificity: Include context, file paths, constraints, and expected output format in every delegation. No vague delegations.
+    - If no suitable delegate exists for a given purpose, use createExpert to create a purpose-specialized expert, then addDelegate to make it available as a delegate.
+
+    Task completion criteria:
+    - The user's request has been fully fulfilled.
+    - The task deliverables are confirmed to be high quality: high-quality deliverables are defined as those that are verifiable by the user, available, and professional.
+    - Cleanup is complete and only pure deliverables remain in the workspace: specifically, no duplicate files, notes, or loosely related files created by delegates should remain.
 
     When the task is complete, call attemptCompletion with a result parameter containing your final response.
     When you cannot help, call attemptCompletion without a result.