scriptorium/docs/development.md

Development

This is the contributor entry point for Scriptorium. Scriptorium is an application that consumes the public Promptkit v0.1.0 package; framework implementation work belongs in Promptkit.

Initial Orientation

Before starting work:

1. inspect the working tree and preserve unrelated changes;
2. read the architecture policy;
3. follow the task-specific contracts and internal documents below; and
4. inspect the relevant implementation and tests before changing them.

Also read the documentation policy before changing documentation and the testing policy before changing tests.

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, and source internals
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
Release packaging or publication	The 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.