3.7 KiB
Development
This is the contributor entry point for Scriptorium. Use the task-specific reading guide below before making changes. Canonical architecture, contracts, component behavior, and policies remain in their owning documents.
Initial Orientation
Before starting work:
- inspect the working tree and preserve unrelated changes;
- read the architecture policy for code or design work;
- read the policy, contract, and internal documents listed for the task;
- inspect the relevant implementation and tests before deciding how to change them.
Start with:
- Architecture policy for system boundaries, invariants, and non-goals;
- Internal component overview for the current package and component map;
- Documentation policy before changing documentation;
- Testing policy before adding, rewriting, or deleting tests.
Task-Specific Reading Guide
| Task | Read before changing |
|---|---|
| Repository orientation or component responsibility | Internal component overview and architecture policy |
| Public Go package or engine behavior | Go package consumer contract, internal component overview, runner internals, adapter internals, and source internals |
| CLI commands, flags, output, or exit behavior | CLI contract, internal component overview, and adapter internals |
| HTTP routes, DTOs, limits, or status mapping | HTTP API contract, internal component overview, adapter internals, and source internals |
| Application configuration | Configuration contract, internal component overview, adapter internals, and source internals |
| Prompt, profile, schema, or artifact loading | Configuration contract, internal component overview, and source internals |
| Runner orchestration, rendering, validation, or repair | Runner internals and source internals |
| OpenAI-compatible request or response behavior | OpenAI-compatible integration, runner internals, and adapter internals |
| Subprocess behavior | Subprocess integration and CLI contract |
| Runtime operation, recovery, or troubleshooting | Operations and troubleshooting |
| Examples or copyable assets | The owning contract for the demonstrated behavior and the related files under examples/ |
| Architecture decisions or future work | The documentation policy, relevant accepted ADRs such as ADR 0001, and relevant roadmap documents under roadmap/ |
For cross-cutting changes, follow every applicable row. Internal component documents own detailed subsystem change recipes.
Baseline Validation
Use focused checks while iterating, then run validation proportionate to the change and the risks described by the testing policy.
The repository-level baseline for code changes is:
go test ./...
go vet ./...
go build ./cmd/scriptorium
Documentation-only work does not require the full Go suite unless it changes commands, examples, generated output, or another behavior that the suite validates. Always check changed links, paths, examples, and canonical ownership.