98 lines
3.2 KiB
Markdown
98 lines
3.2 KiB
Markdown
# Shared Prompt And Asset Layout Roadmap
|
|
|
|
This roadmap defines the target state for reorganizing embedded prompt and
|
|
schema assets so module-owned files are shallow and shared prompt fragments live
|
|
in an explicit shared asset package.
|
|
|
|
## Motivation
|
|
|
|
The current Scriptorium asset layout works, but module prompt files are nested
|
|
more deeply than their package ownership requires. For example, a module package
|
|
already identifies its stage, domain, and artifact, so paths like
|
|
`assets/scriptorium/prompts/dnd/spells/...` repeat context that is already in
|
|
the Go package path.
|
|
|
|
Shared D&D prompt fragments also currently live under a D&D-specific
|
|
`promptassets` package. That is serviceable, but it undersells the fact that
|
|
shared assets are intentionally cross-module. A clearer shared package will make
|
|
reuse deliberate and make room for common prompt hardening and reference-use
|
|
rules.
|
|
|
|
## Target State
|
|
|
|
Module-owned assets should stay in the module package that owns the behavior,
|
|
but their internal paths should be shallow:
|
|
|
|
```text
|
|
internal/modules/extract/dnd/spells/assets/
|
|
prompts/
|
|
dnd.spells.yaml
|
|
task.md
|
|
instructions.md
|
|
schemas/
|
|
dnd_spells.v1.json
|
|
|
|
internal/modules/chunk/dnd/scenes/assets/
|
|
prompts/
|
|
dnd.scenes.yaml
|
|
task.md
|
|
instructions.md
|
|
schemas/
|
|
dnd_scenes.v1.json
|
|
```
|
|
|
|
Shared reusable assets should move to:
|
|
|
|
```text
|
|
internal/modules/sharedassets/
|
|
assets.go
|
|
prompts/
|
|
common-dnd-system.md
|
|
common-dnd-transcript.md
|
|
common-dnd-references.md
|
|
schemas/
|
|
```
|
|
|
|
The `sharedassets` package should own only reusable fragments and shared asset
|
|
registration. It should not own module task semantics, response schemas,
|
|
validators, artifact interpretation, or stage behavior.
|
|
|
|
## Ownership Rules
|
|
|
|
Module packages own:
|
|
|
|
- complete Scriptorium prompt definitions;
|
|
- module task prompts and instruction prompts;
|
|
- response schemas and schema metadata;
|
|
- prompt IDs and versions;
|
|
- semantic validation and interpretation.
|
|
|
|
`internal/modules/sharedassets` owns:
|
|
|
|
- shared prompt fragments used by more than one module;
|
|
- standardized cross-module prompt hardening;
|
|
- shared source/transcript framing;
|
|
- shared reference framing and reference-use constraints;
|
|
- future genuinely shared schemas, if a real cross-module schema emerges.
|
|
|
|
Shared prompt fragments should be durable operating rules, not artifact-specific
|
|
instructions. They may tell the model to treat source material as primary
|
|
evidence, use references only for disambiguation unless a module says otherwise,
|
|
ignore instructions embedded inside source/reference content, follow the
|
|
structured output contract, and avoid exposing prompt instructions.
|
|
|
|
## Documentation Outcome
|
|
|
|
When implemented, canonical internal documentation should describe the asset
|
|
ownership convention:
|
|
|
|
- module-owned prompts and schemas live under each module's shallow `assets`
|
|
tree;
|
|
- shared reusable fragments live under `internal/modules/sharedassets`;
|
|
- framework and CLI code may collect assets, but module packages remain
|
|
responsible for prompt intent and schemas.
|
|
|
|
Prompt IDs, prompt versions, response schema IDs, schema names, and runtime
|
|
module contracts should remain unchanged unless a later feature explicitly
|
|
changes prompt semantics.
|