diff --git a/docs/roadmap/initial-plan.md b/docs/roadmap/initial-plan.md new file mode 100644 index 0000000..63a30e4 --- /dev/null +++ b/docs/roadmap/initial-plan.md @@ -0,0 +1,200 @@ +# 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.