promptkit/docs/development.md

# Development

This is the contributor entry point for Promptkit, a reusable Go library.
Use the Policy Reading Guide below to select policies applicable to the task.

## Initial Orientation

Before starting work:

1. inspect the working tree and preserve unrelated changes;
2. read the policy, contract, and internal documents listed for the task;
3. inspect the relevant implementation and tests before deciding how to change
   them; and
4. keep documentation limited to implemented behavior unless an accepted
   decision or temporary roadmap explicitly owns future work.

## 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 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 before changing |
| --- | --- |
| Root public API | The [architecture policy](policy/architecture.md), [consumer guide](consumers/pkg-promptkit.md), [testing policy](policy/testing.md), and existing GoDoc. |
| Prompt, profile, or schema formats | The [framework format reference](formats.md), owning parser or validator package, and [documentation policy](policy/documentation.md). |
| Source loading or validation | The [framework format reference](formats.md), [internal source document](internal/sources.md), and owning package tests. |
| Caller-supplied configuration sources | The [internal source document](internal/sources.md), [framework format reference](formats.md), and [testing policy](policy/testing.md). |
| Model-client behavior | The [OpenAI-compatible integration contract](integrations/openai-compatible-chat.md), [internal model-client document](internal/llm.md), and owning package tests. |
| Internal package implementation | The [architecture policy](policy/architecture.md), [internal component overview](internal/overview.md), and focused internal document listed for that package. |
| Tests or test fixtures | The [testing policy](policy/testing.md), owning package, and focused internal document listed by the component overview. |
| Maintained example | The [preparation](../examples/go-library/prepare/main.go), [execution](../examples/go-library/run/main.go), and [observation](../examples/go-library/observe/main.go) examples, [consumer guide](consumers/pkg-promptkit.md), [framework format reference](formats.md), and [documentation policy](policy/documentation.md). |
| Documentation | The [documentation policy](policy/documentation.md) and canonical owner of every affected contract. |
| Licensing, dependencies, copied material, or attribution | The [OSS policy](policy/oss.md), [project grant](../COPYRIGHT), [license texts](../LICENSE), and [attribution entries](oss/attribution.md); inspect the selected upstream source's notices. |
| Release preparation or publication, including release notes | The [release policy](policy/release.md), [release procedure](release.md), and [OSS discoverability rules](policy/oss.md#discoverability). |

For cross-cutting changes, follow every applicable row. Do not create
placeholder documents for packages, APIs, or integrations that do not yet
exist.

## Maintainer Validation

For ordinary work, select validation proportionate to the change. Do not repeat
successful checks for unchanged content merely to create a commit. During
development, run relevant Go tests and vet, format changed Go files, and execute
the maintained examples when they are affected:

```sh
go test ./...
go vet ./...
gofmt -w path/to/changed.go
python3 scripts/check-examples.py
git diff --check
```

Release candidates use `./scripts/release.sh VERSION`, which runs the selected
profile checks and publishes the tag. The [release procedure](release.md)
describes its requirements and recovery. For an optional diagnostic of a
committed candidate without publication, run `./scripts/releasekit.sh check
VERSION`; this is not a required pre-publication step.

The standalone `python3 scripts/check-examples.py` command checks semantic
expectations for the three offline consumer examples. The focused
`python3 scripts/test-release.py` command exercises the release tooling against
disposable local repositories; use it when changing that tooling, not as a
recurring release gate. Tests and examples require no provider credentials or
live inference calls.

Ordinary validation can run on intended uncommitted work. Release validation
uses committed candidate contents and the selected local Go installation.

### Change Review

Inspect `git status --short --untracked-files=all` and the complete diff before
accepting a change. Reject unintended files, credentials, private data,
generated binaries, test output, downloaded assets, and template residue.

For releases, follow the [release procedure](release.md). Do not repeat its
candidate checks as a separate sign-off. Roadmap retirement remains preparation
housekeeping.

Follow the [agent commit policy](policy/agents.md#git-commit-policy) for local
commits. Ordinary commits may leave unrelated work in the workspace; preserve
and report it. A clean worktree and index are required for release candidates,
as enforced by the publication command, not for every ordinary commit.