From 724893ad5b5dc5164a2538881fdde52508230be8 Mon Sep 17 00:00:00 2001
From: Aron Prins <pwf.aron@gmail.com>
Date: Fri, 10 Apr 2026 14:22:48 +0200
Subject: [PATCH] fix claude instruction sibling path hint

---
 packages/adapters/claude-local/src/server/execute.ts | 6 +++++-
 server/src/__tests__/claude-local-execute.test.ts    | 5 ++++-
 2 files changed, 9 insertions(+), 2 deletions(-)

diff --git a/packages/adapters/claude-local/src/server/execute.ts b/packages/adapters/claude-local/src/server/execute.ts
index ae5ea3ab..7116be44 100644
--- a/packages/adapters/claude-local/src/server/execute.ts
+++ b/packages/adapters/claude-local/src/server/execute.ts
@@ -387,7 +387,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
     preparedInstructionsFile = true;
     try {
       const instructionsContent = await fs.readFile(instructionsFilePath, "utf-8");
-      const pathDirective = `\nThe above agent instructions were loaded from ${instructionsFilePath}. Resolve any relative file references from ${instructionsFileDir}.`;
+      const pathDirective =
+        `\nThe above agent instructions were loaded from ${instructionsFilePath}. ` +
+        `Resolve any relative file references from ${instructionsFileDir}. ` +
+        `This base directory is authoritative for sibling instruction files such as ` +
+        `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`;
       const combinedPath = path.join(skillsDir, "agent-instructions.md");
       await fs.writeFile(combinedPath, instructionsContent + pathDirective, "utf-8");
       effectiveInstructionsFilePath = combinedPath;
diff --git a/server/src/__tests__/claude-local-execute.test.ts b/server/src/__tests__/claude-local-execute.test.ts
index f40af034..f9516b82 100644
--- a/server/src/__tests__/claude-local-execute.test.ts
+++ b/server/src/__tests__/claude-local-execute.test.ts
@@ -320,7 +320,10 @@ describe("claude execute", () => {
       expect(captured[1]?.appendedSystemPromptFilePath).not.toBe(instructionsFile);
       expect(captured[1]?.appendedSystemPromptFileContents).toContain("# Agent instructions");
       expect(captured[1]?.appendedSystemPromptFileContents).toContain(
-        `The above agent instructions were loaded from ${instructionsFile}. Resolve any relative file references from ${path.dirname(instructionsFile)}/.`,
+        `The above agent instructions were loaded from ${instructionsFile}. ` +
+        `Resolve any relative file references from ${path.dirname(instructionsFile)}/. ` +
+        `This base directory is authoritative for sibling instruction files such as ` +
+        `./HEARTBEAT.md, ./SOUL.md, and ./TOOLS.md; do not resolve those from the parent agent directory.`,
       );
       expect(metaEvents).toHaveLength(2);
       expect(metaEvents[0]?.commandNotes).toHaveLength(0);