commandkit/docs/roadmap/implementation.md

CommandKit vanity migration and dependency alignment plan

Status: Stages 1–2 complete; Stages 3–7 are not started.

This plan is for the Luna coding agent implementing the feature roadmap. Follow the stages in integer order during one end-to-end sprint. Unpublished editing states may be temporarily inconsistent. Each published module must be a coherent, committed candidate validated by its ordinary release workflow.

This planning pass changes documentation only. The target includes three real source releases because later modules need downloadable predecessors. The publication stages below describe that future work; this planning request does not perform or authorize Git pushes. Honor the user's implementation/publication scope when executing the plan, and report any unperformed release as pending.

Read development guidance, the agent policy, architecture policy, testing policy, documentation policy, release policy, and OSS policy for the work they govern. Follow AGENTS.md codebase-memory discovery instructions. The release procedure remains the owner of operational commands.

The previous plan's completed ReleaseKit v0.9.0 stages and evidence remain in Git history. R1/R2 in remediation.md and the ReleaseKit adoption are complete; do not restart them or rewrite their historical evidence.

Baseline and fixed decisions

Planning baseline: c8d659dfe5ae3e834b3aeabdfd0fe29b736dc05a.

Module directory	Current module path	Target module path	Target version and full tag
.	gitea.maximumdirect.net/eric/CommandKit	go.maximumdirect.net/commandkit	v0.3.0; v0.3.0
integrations/ckconfig	gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig	go.maximumdirect.net/ckconfig	v0.2.0; integrations/ckconfig/v0.2.0
integrations/ckprompt	gitea.maximumdirect.net/eric/CommandKit/integrations/ckprompt	go.maximumdirect.net/ckprompt	v0.2.0; integrations/ckprompt/v0.2.0

• Both integrations currently require core v0.2.0; ckprompt also requires ckconfig v0.1.0. Their source uses newer core APIs. Independent baseline suites fail; temporary local-source selections pass only when ckprompt also uses current ckconfig. The feature roadmap records those diagnostics.
• Target ckconfig requires go.maximumdirect.net/commandkit v0.3.0. Target ckprompt requires that core and go.maximumdirect.net/ckconfig v0.2.0.
• Vanity discovery is verified. The integration metadata's fourth field maps the short paths to the existing physical directories. Existing tags still declare old identities. Discovery alone does not complete module migration.
• Preserve package names, exported declaration shapes, runtime behavior, Go 1.26.0 consumer minimums, and the Go 1.26.8 maintainer toolchain. Preserve root ReleaseKit v0.9.0 selection, scripts, profiles, endpoints, and validators.
• Retain ConfigKit v0.8.0 and PromptKit v0.16.0; no upstream library upgrade is selected. Inspect tidy's actual graph changes and update affected attribution.
• The three proposed tags were unused at planning time. Existing publication guards recheck freshness; never move/reuse a published tag. A conflict needs a deliberate new version selection and matching dependent metadata/notes.
• Retain ignored go.work and go.work.sum, and the supplied ignored .releasekit/gitea-token without reading its contents. No credential or live provider is needed for local validation. Source publication uses the existing Git endpoint; hosted delivery remains a separate operation/outcome.

Do not rename physical module directories or flatten integration tag prefixes. Do not add an old-path forwarding module, type-interoperability layer, API rollback, permanent validation shim, or new recurring release gate. These are outside the selected migration, not new restrictions on application behavior.

Execution and validation conventions

Use Go 1.26.8 on PATH following the existing toolchain setup. The ignored workspace declares Go 1.26.10 at baseline; preserve it. Use GOWORK=off GOTOOLCHAIN=local for module preparation and independent validation. Use normal dependency retrieval during preparation; ReleaseKit runs the final selected-module suite offline/read-only.

Migrate module-owned source, tests, and examples together. Apply integration path mappings before the broader core prefix when a replacement tool is used; go.maximumdirect.net/commandkit/integrations/ckconfig is not the selected ckconfig identity. Preserve import aliases such as commandkit. Core internal imports must use the new core prefix. Review identity-sensitive strings as well as Go import declarations.

