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	Adopting policies, checking upstream revisions, or updating the adopted policy set.
Agents	Recommending, planning, or implementing repository changes.
Architecture	Planning or changing 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 before changing
Root public API	The architecture policy, consumer guide, testing policy, and existing GoDoc.
Prompt, profile, or schema formats	The framework format reference, owning parser or validator package, and documentation policy.
Source loading or validation	The framework format reference, internal source document, and owning package tests.
Caller-supplied configuration sources	The internal source document, framework format reference, and testing policy.
Model-client behavior	The OpenAI-compatible integration contract, internal model-client document, and owning package tests.
Internal package implementation	The architecture policy, internal component overview, and focused internal document listed for that package.
Tests or test fixtures	The testing policy, owning package, and focused internal document listed by the component overview.
Maintained example	The preparation, execution, and observation examples, consumer guide, framework format reference, and documentation policy.
Documentation	The documentation policy and canonical owner of every affected contract.
Licensing, dependencies, copied material, or attribution	The OSS policy, project grant, license texts, and attribution entries; inspect the selected upstream source's notices.
Release preparation or publication, including release notes	The release policy, release procedure, and OSS discoverability rules.

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:

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 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. Do not repeat its candidate checks as a separate sign-off. Roadmap retirement remains preparation housekeeping.

Follow the agent 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.