146 lines
8.6 KiB
Markdown
146 lines
8.6 KiB
Markdown
# Developing CommandKit
|
|
|
|
CommandKit is distributed as a core Go module and two optional integration
|
|
modules. Core owns captured declarations, typed input preparation, installation,
|
|
dispatch, outcomes, help, and version. `integrations/ckconfig` owns ConfigKit
|
|
scope adaptation and reports; `integrations/ckprompt` owns PromptKit engine and
|
|
definition inspection adapters. The maintained
|
|
[consumer guide](consumers/guide.md) links to the three maintained consumers.
|
|
The [README](../README.md) provides project orientation; the
|
|
[documentation policy](policy/documentation.md#canonical-ownership) assigns
|
|
canonical documentation owners.
|
|
|
|
## Initial orientation
|
|
|
|
1. Inspect the worktree and preserve unrelated staged and unstaged changes.
|
|
2. Read the [agent policy](policy/agents.md) and select other applicable policies
|
|
using the guide below.
|
|
3. Read the owning roadmap for proposals and implementation status, and the
|
|
applicable ADR for accepted decisions and rationale.
|
|
4. Inspect implementation and relevant consumer contracts when they exist.
|
|
|
|
## Policy Reading Guide
|
|
|
|
| Policy | Read before… |
|
|
| --- | --- |
|
|
| [Policy set provenance](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
|
|
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
|
|
| [Architecture](policy/architecture.md) | Planning or changing Go library code or its structure. |
|
|
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
|
|
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
|
|
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
|
|
| [Release](policy/release.md) | 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](cli.md) |
|
|
| Public API usage and standard-suite wiring | [Consumer guide](consumers/guide.md), [ckconfig package](../integrations/ckconfig/doc.go), [ckprompt package](../integrations/ckprompt/doc.go), and applicable ADRs |
|
|
| Dispatcher, registration, or typed inputs | [Command declarations](../command.go), [bindings](../binding.go), [invocation](../execute.go), and [ADR 0001](adr/0001-command-dispatch-and-inputs.md), refined by [ADR 0011](adr/0011-captured-declarations-and-installation.md) |
|
|
| Backend integration | [Internal overview](internal/overview.md), [adapter implementation](../internal/cobra/parse.go), and [ADR 0002](adr/0002-cobra-backend.md) |
|
|
| Public facade or adapter boundaries | [Internal overview](internal/overview.md), [ADR 0003](adr/0003-public-facade.md) as scoped by [ADR 0010](adr/0010-optional-integration-modules.md), and the architecture policy |
|
|
| Module ownership and public contracts | [Consumer guide](consumers/guide.md), [internal overview](internal/overview.md), [core GoDoc](../doc.go), [ckconfig GoDoc](../integrations/ckconfig/doc.go), [ckprompt GoDoc](../integrations/ckprompt/doc.go), and applicable ADRs |
|
|
| Deferred capabilities and proposals | [Deferred work](roadmap/deferred.md) |
|
|
| Completed planning and implementation history | [Earlier retired records](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/6bc37e7ba64ca0920b4d0cc77039a18d4006b24e/docs/roadmap) and [completed module implementation and remediation](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap) in Git history |
|
|
| Release tooling | [Maintainer release procedure](release.md) |
|
|
| Performance maintenance | [Internal overview](internal/overview.md), existing benchmarks, and [deferred efficiency work](roadmap/deferred.md#possible-further-efficiency-work) |
|
|
| Licensing or incorporated material | [Project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution](oss/attribution.md) |
|
|
| Policy provenance | [Policy provenance](policy/meta.md) |
|
|
|
|
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](release.md) owns current release operations.
|
|
Completed roadmaps and implementation evidence remain available in Git history;
|
|
they are not assignments to restart completed work. The
|
|
[deferred-work record](roadmap/deferred.md) 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:
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
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 sprint's validation record](https://gitea.maximumdirect.net/eric/CommandKit/src/commit/bb2528532b78d30e52f5082e491a5e1fd9b0fb99/docs/roadmap/implementation.md#stage-16-validate-the-complete-end-state-and-finish-the-sprint)
|
|
describes the disposable module-file procedure used during implementation.
|
|
Format changed Go files with `gofmt`. The
|
|
[maintainer release procedure](release.md) 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:
|
|
|
|
```sh
|
|
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](policy/agents.md#git-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:
|
|
|
|
```sh
|
|
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 . promptkit show prompt briefing --campaign spring --format yaml)
|
|
(cd integrations/ckprompt/examples/composed && go run . session restore session-42 --campaign spring)
|
|
```
|
|
|
|
The [consumer guide](consumers/guide.md) explains how their public API usage
|
|
fits together.
|