Update current prose and GoDoc for the module being migrated. Treat repository, license, and immutable historical source links separately from Go import paths. Keep published notes, accepted ADR history, and completed review evidence intact. Do not globally replace every old URL or migrate unrelated upstream identities.

Publication steps use the existing protocol: prepare dependencies, review and commit the final selected candidate on main, publish that candidate commit to the authoritative branch, and invoke the module's release wrapper. The wrapper runs the owning complete suite once, selected file checks, and publication guards, then creates/pushes the intended tag. It does not push main for you. Run validation-only check for diagnosis when useful; do not make it a required duplicate suite before publish. Do not add CI/proxy polling or post-push read-back as a successful-publication gate. Reuse evidence for unchanged content.

Each release has its own candidate commit, suite result, and publication outcome. The next module's dependency download is preparation for that next release; failure to download does not undo completion of the predecessor's source push. Use a command-scoped direct download to diagnose proxy lag if necessary rather than permanently changing proxy settings. Retain authentic downloaded sums.

Stage 1: Migrate core identity and prepare its release candidate

Completed. The root module, owned imports, component build identity, consumer guidance, and v0.3.0 release note use the new core identity. The focused build-identity test passed offline with Go 1.26.8; affected links and whitespace were checked. The complete candidate suite belongs to publication.

1. Change only the root module declaration to go.maximumdirect.net/commandkit. Migrate root-owned imports in production files, root/external tests, internal packages, and examples/core. Leave nested module migration to Stages 3/5. Preserve the root tool declaration and other dependency versions; prepare caches and tidy the root with workspace discovery off.

2. Update commandKitModulePath in builtins.go to the new core identity. version --scope commandkit uses it to find build information. Retain its existing application/component scopes, tag/replacement handling, and dev fallback; do not add a legacy-identity fallback.

3. Adapt existing identity/import-path test expectations. In TestCommandKitBuildIdentityProjectsEffectiveModuleVersion, make at least one existing successful tagged case supply the literal new module path independently of commandKitModulePath. Otherwise a stale constant and its self-referencing fixtures could agree while real version lookup fails. Preserve all existing replacement/development cases and boundary assertions.

4. Update the root row in README's module table, current core imports and installation guidance in docs/consumers/guide.md, affected developer and internal guidance, example documentation, and GoDoc. Describe integrations according to their implemented identity until their migration stages land; keep the matched future set in migration guidance explicit.

5. Refresh docs/releases/v0.3.0.md against the full v0.2.0-to-candidate change: aliases, reporting migration, completion, ReleaseKit maintenance, and the new core import path. Explain consumer updates and the forthcoming matched integration versions. Use current procedure URLs with immutable v0.3.0 source/licensing links. Keep the declared toolchains unchanged.

6. Format changed Go files. Review root-owned imports/identity literals and module metadata; check affected prose links and whitespace. Run the existing focused identity test with prepared caches:

   GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off \
     go test -mod=readonly -count=1 -run '^TestCommandKitBuildIdentityProjectsEffectiveModuleVersion$' .
   

Stage result: a reviewed core v0.3.0 candidate with the new identity, correct component version lookup, migrated root consumers, and current release notes. The full root suite belongs to Stage 2's normal publication workflow.

Stage 2: Validate and publish core v0.3.0

Completed. Core go.maximumdirect.net/commandkit v0.3.0 was published as tag v0.3.0 at candidate e256eb1cc02a0c72c4e23c4967ed1caeaef17008. The ordinary Go 1.26.8 release workflow passed the complete root suite and selected file checks before the successful source-tag push.

1. Review and commit the complete core candidate under the local commit policy. Confirm that unrelated/private files and ignored workspaces are excluded. The independently released integration sources may still declare old paths; that does not make their suites a prerequisite for this root release.

2. From the repository root, execute the existing publication sequence within the authorized release scope:

   git push origin HEAD:refs/heads/main
   ./scripts/release core v0.3.0
   

3. Require the real selected-module suite and file checks to pass. Fix actual failures in scope and commit the corrected candidate before retrying. On a failed/ambiguous push, use the existing publication evidence and recovery procedure. Do not force refs, bypass guards, or treat a local tag as publication.

