docs: explain prompt construction pipeline (heartbeat, cron, subagents)

[TerrysPOV]

Problem

Multiple users have reported confusion about how ClaudeClaw constructs the final prompt sent to Claude — specifically: how CLAUDE.md, USER.md, job frontmatter, and prompt templates combine, and why templates load from the plugin package rather than from the project directory.

This is one of the most-requested documentation improvements in the Mega-Post (#14).

What's needed

A docs/PROMPT_PIPELINE.md (or section in the README) covering:

1. Prompt composition order — what gets prepended, appended, and in what order for each invocation type (heartbeat, cron job, Telegram message, Discord message, subagent)
2. Template loading — which templates come from the plugin package vs. the project directory, and how to override them
3. CLAUDE.md discovery — when and how CLAUDE.md is loaded; how --append-system-prompt interacts with it
4. A flowchart — visual diagram of a single heartbeat invocation from trigger to Claude receiving the prompt

This is the single most-requested documentation item, mentioned by @christian-drescher, @miraculix95, and @m13v.

Source

#14 (Mega-Post), multiple comments.