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
Documentation or examples	The documentation policy and the canonical owner of the affected contract.
Tests or test fixtures	The testing policy, the owning package, and any focused internal document listed by the component overview.
Root public API, once implemented	The architecture policy, root package declaration, testing policy, and existing GoDoc.
Internal package implementation, once introduced	The architecture policy, internal component overview, and any focused internal document that the overview lists for that package.
Integration behavior, once introduced	The architecture policy, documentation policy, and the integration's owning contract under docs/integrations/.
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 vet ./...
go build ./...

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 currently supports:

go test .
go vet .
go build .

Filter tests by name without assuming a future package layout:

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

Replace TestName with a useful regular expression. When internal packages are introduced, target only paths that actually exist, such as go test ./path/to/package, 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.