scriptorium/docs/roadmap/step5.md

# Migration Step 5: Promptkit Repository Foundation

## 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.

## Purpose

Establish Promptkit as an independent, maintainable Go library repository that
is ready to receive the framework extraction in Migration Step 6.

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.

## Confirmed Decisions

- 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.

## Target Repository State

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.

The repository remains intentionally small:

```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
```

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.

## Go Module And Package Foundation

The repository will define:

- 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
go test ./...
go vet ./...
go build ./...
gofmt -l $(git ls-files '*.go')
git diff --check
```

The `gofmt` command must produce no Go source paths. Maintainers must also:

- 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.

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.

## Out Of Scope

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.