notarius/docs/roadmap/sharedassets.md

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:

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:

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.