ADR 0003: Managed Shell Contract

Status: current Last reviewed: 2026-06-20 Superseded by: none Accepted: 2026-05-21

Context

Fish, PowerShell, and Bash need predictable startup behavior without repeated live initialization of every tool. Local overrides must remain possible and must run after managed configuration.

Decision

Managed shell profiles contain small repo-owned startup hooks. Those hooks source cached generated shell fragments when present, fail soft, stay quiet, perform no installs or package-manager work during normal startup, and source local overrides last. The first managed shells are PowerShell 7, Fish, and Bash fallback.

Consequences

• Normal startup should not repeatedly call live starship init, atuin init, zoxide init, mise activate, or completion generators when caches are valid.
• Cache refresh and diagnostics belong to repo-maintained helper scripts and validation, not ad hoc profile glue.
• Changing this contract is a decision gate.

Alternatives considered

• Keep independent per-tool snippets in each shell. That is simple locally, but it makes ordering, cache invalidation, timings, and duplicate initialization harder to reason about.
• Revive ShellKit as the shell runtime helper. That remains parked until current pain points justify a new implementation decision.

Follow-up work

• Keep cache refresh helpers small and covered by source-only smoke validation.
• Revisit a shell runtime coordinator only through a new current decision.