6.4 KiB
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:
- 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.
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. |
| 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. |
| Licensing, dependencies/catalog updates, 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. 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.
Run the consumer example checks independently with
python3 scripts/check-examples.py.
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.