158 lines
6.2 KiB
Markdown
158 lines
6.2 KiB
Markdown
# D&D Shared Module Helper Roadmap
|
|
|
|
This roadmap defines the target state for consolidating Dungeons & Dragons
|
|
helper code that is currently duplicated across the implemented D&D modules.
|
|
The refactor should preserve runtime behavior: module keys, prompt IDs, prompt
|
|
versions, Scriptorium-visible prompt files, message order, response schemas,
|
|
reference slot compatibility, manifests, diagnostics policy, and CLI/config
|
|
semantics should not change.
|
|
|
|
## Motivation
|
|
|
|
The `dnd/scenes` chunker and `dnd/spells` extractor now share several D&D prompt
|
|
and reference conventions:
|
|
|
|
- prompt inputs named `transcript`, `players`, `party`, and `glossary`;
|
|
- deprecated `roster` reference bindings mapped to the `party` prompt input;
|
|
- D&D reference media-type declarations;
|
|
- deterministic rendering of one or more reference files into prompt input
|
|
materials;
|
|
- shared D&D prompt fragments currently under `internal/modules/sharedassets`;
|
|
- prompt hash inclusion for shared D&D prompt fragments.
|
|
|
|
Keeping this logic duplicated makes future D&D modules more likely to drift. It
|
|
also makes small prompt-contract changes expensive because each module must
|
|
update the same reference-slot, prompt-input, and test helper behavior.
|
|
|
|
## Target Package Boundary
|
|
|
|
D&D-specific shared helpers should live under:
|
|
|
|
```text
|
|
internal/modules/sharedassets/dnd
|
|
```
|
|
|
|
The package name should be `dnd`. This keeps generic shared asset plumbing in
|
|
`internal/modules/sharedassets` while giving D&D-specific prompt and reference
|
|
policy a clear home.
|
|
|
|
`internal/modules/sharedassets` should continue to own:
|
|
|
|
- generic shared prompt asset registration;
|
|
- `ModulePromptFS` and related prompt filesystem layout helpers;
|
|
- non-domain-specific embedded asset plumbing;
|
|
- future prompt assets only when they are truly domain-neutral.
|
|
|
|
`internal/modules/sharedassets/dnd` should own D&D-specific reusable helpers:
|
|
|
|
- D&D shared prompt fragments;
|
|
- accepted reference media types for D&D reference slots;
|
|
- reference slot definitions for `players`, `party`, `glossary`, and the
|
|
deprecated `roster` alias;
|
|
- prompt input assembly for D&D modules that use the shared prompt fragments;
|
|
- deterministic reference material rendering;
|
|
- shared D&D prompt hash parts.
|
|
|
|
Concrete D&D modules should continue to own:
|
|
|
|
- stage contracts and module registration;
|
|
- module keys and provided/required capabilities;
|
|
- prompt IDs and prompt versions;
|
|
- module-local prompt definitions, task prompts, and instruction prompts;
|
|
- response schema definitions and schema metadata;
|
|
- artifact interpretation, scene interpretation, validators, and output
|
|
conversion.
|
|
|
|
Framework, core, and CLI packages must not import
|
|
`internal/modules/sharedassets/dnd`.
|
|
|
|
The intended asset layout is:
|
|
|
|
```text
|
|
internal/modules/sharedassets/
|
|
assets.go
|
|
prompt_fs.go
|
|
|
|
internal/modules/sharedassets/dnd/
|
|
assets.go
|
|
prompt_inputs.go
|
|
references.go
|
|
assets/
|
|
prompts/
|
|
common-dnd-system.md
|
|
common-dnd-transcript.md
|
|
common-dnd-references.md
|
|
```
|
|
|
|
The parent `sharedassets` package should have no hard-coded knowledge of
|
|
`common-dnd-*` files. It should provide generic composition primitives that a
|
|
domain package such as `sharedassets/dnd` can use.
|
|
|
|
## Desired End State
|
|
|
|
The `dnd/scenes` and `dnd/spells` modules should remain small owners of their
|
|
stage-specific behavior. Shared D&D helpers should remove duplicated mechanics
|
|
without hiding module semantics.
|
|
|
|
After the refactor:
|
|
|
|
- both modules should call one shared helper to build the D&D prompt input set
|
|
from source input and resolved references;
|
|
- both modules should use one shared source of truth for D&D reference slots and
|
|
accepted media types;
|
|
- D&D shared prompt files should live in `internal/modules/sharedassets/dnd`
|
|
beside the code that owns the D&D prompt contract;
|
|
- generic shared asset plumbing should compose caller-provided shared prompt
|
|
files without knowing which domain owns them;
|
|
- deprecated `roster` bindings should continue to work as an alias for `party`;
|
|
- reference rendering behavior should remain deterministic and covered by tests
|
|
in the shared D&D helper package;
|
|
- real prompt asset tests should remain decoupled from exact embedded prompt
|
|
prose;
|
|
- D&D module tests should focus on module contracts, request construction,
|
|
response interpretation, validators, diagnostics, and manifest metadata rather
|
|
than duplicate reference rendering details.
|
|
|
|
## Documentation Outcome
|
|
|
|
Current-behavior docs should describe the D&D shared helper package only where
|
|
it helps future maintainers understand ownership:
|
|
|
|
- [Internal Modules](../internal/modules.md) should mention that common D&D
|
|
prompt/reference helper behavior lives under
|
|
`internal/modules/sharedassets/dnd`.
|
|
- [Internal Overview](../internal/overview.md) may mention the package if it
|
|
lists shared module-support packages.
|
|
|
|
User-facing docs should not describe internal helper placement unless behavior
|
|
visible to users changes. This refactor should not change visible behavior.
|
|
|
|
## Resolved Decisions
|
|
|
|
### Should generic reference-slot cloning move to `contracts`?
|
|
|
|
Decision: move generic cloning to `internal/framework/contracts`, for example
|
|
as `CloneReferenceSlots`. The operation is not D&D-specific and exists because
|
|
`contracts.ReferenceSlot` contains mutable slices. Keeping the clone helper with
|
|
the contract type makes defensive copying easier to reuse in future modules
|
|
without introducing domain imports.
|
|
|
|
### Should shared D&D prompt hash parts move into `sharedassets/dnd`?
|
|
|
|
Decision: move D&D shared prompt hash helpers into
|
|
`internal/modules/sharedassets/dnd`. The hash parts are D&D-specific prompt
|
|
provenance, and placing them beside the D&D prompt contract reduces drift.
|
|
|
|
### Should D&D shared prompt assets move into `sharedassets/dnd`?
|
|
|
|
Decision: move D&D shared prompt assets into
|
|
`internal/modules/sharedassets/dnd/assets/prompts`. The current
|
|
`common-dnd-system.md`, `common-dnd-transcript.md`, and
|
|
`common-dnd-references.md` files are not truly generic; they are part of the
|
|
D&D prompt contract. Keeping the files beside D&D reference slots, prompt input
|
|
assembly, reference rendering, and prompt hash helpers gives the package clear
|
|
ownership of reusable D&D prompt behavior.
|
|
|
|
The parent `internal/modules/sharedassets` package may still contain prompt
|
|
assets in the future, but only when they are genuinely domain-neutral.
|