6.0 KiB
Development
This is the contributor entry point for Scriptorium. Scriptorium is an application that consumes the public PromptKit v0.23.2 package; framework implementation work belongs in Promptkit. Application configuration uses ConfigKit v1.2.1; keep Scriptorium's schema and source selection local. PromptKit uses the same ConfigKit release to load framework sources under its own separate schema and format contract.
Initial Orientation
Before recommending, planning, or implementing work:
- inspect the working tree and preserve unrelated changes;
- use the policy and task-specific reading guides below; and
- 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 |
| Promptkit source selection or captured framework inspection | Configuration contract, framework configuration CLI contract, and source internals |
| Prompt, profile, schema, generation, or validation semantics | PromptKit v0.23.2 framework formats and the Promptkit consumer guide |
| OpenAI-compatible outbound behavior or timeout layering | PromptKit v0.23.2 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 v0.23.2 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.
The module graph can include upstream maintainer tools such as ReleaseKit and
their dependencies even though those graph-only packages are not linked into
the Scriptorium runtime; use go list -deps ./cmd/scriptorium to distinguish
the linked packages.
Baseline Validation
The Go consumer minimum is the version declared in go.mod, currently 1.27.0,
required by application ConfigKit v1.2.1. Running a published binary does not
require a Go installation. Release validation and builds use
the separately selected toolchain in the release procedure.
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.