commandkit/docs/development.md

# Developing CommandKit

CommandKit currently contains adopted repository policies, accepted architectural
decisions, implementation plans, 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 and scope discovery are implemented; the
configuration operations remain pending. 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) |
| Standard command vocabulary, reports, or remaining operator-contract proposals | [CLI plan](roadmap/01-cli-plan.md) |
| Dispatcher, registration, or typed input design | [Dispatcher roadmap](roadmap/02-dispatch.md) and [ADR 0001](adr/0001-command-dispatch-and-inputs.md) |
| Backend integration | [Backend roadmap](roadmap/03-backend.md) and [ADR 0002](adr/0002-cobra-backend.md) |
| Public API or internal adapter boundaries | [Facade roadmap](roadmap/04-facade.md), [ADR 0003](adr/0003-public-facade.md), and the architecture policy |
| 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. 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:

```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 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](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.