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.