diff --git a/docs/decisions/0003-system-prompts-stay-user-directed.md b/docs/decisions/0003-system-prompts-stay-user-directed.md new file mode 100644 index 0000000..191c6ec --- /dev/null +++ b/docs/decisions/0003-system-prompts-stay-user-directed.md @@ -0,0 +1,43 @@ +# ADR 0003: Keep agent system prompts user-directed, not auto-generated from config + +- **Status:** Accepted +- **Date:** 2026-05-29 +- **Deciders:** didericis + +## Context + +A bottle already declares exactly what an agent can reach: egress routes +(allowlisted hosts + auth) and git config (remotes + identity). We +considered deriving an agent's system prompt — or a section of it — +automatically from those configs, so an agent would be told up front +what it has access to (e.g. "you can reach `gitea.dideric.is` over the +git remote and its API"). The question surfaced while hand-writing that +exact line into the `claude-implementer` prompt. + +## Decision + +System prompts stay **user-directed** — authored by the operator. We do +not auto-generate prompt content from a bottle's egress / git config. + +## Consequences + +- The operator controls what the agent is *told* about its environment, + independently of what the bottle *grants*. Sometimes we may want to + withhold that information from the agent directly — keep the prompt + silent about an allowlisted host even though egress permits it. +- The agent can still infer its access on its own (attempt a request, + read its env, `git remote -v`, the gitconfig), so auto-injection is a + convenience, not a capability the agent depends on. +- Cost accepted: operators must restate access in the prompt when they + want the agent to know it (as we did for the Gitea instance), and the + prompt can drift from the config. That decoupling of "what the bottle + grants" from "what the agent is told" is the point. +- Revisit if keeping prompts in sync with configs becomes a real pain. + An *opt-in* helper that emits a capability summary the operator + chooses to include would honor this decision; silent auto-injection + would not. + +## Links + +- ADR 0002 (`0002-agent-identity-claimed-not-vouched.md`) — related + agent-trust posture (what the agent is granted vs. what it can claim).