promptkit/docs/development.md

Development

This is the contributor entry point for Promptkit, a reusable Go library. All contributors must read the architecture policy before making changes.

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.

Start with:

• the architecture policy for library boundaries, dependency direction, invariants, and non-goals;
• the internal component overview for the current package and component inventory;
• the documentation policy before changing documentation;
• the testing policy before adding, rewriting, or deleting tests; and
• the release procedure for version and publication work.

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.
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 example, consumer guide, framework format reference, and documentation policy.
Documentation	The documentation policy and canonical owner of every affected contract.
Release preparation or publication	The release procedure.

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

Maintainer-Run Validation

Promptkit does not currently use hosted CI. Maintainers are responsible for running the documented checks before accepting changes. Run the default Go validation from the Promptkit repository root:

go test ./...
go test -race ./...
go vet ./...
go build ./...
go run ./examples/go-library/prepare

Check formatting across every tracked Go file:

gofmt -l $(git ls-files '*.go')

The formatting command must produce no paths. Follow every added or changed Markdown link and confirm its target exists. Finally, check whitespace:

git diff --check

Documentation-only work does not require unrelated new tests, but it still requires link validation and git diff --check. Run the Go validation whenever documentation changes commands, examples, generated output, or another behavior checked by the module.

Focused Validation

Use focused checks while iterating, then run the complete validation sequence before accepting the change. The root package supports:

go test .
go vet .
go build .

Filter tests by name without assuming a fixed internal package layout:

go test ./... -run 'TestName'

Replace TestName with a useful regular expression. Target only paths that exist, and consult the internal component overview for their owning documentation. A filtered or package-specific run does not replace the complete repository validation.

Coordinated Work With Scriptorium

Promptkit and Scriptorium must remain independently valid. For temporary local integration, use either a Go workspace outside both repositories or an uncommitted replacement in the consuming module.

If the repositories are sibling directories, run the workspace commands from their parent directory:

go work init ./promptkit ./scriptorium
go work sync

Use the workspace only for coordinated local checks. From the same parent directory, remove it when finished:

rm -f go.work go.work.sum

Alternatively, from the Scriptorium repository root, temporarily point its Promptkit dependency at the sibling checkout:

go mod edit -replace gitea.maximumdirect.net/eric/promptkit=../promptkit

After coordinated checks, remove the replacement and reconcile module metadata:

go mod edit -dropreplace gitea.maximumdirect.net/eric/promptkit
go mod tidy

Never commit go.work, go.work.sum, or a local filesystem replace directive. Before committing in either repository, inspect its module files and working tree independently. Published consumer versions must depend on a tagged Promptkit version, not a workspace, local replacement, or unpublished commit.