# 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.