5.3 KiB
Development
This is the contributor entry point for Promptkit, a reusable Go library. All contributors must read the architecture policy before making changes. Agents must also follow the agent policy before recommendations or work.
Initial Orientation
Before starting work:
- inspect the working tree and preserve unrelated changes;
- read the policy, contract, and internal documents listed for the task;
- inspect the relevant implementation and tests before deciding how to change them; and
- 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 policy and 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. |
| Maintained external catalogs or built-ins | The internal source document, framework format reference, testing policy, both catalog module repositories, each catalog's release procedure, and the selected module versions in go.mod. |
| 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. |
| Release preparation or publication | The release policy and 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 Validation
For ordinary work, select validation proportionate to the change. Do not repeat successful checks for unchanged content merely to create a commit. The full release-candidate checks have one executable entry point from the repository root:
./scripts/release-check.sh
The script owns the executable checks: race-enabled tests, vet, the three offline consumer examples with semantic output assertions, tracked Go formatting, local Markdown links, module/workspace hygiene, whitespace, and the credential-pattern scan. It does not publish, change files, validate release-note structure, or retire roadmaps. It requires Go, Git, a POSIX shell, and Python 3. Tests and examples require no provider credentials or live inference calls.
The script can run on intended uncommitted changes during development. Formatting and documentation checks use tracked files; stage intended new files before final validation so those checks include them. The release procedure separately enforces a clean, committed candidate.
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.
The automated credential scan does not replace review of the actual change.
For releases, follow the release procedure. Its publication command runs the full local checks once on the final committed candidate and automates release-note structure and Git checks. Do not repeat ordinary change review as a release 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.