promptkit/docs/roadmap/releasekit.md

ReleaseKit Adoption Assessment

Status: Recommendations for review. Release tooling and adopted policies have not changed. This assessment is the basis for a later feature roadmap and implementation plan.

Purpose And Evaluation Standard

Adopt ReleaseKit to standardize PromptKit's release process and reduce the amount and complexity of release code maintained here. Prefer the shared workflow over reproducing every existing local behavior. Retain local checks where they protect a substantive project requirement; propose broadly useful validation upstream where doing so saves continuing maintenance.

Changes to release mechanics are acceptable. Their value should be assessed against the release policy, testing policy, and the user's preference for few, automated, nonredundant gates. Existing local release checks are evidence to evaluate, rather than a requirement to preserve them all.

This document recommends future changes. The current release procedure remains authoritative until adoption lands.

Reviewed Baseline

Assessment date: 2026-10-07.

• PromptKit: commit 4b8169da286917fde7875425bb32b799b12c6af3, with a clean worktree before this assessment. Its release scripts contain 209 lines: 57 in publication and 152 in validation.
• ReleaseKit: published v0.1.0, commit 5e60fe3113c69f95c42fbbe32a8ca4b51f5b83c1. The local checkout and upstream main match the tag's peeled commit. See its configuration reference, publication guide, and CLI contract.
• The preceding review ran ReleaseKit's offline Go suite successfully. Its tests use local Git remotes and HTTP fixtures for publication and delivery; this is not evidence of a live PromptKit integration or deployed delivery workflow. No candidate was published as part of either review.

The assessment examined both release scripts, their owning documentation, ReleaseKit's candidate and publication behavior, additional-check execution, and its controlled Go environment. Installed go help test confirms that ordinary go test includes a subset of vet's default analyses.

Overall Fit

ReleaseKit already owns stable-version parsing, committed release-note capture, a clean candidate on main, unused local and authoritative remote tags, exact candidate identity, annotated-tag creation, publication, and bounded reconciliation after a failed push. PromptKit already uses the same main-before-tag publication model. ReleaseKit can replace those mechanics without a PromptKit-owned orchestration package.

Its standard candidate suite is go test -mod=readonly -count=1 ./.... It uses the available compatible local Go toolchain, disables workspace discovery and module/toolchain downloads for that run, and controls settings that could change the selected tests or host target. Dependency and tool installation belong to preparation. Additional check commands are separate children; they do not automatically inherit that entire controlled Go environment.

Successful source publication remains the completion point. The native CLI also reports known failures, conflicts, and uncertain pushes. PromptKit can use that recovery model directly, including querying the captured publication endpoint when needed. Neither CI success nor consumer installation becomes a release gate.

Assessment Of Existing Checks

Current check or responsibility	Recommendation	Reason and ownership
Stable SemVer, clean main, unused version, synchronized authoritative branch, and candidate rechecks	Adopt ReleaseKit.	These are shared publication mechanics, already implemented and tested upstream. Remove the local equivalents.
Annotated tag, release-note annotation, and explicit tag-only push	Adopt ReleaseKit.	Use the committed note as the annotation. The extra Validated commit annotation line is unnecessary: the tag already identifies that commit.
Failed or ambiguous push recovery	Adopt ReleaseKit.	Its bounded reconciliation and reported endpoint replace local recovery mechanics. Retain a short maintainer runbook linked to the upstream contract.
Full Go test suite	Adopt the shared standard suite once.	Remove the suite invocation from additional checks. A separate check invocation before publish is diagnostic, not a required second pass.
Race detector	Seek a shared race-enabled standard-suite variant; resolve Open Question 1.	PromptKit has real concurrent execution and capacity management. Race detection offers distinct protection, but the current upstream suite cannot enable it. Do not attach a second complete test run just to preserve the old command.
Explicit go vet ./...	Retain as a configured command pending Open Question 2.	Ordinary go test runs only a subset of vet analyses. Full vet is not wholly redundant, although part of its work overlaps. Its invocation needs no custom local implementation.
Three offline consumer examples with semantic JSON assertions	Retain locally as a focused additional check.	Expected preparation, execution, retry, validation, and usage results are PromptKit-specific. Preserve these assembled consumer workflows without moving their expected values into ReleaseKit.
Tracked Go formatting	Propose shared upstream support.	Enumerating source files, invoking gofmt, and reporting unformatted files are reusable mechanics. Select this check for PromptKit without maintaining its shell loop here.
Local Markdown paths and heading fragments	Propose shared upstream support.	This is the largest generic block in the checker. Offline broken-link detection protects documentation consumers across repositories. Replace the local parser with supported upstream behavior.
Rejection of an ambient active Go workspace	Remove this release gate.	ReleaseKit already runs its standard suite with workspace discovery disabled. Apply suitable settings to additional Go commands as well; an unrelated active workspace need not prevent release.
Tracked go.work and go.work.sum	Retain the project rule through a small additional check.	The architecture policy expressly keeps workspace files out of PromptKit's committed source. Disabling discovery does not enforce that distribution rule.
Blanket rejection of every replace directive	Narrow to the established project requirement.	Architecture prohibits local filesystem replacements. A versioned module replacement is different; the current blanket check is broader than that stated requirement. Do not export the blanket ban as a shared standard.
Rejection whenever a vendor path exists	Remove the blanket release gate.	The architecture policy does not establish this prohibition. ReleaseKit's standard -mod=readonly run avoids automatic vendor selection; a local ignored directory need not block it. Review any intentional distribution change through ordinary development.
git diff --check and its staged counterpart	Keep in ordinary development; remove as release gates.	A clean, committed release candidate has no staged or unstaged diff. These commands add no source-whitespace protection at that point. A new historical or whole-tree whitespace audit would be a different check, not something to add implicitly.
Fixed credential-pattern scan	Recommend retiring the mandatory release gate; resolve Open Question 4.	The small regex catches some recognizable formats but is incomplete and can match synthetic data. Ordinary credential-aware change review already applies. A broader shared scanner requires its own demonstrated benefit.
Exact title plus mandatory Summary, Compatibility, Upgrade, and Changes headings	Adopt ReleaseKit's note convention.	Retain the substantive summary and relevant compatibility/upgrade guidance, but remove the extra structure validator. Section names are an editorial choice. Historical notes remain untouched.
Licensing footer and canonical documentation updates	Retain as preparation under the OSS/documentation policies.	ReleaseKit preserves the captured note, including its footer. This does not call for URL probes, a recurring attribution audit, or another publication sign-off.
Completed-roadmap retirement	Retain as preparation housekeeping.	Determining whether feature work is complete is project-specific. It does not justify a generic automatic gate or a new human approval step.
Separate builds, binary targets, provider probes, CI/module-availability waits	Keep absent from source publication.	PromptKit has no binary deliverables or live inference requirement for releases. ReleaseKit supports source-only publication. Hosted note-page delivery is considered separately below.

