12 KiB
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 0013. Keep deferred capabilities in deferred 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
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 application-owned alias planning, implementation, and remediation and PromptKit requirements implementation and remediation. These records are not assignments to restart completed work. The deferred-work record preserves future capability targets 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. During development, use a
local workspace for all three modules; it is ignored and must not be committed.
If a local go.work already exists, preserve it and add these module directories:
if [ -f go.work ]; then
go work use . ./integrations/ckconfig ./integrations/ckprompt
else
go work init . ./integrations/ckconfig ./integrations/ckprompt
fi
go test ./...
(cd integrations/ckconfig && go test ./...)
(cd integrations/ckprompt && go test ./...)
The workspace checks package behavior. Workspace-off checks with each module's
own dependency graph are separate evidence. For unpublished CommandKit dependency
versions, the completed integration validation record
describes the disposable module-file procedure used during implementation.
Format changed Go files with gofmt. The
maintainer release procedure owns candidate preparation and
publication commands.
Release tooling development
The local publication exercise is opt-in and uses disposable Git repositories. Prepare the module cache before running it; ordinary tests do not bootstrap or publish a release:
GOWORK=off GOTOOLCHAIN=local go mod download
COMMANDKIT_RELEASE_INTEGRATION=1 GOWORK=off GOTOOLCHAIN=local GOPROXY=off GONOPROXY=none GOSUMDB=off go test -mod=readonly -count=1 ./scripts -run '^TestReleaseIntegration$'
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 compile with their owning module suites and run without external services. The PromptKit smoke examples use local fixtures and the example's configured client:
go run ./examples/core workspace greet --count=0 --tag=first --tag second
(cd integrations/ckconfig/examples/simple && go run . config show)
(cd integrations/ckconfig/examples/simple && go run . config diff --config fixtures/before.yml --against-config fixtures/after.yml)
(cd integrations/ckprompt/examples/composed && go run . config validate --scope all --campaign spring --limit=0)
(cd integrations/ckprompt/examples/composed && go run . config diff --scope app --config fixtures/before.yml --against-config fixtures/after.yml)
(cd integrations/ckprompt/examples/composed && go run . config diff --scope promptkit --config fixtures/before.yml --against-config fixtures/after.yml --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit list prompts --config fixtures/before.yml --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit list profiles --config fixtures/after.yml --campaign autumn --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit list backends --namespace team)
(cd integrations/ckprompt/examples/composed && go run . promptkit list namespaces --kind prompt --kind profile)
(cd integrations/ckprompt/examples/composed && go run . promptkit list collections)
(cd integrations/ckprompt/examples/composed && go run . promptkit show prompt briefing --campaign spring --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements show briefing --campaign spring --var mode=full --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt)
(cd integrations/ckprompt/examples/composed && go run . promptkit requirements validate briefing --campaign spring --input topic=fixtures/topic.txt --var mode=full --input notes=fixtures/notes.txt --format yaml)
(cd integrations/ckprompt/examples/composed && go run . promptkit test reachability --campaign spring --prompt briefing --profile spring)
(cd integrations/ckprompt/examples/composed && go run . promptkit test all --campaign spring --prompt briefing --profile spring)
(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
The consumer guide explains how their public API usage fits together.