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).