scriptorium/docs/roadmap/implementation.md

Step 5 Implementation Plan

Status

Proposed.

This plan implements Migration Step 5: Promptkit Repository Foundation. 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 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:

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:

   go test ./...
   go vet ./...
   go build ./...
   

3. Confirm module metadata:

   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:

   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:

  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:

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.