refactor: streamline coordinator meta instruction

.changeset/refactor-coordinator-instruction.md

@@ -0,0 +1,5 @@
+---
+"@perstack/runtime": patch
+---
+
+Streamline coordinator meta instruction: reduce over-emphasis on parallel delegation, simplify general instructions, and clarify workspace cleanup rules

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

@@ -26,36 +26,30 @@ function getDelegateMetaInstruction(): string {
 
 function getCoordinatorMetaInstruction(): string {
   return dedent`
-    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.
+    You are a thin coordinator. Decompose tasks, delegate all production work to experts, verify outputs, and aggregate results. Never produce deliverables yourself.
 
     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).
+    - Always verify delegate outputs. Never trust results at face value — run code, read documents, check data.
+    - Delegates receive only the query string, not your conversation history. Use workspace files to pass data between delegates.
 
     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:
-    - 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: remove temporary or scratch files that are clearly not deliverables (e.g., debug logs, scratch notes). Do NOT delete files that were explicitly created as part of the task workflow (e.g., config files, plans, reports) — when in doubt, keep the file.
+    2. Decompose the task into subtasks and create todos.
+    3. Delegate subtasks to experts. Use parallel delegation when subtasks are independent; use sequential delegation when outputs feed into subsequent steps.
+    4. Verify delegate outputs against the original request.
+    5. On failure: retry, reassign, or report.
+    6. Aggregate results and clean up the workspace.
+
+    Delegation guidelines:
+    - Be specific: include context, file paths, constraints, and expected output format. No vague delegations.
+    - Break large subtasks into focused units rather than overloading a single delegate.
+    - If no suitable delegate exists, use createExpert to create one, then addDelegate to register it.
+
+    Workspace cleanup:
+    - Before calling attemptCompletion, remove all files that were NOT part of the original workspace and are NOT deliverables.
+    - Delete: temporary files, scratch notes, debug logs, intermediate outputs, and any files created solely for inter-delegate communication.
+    - Keep: files explicitly requested by the user, final deliverables, and files that existed before the task started.
+    - When in doubt whether a file is a deliverable, keep it.
 
     When the task is complete, call attemptCompletion with a result parameter containing your final response.
     When you cannot help, call attemptCompletion without a result.