eric/scriptorium
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 6 Wiki Activity

Complete Promptkit repository foundation

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-28 02:25:20 +00:00
parent 416438d80d
commit 68cd90c657
3 changed files with 157 additions and 797 deletions
Download Patch File Download Diff File Expand all files Collapse all files

552
docs/roadmap/implementation.md
View File

@@ -1,422 +1,63 @@
# Step 5 Implementation Plan
# Step 5 Implementation Record
## Status
Proposed.
This plan implements
[Migration Step 5: Promptkit Repository Foundation](step5.md). The feature
roadmap is the canonical source for the intended end state and policy choices;
this document owns implementation order, concrete changes, and validation.
## Scope and Repository Boundaries
Step 5 changes two sibling repositories:
- `scriptorium` remains the controlling repository for the migration roadmap
and architectural decision records.
- `promptkit` becomes a self-contained Go library repository with its own
policies, contributor guidance, release procedure, module metadata, and
validation baseline.
Paths in this plan are relative to the named repository unless otherwise
stated. Run commands from the root of the repository named by the stage.
The implementation agent must preserve these boundaries:
- Do not move framework implementation or public APIs from Scriptorium. That is
Step 6 work.
- Do not add placeholder packages or empty directory scaffolding for future
framework components.
- Do not add hosted CI configuration, release binaries, or binary-packaging
automation to Promptkit.
- Do not create or publish a Promptkit version tag. The first `v0.1.0` tag
belongs to Step 6 after framework extraction.
- Do not add a committed `go.work` file or a committed local `replace`
directive to either repository.
- Keep Scriptorium and Promptkit changes in their respective Git histories.
Never create a cross-repository commit.
## Stage 1: Reconcile the Durable Validation and Release Decision
### Objective
Record the approved Promptkit validation and release model in a permanent ADR,
then make the controlling migration roadmap consistent with that decision
before relying on it in Promptkit documentation.
### Scriptorium Changes
Create the next sequential ADR under `docs/adr/` with an Accepted status. Use
the repository's current ADR format and the actual implementation date. Give it
a title that describes the decision, such as
`Use Maintainer-Run Validation and Tag-Only Releases for Promptkit`.
The ADR must make the following points decision content:
- Promptkit is a Go library and does not release runnable binaries.
- Promptkit does not use hosted CI at this stage.
- Its required checks are run by the maintainer from a clean checkout before
changes are accepted and before a release tag is published.
- Promptkit releases consist of source commits and semantic Go module tags.
- The required local checks are the repository-documented test, vet, build,
formatting, documentation-link, and repository-hygiene checks.
- Scriptorium's own executable build and CI policy are unaffected.
- The repository boundary, independent version history, and migration ordering
accepted by
[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) remain in force.
- Where ADR 0002 anticipated independent hosted CI for Promptkit, the new ADR
is the later, controlling decision for Promptkit validation.
Document at least hosted Promptkit CI and required local hooks as alternatives.
Explain why maintainer-run validation is proportionate for the present
single-maintainer library while making clear that a later ADR may introduce
hosted CI if maintenance or contribution patterns change.
Do not mark ADR 0002 Rejected or Superseded. The new decision refines only its
validation assumption and does not replace the accepted repository split. Link
the new ADR to ADR 0002 from the new record; do not rewrite ADR 0002's
historical decision content.
Update `docs/roadmap/migration.md` so that:
- Step 5 requires Promptkit's documented maintainer-run validation and
tag-based release procedure instead of hosted CI or binary packaging;
- Step 6 requires the extracted library to pass Promptkit's documented
validation rather than “CI checks”;
- the release-order gate continues to require Promptkit's first versioned tag
before Scriptorium consumes it; and
- the new ADR is linked wherever the later validation decision is material.
Do not mark Step 5 complete in this stage.
### Stage 1 Validation
From the Scriptorium repository:
1. Confirm the new ADR contains a title, date, Accepted status, context,
decision, alternatives, and consequences.
2. Confirm ADR 0002 remains Accepted and its decision content is unchanged.
3. Search `docs/roadmap/migration.md` for Promptkit CI and binary-release
requirements and confirm no obsolete requirement remains.
4. Check every changed Markdown link.
5. Run `git diff --check`.
### Stage 1 Completion Gate
Proceed only when the permanent decision record and controlling migration
roadmap consistently describe maintainer-run validation, tag-only library
releases, and no Promptkit release binaries.
## Stage 2: Establish the Promptkit Go Module and License Baseline
### Objective
Make Promptkit a valid, independently buildable Go module with an accurate root
package and project-specific GPLv3 example notices.
### Promptkit Module Files
Create `go.mod` with exactly this module identity and Go baseline:
```go
module gitea.maximumdirect.net/eric/promptkit
go 1.25.5
```
Do not add dependencies solely to populate the module. A `go.sum` file is not
expected while the module has no external dependencies.
Create a root `doc.go` that:
- declares `package promptkit`;
- contains a package comment beginning with `Package promptkit`;
- describes the package only as the public package boundary for the Promptkit
Go module; and
- does not claim that framework behavior or APIs have already been migrated.
Do not add exported symbols, placeholder implementations, empty internal
packages, or speculative package trees. The root package alone is the correct
foundation state.
### Promptkit License Hygiene
Preserve `LICENSE` as GPLv3 and preserve its existing copyright attribution and
license text. Replace the template project name in both GPL example notices
with `Promptkit`. Do not use this stage to relicense Promptkit, add a second
license, or alter GPLv3 wording outside those project-name examples.
Review `.gitignore` and retain coverage for Go build and test output, editor and
operating-system files, `.env`, `go.work`, and `go.work.sum`. Change it only if
one of those required rules is missing; do not add broad rules that could hide
source or documentation.
### Stage 2 Validation
From the Promptkit repository:
1. Run `go mod tidy` and confirm it does not introduce unnecessary
dependencies or a spurious `go.sum`.
2. Run:
```sh
go test ./...
go vet ./...
go build ./...
```
3. Confirm module metadata:
```sh
go list -m -f '{{.Path}} {{.GoVersion}}'
go list -f '{{.Name}} {{.ImportPath}}' .
```
The results must identify module
`gitea.maximumdirect.net/eric/promptkit`, Go `1.25.5`, package `promptkit`,
and the matching root import path.
4. Run `gofmt -l` over all tracked Go files and confirm it produces no output.
5. Search `LICENSE` for `go-application-template` and confirm no matches.
6. Confirm `.gitignore` covers every required repository-local artifact without
hiding maintained source.
7. Confirm no `go.work`, local `replace` directive, CI configuration, command
package, or placeholder package was added.
8. Run `git diff --check`.
### Stage 2 Completion Gate
Proceed only when Promptkit builds as an independent, dependency-free root Go
package and its retained GPLv3 license notices identify the correct project.
## Stage 3: Replace Promptkit's Template Policies and Architecture Guide
### Objective
Replace inherited application-template guidance with durable policies that
accurately govern a reusable Go library and its manual validation model.
### Documentation Policy
Rewrite `docs/policy/documentation.md` for Promptkit while retaining the useful
principles established in the Scriptorium documentation policy. It must:
- identify Promptkit as a reusable Go library, not an application;
- preserve the distinction between current-state documentation, accepted ADRs,
and temporary roadmaps;
- preserve the one-canonical-owner rule and require other documents to link to
the owner rather than duplicate exact contracts;
- assign canonical ownership for project orientation, contributor workflow,
architecture, testing, release procedure, public Go contracts, integrations,
internal subsystem detail, ADRs, and temporary feature roadmaps;
- state that Go declarations and GoDoc own exact exported API contracts once
APIs exist;
- use the ADR statuses Proposed, Accepted, Rejected, and Superseded;
- require a later ADR for changed accepted decisions rather than rewriting
accepted decision content;
- retain link, example, code-fence, and document-lifecycle expectations; and
- avoid claiming that absent consumer, integration, or subsystem documents
already exist.
State ownership rules for future document categories conditionally rather than
creating placeholder documents.
### Architecture Policy
Rewrite `docs/policy/architecture.md` as Promptkit's canonical current-state
architecture policy. It must define:
- Promptkit as an importable Go library with no runnable command or HTTP
service;
- the root `promptkit` package as the public facade and only implemented package
at the Step 5 foundation state;
- the intended dependency direction: public facade to internal framework
components, with internal components depending on narrow abstractions rather
than on consumers or Scriptorium;
- Scriptorium as a downstream application boundary, not an internal Promptkit
package;
- package ownership, exported-API discipline, error-boundary expectations, and
dependency-injection principles that future extraction work must preserve;
- the rule that implementation packages remain internal unless a stable public
contract requires otherwise;
- no committed workspace coupling or local module replacement;
- no binary, CLI, HTTP-server, deployment, or application-configuration
ownership in Promptkit; and
- the relationship between this high-level policy and
`docs/internal/overview.md`.
Describe future package boundaries as constraints on Step 6, not as current
implemented components.
### Testing Policy
Revise `docs/policy/testing.md` only as needed to make it accurate for
Promptkit. Preserve its deterministic, offline, behavior-focused standards.
Specifically:
- describe the subject as a library or project rather than an application;
- make required maintainer-run checks the active validation model;
- remove language that represents hosted CI as an existing workflow;
- retain requirements that tests be deterministic, parallel-safe, and free of
live network dependencies;
- retain appropriate guidance for unit, integration, contract, fixture,
golden-file, and failure-path tests; and
- phrase golden-file safeguards in terms of validation runs rather than a CI
system that does not exist.
The policy may permit future hosted CI, but must not require or document it as
current state.
### Internal Architecture Inventory
Create `docs/internal/overview.md` as the current component inventory. It must:
- identify the root `promptkit` package as the sole implemented Go package;
- describe its present role without claiming migrated framework behavior;
- state that no internal framework packages exist yet;
- link to the architecture policy for durable boundary rules;
- link to `docs/development.md` for contributor workflow; and
- state that the inventory must be updated as Step 6 introduces components.
Do not include aspirational packages in the implemented-component table.
### Stage 3 Validation
From the Promptkit repository:
1. Check every Markdown link added or changed in this stage.
2. Search policy and internal documentation for stale template terms,
misspellings, Scriptorium application commands, and unsupported current
claims. At minimum inspect matches from:
```sh
rg -n -i 'go-application-template|cmd/scriptorium|thsi|thos|todo|hosted ci|application' docs
```
Review legitimate contextual uses rather than deleting them mechanically.
3. Confirm the documentation policy names all four permitted ADR statuses.
4. Confirm the architecture policy and internal overview agree that the root
package is the only implemented component.
5. Confirm no roadmap detail or future API specification was copied into a
permanent current-state document.
6. Run `git diff --check`.
### Stage 3 Completion Gate
Proceed only when Promptkit's permanent policy and architecture documents are
self-consistent, library-specific, accurate for the foundation state, and free
of claims that hosted CI or migrated framework packages already exist.
## Stage 4: Complete Promptkit Orientation, Development, and Release Guidance
### Objective
Give maintainers and prospective consumers an accurate repository entry point,
a usable local workflow, and a complete manual release procedure.
### Repository README
Rewrite `README.md` as a concise Promptkit orientation document. It must:
- identify Promptkit as the reusable Go framework being separated from
Scriptorium;
- show module path `gitea.maximumdirect.net/eric/promptkit`;
- state that Step 5 establishes the repository foundation and framework APIs
have not yet been extracted;
- avoid speculative install or usage examples;
- link to `docs/development.md` and `docs/policy/architecture.md`; and
- identify GPLv3 as the current license.
Do not make the README depend on a temporary Scriptorium roadmap for basic
orientation.
### Contributor Guide
Rewrite `docs/development.md` as Promptkit's contributor entry point. It must:
- direct all contributors to read `docs/policy/architecture.md`;
- retain a task-specific reading guide for documentation, tests, public API,
internal packages, integrations, and releases;
- link only to documents that exist, using conditional instructions for
subsystem documents introduced later;
- list the default validation sequence:
```sh
go test ./...
go vet ./...
go build ./...
```
- require tracked-Go-file formatting checks, Markdown-link validation, and
`git diff --check`;
- describe test filtering and targeted package validation without referring to
nonexistent packages;
- explain that Promptkit has no hosted CI and maintainers run the checks;
- explain temporary sibling integration through a local Go workspace or an
uncommitted `replace` directive; and
- prohibit committing `go.work`, `go.work.sum`, or local `replace` directives.
The workspace example must use repository-relative or clearly illustrative
paths, explain its working directory and cleanup, and avoid the maintainer's
absolute filesystem path.
Keep `AGENTS.md` as the short route to `docs/development.md`; update it only if
its link or wording is inaccurate.
### Release Procedure
Create `docs/release.md` as the canonical Promptkit release procedure. It must:
- state that Promptkit publishes a Go library through source commits and
semantic version tags;
- state that it publishes no binaries and currently uses no hosted CI;
- require a clean checkout and working tree;
- require the complete documented local validation suite before tagging;
- include review of module path, Go version, links, formatting, repository
hygiene, and absence of committed workspace overrides;
- describe annotated semantic-version tag creation and publication without a
hosting-provider-specific release UI;
- require the annotated tag message to identify the release and record that the
documented validation suite passed for the tagged commit;
- require post-push verification that the tag resolves to the intended commit;
- explain that the first `v0.1.0` tag is created only after Step 6 extraction
and validation; and
- require documentation before future changes to hosted automation, binary
artifacts, or release governance.
Do not create a release tag while implementing Step 5.
### Stage 4 Validation
From the Promptkit repository:
1. Follow every internal link in `README.md`, `AGENTS.md`,
`docs/development.md`, and `docs/release.md`.
2. Confirm documented commands work from their stated directories.
3. Confirm development and release guides use the same validation commands.
4. Search maintained documentation for stale template and Scriptorium
application commands, hosted-CI or binary claims, claims that framework APIs
exist, and absolute maintainer-specific paths.
5. Confirm no temporary workspace or replacement file was created or staged.
6. Run `git diff --check`.
### Stage 4 Completion Gate
Proceed only when a new contributor can orient, validate, and understand the
future release process using Promptkit's own maintained documentation, with no
dependency on hidden CI or unpublished framework APIs.
## Stage 5: Perform Cross-Repository Acceptance and Close Step 5
### Objective
Validate the foundation independently, verify both repositories tell the same
migration story, and update planning status only after all checks succeed.
### Promptkit Acceptance Validation
Start from Promptkit with no active parent or repository-local Go workspace and
no local module replacement. Run:
Complete as of 2026-07-28.
This record summarizes the completed implementation of
[Migration Step 5: Promptkit Repository Foundation](step5.md). The
[main migration roadmap](migration.md) owns the continuing cross-repository
sequence.
## Completed Work
### Validation And Release Decision
- Added accepted
[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md)
for maintainer-run Promptkit validation and source-and-tag releases.
- Preserved accepted
[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) and its repository
split, ownership, independent versioning, and release-order decisions.
- Reconciled the migration roadmap so Promptkit validation no longer depends on
hosted CI or binary packaging.
### Promptkit Module And License
- Created module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`.
- Added the root `promptkit` package as the only implemented Go package.
- Kept the module dependency-free and added no placeholder implementation.
- Preserved GPLv3 wording and attribution while changing the two template
example-notice project names to `Promptkit`.
- Confirmed the existing ignore rules cover Go output, editor and operating
system artifacts, `.env`, `go.work`, and `go.work.sum`.
### Policies And Architecture
- Replaced template documentation and architecture material with durable
library-specific policies.
- Assigned canonical documentation ownership, including conditional ownership
for public contracts, integrations, internal subsystems, ADRs, roadmaps, and
examples that may exist later.
- Defined the root facade, internal-package direction, consumer boundary,
exported-API discipline, error boundary, dependency injection, and repository
independence constraints for future extraction.
- Updated testing policy for deterministic, offline, parallel-safe,
behavior-focused, maintainer-run validation.
- Recorded the root package as the sole implemented component.
### Orientation, Development, And Releases
- Rewrote the Promptkit README without claiming unimplemented APIs.
- Replaced the contributor guide with task routing, complete local validation,
focused checks, and safe sibling-repository workflows.
- Added the canonical release procedure for annotated semantic Go module tags,
validation evidence, publication verification, and consumer release ordering.
- Added no hosted CI, binary packaging, executable command, or release tag.
### Cross-Repository Acceptance
Promptkit passed, without an active workspace or local replacement:
```sh
go test ./...
@@ -426,71 +67,24 @@ gofmt -l $(git ls-files '*.go')
git diff --check
```
The formatting command must produce no output. Also:
Acceptance also verified exact module and package metadata, all maintained
Markdown links, clean repository hygiene, the Promptkit origin and tracked
default branch, the absence of dependencies and prohibited artifacts, and the
retained GPLv3 license.
1. Use `go list -m -f '{{.Path}} {{.GoVersion}}'` to confirm the exact module
path and Go version.
2. Use `go list -f '{{.Name}} {{.ImportPath}}' .` to confirm the root package.
3. Confirm `go.mod` has no `replace` and no unnecessary dependency.
4. Confirm no `go.work`, `go.work.sum`, CI configuration, command, release
artifact, version tag, or placeholder package was added.
5. Use `git remote get-url origin` to confirm the origin belongs to Promptkit,
not Scriptorium.
6. Use `git branch -vv` and
`git rev-parse --abbrev-ref --symbolic-full-name '@{upstream}'` to confirm
the current default branch tracks the intended Promptkit remote branch.
7. Check every maintained Markdown link.
8. Search the repository for stale template naming and investigate each match.
9. Confirm `LICENSE` remains GPLv3 with Promptkit-specific notices and unchanged
attribution.
Scriptorium acceptance confirmed that ADR 0003 and the migration roadmap
distinguish Scriptorium's executable CI policy from Promptkit's maintainer-run
checks, preserve the first-tag release gate, and introduce no production code,
module dependency, workspace, or replacement change.
If a check fails, correct the owning stage and repeat the complete suite.
## Repository Boundaries
### Scriptorium Acceptance Validation
Promptkit foundation changes remain in Promptkit's Git history. Scriptorium
contains only the durable cross-project ADR and migration-roadmap records. No
tag was created and neither repository was pushed as part of this work.
From Scriptorium:
## Next Work
1. Confirm the new ADR and `docs/roadmap/migration.md` distinguish
Scriptorium's CI from Promptkit's maintainer-run checks.
2. Confirm Step 6 still requires Promptkit validation and its first release tag
before Scriptorium changes its dependency.
3. Check every changed Markdown link.
4. Run `git diff --check`.
5. Confirm no Scriptorium production code, module dependency, workspace file,
or local replacement changed during Step 5.
### Planning-State Updates
Only after both acceptance suites pass:
- change `docs/roadmap/step5.md` from Accepted scope to Complete and replace its
future-oriented lifecycle text with a concise completion record;
- update `docs/roadmap/migration.md` to mark Step 5 complete, record successful
maintainer-run validation, and identify Step 6 as the next gate; and
- revise this file so completed stages appear as a concise `Completed Work`
summary rather than an active execution checklist.
Do not delete the Step 5 roadmap while its completion record remains useful,
and do not create a Step 6 roadmap incidentally.
### Repository and Publication Boundaries
Before handoff:
- keep Promptkit changes in the Promptkit repository only;
- keep the ADR and migration-roadmap changes in Scriptorium only;
- review each repository's diff independently; and
- do not publish a Promptkit tag or push either repository unless separately
requested.
### Stage 5 Completion Gate
Step 5 is complete only when every feature-roadmap criterion is satisfied, both
repositories are internally coherent, all checks pass without workspace
overrides, and the Scriptorium roadmap records Step 6 as the next authorized
work.
## Open Questions
None. The Step 5 roadmap and confirmed governance, validation, and licensing
choices are sufficient to implement this plan without further design decisions.
Migration Step 6 may now extract and stabilize the application-neutral
framework. It must not update Scriptorium to consume Promptkit until Promptkit
passes its documented validation and publishes its first versioned tag.

40
docs/roadmap/migration.md
View File

@@ -2,7 +2,7 @@
## Status
Accepted plan. Steps 1 through 4 are complete. Steps 5 through 9 remain
Accepted plan. Steps 1 through 5 are complete. Steps 6 through 9 remain
proposed and are not yet implemented.
## Objective
@@ -182,33 +182,31 @@ creation is next.
### Step 5: Create The Promptkit Repository
Create the Promptkit repository and Go module as an explicit out-of-band
operation.
Promptkit was established as an independent repository and Go module through
the out-of-band workflow recorded in the
[Step 5 completion record](step5.md). Its foundation includes:
Establish:
- repository access, ownership, and branch protections;
- the module path selected by the ADR;
- baseline development, architecture, documentation, and release policies;
- confirmed repository access, governance, origin, and default-branch tracking;
- module `gitea.maximumdirect.net/eric/promptkit` at Go `1.25.5`;
- a minimal root `promptkit` public package boundary with no placeholder
framework packages;
- library-specific development, architecture, documentation, testing, and
release policies;
- documented maintainer-run test, vet, build, formatting, documentation-link,
and repository-hygiene validation;
- a tag-based release procedure for source commits and semantic Go module tags,
without runnable binaries or binary packaging;
- an initial package layout centered on a small public facade with internal
implementation packages;
- a local development workflow for coordinated Promptkit and Scriptorium
changes, using a workspace or temporary uncommitted module replacement where
appropriate.
- source-commit and semantic Go module tag releases without runnable binaries
or binary packaging; and
- temporary workspace and uncommitted replacement workflows for coordinated
development without committed repository coupling.
Do not commit local filesystem `replace` directives to release branches.
[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md)
records the controlling Promptkit validation and release decision.
**Gate:** The Promptkit repository exists, is accessible to maintainers, has
documented maintainer-run validation and tag-based release procedures, has the
required policy scaffolding, and can receive the extracted framework. Do not
begin cross-repository extraction until this out-of-band work is confirmed
complete.
**Gate status:** Complete as of 2026-07-28. Promptkit passed its documented
validation independently, all maintained links and repository-hygiene checks
passed, and no workspace, replacement, CI configuration, binary, tag, command,
or placeholder package was added. Framework extraction and stabilization in
Step 6 is the next gate.
### Step 6: Extract And Stabilize Promptkit

362
docs/roadmap/step5.md
View File

@@ -2,252 +2,63 @@
## Status
Accepted scope. The Promptkit repository exists and its governance has been
confirmed, but the repository foundation is not complete until the target state
and completion criteria below are satisfied.
Complete as of 2026-07-28.
## Purpose
Establish Promptkit as an independent, maintainable Go library repository that
is ready to receive the framework extraction in Migration Step 6.
Establish Promptkit as an independent, maintainable Go library repository ready
to receive framework extraction in Migration Step 6 without moving framework
behavior prematurely.
This step creates the repository and its durable project scaffolding; it does
not extract framework behavior. The
[main migration roadmap](migration.md) owns the overall sequence, and
[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) owns the selected
project boundary, module path, versioning direction, and cross-repository
ownership decisions.
The [main migration roadmap](migration.md) owns the overall sequence.
[ADR 0002](../adr/0002-split-promptkit-from-scriptorium.md) owns the repository
boundary, module path, versioning direction, and cross-repository ordering.
[ADR 0003](../adr/0003-use-maintainer-run-validation-and-tag-only-releases-for-promptkit.md)
owns the maintainer-run validation and tag-only release decision.
## Confirmed Decisions
## Completed Work
- The repository is named `promptkit`, is accessible at its configured origin,
and has the intended maintainer governance and branch protections. No further
governance work is required for Step 5.
- Promptkit is a Go library and will not publish executable binaries.
- Promptkit will not use a hosted CI integration at this stage. Maintainers will
run and record the repository's required validation before merging and
tagging.
- Promptkit will remain licensed under GPLv3 for now. A future license change is
a separate legal and project decision.
- The first Promptkit release remains planned as `v0.1.0`, but creating that tag
belongs to Step 6 after the framework is extracted and validated.
### Repository And Module Foundation
## Target Repository State
- Confirmed the Promptkit repository, maintainer governance, configured origin,
and `main` tracking of `origin/main`.
- Created dependency-free module
`gitea.maximumdirect.net/eric/promptkit` with Go `1.25.5`.
- Added the root `promptkit` package as the sole implemented Go package and
public package boundary.
- Added no framework implementation, exported API, internal package,
speculative package tree, command, workspace file, or local replacement.
- Retained GPLv3 and changed only the two template project names in its example
notices to `Promptkit`.
Promptkit is a valid standalone Go module with a minimal public package and
project-specific repository guidance. A fresh checkout can be understood,
validated, and used for coordinated local extraction work without relying on
undocumented Scriptorium knowledge or committed machine-local configuration.
### Durable Repository Guidance
The repository remains intentionally small:
- Replaced application-template architecture, documentation, and testing
policies with library-specific policies.
- Recorded the root package as the only implemented component and kept future
framework boundaries explicitly unimplemented.
- Rewrote repository orientation and contributor workflow for the Promptkit
module.
- Documented deterministic, offline, parallel-safe, maintainer-run validation.
- Documented temporary sibling workspace and uncommitted replacement workflows
without committing machine-local coupling.
- Added a semantic Go module tag release procedure with no runnable binaries or
hosted CI.
```text
promptkit/
├── go.mod
├── doc.go
├── README.md
├── LICENSE
├── AGENTS.md
└── docs/
├── development.md
├── release.md
├── internal/
│ └── overview.md
└── policy/
├── architecture.md
├── documentation.md
└── testing.md
```
### Decision Reconciliation
Additional files are appropriate only when they describe or validate the
implemented repository foundation. Do not create empty `internal/`, `examples/`,
consumer, integration, or ADR directories merely to reserve future structure.
- Accepted ADR 0003 as the later controlling decision for Promptkit validation
while leaving ADR 0002 Accepted and its repository-split decision unchanged.
- Reconciled the main migration roadmap with maintainer-run validation,
tag-only releases, and the requirement that Promptkit publish its first
versioned tag before Scriptorium adopts it.
## Go Module And Package Foundation
## Acceptance Record
The repository will define:
From a clean Promptkit checkout with no active Go workspace or local
replacement, the maintainer successfully ran:
- module path `gitea.maximumdirect.net/eric/promptkit`;
- Go version `1.25.5`, matching Scriptorium during the extraction;
- a root package named `promptkit`; and
- no external dependencies until implemented code requires them.
The root `doc.go` will contain an accurate package comment and package
declaration. It establishes the public package boundary but must not claim that
the future engine, profiles, loaders, clients, or validation features have
already been extracted.
Promptkit implementation will live under `internal/` once Step 6 moves real
implementation packages. No placeholder public subpackages or empty internal
packages are needed in Step 5. The supported public facade will remain centered
at the module root as required by ADR 0002.
The foundation must support:
```bash
go test ./...
go vet ./...
go build ./...
```
These commands validate packages only; they do not build or package a binary.
## Architecture And Dependency Policy
Promptkit's architecture policy will describe the implemented Step 5 shape and
the boundaries that later extraction must preserve:
- the module root is the supported public facade;
- implementation packages belong under `internal/`;
- consumer extension points become public only when a demonstrated consumer
requires them;
- Promptkit owns application-neutral prompt-execution behavior;
- CLI, HTTP, process, deployment, and executable-release concerns do not belong
in Promptkit; and
- future package movement must follow the ownership recorded by ADR 0002.
The architecture document must distinguish the implemented empty foundation
from the accepted future extraction. Detailed future package and feature claims
remain in Scriptorium's migration roadmap until they are implemented.
The internal overview will inventory only implemented components. At Step 5
completion it will identify the root package and repository guidance; it will
not contain template tables or describe uncreated framework packages.
## Documentation And Contributor Foundation
Promptkit's repository documentation will be rewritten for a reusable Go
library rather than copied from an executable application template.
### README
The README will:
- identify Promptkit and its module path;
- explain that the repository foundation exists but framework extraction is
still pending;
- avoid presenting unimplemented APIs as available;
- point contributors to `docs/development.md`; and
- state the GPLv3 license without providing legal interpretation.
A consumer quickstart is not required until Step 6 provides a usable public
API.
### Contributor Guide
`docs/development.md` will:
- describe Promptkit as a library;
- provide a task-specific reading guide for the current repository;
- use `go test ./...`, `go vet ./...`, and `go build ./...` as the baseline;
- remove Scriptorium command and executable references; and
- document coordinated local work with Scriptorium.
The coordinated workflow will permit either:
- a temporary Go workspace containing the sibling Promptkit and Scriptorium
modules; or
- an uncommitted local `replace` directive in the consuming module.
The guide must not hard-code a maintainer's absolute filesystem path.
`go.work`, `go.work.sum`, and local filesystem `replace` directives must not be
committed. Each repository must remain independently valid outside the shared
workspace.
### Documentation Policy
The documentation policy will be tailored to a library:
- remove template typos and executable-only ownership categories that do not
apply;
- assign canonical ownership for the README, public Go consumer contract,
contributor guide, architecture, testing, releases, internal components,
integrations, ADRs, roadmaps, and maintained examples when those materials
exist;
- retain the current-versus-future behavior rule;
- retain the security, privacy, example, and canonical-owner rules; and
- use the same enumerated ADR statuses and immutable accepted-decision policy
established in Scriptorium.
Promptkit does not need repository-local ADRs at Step 5. Remove links to a
nonexistent ADR directory; create that directory only when Promptkit has a
repository-local architectural decision to record. Cross-project migration
decisions remain owned by Scriptorium.
### Testing Policy
The existing risk-based testing philosophy may remain, but it must consistently
refer to Promptkit as a library or project rather than a generic application.
Its default suite must be offline, deterministic, credential-free, and runnable
manually from a fresh checkout.
## Manual Validation And Release Policy
Promptkit will use maintainer-run validation instead of hosted CI. This is an
intentional policy choice, not a temporary missing integration.
`docs/release.md` will be the canonical Promptkit release guide. It will state:
- releases are Go module tags and do not contain binary artifacts;
- semantic-versioning begins with the planned `v0.1.0`;
- the release maintainer must run the documented full test, vet, build,
formatting, link, and whitespace checks before tagging;
- the repository and module must be clean and independently valid without a
local workspace or replacement;
- Promptkit must be tagged before Scriptorium or another consumer publishes a
release depending on that version;
- released consumer modules must use a tagged Promptkit version rather than a
local replacement or unpublished revision; and
- release notes should identify intentional public API changes while Promptkit
remains pre-`v1`.
Step 5 establishes this policy but does not create `v0.1.0`. Step 6 owns the
first releasable framework version and its tag.
No CI configuration, CI badge, executable packaging, or binary release
workflow is required.
## Decision-Record Reconciliation
The no-CI decision changes the automation assumption recorded in accepted ADR
0002 and in the main migration roadmap. Accepted ADR decision text remains
unchanged.
At completion, the controlling records have this state:
- A later accepted Scriptorium ADR records maintainer-run Promptkit validation
and tag-only library releases in place of hosted Promptkit CI and binary
packaging.
- That decision links to ADR 0002 as a refinement of its validation and
release-coordination provisions without changing the accepted project split.
- The Step 5 and later affected gates in `migration.md` require the documented
manual validation rather than CI.
- The repository boundary, module path, ownership, versioning, tagging order,
and no-committed-replacement decisions from ADR 0002 remain unchanged.
The new ADR records the durable policy decision. This roadmap continues to own
implementation status and completion.
## License And Repository Hygiene
Promptkit retains the existing GPLv3 license text. The example notices at the
end of `LICENSE` name `Promptkit` rather than `go-application-template`. The
license version and existing copyright attribution remain unchanged.
Repository hygiene will retain:
- ignore rules for Go build/test outputs, editor and operating-system files,
`.env`, `go.work`, and `go.work.sum`;
- no committed credentials, private data, generated binaries, coverage output,
workspace files, or local replacements;
- no dependency changes unsupported by implemented code; and
- clean Markdown links and whitespace.
## Required Validation Outcome
From a clean Promptkit checkout, maintainers must successfully run:
```bash
```sh
go test ./...
go vet ./...
go build ./...
@@ -255,72 +66,29 @@ gofmt -l $(git ls-files '*.go')
git diff --check
```
The `gofmt` command must produce no Go source paths. Maintainers must also:
The formatting command produced no paths. Acceptance also confirmed:
- validate all local Markdown links;
- confirm the module path, root package name, and Go version;
- confirm the repository contains no `go.work`, `go.work.sum`, or local
`replace` directive;
- confirm the origin and tracked default branch are correct;
- inspect the final file inventory for template residue and unsupported future
claims; and
- record the successful manual validation in the Step 5 completion update.
- module path `gitea.maximumdirect.net/eric/promptkit`, Go `1.25.5`, root
package `promptkit`, and matching import path;
- no external dependency, `go.sum`, `go.work`, `go.work.sum`, or `replace`
directive;
- no hosted CI configuration, command package, release artifact, version tag,
or placeholder framework package;
- every maintained Markdown link resolves;
- repository orientation, policies, inventory, contributor workflow, and
release procedure are internally consistent and free of template residue;
- the configured origin belongs to Promptkit and `main` tracks `origin/main`;
- GPLv3 wording and attribution remain unchanged apart from the two approved
Promptkit example-notice names; and
- Scriptorium contains only the decision and roadmap documentation required for
this foundation work, with no production code or module dependency change.
The Scriptorium repository requires documentation validation for the new ADR,
this feature roadmap, and the reconciled main migration roadmap. No Scriptorium
code change or full executable test suite is required solely for the Promptkit
foundation, unless implementation work unexpectedly changes Scriptorium code
or maintained examples.
## Scope Boundary And Next Gate
## Out Of Scope
No framework implementation or public framework API was extracted, no consumer
was migrated, and no `v0.1.0` tag was created. Promptkit remains an independently
valid repository foundation.
Step 5 does not:
- extract or copy framework implementation from Scriptorium;
- add Promptkit engine, request, result, profile, source, validation, artifact,
or model-client APIs;
- create placeholder internal packages or consumer examples;
- tag or publish `v0.1.0`;
- update Scriptorium to import Promptkit;
- migrate downstream consumers;
- add CI integration or release binaries;
- reconsider GPLv3 beyond removing the template project name; or
- change the accepted Promptkit/Scriptorium ownership boundary.
Those changes belong to Steps 6 through 8 or to a separately accepted decision.
## Completion Criteria
Step 5 is complete when:
- the confirmed Promptkit governance remains in place and its origin and
tracked default branch are correct;
- Promptkit is a standalone module at
`gitea.maximumdirect.net/eric/promptkit` with Go `1.25.5` and a minimal root
`promptkit` package;
- repository documentation and policies are Promptkit-specific, internally
consistent, free of template residue, and accurate for the implemented
foundation;
- architecture and internal inventory clearly distinguish the current
foundation from the future framework extraction;
- contributor guidance documents the manual validation and safe
cross-repository development workflow;
- the tag-only, no-binary release policy and pre-`v1` coordination rules are
documented;
- the no-CI decision is recorded in a new accepted ADR and reconciled with the
main migration roadmap;
- GPLv3 remains in place with corrected Promptkit example notices;
- Promptkit passes every required manual validation check independently of
Scriptorium and without a workspace or local replacement;
- no framework extraction, consumer migration, tag, compatibility layer, or
unrelated work is included; and
- `migration.md` records Step 5 as complete and identifies framework extraction
and stabilization in Step 6 as the next gate.
Migration Step 6 must not begin until these criteria are satisfied.
## Lifecycle
This feature roadmap is a temporary migration artifact. It may be removed after
Step 5 is complete and no longer needs to guide active work; repository history
will retain the accepted scope and completion record.
Migration Step 6 is now authorized to extract and stabilize the framework. It
must pass Promptkit's documented validation and publish the first versioned tag
before Scriptorium or another consumer adopts the module.