121 lines
5.2 KiB
Markdown
121 lines
5.2 KiB
Markdown
# Shared Prompt And Asset Layout Implementation Plan
|
|
|
|
## Summary
|
|
|
|
Implement the asset layout defined in
|
|
[Shared Prompt And Asset Layout Roadmap](sharedassets.md). This is a structural
|
|
reorganization only: prompt semantics, prompt IDs, prompt versions, response
|
|
schema IDs, schema names, runtime module contracts, diagnostics policy, and
|
|
manifest provenance shape must remain unchanged.
|
|
|
|
## Stage 1: Introduce Shared Assets Package
|
|
|
|
- Create `internal/modules/sharedassets` as the cross-module shared asset
|
|
package.
|
|
- Move the existing shared D&D prompt fragments from
|
|
`internal/modules/dnd/promptassets` into `internal/modules/sharedassets`.
|
|
- Rename shared prompt files exactly as:
|
|
- `common-dnd-system.md`
|
|
- `common-dnd-transcript.md`
|
|
- `common-dnd-references.md`
|
|
- Implement the shared package with the same responsibilities as the current
|
|
shared prompt package:
|
|
- embed shared prompt files;
|
|
- register them with `llm.AssetRegistry`;
|
|
- expose hash-part helpers for common shared prompts and reference prompts.
|
|
- Keep Scriptorium-visible prompt paths under the shared prompt root as
|
|
`common-dnd-*.md`; do not preserve the old `shared/*.md` Scriptorium paths.
|
|
- Update production prompt asset collection in `internal/cli` and D&D module
|
|
prompt tests to import `internal/modules/sharedassets`.
|
|
- Do not delete the old `internal/modules/dnd/promptassets` package until all
|
|
callers have been updated and tests compile.
|
|
|
|
## Stage 2: Flatten Module Asset Trees
|
|
|
|
- Move `dnd/spells` module-owned prompt assets to:
|
|
- `internal/modules/extract/dnd/spells/assets/prompts/dnd.spells.yaml`
|
|
- `internal/modules/extract/dnd/spells/assets/prompts/task.md`
|
|
- `internal/modules/extract/dnd/spells/assets/prompts/instructions.md`
|
|
- Move `dnd/scenes` module-owned prompt assets to:
|
|
- `internal/modules/chunk/dnd/scenes/assets/prompts/dnd.scenes.yaml`
|
|
- `internal/modules/chunk/dnd/scenes/assets/prompts/task.md`
|
|
- `internal/modules/chunk/dnd/scenes/assets/prompts/instructions.md`
|
|
- Keep module schemas under each module's existing shallow schema directory:
|
|
- `assets/schemas/dnd_spells.v1.json`
|
|
- `assets/schemas/dnd_scenes.v1.json`
|
|
- Update each module's `go:embed` patterns to include only the new shallow
|
|
prompt and schema paths.
|
|
- Update each module's prompt registration root from the old
|
|
`assets/scriptorium/prompts` tree to `assets/prompts`.
|
|
- Update prompt hash inputs to point at the new module prompt paths and the new
|
|
shared asset hash parts.
|
|
|
|
## Stage 3: Update Scriptorium Prompt Definitions
|
|
|
|
- Update `dnd.spells.yaml` and `dnd.scenes.yaml` to use the new shallow
|
|
`content_file` paths.
|
|
- Shared prompt references must point to:
|
|
- `./common-dnd-system.md`
|
|
- `./common-dnd-transcript.md`
|
|
- `./common-dnd-references.md`
|
|
- Module prompt references must point to:
|
|
- `./task.md`
|
|
- `./instructions.md`
|
|
- Keep all existing prompt IDs, prompt versions, default profiles, inputs,
|
|
cache-control settings, output schema paths, validation modes, and repair
|
|
attempts unchanged.
|
|
- Confirm the flattened module prompt roots and shared prompt roots combine into
|
|
one Scriptorium prompt filesystem without duplicate asset paths.
|
|
|
|
## Stage 4: Remove Old Package And Update Docs
|
|
|
|
- Delete `internal/modules/dnd/promptassets` after all imports and asset
|
|
references are gone.
|
|
- Update canonical current-behavior docs to describe the new convention:
|
|
- module-owned prompts and schemas live under each module's shallow
|
|
`assets/prompts` and `assets/schemas` directories;
|
|
- shared reusable prompt fragments live under
|
|
`internal/modules/sharedassets`;
|
|
- framework and CLI code may collect assets, but modules still own prompt
|
|
intent, prompt IDs, schemas, and interpretation.
|
|
- Keep roadmap docs as future/target-state material only; do not describe
|
|
completed behavior in `docs/roadmap/` until the implementation is complete.
|
|
|
|
## Stage 5: Verification
|
|
|
|
- Update focused tests that assert asset paths, prepared prompt message content,
|
|
prompt hash metadata, or import paths.
|
|
- Add or preserve coverage proving:
|
|
- production prompt asset registration includes shared assets, `dnd/scenes`
|
|
assets, and `dnd/spells` assets;
|
|
- Scriptorium can prepare both D&D prompts using the moved assets;
|
|
- prompt and schema hashes remain present in module manifest metadata;
|
|
- raw source input, references, prompt text, and schema JSON still do not leak
|
|
into default diagnostics or manifests.
|
|
- Run focused validation:
|
|
|
|
```sh
|
|
go test ./internal/framework/llm
|
|
go test ./internal/modules/chunk/dnd/scenes ./internal/modules/extract/dnd/spells
|
|
go test ./internal/cli
|
|
```
|
|
|
|
- Run full validation:
|
|
|
|
```sh
|
|
go test ./...
|
|
go vet ./...
|
|
go build ./cmd/notarius
|
|
```
|
|
|
|
## Assumptions
|
|
|
|
- This migration is allowed to change internal asset paths because prompt assets
|
|
are embedded implementation details, not public API.
|
|
- Prompt IDs, versions, schema IDs, schema names, runtime request contracts, and
|
|
output manifest shape are stable and must not change in this pass.
|
|
- `internal/modules/sharedassets` may contain D&D-specific reusable prompt
|
|
fragments when filenames make the domain scope explicit.
|
|
- Shared assets should contain durable operating rules and reusable framing, not
|
|
module-specific extraction, chunking, normalization, or validation semantics.
|