scriptorium/docs/roadmap/implementation.md

# Step 5 Implementation Plan

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

```sh
go test ./...
go vet ./...
go build ./...
gofmt -l $(git ls-files '*.go')
git diff --check
```

The formatting command must produce no output. Also:

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.

If a check fails, correct the owning stage and repeat the complete suite.

### Scriptorium Acceptance Validation

From Scriptorium:

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.