4. Record the candidate commit, module path, full tag, validation outcome, and confirmed source outcome here. A successful tag push completes this source release; move to dependent preparation without waiting for hosted pages.

Stage result: core v0.3.0 is source-published with module go.maximumdirect.net/commandkit. Actual download of this version and its sums is part of Stage 3, not a new completion gate for core publication.

Stage 3: Migrate ckconfig and prepare its independent candidate

Status: not started.

1. In integrations/ckconfig, migrate the module declaration to go.maximumdirect.net/ckconfig. Update all owned imports, tests, and the maintained simple example to that self-path and the new core path. Keep package names and existing adapter behavior.

2. Replace its old core dependency key with the published new-path version. From the ckconfig module directory, use:

   GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckconfig -droprequire=gitea.maximumdirect.net/eric/CommandKit -require=go.maximumdirect.net/commandkit@v0.3.0
   GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0
   GOWORK=off GOTOOLCHAIN=local go mod tidy
   

   Perform source import migration before tidy to avoid resolving old imports. Keep real downloaded sums. If retrieval is unavailable, resolve dependency preparation before proceeding; do not fabricate metadata or substitute a local replacement as final release evidence.

3. Inspect the actual direct and indirect graph, including tool requirements. Preserve ConfigKit v0.8.0 and unrelated versions. Update affected notices in integrations/ckconfig/docs/oss/attribution.md under the OSS policy using the actual selected source revisions; add/retain applicable license texts. Do not assume similarly named old/new upstream modules are interchangeable.

4. Prepare integrations/ckconfig/docs/releases/v0.2.0.md with product CommandKit ckconfig, the new module/core paths, compatible dependency set, and relevant reporting/completion migration. Immutable footer/source URLs use the full tag integrations/ckconfig/v0.2.0 and correct physical files.

5. Update README's ckconfig row, consumer module/import examples, the simple example guidance, affected GoDoc, and relevant current release/development references. Explain that applications moving to the new core identity also use the matched new integration identity.

6. Format changed Go files. Review for stale owned imports/direct requirement keys, accidental replacements/workspace files, and unexplained graph churn. Check current links and whitespace. The owning complete suite runs in Stage 4; a local workspace pass is not a substitute.

Stage result: a ckconfig v0.2.0 candidate whose actual dependency is downloaded go.maximumdirect.net/commandkit v0.3.0, with authentic metadata and aligned current documentation/attribution.

Stage 4: Validate and publish ckconfig v0.2.0

Status: not started.

Review and commit the complete ckconfig candidate. From the repository root, use the same authoritative-branch protocol as Stage 2:

git push origin HEAD:refs/heads/main
./scripts/release ckconfig v0.2.0

The normal release command must pass the independent ckconfig suite, including its maintained example, with workspace discovery off and without dependency redirection. It must also pass selected committed-file checks and publication guards. Do not insert the earlier temporary Go shim or weaken a selected check. Apply the existing failed/ambiguous-publication procedure if needed.

Record the candidate, path, version, full tag, validation, and source outcome. The intended tag is integrations/ckconfig/v0.2.0; the physical directory remains integrations/ckconfig despite the short vanity module path.

Stage result: compatible ckconfig v0.2.0 is source-published under its vanity identity. Downloading it for ckprompt is the next module's preparation.

Stage 5: Migrate ckprompt and prepare its independent candidate

Status: not started.

1. Migrate integrations/ckprompt to go.maximumdirect.net/ckprompt. Update its owned source/tests and composed example to import the new core, ckconfig, and ckprompt paths. Preserve PromptKit adaptation and reporting behavior.

2. From that module directory, replace both old CommandKit dependency keys:

   GOWORK=off GOTOOLCHAIN=local go mod edit -module=go.maximumdirect.net/ckprompt -droprequire=gitea.maximumdirect.net/eric/CommandKit -droprequire=gitea.maximumdirect.net/eric/CommandKit/integrations/ckconfig -require=go.maximumdirect.net/commandkit@v0.3.0 -require=go.maximumdirect.net/ckconfig@v0.2.0
   GOWORK=off GOTOOLCHAIN=local go mod download go.maximumdirect.net/commandkit@v0.3.0 go.maximumdirect.net/ckconfig@v0.2.0
   GOWORK=off GOTOOLCHAIN=local go mod tidy
   

   Migrate imports before tidy. Retain actual downloaded sums; resolve fetch failures as preparation rather than masking them with local source. A new core with old ckconfig v0.1.0 is the known incompatible combination.

