promptkit/docs/development.md

# Development

This is the contributor entry point for Promptkit, a reusable Go library. All
contributors must read the
[architecture policy](policy/architecture.md) 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](policy/architecture.md) for library boundaries,
  dependency direction, invariants, and non-goals;
- the [internal component overview](internal/overview.md) for the current
  package and component inventory;
- the [documentation policy](policy/documentation.md) before changing
  documentation;
- the [testing policy](policy/testing.md) before adding, rewriting, or deleting
  tests; and
- the [release procedure](release.md) for version and publication work.

## 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. |
| 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 [example](../examples/go-library/prepare/main.go), [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. |
| Release preparation or publication | The [release procedure](release.md). |

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:

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

Check formatting across every tracked Go file:

```sh
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:

```sh
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:

```sh
go test .
go vet .
go build .
```

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

```sh
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:

```sh
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:

```sh
rm -f go.work go.work.sum
```

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

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

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

```sh
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.