7.2 KiB
Developing CommandKit
CommandKit currently contains adopted repository policies, accepted architectural
decisions, identity and outcome primitives, typed command
declarations, an instance-owned registry, a Cobra-backed routing and parsing
adapter, public App.Execute coordination, and generated help/version commands.
Configuration suite registration, scope discovery, ConfigKit validation and
reports, PromptKit engine configuration inspection, and optional PromptKit
prompt/profile inspection commands are implemented. The maintained
consumer guide links to maintained examples. The
README provides project orientation; the
documentation policy assigns
canonical documentation owners.
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 |
| Public API usage and standard-suite wiring | Consumer guide, configuration declarations, PromptKit declarations, and applicable ADRs |
| Dispatcher, registration, or typed inputs | Command declarations, bindings, invocation, and ADR 0001, refined by ADR 0011 |
| Backend integration | Internal overview, adapter implementation, and ADR 0002 |
| Public facade or adapter boundaries | Internal overview, ADR 0003 as scoped by ADR 0010, and the architecture policy |
| Optional integration module transition and finalized API | Module roadmap, registration API target, and ADR 0011 |
| Deferred capabilities and proposals | Deferred work |
| Completed planning and implementation history | Retired records in Git history |
| Release tooling | Maintainer release procedure |
| Performance maintenance | Internal overview, existing benchmarks, and deferred 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; they 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.
Run go test ./... from the repository root to compile the module and run its
deterministic tests. 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 under examples/ compile with the module suite and
run without external services:
go run ./examples/simple config show
go run ./examples/simple greet --count=0 --tag=first --tag second
go run ./examples/composed config validate --scope all --campaign spring
go run ./examples/composed promptkit show prompt briefing --campaign spring --format yaml
go run ./examples/composed session restore session-42 --campaign spring
The consumer guide explains how their public API usage fits together.