commandkit/docs/roadmap/04-facade.md

# CommandKit facade planning record

Status: initial public facade and internal adapter implemented.

Original planning: 2026-10-06. Reconciled: 2026-10-07.

## Authority and current owners

[ADR 0003](../adr/0003-public-facade.md) owns the facade/adapter decision and its
rationale. The [architecture policy](../policy/architecture.md) owns normative
dependency and public-surface boundaries.

Root public declarations, private implementation state, and the internal
Cobra/pflag adapter exist. Exact contracts belong in Go declarations and GoDoc;
the [consumer guide](../consumers/guide.md) explains their use. The
[internal overview](../internal/overview.md) owns the actual package inventory,
and [go.mod](../../go.mod) owns dependency versions.

The [initial target](initial.md) and [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
record the chosen layout and delivered API work. The initial implementation
requires no further facade package construction.

## Retired package exploration

Early illustrations considered an `internal/engine` for registration and
coordination and an `internal/command` for shared declarations, with a root
limited mainly to forwarding. Those were possible layouts, not required
packages, and are superseded as active implementation targets.

The selected root contains straightforward private implementation alongside its
public contracts; the internal adapter isolates backend machinery. Consult the
internal overview for current responsibilities instead of treating the early
package table as an inventory or expansion checklist.

## Completed boundary work

The initial work established root-owned public named types and handles, selected
integration dependencies, typed callback/value semantics, backend-neutral bridge
metadata/results, and adaptation of backend-owned failures. API design,
package-selection, and initial documentation tasks are complete.

The completed plan records review of public declarations and dependency direction,
plus consumer behavior through the real adapter. Earlier suggestions to adopt
ConfigKit/ReleaseKit-style automated export scanners were validation possibilities,
not a requirement to add a checker. Future automation remains a maintenance
choice under the [testing policy](../policy/testing.md) when its protection
justifies its cost.

## Future backend replacement

A later replacement remains possible behind the accepted boundary. It must
preserve the public API and selected CLI behavior or follow the
[release policy](../policy/release.md) for deliberate incompatible changes.
Signature isolation alone does not prove behavioral compatibility; parsing,
help, diagnostic delivery, reports, and outcomes remain relevant to that review.
Replacement and public backend selection are outside the initial delivered scope.