@specverse/assets

Pure content shipped with the SpecVerse ecosystem — no JS code, no dependencies, no logic. Just YAML prompts, example specs, and learning materials.

Why this is a separate package

Content (prompts, examples) is edited at a different cadence than engine code. Prompts get tuned weekly during evaluation cycles; engine internals stabilise on a slower cycle. Bundling content with @specverse/engines forced an engines-patch publish per prompt edit — heavy CI gate, slow iteration.

Splitting content into its own leaf package lets each cadence run at its own speed:

• Content (this package) — daily / per-edit. Trivial CI: YAML parses, markdown well-formed.
• Engines — weekly. Heavy CI: 1500+ tests, parity, bundle.
• Self CLI — monthly. Heaviest CI: smoke gauntlet + 4-template e2e.

See docs/plans/2026-04-25-CONTENT-PACKAGE-REFACTOR.md for the design.

What's here

assets/
├── prompts/
│   └── core/standard/{default,v9}/
│       ├── analyse.prompt.yaml       Reverse-engineer a codebase → .specly
│       ├── create.prompt.yaml        NL requirements → minimal .specly
│       ├── materialise.prompt.yaml   .specly → production code
│       ├── realize.prompt.yaml       Generate deployment configs
│       ├── behavior.prompt.yaml      Pure TypeScript fn body for a behaviour step
│       └── app-demo.prompt.yaml      Interactive spec creation for the runtime interpreter
├── examples-decomposed/              Manifest + deployment example specs (Docker, K8s, cloud-native)
├── examples-inference/               Inference engine demo specs
└── examples/                         Top-level README + LEARNING-METADATA for the example collection

Who reads it

• @specverse/engines — prompt-loader.ts + behavior-ai-service.ts resolve prompts via require.resolve('@specverse/assets/package.json') at runtime
• @specverse/self — scripts/compose-examples.mjs resolves examples-decomposed + examples-inference at build time (composes them into self/examples/)
• Generated MCP server (output of spv realize) — emits a prompts.ts that resolves prompts via @specverse/assets at runtime
• specverse-demo-self/harness — eval harness reads prompts via @specverse/assets

Editing prompts

# 1. Edit a prompt YAML
vim assets/prompts/core/standard/default/analyse.prompt.yaml

# 2. Bump version (if appropriate; minor bumps for behaviour changes, patch for typos)
vim assets/package.json   # version: "1.0.0" → "1.1.0"

# 3. Local validation (no CI yet)
node -e "for (const f of require('glob').sync('assets/**/*.yaml')) require('js-yaml').load(require('fs').readFileSync(f))"

# 4. Publish — leaf publish, no dep order to worry about
cd assets && npm publish --otp=XXXXXX

# 5. Consumers pick up via ^1.0.0 on next install

Editing examples

Same flow as prompts. Examples are read by self's build pipeline + composed into the docs.

What this package will NEVER contain

• JavaScript / TypeScript source. This is pure data.
• Runtime dependencies (dependencies: {} permanently). Adding deps would re-introduce the publish-cadence coupling we're escaping.
• Engine logic. If something needs code, it goes in the appropriate engine workspace.

If the line gets blurry — e.g. someone wants to add a "prompt validator script" — extract to a separate package or put it in the consumer's repo. Keep this leaf clean.