64 lines
3.7 KiB
Markdown
64 lines
3.7 KiB
Markdown
# 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:
|
|
|
|
1. inspect the working tree and preserve unrelated changes;
|
|
2. read the architecture policy for code or design work;
|
|
3. read the policy, contract, and internal documents listed for the task;
|
|
4. inspect the relevant implementation and tests before deciding how to change
|
|
them.
|
|
|
|
Start with:
|
|
|
|
- [Architecture policy](policy/architecture.md) for system boundaries,
|
|
invariants, and non-goals;
|
|
- [Internal component overview](internal/overview.md) for the current package
|
|
and component map;
|
|
- [Documentation policy](policy/documentation.md) before changing
|
|
documentation;
|
|
- [Testing policy](policy/testing.md) before adding, rewriting, or deleting
|
|
tests.
|
|
|
|
## Task-Specific Reading Guide
|
|
|
|
| Task | Read before changing |
|
|
| --- | --- |
|
|
| Repository orientation or component responsibility | [Internal component overview](internal/overview.md) and [architecture policy](policy/architecture.md) |
|
|
| Public Go package or engine behavior | [Go package consumer contract](consumers/pkg-scriptorium.md), [internal component overview](internal/overview.md), [runner internals](internal/runner.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
|
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md), [internal component overview](internal/overview.md), and [adapter internals](internal/adapters.md) |
|
|
| HTTP routes, DTOs, limits, or status mapping | [HTTP API contract](api.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
|
| Application configuration | [Configuration contract](config.md), [internal component overview](internal/overview.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
|
| Prompt, profile, schema, or artifact loading | [Configuration contract](config.md), [internal component overview](internal/overview.md), and [source internals](internal/sources.md) |
|
|
| Runner orchestration, rendering, validation, or repair | [Runner internals](internal/runner.md) and [source internals](internal/sources.md) |
|
|
| OpenAI-compatible request or response behavior | [OpenAI-compatible integration](integrations/openai-compatible-chat.md), [LLM internals](internal/llm.md), [runner internals](internal/runner.md), and [adapter internals](internal/adapters.md) |
|
|
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
|
|
| Runtime operation or recovery | [Operations](operations.md) |
|
|
| 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](policy/documentation.md), relevant accepted ADRs such as [ADR 0001](adr/0001-adopt-canonical-documentation-ownership.md), 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:
|
|
|
|
```bash
|
|
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.
|