76 lines
4.9 KiB
Markdown
76 lines
4.9 KiB
Markdown
# Development
|
|
|
|
This is the contributor entry point for Scriptorium. Scriptorium is an
|
|
application that consumes the public
|
|
[Promptkit v0.11.1 package](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md);
|
|
framework implementation work belongs in Promptkit. Application configuration
|
|
uses ConfigKit v0.4.1; 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](policy/meta.md) | Adopting policies, checking upstream revisions, or updating the adopted policy set. |
|
|
| [Agents](policy/agents.md) | Recommending, planning, or implementing repository changes. |
|
|
| [Architecture](policy/architecture.md) | Planning or changing application code or its structure. |
|
|
| [Testing](policy/testing.md) | Selecting validation for code changes, or adding, changing, removing, or evaluating tests. |
|
|
| [Documentation](policy/documentation.md) | Writing, revising, or reorganizing documentation. |
|
|
| [OSS](policy/oss.md) | Adding or updating dependencies or incorporated third-party material, or changing licensing or attribution. |
|
|
| [Release](policy/release.md) | 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](internal/overview.md) and [architecture policy](policy/architecture.md) |
|
|
| CLI commands, flags, output, or exit behavior | [CLI contract](cli.md) and [adapter internals](internal/adapters.md) |
|
|
| HTTP routes, DTOs, limits, status mapping, or artifact policy | [HTTP API contract](api.md), [adapter internals](internal/adapters.md), and [source internals](internal/sources.md) |
|
|
| Application configuration or precedence | [Configuration contract](config.md), [adapter internals](internal/adapters.md), [source internals](internal/sources.md), and `internal/config` definition/load tests |
|
|
| Prepared-run presentation | [CLI contract](cli.md), [adapter internals](internal/adapters.md), and `internal/format` |
|
|
| Prompt, profile, schema, generation, or validation semantics | [Promptkit framework formats](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/formats.md) and the [Promptkit consumer guide](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/consumers/pkg-promptkit.md) |
|
|
| OpenAI-compatible outbound behavior or timeout layering | [Promptkit integration contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/integrations/openai-compatible-chat.md) |
|
|
| Subprocess behavior | [Subprocess integration](integrations/subprocess.md) and [CLI contract](cli.md) |
|
|
| Runtime operation or recovery | [Operations](operations.md) |
|
|
| Dependencies, copied assets, or attribution | The [OSS policy](policy/oss.md), [component attributions](oss/attribution.md), and [architecture policy](policy/architecture.md) |
|
|
| Release documentation, packaging, or publication | The [release policy](policy/release.md), [OSS policy](policy/oss.md), [release procedure](release.md), [hosted release workflow](../.woodpecker/release.yml), and [architecture policy](policy/architecture.md) |
|
|
| Examples or copyable assets | The owning Scriptorium contract, the relevant [Promptkit format contract](https://gitea.maximumdirect.net/eric/promptkit/src/tag/v0.11.1/docs/formats.md), and the related files under `examples/` |
|
|
| Architecture decisions or future work | The [documentation policy](policy/documentation.md), 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:
|
|
|
|
```bash
|
|
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.
|