agent-afk 1.15.0 → 1.21.0

package/README.md

@@ -11,7 +11,7 @@
 - 🔌 **Plugin skill-router** — skills under `~/.afk/plugins/*/skills/` auto-exposed as slash commands
 - 🏠 **AFK-scoped config** — `~/.afk/` independent of `~/.claude/`, with `afk plugin install/update/list/remove`
 - 💬 **Three surfaces** — interactive REPL, daemon, Telegram bot sharing one session manager
-- 📊 **Routing telemetry** — every subagent dispatch appended to `~/.claude/agent-framework/routing-decisions.jsonl`
+- 📊 **Routing telemetry** — every subagent dispatch appended to `~/.afk/agent-framework/routing-decisions.jsonl`
 - 🤖 **Multiple Claude models** — Opus, Sonnet, Haiku
 - 🔓 **Bypass permissions mode** — no prompts, fully automated tool execution
 - 🛡️ **Type-safe** — TypeScript strict mode
@@ -200,7 +200,7 @@ pnpm telegram:restart
 
 ## Orchestration Skills
 
-agent-afk ships seven built-in subagent orchestrators plus `devils-advocate` (in development). These are **skill-router-dispatched**: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a skill handler under `src/skills/<name>/`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.claude/agent-framework/routing-decisions.jsonl`.
+agent-afk ships seven built-in subagent orchestrators plus `devils-advocate` (in development). These are **skill-router-dispatched**: typing `/mint add dark mode` in the REPL parses the slash form, resolves it to a skill handler under `src/skills/<name>/`, and dispatches a fresh subagent via `SubagentManager.forkSubagent()`. Every dispatch is logged to `~/.afk/agent-framework/routing-decisions.jsonl`.
 
 | Skill | Purpose |
 |---|---|
@@ -304,6 +304,24 @@ AFK_PROMPT_CACHE_TTL=1h            # 5m | 1h (default 1h)
 NO_COLOR=
 ```
 
+### System Prompt Auto-Discovery
+
+agent-afk resolves the session system prompt through a 4-tier precedence chain (highest tier wins):
+
+| Tier | Source | Notes |
+|------|--------|-------|
+| 1 | `AFK_SYSTEM_PROMPT` env var | Highest priority — overrides everything |
+| 2 | `afk.config.json` (`systemPrompt` field) | Searched in: `<cwd>/afk.config.json` → `~/.afk/config/afk.config.json` → legacy `~/.afk.config.json` |
+| 3 | `AFK.md` file | Searched in: `<cwd>/AFK.md` → `$AFK_HOME/AFK.md` (default `~/.afk/AFK.md`) |
+| 4 | None | `systemPrompt` is `undefined`; SDK uses its default behavior |
+
+**AFK.md format:** Plain Markdown, no frontmatter. The entire file content (trimmed) becomes the system prompt. Empty or whitespace-only files are treated as absent (tier 4 applies instead).
+
+**Provenance tracking:** When using `--dump-prompt`, the `systemPromptSource` field in the dump shows which tier won:
+- `"env:AFK_SYSTEM_PROMPT"` — tier 1
+- `"file:/abs/path/afk.config.json"` — tier 2
+- `"afk-md:/abs/path/AFK.md"` — tier 3
+
 ### Prompt Caching (anthropic-direct provider)
 
 The `anthropic-direct` provider stamps two `cache_control` breakpoints per request — one at the end of `system` (which implicitly caches `tools + system` together) and one at the end of the last `messages[]` entry. The end-of-messages marker floats forward each turn; cache lookup walks back over prefix-hash matches up to a 20-block window, so the moving marker still hits prior cache writes within a tool-use loop and across consecutive turns.