commandkit/docs/roadmap/initial-plan.md

# Preparing the initial CommandKit feature roadmap

Status: roadmap preparation and implementation-plan handoff complete.

Date: 2026-10-07.

The [feature roadmap](initial.md) records the selected initial target and its
completion. The [implementation plan](implementation.md) was prepared from that
review and has been executed. Checked entries below record the completed
preparation process; they are not assignments to restart planning.

## Historical preparation process

The checklist below was used to select the initial feature target and prepare an
ordered Luna implementation plan. Its instructions and suggested outline are
retained as planning history. Current public contracts belong in Go declarations
and GoDoc, operator behavior in the [CLI reference](../cli.md), and usage guidance
in the [consumer guide](../consumers/guide.md).

The [architecture policy](../policy/architecture.md) and accepted ADRs control
architectural choices. This document owns the preparation process; `initial.md`
owns the initial feature targets. Exact implemented contracts belong in
Go declarations, GoDoc, and the CLI reference under the
[documentation policy](../policy/documentation.md).

## 1. Establish authoritative requirements

- [x] Review all nine accepted ADRs and the architecture policy.
- [x] Build a requirements checklist linking each requirement to its authority.
- [x] Review the four numbered roadmaps as evidence and design proposals:
  [CLI plan](01-cli-plan.md), [dispatcher](02-dispatch.md),
  [backend](03-backend.md), and [facade](04-facade.md).
- [x] Identify conflicts with accepted decisions and carry the controlling choice
  into the new roadmap.
- [x] Distinguish accepted requirements, remaining design choices, and proposed
  delivery scope. Approval of this drafting process leaves those design choices
  to be resolved during roadmap preparation.

Use these ADR owners for traceability:

| Topic | Authority |
| --- | --- |
| Dispatch, registration, typed inputs, and consumer boundaries | [ADR 0001](../adr/0001-command-dispatch-and-inputs.md) |
| Initial backend and invocation state | [ADR 0002](../adr/0002-cobra-backend.md) |
| Public facade and internal adapter | [ADR 0003](../adr/0003-public-facade.md) |
| Standard operations and capability-based availability | [ADR 0004](../adr/0004-standard-inspection-surface.md) |
| Outcomes, streams, and diagnostic delivery | [ADR 0005](../adr/0005-invocation-outcomes.md) |
| Grammar and vocabulary guidance | [ADR 0006](../adr/0006-command-grammar.md) |
| Native YAML and combined display | [ADR 0007](../adr/0007-native-yaml-reports.md) |
| Semantic comparison and sensitivity gaps | [ADR 0008](../adr/0008-semantic-configuration-diff.md) |
| Scopes, supported operations, and selection defaults | [ADR 0009](../adr/0009-configuration-scopes.md) |

Confirm these known differences from older planning material:

- Singleton flags use the last occurrence; repeatable flags accumulate in order.
- Configuration operations, including validation, default to `app`.
- Straightforward implementation may live in the root package.
- Providers can expose subsets of inspection capabilities.
- Loading all selected views before output is specifically a `config show`
  requirement; other operations define their own output timing.

**Result:** a traceable requirements checklist and a reconciliation of older
planning assumptions.

## 2. Select a concrete package layout

Evaluate this starting recommendation:

| Package | Target responsibilities |
| --- | --- |
| Root `commandkit` | Public API; instance registry; command groups; typed bindings and presence; invocation coordination; outcomes; standard handlers; scope metadata; ConfigKit/PromptKit integration contracts; report composition. Straightforward unexported implementation can live here. |
| `internal/cobra` | Translate backend-neutral declarations into Cobra/pflag machinery; implement parsing and help mechanics; maintain independent invocation state; translate backend-owned failures. |

- [x] Define each package's purpose, owned features, inputs, outputs, dependencies,
  and extension points.
- [x] Describe the boundary between the root and adapter, including how declarations
  and callbacks cross it while retaining supported value and error semantics.
- [x] Keep Cobra/pflag types and operations confined to the internal adapter and
  retain root-owned public named types.
- [x] Evaluate whether comparison or inspection code warrants another cohesive
  internal package, using concrete implementation and integration needs.
- [x] Settle package placement during roadmap preparation so the later plan gives
  Luna a defined target layout.
- [x] Keep package structure proportionate to the actual responsibilities under
  the architecture and agent policies.

**Result:** a target package inventory and dependency/ownership map.

## 3. Define the initial feature inventory

Organize the inventory around these feature groups:

| Group | Features to evaluate |
| --- | --- |
| Command infrastructure | Construction, registration, groups, ownership checks, typed inputs, presence, repetition, operands, help, and invocation. |
| Identity and outcomes | Application/component version reporting, classifications, supported error identity, streams, and delivery failures. |
| Configuration inspection | Scopes, validation, native display, combined display, sources, explanation, and semantic comparison. |
| PromptKit inspection | Configuration scope, prompt/profile catalogs, and definition inspection. |
| Consumer integration | Lazy acquisition, selector applicability, upstream public types, and application-owned callbacks. |

