201 lines
11 KiB
Markdown
201 lines
11 KiB
Markdown
# Preparing the initial CommandKit feature roadmap
|
|
|
|
Status: agreed drafting process; checklist work pending.
|
|
|
|
Date: 2026-10-07.
|
|
|
|
## Purpose and use
|
|
|
|
Use this checklist to prepare `docs/roadmap/initial.md`, which will describe the
|
|
targeted end state of CommandKit's initial implementation: its packages, features,
|
|
integration contracts, and ownership boundaries. After reviewing that roadmap,
|
|
use it to prepare a separate, ordered implementation plan for a Luna agent.
|
|
|
|
Work through the sections below in order. Check an item when its result is
|
|
recorded in the draft or its supporting planning notes. Record unresolved choices
|
|
with a recommendation, alternatives, and the decision needed. Revisit earlier
|
|
sections when later evidence affects their conclusions.
|
|
|
|
The [architecture policy](../policy/architecture.md) and accepted ADRs control
|
|
architectural choices. This document owns the preparation process; `initial.md`
|
|
will own the initial feature targets. Exact implemented contracts will belong in
|
|
Go declarations, GoDoc, and the CLI reference under the
|
|
[documentation policy](../policy/documentation.md).
|
|
|
|
## 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](01-cli-plan.md), [dispatcher](02-dispatch.md),
|
|
[backend](03-backend.md), and [facade](04-facade.md).
|
|
- [ ] 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](../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. |
|
|
|
|
- [ ] 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](../../../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.
|
|
|
|
- [ ] 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](../policy/oss.md) 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](../policy/testing.md),
|
|
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 that can be translated into a strictly
|
|
ordered implementation plan suitable for Luna.
|
|
|
|
## Recommended 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.
|