commandkit/docs/roadmap/03-backend.md

# CommandKit backend planning record

Status: initial Cobra/pflag backend implemented.

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

## Authority and current owners

[ADR 0002](../adr/0002-cobra-backend.md) records the backend selection and rationale;
[ADR 0003](../adr/0003-public-facade.md) records its isolation behind the public
facade. The [architecture policy](../policy/architecture.md) owns boundaries.

Cobra/pflag dependencies, the internal adapter, routing/parsing, generated help,
and invocation integration are implemented. Selected dependency versions belong
in [go.mod](../../go.mod); license and notice entries belong in
[attribution](../oss/attribution.md). The former dependency-selection and
adapter-construction tasks are complete.

Current mechanics belong in the [internal overview](../internal/overview.md),
with adapter contracts and implementation in
[internal/cobra](../../internal/cobra/parse.go). The root owns registration,
typed input preparation, invocation coordination, standard handlers, and reports.
The [CLI reference](../cli.md) owns observable syntax and presentation.

## Completed adaptation and evidence

The initial implementation translated registered metadata through a neutral
bridge, rebuilt backend state for each invocation, and adapted backend routing,
local flags, operands, presence, help, and syntax failures to selected semantics.
The [completed initial implementation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/3871d837489b9955998b362587a52b47282dc021/docs/roadmap/implementation.md)
records these stages and their checks.

The earlier discussion of rejecting repeated singletons was superseded by the
accepted last-occurrence rule in [ADR 0006](../adr/0006-command-grammar.md).
Detailed conversion, repetition, and terminator behavior belongs in
[registered command syntax](../cli.md#registered-command-syntax).

The delivered integrations expose native ConfigKit/PromptKit reports through the
root, as recorded in the [feature target](initial.md). Backend selection creates
no parallel configuration engine or public backend-specific provider contract.
Completed parsing/help, provider integration, attribution, and evidence tasks
have been retired from this roadmap.

## Future maintenance and adoption

A later backend replacement remains a maintenance possibility governed by the
accepted public/CLI boundary and [release policy](../policy/release.md). A second
backend or generalized selection framework is outside the initial delivery.

Application migrations and updates to their documentation/subprocess consumers
remain separate work. They can use the [consumer guide](../consumers/guide.md)
and maintained examples; this record does not claim migration completion.
Other deferred capabilities remain in the
[feature roadmap](initial.md#explicit-deferrals).