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 records the selected initial target and its completion. The implementation plan 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, and usage guidance in the consumer guide.

The architecture policy 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.

1. Establish authoritative requirements

• Review all nine accepted ADRs and the architecture policy.
• Build a requirements checklist linking each requirement to its authority.
• Review the four numbered roadmaps as evidence and design proposals: CLI plan, dispatcher, backend, and facade.
• Identify conflicts with accepted decisions and carry the controlling choice into the new roadmap.
• 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
Initial backend and invocation state	ADR 0002
Public facade and internal adapter	ADR 0003
Standard operations and capability-based availability	ADR 0004
Outcomes, streams, and diagnostic delivery	ADR 0005
Grammar and vocabulary guidance	ADR 0006
Native YAML and combined display	ADR 0007
Semantic comparison and sensitivity gaps	ADR 0008
Scopes, supported operations, and selection defaults	ADR 0009

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.

• Define each package's purpose, owned features, inputs, outputs, dependencies, and extension points.
• Describe the boundary between the root and adapter, including how declarations and callbacks cross it while retaining supported value and error semantics.
• Keep Cobra/pflag types and operations confined to the internal adapter and retain root-owned public named types.
• Evaluate whether comparison or inspection code warrants another cohesive internal package, using concrete implementation and integration needs.
• Settle package placement during roadmap preparation so the later plan gives Luna a defined target layout.
• 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.

• Assign stable feature identifiers for later implementation-plan traceability.
• For each feature, specify its observable result, package owner, provider requirements, dependencies, and completion evidence.
• Describe CommandKit behavior and provider result contracts separately from recommended consumer practices.
• Build an upstream capability matrix from current supported ConfigKit and PromptKit public APIs, recording the inspected revisions or versions.
• Identify which capabilities are available now and which need upstream work.
• For each missing capability, recommend including the upstream work or explicitly deferring that feature, with the reason and affected targets.
• 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: native effective configuration and explanation integration.
• Scriptorium inspection commands: 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.

• Identify reusable logic and the behavior it supplies.
• Separate it from application-specific acquisition, schemas, domain resolution, parsers, names, statuses, and formats.
• Evaluate the candidate against the accepted CommandKit contracts and the selected feature target.
• For each proposed port, record the source revision, relevant symbols/files, adaptation work, and dependencies.
• Verify applicable licensing and attribution treatment under the OSS policy before copying material.
• Identify reusable examples or fixtures that demonstrate meaningful behavior.
• 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

• Recommend construction, registration, command-group, and typed-binding API shapes, including presence-aware inputs.
• Select narrow provider representations against concrete integration needs, reusing upstream public types where useful.
• Define acquisition lifetime and any justified dependency coordination or result reuse, with callback ownership clear.
• Specify configuration and context selectors and their applicability.
• Define diagnostic presentation responsibility and delivery-failure handling.
• Select report formats, framing, and schemas for the included operations.
• Define comparison selection inputs for included diff capabilities.
• Select the module baseline and supported dependency versions using the applicable policies and current dependency requirements.
• For viable alternatives, record a recommendation and a short analysis of each alternative.
• 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

• Define observable completion criteria for each included feature.
• Cover supported commands, capability discovery, native YAML preservation, outcomes, backend isolation, and representative public API usage.
• Identify proportionate evidence under the testing policy, prioritizing real adapter behavior and the supported public consumer boundary.
• Identify documentation and attribution deliverables as their corresponding implementation lands.
• Review the complete draft against its requirements checklist and package map.
• Make upstream work, deferrals, and unresolved decisions visible in the draft.
• Review the targeted end state before translating it into implementation tasks.
• 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.