scriptorium/docs/development.md

Development

This is the contributor entry point for Scriptorium. Scriptorium is an application that consumes the public Promptkit v0.11.2 package; framework implementation work belongs in Promptkit. Application configuration uses ConfigKit v0.4.2; keep Scriptorium's schema and source selection local.

Initial Orientation

Before recommending, planning, or implementing work:

1. inspect the working tree and preserve unrelated changes;
2. use the policy and task-specific reading guides below; and
3. inspect the relevant implementation and tests before changing them.

Policy Reading Guide

Policy	Read before…
Policy set provenance	Adopting policies, checking upstream revisions, or updating the adopted policy set.
Agents	Recommending, planning, or implementing repository changes.
Architecture	Planning or changing application code or its structure.
Testing	Selecting validation for code changes, or adding, changing, removing, or evaluating tests.
Documentation	Writing, revising, or reorganizing documentation.
OSS	Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution.
Release	Preparing or publishing a release, changing release procedures, or making versioning and compatibility decisions.

• Read applicable policies before making decisions they govern; multiple policies may apply.
• Select policies using the task triggers above. Follow cross-references to relevant sections when needed to resolve a concrete question.
• Reuse policies already available in context; reread when changed or no longer available.
• Expand reading when the task's scope expands.
• When revising a policy itself, read that policy and any provisions elsewhere affected by the revision.

Task-Specific Reading Guide

Task	Read before changing
Repository orientation or component responsibility	Internal component overview and architecture policy
CLI commands, flags, output, or exit behavior	CLI contract and adapter internals
HTTP routes, DTOs, limits, status mapping, or artifact policy	HTTP API contract, adapter internals, and source internals
Application configuration or precedence	Configuration contract, adapter internals, source internals, and internal/config definition/load tests
Prepared-run presentation	CLI contract, adapter internals, and internal/format
Prompt, profile, schema, generation, or validation semantics	Promptkit framework formats and the Promptkit consumer guide
OpenAI-compatible outbound behavior or timeout layering	Promptkit integration contract
Subprocess behavior	Subprocess integration and CLI contract
Runtime operation or recovery	Operations
Dependencies, copied assets, or attribution	The OSS policy, component attributions, and architecture policy
Release documentation, packaging, or publication	The release policy, OSS policy, release procedure, hosted release workflow, and architecture policy
Examples or copyable assets	The owning Scriptorium contract, the relevant Promptkit format contract, and the related files under examples/
Architecture decisions or future work	The documentation policy, relevant accepted ADRs, and relevant roadmap documents

Cross-project changes land and release in Promptkit before Scriptorium adopts the tagged version. Do not commit a Go workspace, local replacement, vendored Promptkit source, or an import of a Promptkit internal package.

Baseline Validation

For code changes, run:

go test ./...
go test -race ./...
go vet ./...
go build ./cmd/scriptorium

Check formatting with gofmt, run git diff --check, and validate affected examples and documentation links. Documentation-only work does not require unrelated new tests, but commands and examples changed by documentation must be run.