docs: add system prompt extensions, include original, and specifics file
linuztx committed
Mar 22, 2026 at 20:40 UTC
add0546508c343107dfb5bdf02aa34e477b53dc3
2 files changed
+28
-5
docs/developer/architecture.md
+16
-3
@@ -227,14 +227,27 @@ The `prompts` directory contains various Markdown files that control agent behav
227
#### Prompt Inheritance with `{{include original}}`
228
When overriding a prompt, you can extend the original instead of replacing it entirely. Use `{{include original}}` to pull in the default version and add your changes on top:
229
230
+**Example:** `agents/developer/prompts/agent.system.main.communication.md`:
231
```markdown
232
{{include original}}
233
233
-## Additional instructions
234
-- my custom additions here
234
+- always explain your reasoning
235
+- include code snippets in responses
236
```
237
237
-This keeps overrides small and ensures they stay in sync when the default prompt is updated.
238
+This finds `agent.system.main.communication.md` in the next directory up the hierarchy → includes the default from `prompts/` → appends the additions. Result:
239
+
240
+```markdown
241
+## Communication
242
+- be concise
243
+- use markdown formatting
244
+- ask clarifying questions when unsure
245
+
246
+- always explain your reasoning
247
+- include code snippets in responses
248
+```
249
+
250
+Overrides stay small and automatically inherit any future changes to the default.
251
252
#### Dynamic Behavior System
253
- **Behavior Adjustment**:
docs/developer/extensions.md
+12
-2
@@ -225,9 +225,19 @@ When overriding a prompt file, you can **extend** the original instead of replac
225
- include code snippets in responses
226
```
227
228
-This includes the default `prompts/agent.system.main.communication.md` first, then appends the developer-specific additions. If the default file changes later, the override automatically inherits the changes.
228
+This resolves to: find `agent.system.main.communication.md` in the next directory up the hierarchy → finds the default in `prompts/` → includes it. Result:
229
230
-Works at any level of the hierarchy — if multiple overrides each use `{{include original}}`, they chain together from highest to lowest priority.
230
+```markdown
231
+## Communication
232
+- be concise
233
+- use markdown formatting
234
+- ask clarifying questions when unsure
235
+
236
+- always explain your reasoning
237
+- include code snippets in responses
238
+```
239
+
240
+The override stays small and automatically inherits any future changes to the default file. Works at any level of the hierarchy — if multiple overrides each use `{{include original}}`, they chain together from highest to lowest priority.
241
242
##### Agent Specifics File
243
The default `agent.system.main.md` includes `agent.system.main.specifics.md` — an empty file by default. Subagent profiles can override just this file to add profile-specific instructions without touching role, communication, or other sections.