dot-prompt

Versioning

.prompt uses semantic versioning to manage changes and ensure backward compatibility. Both the prompt and its contract are versioned together.

Version Fields

init do
  @major: 1      # Stability version — callers pin to this
  @version: 1.3  # Precise version (major.minor)
end init
Field Managed By Purpose
@major Developer Stability — bumping major allows breaking changes
@version Container/Dev Precision — managed via major.minor format

Breaking Changes

These require bumping @major:

  • Removing or renaming parameters
  • Changing parameter types
  • Removing response fields
  • Changing response field types

Non-Breaking Changes

These auto-bump @minor:

  • Adding parameters with defaults
  • Adding optional response fields
  • Changing documentation
  • Editing prompt content

How It Works

  1. You edit a .prompt file and save
  2. Container detects what changed
  3. If breaking — prompts you to bump major version
  4. If non-breaking — auto-bumps minor on commit
  5. Old version archived to archive/

Folder Structure

priv/prompts/
├── concept_explanation.prompt  # current — always latest
├── practice.prompt
├── skills/
│   ├── milton_model.prompt
│   ├── meta_model.prompt
│   └── archive/
│       └── milton_model_v1.prompt
└── archive/
    └── concept_explanation_v1.prompt

For Callers

Pin to a major version to receive non-breaking updates automatically: 

client.render(
    "concept_explanation",
    major=1,  # Get latest 1.x.x
    params={...}
)

Breaking Change Detection

Breaking Change Detection

The container warns you on save and gives a hard warning at git commit if unversioned breaking changes exist.

Next Steps