Developing CommandKit

CommandKit is distributed as a core Go module and two optional integration modules. Core owns captured declarations, typed input preparation, installation, dispatch, invocation reporting and outcomes, help, and version. integrations/ckconfig owns ConfigKit scope adaptation and reports; integrations/ckprompt owns PromptKit engine, definition inspection, requirements discovery, and concrete request validation. The maintained consumer guide links to the three maintained consumers. The README provides project orientation; the documentation policy assigns canonical documentation owners.

For application-owned aliases, use the CLI reference, Go declarations and GoDoc, and ADR 0005. Keep unfinished work and capability proposals in future work.

Initial orientation

Inspect the worktree and preserve unrelated staged and unstaged changes.
Read the agent policy and select other applicable policies using the guide below.
Read the owning roadmap for proposals and implementation status, and the applicable ADR for accepted decisions and rationale.
Inspect implementation and relevant consumer contracts when they exist.

Policy Reading Guide

Policy	Read before…
Policy set provenance	Adopting policies, checking upstream revisions, or updating the adopted policy set.
Agents	Recommending, planning, or implementing repository changes.
Architecture	Planning or changing Go library code or its structure.
Testing	Selecting validation for code changes, or adding, changing, removing, or evaluating tests.
Documentation	Writing, revising, or reorganizing documentation.
OSS	Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution.
Release	Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions.

Read applicable policies before making decisions they govern; multiple policies may apply.
Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question.
Reuse policies already available in context; reread when changed or no longer available.
Expand reading when the task's scope expands.
When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.

Task-specific reading guide

Task	Read
Implemented CLI behavior	CLI reference
Invocation reporting	CLI reporting contract, consumer guide, core GoDoc, and ADR 0006
Application-owned aliases	CLI reference, Go declarations and GoDoc, consumer guide, and ADR 0005
Public API usage and standard-suite wiring	Consumer guide, ckconfig package, ckprompt package, and applicable ADRs
Dispatcher, registration, or typed inputs	Command declarations, bindings, invocation, and ADR 0001
Backend integration	Internal overview, adapter implementation, and ADR 0002
Public facade or adapter boundaries	Internal overview, ADR 0002, ADR 0004, and the architecture policy
Module ownership and public contracts	Consumer guide, internal overview, core GoDoc, ckconfig GoDoc, ckprompt GoDoc, and applicable ADRs
Unfinished work and capability proposals	Future work
Completed planning and implementation history	Completed dependency upgrades, PromptKit validation, discovery, smoke testing, and remediation, earlier ConfigKit and PromptKit adoption and remediation, earlier retired records, and completed module implementation and remediation in Git history
Release tooling	Maintainer release procedure
Performance maintenance	Internal overview, existing benchmarks, and possible further efficiency work
Licensing or incorporated material	Project grant, license texts, and attribution
Policy provenance	Policy provenance

Read all applicable rows for cross-cutting work. Go declarations and GoDoc own current exported contracts; the CLI reference owns operator behavior. The maintainer release procedure owns current release operations. Completed roadmaps and implementation evidence remain available in Git history, including PromptKit v0.18.0 adoption and implementation, ConfigKit adoption, reporting, release-tooling, and remediation records, application-owned alias planning, implementation, and remediation and PromptKit requirements implementation and remediation. These records are not assignments to restart completed work. The future work record preserves unfinished work and unselected proposals separately from current contracts.

Documentation validation

For current prose work, inspect relevant diffs, check local links and fragment destinations, check provenance and template residue, and confirm that statements about current behavior match the repository. Include intended new files in that review. Preserve supplied license-text formatting and compare copied texts with their pinned source.

For tracked and staged prose, run from the repository root:

git diff --check -- '*.md' COPYRIGHT
git diff --cached --check -- '*.md' COPYRIGHT

These commands do not cover untracked files. Review their contents and whitespace before staging, or use the staged check after staging only the intended files. Sibling-checkout references in retired planning records are historical review evidence, not build dependencies. Implemented contracts belong in CommandKit under their canonical owners.

The root module does not traverse nested modules. Preserve the ignored go.work and go.work.sum; use GOWORK=off GOTOOLCHAIN=local for dependency preparation and independent module suites once released requirements are aligned. Until then, the integrations require a Go 1.27.0 workspace containing all three modules. Run GOWORK=off GOTOOLCHAIN=local go test ./... separately from each module directory. From the repository root, a workspace containing all three modules can also run:

GOTOOLCHAIN=local go test ./...
GOTOOLCHAIN=local go test ./integrations/ckconfig/...
GOTOOLCHAIN=local go test ./integrations/ckprompt/...

Format changed Go files with gofmt. The maintainer release procedure owns candidate preparation and publication commands.

Release tooling development

Run the focused launcher wiring tests with go test ./scripts. The release profiles select upstream checks of committed inputs independently for each module; these checks do not replace domain review. See the release procedure for publication, delivery, and recovery.

Follow the local commit policy. Completed units receive local commits by default, subject to explicit user instructions. Preserve unrelated work; default commit authorization does not authorize pushing or publishing.

Current public examples

The maintained consumers run without external services using the aligned local workspace. The PromptKit smoke examples use local fixtures and the example's configured client:

GOTOOLCHAIN=local go run ./examples/core workspace greet --count=0 --tag=first --tag second
(cd integrations/ckconfig/examples/simple && GOTOOLCHAIN=local go run . config show)
(cd integrations/ckconfig/examples/simple && GOTOOLCHAIN=local go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . config validate --scope all --campaign spring --limit=0)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit list backends --namespace team)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit list namespaces --kind prompt --kind profile)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit list collections)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit show prompt briefing --campaign spring --format yaml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit show prepared briefing --campaign spring --input topic=sprint --profile spring --extra-params '{"campaign":"preview"}')
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input-file topic=fixtures/topic.txt)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit requirements validate briefing --campaign spring --input-file topic=fixtures/topic.txt --var mode=full --input-file notes=fixtures/notes.txt --format yaml)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit test reachability --campaign spring --prompt briefing --profile spring)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . promptkit test all --campaign spring --prompt briefing --profile spring)
(cd integrations/ckprompt/examples/composed && GOTOOLCHAIN=local go run . session restore session-42 --campaign spring)

The consumer guide explains how their public API usage fits together.

Shell completion validation

The opt-in interactive completion checks require Bash, Zsh, Fish, Python with pexpect, and the Bash completion package. The harness starts a clean Bash and sources /usr/share/bash-completion/bash_completion by default. Set COMPLETION_BASH_INIT to your installation's initialization file if it is elsewhere. See the operator setup for ordinary use.

COMMANDKIT_COMPLETION_SHELLS=1 go test -count=1 -run '^TestCompletionShells$' ./internal/cobra
COMMANDKIT_COMPLETION_SHELLS=1 go test -count=1 -run '^TestCompletionConsumerInShells$' .

13 KiB Raw Blame History