3. Review graph changes while retaining ConfigKit v0.8.0 and PromptKit v0.16.0. Update affected module-local attribution and immutable notice links based on the resolved graph, including transitive tools. Keep actual upstream module identities distinct from the three CommandKit identities being migrated.

4. Prepare integrations/ckprompt/docs/releases/v0.2.0.md with product CommandKit ckprompt, new imports/dependencies, and consumer migration. Footer/source links use full tag integrations/ckprompt/v0.2.0 and physical module-local files. Preserve the published v0.1.0 record.

5. Update README's ckprompt row, consumer composition/import examples, composed example guidance, affected GoDoc, and remaining current module descriptions. Keep URLs to hosted repository files separate from Go package links.

6. Format changed Go files and review remaining owned old-path imports or direct requirement keys, metadata, links, and whitespace. Keep the ordinary source checks intact; the independent suite runs in Stage 6.

Stage result: ckprompt v0.2.0 composes the real new-path core and ckconfig versions in its declared graph, with current guidance and authentic metadata.

Stage 6: Validate and publish ckprompt v0.2.0

Status: not started.

Review and commit the complete ckprompt candidate. From the repository root:

git push origin HEAD:refs/heads/main
./scripts/release ckprompt v0.2.0

The normal publication workflow must pass the independent ckprompt suite and composed consumer with actual downloaded predecessors, plus selected file and publication checks. Preserve the offline/read-only suite environment and ordinary recovery handling. No workspace or replacement shim supplies final release evidence.

Record its candidate, module identity, full tag integrations/ckprompt/v0.2.0, suite outcome, and source-publication outcome. Report any separate hosted delivery under its own outcome; page publication is not required to establish dependency alignment.

Stage result: all three matched source releases are published with vanity module declarations and verified independent dependency graphs.

Stage 7: Audit the completed migration and record evidence

Status: not started.

1. Review the cumulative diff against the feature roadmap. Confirm all three module declarations, owned imports, examples, direct dependency keys, and component build identity use the new paths. Preserve physical directories, tag prefixes, root ReleaseKit selection, scripts/profiles, exported shapes, Go minimums, and upstream versions apart from explained graph consequences.
2. Check that tests and current guidance use the new identities while historical notes, accepted ADRs, and immutable source URLs retain their historical meaning. Resolve current dependency-readiness claims that are now stale. Do not mechanically rewrite every old-path reference in completed records.
3. Record each final candidate's exact commit, full tag, suite result, and publication outcome. Identify diagnostic-only earlier evidence separately. Reuse each successful publication suite for its unchanged candidate; do not require another complete run just to finish this stage. Any later code or metadata correction belongs in a new candidate/version under release policy.
4. Mark stages complete only with their stated evidence and update the feature roadmap's status/link here. Preserve this record and prior immutable plans; apply normal roadmap retirement only during later preparation. If publication was outside the authorized implementation scope or could not finish, record the actual prepared state and pending release stages rather than claiming alignment is complete.
5. Review new evidence prose, links/fragments, intended staged files, and git diff --check / git diff --cached --check. Commit any remaining nonempty documentation unit with a short plain-English message, following the local commit policy. Finish with a clean tracked worktree when only planned work is present; preserve unrelated and ignored local files.

Stage result: the implemented and published matched version set has accurate source/validation evidence, current migration guidance, and committed tracking. Source release and hosted-delivery outcomes remain separate.

Open Questions

None required to choose the implementation. Vanity paths, target versions, physical layout, dependency order, validation ownership, and compatibility scope are selected in the roadmap. Publication authorization is an execution-scope constraint, not a reason to invent different versions, fabricated sums, or a local-only substitute for the target end state.