ADR 0004: Two-Binary ShellKit Architecture

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 removed ShellKit Rust architecture. ShellKit is parked and this two-binary design is not current repo direction.

Context

Shell startup has a strict latency and failure budget, while machine/bootstrap orchestration can be slower and more featureful. A single broad binary in the startup path would couple those concerns.

Decision

Use one Rust workspace with separate binaries:

• shellkit: full CLI for planning, applying, updating, diagnostics, tools, config, and agent workflow integration.
• shellkit-shim: tiny runtime helper for shell startup and cache repair.

Normal shell startup must not invoke the full machine orchestrator.

Consequences

• Runtime code stays small enough for startup-sensitive paths.
• Machine/bootstrap orchestration can grow without taxing every interactive shell launch.
• Changing the two-binary architecture is a decision gate.

Alternatives considered

• Single ShellKit binary for everything. That is simpler initially, but it risks pulling heavy dependencies into shell startup.
• Shell-only implementation. That avoids Rust bootstrap work, but it keeps timeout handling, process-tree cleanup, diagnostics, and cross-shell behavior fragmented.

Follow-up work

• Scaffold the Rust workspace and add both binary targets.
• Keep profile integration out of the first scaffold commit.