ADR 0002: ShellKit Runtime Coordinator First

Status: parked Last reviewed: 2026-06-20 Superseded by: DECISIONS.md#parked-shellkit-direction Accepted: 2026-05-21

This ADR is a historical record for the parked ShellKit direction. It does not authorize rebuilding ShellKit or making it the active runtime path.

Context

Shell startup currently coordinates several external tools through shell-specific snippets. Fish and PowerShell already have cache-generation prototypes, while Bash still performs more live initialization. The next strategic step is to make runtime orchestration explicit before broader machine bootstrap work.

Decision

Build ShellKit's shell runtime coordinator first. It coordinates Starship, Atuin, zoxide, mise, Scoop/PATH handling, PSReadLine, shell completions, cache freshness, startup timing, duplicate-init prevention, diagnostics, and local override ordering. It does not replace those tools.

Consequences

• Runtime status, refresh, doctor, timings, and path diagnostics are the first ShellKit command surface.
• Bootstrap, desktop app orchestration, and broad machine updates remain important but secondary.
• Existing Fish and PowerShell cache helpers are source material for ShellKit, not final architecture.

Alternatives considered

• Rewrite bootstrap first. That leaves the daily shell startup problems unsolved and expands scope too early.
• Replace Starship, Atuin, zoxide, or mise. Those tools remain better as focused dependencies; ShellKit should orchestrate them.

Follow-up work

• Create the Rust workspace with shellkit and shellkit-shim binaries.
• Implement shellkit shell status and shellkit shell doctor before changing managed profiles.