commandkit/docs/development.md

Developing CommandKit

CommandKit currently contains adopted repository policies, accepted architectural decisions, implementation plans, identity and outcome primitives, typed command declarations, and an instance-owned registry. Command execution is not implemented yet. The README provides project orientation; the documentation policy assigns canonical documentation owners.

Initial orientation

1. Inspect the worktree and preserve unrelated staged and unstaged changes.
2. Read the agent policy 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	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
Standard command vocabulary, reports, or remaining operator-contract proposals	CLI plan
Dispatcher, registration, or typed input design	Dispatcher roadmap and ADR 0001
Backend integration	Backend roadmap and ADR 0002
Public API or internal adapter boundaries	Facade roadmap, ADR 0003, and the architecture policy
Licensing or incorporated material	Project grant, license texts, and attribution
Policy provenance	Policy provenance

Read all applicable rows for cross-cutting work. These roadmaps describe future implementation; their illustrative Go types and package layouts are not APIs.

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 evidence links in the CLI proposal are review references, not build dependencies; durable implemented contracts will belong in CommandKit.

Run go test ./... from the repository root to compile the module and run its deterministic tests. Format changed Go files with gofmt. The release procedure and publication tooling will be introduced with a releasable module under the release policy.

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.