commandkit/docs/roadmap/modules.md

# Optional integration modules

Status: module boundary accepted in ADR 0010; implementation planning remains
in progress and no module extraction has begun.

## Purpose and authority

Make CommandKit useful to consumers that use both ConfigKit and PromptKit,
ConfigKit alone, or neither library. Consumers using only CommandKit's core
should acquire neither ConfigKit nor PromptKit through CommandKit's package or
module dependencies. ConfigKit-only consumers should not acquire PromptKit.

This roadmap records the targeted end state, selected module layout, and
migration work. Recommendations under [Open Decisions](#open-decisions) remain
proposals. It does not describe these changes as implemented.
[ADR 0010](../adr/0010-optional-integration-modules.md) owns the accepted module
boundary and convenient registration principles; it partially supersedes
[ADR 0003](../adr/0003-public-facade.md), whose remaining principles still apply.
Alignment of the [architecture policy](../policy/architecture.md) remains part of
the work below. GoDoc, the [CLI reference](../cli.md), and the
[consumer guide](../consumers/guide.md) describe the prototype baseline; they do
not make its incidental API shapes compatibility requirements for this sprint.

## Organizing principle: design the final API

CommandKit is an unreleased prototype with no downstream consumers. Give the
existing implementation zero deference when selecting the final API. The goal is
the best, simplest, most coherent API for the accepted responsibilities and
representative consumers, not the smallest diff or a mechanically relocated
prototype. Accepted architectural decisions and explicitly selected behavior
remain requirements; prototype declarations, helpers, bookkeeping, and tests do
not independently establish contracts.

Complete the transition in one sprint. No backward-compatibility wrappers,
deprecation period, or migration bridge is needed. Intermediate commits need not
build or pass tests; do not add temporary machinery merely to make them do so.
Validate the complete target state before release. Reuse existing code where it
serves that design, and refactor, replace, or remove it where it does not.

## Current baseline

At the start of this roadmap, CommandKit has one Go module and one supported
public root package. It requires ConfigKit v0.5.0 and PromptKit v0.12.0 and
declares Go 1.26.0. Its internal Cobra adapter implements routing and parsing.

The root combines core command infrastructure with configuration and PromptKit
inspection. Coupling extends beyond constructors:

- `NewConfigKitScope` accepts ConfigKit results and maps their diagnostics.
- Core `Diagnostic.Severity` currently uses ConfigKit's public severity type;
  moving inspection handlers alone will not remove that dependency.
- `SourceReader` returns ConfigKit source records; `ExplanationReader` accepts
  ConfigKit paths and returns ConfigKit explanations.
- `PromptKitSuite` callbacks return PromptKit inspection types.
- `NewPromptKitScope` adapts engine configuration into the configuration suite.
- Standard handlers share root-private helpers and state. For example,
  configuration registration accesses the application's registry and records
  whether the suite has already been installed.

The [internal overview](../internal/overview.md) describes the implemented
inventory. The maintained examples and integration tests currently belong to the
root module. ReleaseKit v0.3.0 is also selected there as a Go tool dependency;
the [release procedure](../release.md) assumes one module and one version tag.

Optional command registration currently controls behavior, not dependencies.
Moving integration code into packages sharing the root `go.mod` would separate
compiled imports but retain integration requirements in the module graph.
Go's [module graph rules](https://go.dev/ref/mod#module-graph-pruning) explain
that distinction.

## Targeted end state

Provide three consumer modules in this repository with dependencies directed
toward the core. Keep the core at `gitea.maximumdirect.net/eric/CommandKit` and
give each integration its own `go.mod`:

| Directory | Module path | Package name |
| --- | --- | --- |
| Repository root | `gitea.maximumdirect.net/eric/CommandKit` | `commandkit` |
| `integrations/ckconfig` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig` | `ckconfig` |
| `integrations/ckprompt` | `gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt` | `ckprompt` |

The `integrations/` grouping keeps optional modules together as their number
grows; the anticipated three to ten integrations are planning context, not a
limit or delivery commitment. Distinct package names avoid requiring local
aliases when these integrations are imported alongside ConfigKit and PromptKit.
Separate module files establish dependency isolation; directory naming alone
does not. The shared repository requires explicit multi-module testing and
publication orchestration.

| Module | Responsibility | Integration dependencies |
| --- | --- | --- |
| Core | Application construction, command/group registration, typed bindings, dispatch, help/version, common grammar, outcomes, and diagnostics | Neither ConfigKit nor PromptKit |
| ConfigKit integration | Standard configuration family, scope composition, reports, and ConfigKit adapters | Core and ConfigKit; no PromptKit |
| PromptKit integration | Named prompt/profile inspection and the PromptKit configuration-scope adapter | Core, PromptKit, and the ConfigKit integration |

The core remains an opinionated command library with its existing internal
Cobra boundary. The dependency goal is independence from ConfigKit and PromptKit,
not a standard-library-only implementation.

Integrations remain maintained parts of CommandKit. They install commands into
the same application through supported public core operations and follow its
grammar, help, invocation, and outcome conventions. Applications retain domain
commands, acquisition, runtime construction, streams, and process exit.

The selected configuration boundary moves the existing ConfigKit-shaped
contracts with their handlers into the ConfigKit integration. Only ConfigKit
support is needed for now; a generic configuration interface is outside this
migration. The PromptKit integration may depend on the ConfigKit integration,
consistent with PromptKit's own ConfigKit dependency. Document that relationship
in consumer guidance: `ckprompt` depends on `ckconfig`.

This boundary preserves one configuration suite into which
applications compose `app`, `promptkit`, and other supported scopes. PromptKit
configuration inspection and named-definition inspection remain independently
selectable. A module dependency does not automatically install a command family.

Core public signatures and implementation imports contain no ConfigKit or
PromptKit types. Integration-specific types and helpers move to their owning
modules. Do not retain root forwarding wrappers that restore those imports.
Shared helpers stay private unless a concrete cross-module interaction needs a
supported contract; extraction is not a reason to expose every existing helper.

Preserve explicitly selected operator behavior: command vocabulary, selection
and scope semantics, native reports, diagnostics, error identity, outcomes, and
help without provider acquisition. Identify and decide any changes to selected
CLI behavior separately. Do not preserve accidental prototype behavior or Go API
shapes merely because they already exist.

### Selected API and release principles

- Design convenient integration registration around representative consumers.
  Reuse public command/group registration when it fits the final design. Add a
  narrow core capability only where a concrete responsibility requires it; do
  not introduce a general family framework or preserve private bookkeeping for
  its own sake. Exact signatures remain implementation-planning work.
- Core diagnostics use a small CommandKit-owned severity type. Upstream
  diagnostic conversion belongs in the integrations, preserving selected
  classification, delivery, and error semantics without copying ConfigKit's
  wider data model into the core.
- Version the modules independently according to their own changes and the
  [release policy](../policy/release.md#versioning-and-compatibility). Do not
  require integration version numbers to match either the core or upstream
  dependency versions. Record selected dependencies in `go.mod` and explain
  relevant upstream adoption in module release notes. Coordinate publication
  when changes span modules; independent versions do not imply an exhaustive
  compatibility matrix.

## Work sequence

### 1. Align policy and settle implementation boundaries

Completed: ADR 0010 is accepted and ADR 0003 is marked partially superseded,
with its decision text preserved. The partial status follows the explicitly
authorized exception to the documentation policy for this decision.

- Resolve the remaining choices under Open Decisions before moving public
  symbols, using the selected module paths and package names above.
- Align the architecture policy with ADR 0010 and review other
  ADRs for affected ownership statements without reopening unrelated decisions.
- Inventory root exports, imports, private helper use, and family registration
  behavior. Use the inventory as evidence of responsibilities and coupling, not
  as a list of APIs to preserve. Select final exports and ownership from consumer
  needs; no compatibility mapping for the unpublished prototype is required.
- Sketch three representative consumers: core only, ConfigKit only, and both
  libraries. Confirm that combined configuration scopes remain straightforward
  and that registration meets ADR 0010's convenience principle without replacing
  removed boilerplate with new plumbing. Use these examples to evaluate the
  registration API; no fixed call count or particular options pattern is selected.

Completion: the dependency direction, final API, and registration approach
are concrete enough to implement without inventing a general plugin framework.

### 2. Extract the integrations and isolate the core

- Establish the selected module layout, preserving the existing root import
  path for the core.
- Move configuration declarations, registration, handlers, reports, and
  ConfigKit adapters together. Move PromptKit declarations, handlers, reports,
  and its configuration-scope adapter into the PromptKit integration.
- Replace access to root-private registry state and helpers with the smallest
  supported interactions needed by those integrations. Preserve duplicate
  registration handling and standard-family ownership; audit these boundaries
  rather than assuming package relocation preserves them automatically.
- Design core outcomes, diagnostics, bindings, and command declarations as shared
  contracts for the final API. Replace ConfigKit severity in core diagnostics
  with the selected CommandKit-owned type. Place report encoding and upstream
  diagnostic conversion with their owners. Remove redundant prototype state and
  helpers; avoid copying ConfigKit's data model merely to remove imports.
- Remove integration dependencies from the core module, including dependencies
  reintroduced by its tests, examples, tools, or remaining public declarations.
  Review tool dependencies for that specific objective; broad removal of all
  maintainer dependencies is not a prerequisite.
- Use released inter-module requirements for consumer builds. Local workspace
  composition may support development, but published modules must not depend
  on sibling checkouts or consumer-applied `replace` directives.

Completion: core-only and ConfigKit-only consumers have the intended dependency
boundaries, while the composed consumer retains the existing standard commands.

### 3. Move examples and validate the consumer boundaries

- Keep a genuine core-only example with no configuration-library imports. Place
  ConfigKit and composed examples, fixtures, and integration tests in modules
  that can legitimately depend on those integrations. Choose their exact home
  with the module layout; examples in the root module must not defeat isolation.
- Move or rewrite existing tests for their final owners and selected contracts.
  Remove assertions that merely freeze incidental prototype design. Retain
  coverage for typed presence, repeated invocations, registration collisions,
  provider errors, report delivery, and selected CLI behavior without duplicating
  every suite.
- Add focused consumer checks for the three adoption paths. Verify both package
  dependencies and the selected module graph, including transitive requirements.
  Core-only checks exclude both libraries; ConfigKit-only checks exclude
  PromptKit. Merely observing a smaller executable is insufficient.
- Exercise combined `app` and `promptkit` configuration scopes and independent
  installation of named PromptKit inspection through public APIs.
- Run each module's relevant suite. Verify ordinary module consumption with
  workspace mode disabled so local workspace resolution cannot hide missing
  requirements. Root `go test ./...` alone will not cover nested modules.

Completion: representative public consumers demonstrate isolation and retained
composition. These checks protect the selected boundary without requiring an
exhaustive matrix of historical dependency versions.

### 4. Prepare final API documentation and initial module releases

- Update GoDoc, the consumer guide, maintained examples, README, internal
  inventory, and contributor reading guide as the implementation lands. Keep
  the CLI reference unchanged except where actual behavior or relevant ownership
  changes require an update. Link this roadmap from contributor navigation when
  integrating it into the implementation workflow.
- Document final imports, constructors, and optional module selection directly.
  Rewrite prototype guidance where necessary rather than publishing a downstream
  migration guide. Prepare initial module versions and notes under the
  [release policy](../policy/release.md); unpublished prototype API changes do
  not require a compatibility release or a version bump solely for relocation.
- Adapt release profiles, module discovery, validation, note locations, version
  reporting, and publication commands to the selected release model. Verify
  ReleaseKit's supported capabilities before choosing the mechanics; the current
  single-module profile is not evidence of multi-module support.
- For nested modules, use Go's module-subdirectory tag prefixes and make
  release-note paths and immutable links unambiguous. Review licensing and
  attribution visibility in each distributed module under the
  [OSS policy](../policy/oss.md).
- Establish publication order from module dependencies and record compatible
  requirements explicitly. Published consumers must resolve actual released
  versions. A local workspace is not a substitute for that release sequence.
  Preserve the existing successful-source-publication completion model.

Completion: every consumer module can be released and consumed independently of
local workspace state, with documentation of the final public API and optional
integration choices.

## Scope and follow-up

This work changes packaging and integration boundaries. It does not select a
new backend, concurrent-dispatch contract, dynamic plugin system, or replacement
configuration engine. It does not lower the existing Go minimum.

Keep the PromptKit v0.13.0 and ConfigKit v0.6.0 adoption identifiable as a separate
change after extraction unless an implementation dependency justifies combining
them. Catalogs and requirement discovery are subsequent integration features.
Semantic comparison retains the upstream-contract dependency recorded in
[deferred work](deferred.md). None is needed to demonstrate module isolation.

## Open Decisions

### Exact registration API

The design principle is selected: convenient registration through the simplest
coherent public core contracts, without preserving the prototype. Exact
signatures and any additional core capability remain to be settled through the
three representative consumer sketches and an ownership/collision review.

**Recommendation:** integrations construct their standard groups and install them
through ordinary public registration, adding a narrow capability only if the
selected ownership or atomicity behavior cannot be expressed coherently. Remove
redundant private flags and checks rather than reproducing them publicly.

**Alternative:** an explicit public family declaration and installation API can
represent ownership and collision handling if command groups cannot adequately
express those responsibilities. It adds a lasting abstraction, so select it only
for a demonstrated consumer or core responsibility, not to imitate current state.

### Multi-module release mechanics

Independent versioning is selected. Exact release tooling and per-module note
locations still require investigation of ReleaseKit's supported capabilities.
This is release-workflow design work, not a reason to retain the combined module.

**Recommendation:** reuse shared publication machinery with explicit module
selection, module-specific versions and notes, and the appropriate tag prefixes.
Validate the selected candidate and publish in dependency order as required by
actual module requirements. Keep the successful source-publication completion
model and avoid duplicate validation of an unchanged final candidate.

**Alternative:** maintain separate per-module release entry points or profiles
using ReleaseKit's supported mechanisms. This may be simpler if ReleaseKit is
intrinsically single-module, but risks duplicated guards and inconsistent
procedures. Verify its capabilities before selecting exact commands; neither
approach requires matching module versions or a new general release framework.