The module-file checks should express the selected requirement accurately. Workspace-file and local-replacement rules can share reusable upstream mechanics if there is wider demand, but their policy is not universal to Go applications. Keeping a small local check is preferable to building a broad configuration framework solely to eliminate a few lines.

Recommended Upstream Work

Shared Source And Documentation Checks

The strongest immediate requests are reusable Go formatting and local Markdown-link checks, available through the shared tooling rather than merely through a Go helper that PromptKit must wrap in its own executable.

The consumer needs are straightforward: inspect the selected repository's tracked source, report actionable failures, and perform offline checks without rewriting files. Markdown checking should cover local paths and supported heading fragments while excluding external URL availability checks. Let ReleaseKit establish its supported Markdown conventions; PromptKit need not preserve its exact regex parser, anchor algorithm, or blanket rejection of links outside the repository as universal policy.

Propose the capabilities and rationale upstream, leaving API and internal implementation design to ReleaseKit. Its routine-release priorities should guide whether these checks become shared defaults or optional selections. Either approach can reduce PromptKit-owned code. PromptKit need not prescribe mandatory checks for every unrelated consumer.

One Standard Suite With Useful Go Validation

Race-enabled execution is a credible upstream request for concurrent Go projects. Full vet within the same standard test operation is another useful candidate. The desired benefit is one complete suite execution with the selected analysis, rather than duplicate test runs or custom per-project test orchestration.

ReleaseKit currently ignores ambient GOFLAGS, so setting that variable is not a supported way to alter its suite. Do not work around the standard by trying to filter or neutralize its mandatory tests. Request a small supported capability if these choices remain release requirements. An arbitrary replacement validation command is unnecessary for PromptKit's use case.

These enhancements are not prerequisites for adopting publication. Their acceptance affects the final validation selection, as described under Open Questions. Shared formatting and link checks can also follow initial adoption; until they are available, retain a transitional local implementation only for checks selected to continue.

Work Not Recommended For Upstreaming Now

Do not propose PromptKit's four note headings, example output values, completed-roadmap judgments, or architecture-specific module restrictions as ReleaseKit defaults. There is also no value in upstreaming the current clean-candidate diff-whitespace checks. The narrow credential regex is not a sufficient basis for a shared security-check subsystem.

Recommended Adoption Shape

Use ReleaseKit's pinned native executable as maintainer tooling. A small releasekit.json profile supplies product identity, remote selection where needed, and additional checks. A thin repository entry point invokes the tool and preserves its native exit status; direct go run publication loses the distinction between ordinary failure and an uncertain push.

This needs no PromptKit runtime import, buildinfo integration, or public API change. Prefer a separately installed pinned tool over adding release orchestration to the consumer library's dependency graph. Use a released version and documented preparation rather than a sibling-checkout dependency or local replace directive.

PromptKit should own only its product facts, release-note content, substantive compatibility choices, and focused additional checks. The selected example, vet, and module checks should use the intended Go toolchain/module context; dependency preparation precedes their offline execution. Keep generic publication guards and recovery tests upstream, with a small local integration check for the actual profile and entry point when adoption is implemented.

Hosted note pages are supported independently of publication. The ReleaseKit product roadmap favors pages for source-only consumers, but its implemented publish operation does not require delivery configuration or credentials. Open Question 3 distinguishes adopting that additional channel from adopting source publication.

