From 30a126f2bdab7e22d26e4e54e536cb97a3bfd46d Mon Sep 17 00:00:00 2001
From: Jian Zhang <tallshort@gmail.com>
Date: Wed, 14 Jan 2026 17:25:38 +0800
Subject: [PATCH] feat(coding-agent): add support for APPEND_SYSTEM.md to
 append instructions to system prompt (#716)

Co-authored-by: Jian Zhang <jzhang@yanhuangdata.com>
---
 packages/coding-agent/README.md   | 13 +++++++++++--
 packages/coding-agent/src/main.ts | 22 +++++++++++++++++++++-
 2 files changed, 32 insertions(+), 3 deletions(-)

diff --git a/packages/coding-agent/README.md b/packages/coding-agent/README.md
index fc8feb17..a6fdbffe 100644
--- a/packages/coding-agent/README.md
+++ b/packages/coding-agent/README.md
@@ -573,7 +573,7 @@ Use these for:
 
 ### Custom System Prompt
 
-Replace the default system prompt entirely by creating a `SYSTEM.md` file:
+Replace the default system prompt **entirely** by creating a `SYSTEM.md` file:
 
 1. **Project-local:** `.pi/SYSTEM.md` (takes precedence)
 2. **Global:** `~/.pi/agent/SYSTEM.md` (fallback)
@@ -589,7 +589,16 @@ Focus on:
 - Proper formatting
 ```
 
-The `--system-prompt` CLI flag overrides both files. Use `--append-system-prompt` to add to (rather than replace) the prompt.
+The `--system-prompt` CLI flag overrides both files.
+
+### Appending to the System Prompt
+
+To add instructions to the system prompt **without** replacing the default (preserving automatic loading of `AGENTS.md` context files, skills, and tools guidelines), create an `APPEND_SYSTEM.md` file:
+
+1. **Project-local:** `.pi/APPEND_SYSTEM.md` (takes precedence)
+2. **Global:** `~/.pi/agent/APPEND_SYSTEM.md` (fallback)
+
+The `--append-system-prompt` CLI flag overrides both files.
 
 ### Custom Models and Providers
 
diff --git a/packages/coding-agent/src/main.ts b/packages/coding-agent/src/main.ts
index b50a7e2b..1a37d49b 100644
--- a/packages/coding-agent/src/main.ts
+++ b/packages/coding-agent/src/main.ts
@@ -116,6 +116,23 @@ function discoverSystemPromptFile(): string | undefined {
 	return undefined;
 }
 
+/** Discover APPEND_SYSTEM.md file if no CLI append system prompt was provided */
+function discoverAppendSystemPromptFile(): string | undefined {
+	// Check project-local first: .pi/APPEND_SYSTEM.md
+	const projectPath = join(process.cwd(), CONFIG_DIR_NAME, "APPEND_SYSTEM.md");
+	if (existsSync(projectPath)) {
+		return projectPath;
+	}
+
+	// Fall back to global: ~/.pi/agent/APPEND_SYSTEM.md
+	const globalPath = join(getAgentDir(), "APPEND_SYSTEM.md");
+	if (existsSync(globalPath)) {
+		return globalPath;
+	}
+
+	return undefined;
+}
+
 function buildSessionOptions(
 	parsed: Args,
 	scopedModels: ScopedModel[],
@@ -128,8 +145,11 @@ function buildSessionOptions(
 
 	// Auto-discover SYSTEM.md if no CLI system prompt provided
 	const systemPromptSource = parsed.systemPrompt ?? discoverSystemPromptFile();
+	// Auto-discover APPEND_SYSTEM.md if no CLI append system prompt provided
+	const appendSystemPromptSource = parsed.appendSystemPrompt ?? discoverAppendSystemPromptFile();
+
 	const resolvedSystemPrompt = resolvePromptInput(systemPromptSource, "system prompt");
-	const resolvedAppendPrompt = resolvePromptInput(parsed.appendSystemPrompt, "append system prompt");
+	const resolvedAppendPrompt = resolvePromptInput(appendSystemPromptSource, "append system prompt");
 
 	if (sessionManager) {
 		options.sessionManager = sessionManager;