refactor: split InstructionMessage into multiple system message blocks

.changeset/split-instruction-message-blocks.md

@@ -0,0 +1,5 @@
+---
+"perstack": patch
+---
+
+Split InstructionMessage into multiple system message blocks for improved prompt clarity and per-block cache control

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

@@ -62,28 +62,25 @@ export function createInstructionMessage(expert: Expert, startedAt: number): Ins
     ? getCoordinatorMetaInstruction(startedAt)
     : getDelegateMetaInstruction(startedAt)
 
-  const instruction = dedent`
+  const preamble = dedent`
     You are Perstack, an AI expert that tackles tasks requested by users by utilizing all available tools.
 
     ${metaInstruction}
+  `
 
-    ---
-
-    ${expert.instruction}
+  const contents: InstructionMessage["contents"] = [
+    { id: createId(), type: "textPart", text: preamble },
+    { id: createId(), type: "textPart", text: expert.instruction },
+  ]
 
-    ---
+  const skillRules = getSkillRules(expert)
+  if (skillRules) {
+    contents.push({ id: createId(), type: "textPart", text: skillRules })
+  }
 
-    ${getSkillRules(expert)}
-  `
   return {
     type: "instructionMessage",
-    contents: [
-      {
-        id: createId(),
-        type: "textPart",
-        text: instruction,
-      },
-    ],
+    contents,
     id: createId(),
   }
 }