Local Changes Needed When Adoption Is Approved

Affected material	Proposed change
scripts/release.sh	Replace local orchestration with native ReleaseKit invocation. Preserve one publication entry point.
scripts/release-check.sh	Remove shared-suite execution and retired gates. Move the retained example assertions and module checks into focused additional checks; use upstream generic checks when available. Decide whether a standalone development command still provides value.
releasekit.json and tool preparation guidance	Introduce a small profile and a selected released tool version. Build/delivery settings depend on the chosen deliverables.
docs/policy/release.md	Adopt shared validation, note structure, and recovery behavior; preserve source/tag integrity, compatibility policy, catalog exceptions, and the no-CI-wait completion rule. Record any selected delivery channel.
docs/policy/testing.md	Update the release-candidate validation description consistently with the selected race/vet approach and retained consumer workflows.
docs/release.md	Document preparation, the single publication command, ReleaseKit failure states, and recovery. Link to upstream contracts rather than recreating them.
docs/development.md	Replace the current script inventory and prerequisites with the implemented tool/check ownership and proportionate development validation.
docs/policy/architecture.md	Preserve the explicit committed-workspace/local-replacement boundary. Only adjust text if adoption actually changes that deliberate project decision.
Release notes and licensing material	Describe adopted operational changes in the next appropriate release note. Preserve the OSS footer. Tool use alone requires no new attribution entry; assess any copied/adapted implementation or documentation under the OSS policy.

These are proposed changes, not permission to update unrelated policies or distribution channels during this assessment. A later implementation plan should use the selected released upstream contracts and resolved decisions.

Expected Benefit And Validation

The immediate benefit is eliminating most of the 57-line publication script and moving its consequential Git behavior and recovery maintenance upstream. Most of the remaining 152 lines are validation, including a large generic Markdown checker. Shared checks, removal of ineffective gates, and simpler note rules can remove substantially more. Exact savings depend on upstream capabilities and the selected validation policy; no deletion quota is needed.

The resulting local surface should be a tool invocation, product settings, and small project-specific checks. Validate those through a representative offline integration using a temporary Git remote, not by reimplementing or retesting ReleaseKit's entire publication matrix. Generic checks receive their behavioral coverage upstream; local tests cover meaningful wiring and PromptKit-specific expectations. Live hosted delivery validation is relevant only if that channel is selected, and never delays source-release completion.

Open Questions

1. Should Race Detection Remain A Release-Candidate Gate?

Recommendation: Seek supported upstream race-enabled standard-suite execution and select it for PromptKit if accepted. Concurrency is substantive library behavior, so this protects a real failure class while retaining one suite run. This is a capability request, not a requirement to preserve our exact existing shell command or to enable race testing for every consumer.

Alternative: Adopt the current ordinary ReleaseKit suite and use race testing during concurrency-related development. This provides immediate standardization and avoids an upstream option or additional release cost, but removes a last check for races introduced outside explicitly concurrency-focused work. If the upstream capability is unavailable, this is the recommended fallback after deliberately updating the release/testing policies; do not block adoption indefinitely or silently run the complete suite twice.

2. How Much Static Analysis Should Publication Require?

Recommendation: Keep full vet through a configured go vet ./... check initially, and ask ReleaseKit to consider full vet as part of its one standard test operation. Current go test includes only a subset of analyses, so full vet can catch additional defects. The transitional command costs virtually no local implementation, though it repeats some analysis.

Alternative: Use only ReleaseKit's standard go test vet subset and run full vet during ordinary development. This most closely follows the minimal upstream baseline and removes overlapping analysis; it trades away release-time coverage of the omitted analyses. Either choice requires updating the existing explicit static-analysis requirement rather than assuming the checks are equivalent.

3. Should Adoption Add Hosted Gitea Release Notes?

Recommendation: Adopt source publication first and leave hosted delivery for a separately selected expansion. Source publication already provides the desired standardization. PromptKit currently has no hosted CI, and adding a delivery workflow and credentials is additional operational scope rather than a prerequisite for using ReleaseKit.

Alternative: Include asynchronous page-only delivery in adoption, using the upstream maintained workflow and the committed note as the hosted body. This follows ReleaseKit's broader consumer direction and improves release discoverability with little bespoke code. It requires provisioning CI and a Gitea credential, plus keeping delivery status and retries separate from source publication. Successful tag publication still completes the release, even when page delivery is delayed or fails.

4. Is The Credential-Pattern Scan Worth Retaining As A Gate?

Recommendation: Retire the mandatory release scan and retain the existing credential-aware ordinary change review. The regex offers narrow detection and can reject synthetic fixtures; there is no evidence in this assessment that it provides enough additional protection to warrant preserving it as a shared release requirement. This changes the selected check, not the obligation to keep actual credentials out of committed source.

Alternative: Keep the small check, or request an optional shared equivalent, if catching a few recognizable accidentally committed credential formats is worth its low execution cost and possible false positives. This provides an independent automated signal beyond review. Its supported formats and intended scope should remain explicit, without treating it as comprehensive detection or making a broader scanner a prerequisite for adoption.