202 lines
11 KiB
Markdown
202 lines
11 KiB
Markdown
# 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.
|