- [x] Assign stable feature identifiers for later implementation-plan traceability.
- [x] For each feature, specify its observable result, package owner, provider
  requirements, dependencies, and completion evidence.
- [x] Describe CommandKit behavior and provider result contracts separately from
  recommended consumer practices.
- [x] Build an upstream capability matrix from current supported ConfigKit and
  PromptKit public APIs, recording the inspected revisions or versions.
- [x] Identify which capabilities are available now and which need upstream work.
- [x] For each missing capability, recommend including the upstream work or
  explicitly deferring that feature, with the reason and affected targets.
- [x] Settle initial delivery scope before preparing the ordered implementation
  plan. Missing capabilities leave independently supported operations available.

**Result:** feature specifications and an explicit initial delivery scope with its
upstream dependencies and deferrals.

## 4. Evaluate existing code for reuse

Begin with these review candidates:

- [Notarius configuration commands](../../../notarius/internal/cli/configkit_commands.go):
  native effective configuration and explanation integration.
- [Scriptorium inspection commands](../../../scriptorium/internal/adapter/cli/inspect.go):
  PromptKit inspection acquisition and report preparation.

Expand to other consumers where their implementations provide useful evidence.
Use the repository's code-discovery workflow when locating and tracing code.

- [x] Identify reusable logic and the behavior it supplies.
- [x] Separate it from application-specific acquisition, schemas, domain resolution,
  parsers, names, statuses, and formats.
- [x] Evaluate the candidate against the accepted CommandKit contracts and the
  selected feature target.
- [x] For each proposed port, record the source revision, relevant symbols/files,
  adaptation work, and dependencies.
- [x] Verify applicable licensing and attribution treatment under the
  [OSS policy](../policy/oss.md) before copying material.
- [x] Identify reusable examples or fixtures that demonstrate meaningful behavior.
- [x] Use representative simple and complex consumer examples to evaluate whether
  the proposed API removes repeated infrastructure and remains practical to wire.

Sibling checkout links are review references. CommandKit implementation and
consumer examples use supported published APIs and module dependencies.

**Result:** a reuse assessment and representative integration examples, with
provenance and adaptation requirements for proposed ports.

## 5. Resolve implementation choices explicitly

- [x] Recommend construction, registration, command-group, and typed-binding API
  shapes, including presence-aware inputs.
- [x] Select narrow provider representations against concrete integration needs,
  reusing upstream public types where useful.
- [x] Define acquisition lifetime and any justified dependency coordination or
  result reuse, with callback ownership clear.
- [x] Specify configuration and context selectors and their applicability.
- [x] Define diagnostic presentation responsibility and delivery-failure handling.
- [x] Select report formats, framing, and schemas for the included operations.
- [x] Define comparison selection inputs for included diff capabilities.
- [x] Select the module baseline and supported dependency versions using the
  applicable policies and current dependency requirements.
- [x] For viable alternatives, record a recommendation and a short analysis of
  each alternative.
- [x] Resolve choices that would otherwise require Luna to invent public behavior
  or package boundaries while following the implementation plan.

API shapes in planning remain design targets until implemented. Go declarations
and GoDoc will own the exact exported contracts. Significant changes to accepted
architecture follow the ADR process in the documentation policy.

**Result:** a coherent design with remaining decisions explicitly tracked and
resolved to the depth needed by the later implementation plan.

## 6. Define completion and prepare the handoff

- [x] Define observable completion criteria for each included feature.
- [x] Cover supported commands, capability discovery, native YAML preservation,
  outcomes, backend isolation, and representative public API usage.
- [x] Identify proportionate evidence under the [testing policy](../policy/testing.md),
  prioritizing real adapter behavior and the supported public consumer boundary.
- [x] Identify documentation and attribution deliverables as their corresponding
  implementation lands.
- [x] Review the complete draft against its requirements checklist and package map.
- [x] Make upstream work, deferrals, and unresolved decisions visible in the draft.
- [x] Review the targeted end state before translating it into implementation tasks.
- [x] Prepare the subsequent staged plan with ordered tasks, prerequisites, precise
  deliverables, and completion checks mapped to the roadmap's feature identifiers.

**Result:** a reviewed feature roadmap and the completed staged implementation
plan suitable for Luna.

## Historical outline for `initial.md`

1. Authority and initial scope.
2. Target package layout and dependencies.
3. Public API and integration model.
4. Feature specifications by package.
5. Ownership boundaries.
6. Upstream dependencies and reuse candidates.
7. Explicit deferrals.
8. Completion criteria.