prompt_manager 0.5.8 → 1.0.0

data/README.md

@@ -1,625 +1,315 @@
-# PromptManager
-
-> [!CAUTION]
-> ## ⚠️ Breaking Changes are Coming ⚠️
-> See [Roadmap](#roadmap) for details about upcoming changes.
-<br />
-<div align="center">
-  <table>
-    <tr>
-      <td width="40%" align="center" valign="top">
-        <a href="https://madbomber.github.io/blog/" target="_blank">
-          <img src="prompt_manager_logo.png" alt="PromptManager - The Enchanted Librarian of AI Prompts" width="800">
-        </a>
-        <br /><br />
-        [Comprehensive Documentation Website](https://madbomber.github.io/prompt_manager/)
-      </td>
-      <td width="60%" align="left" valign="top">
-        Like an enchanted librarian organizing floating books of knowledge, PromptManager helps you masterfully orchestrate and organize your AI prompts through wisdom and experience. Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships.
-        <br/><br/>
-        <h3>Key Features</h3>
-        <ul>
-            <li><strong>📚 <a href="#storage-adapters">Multiple Storage Adapters</a></strong>
-            <li><strong>🔧 <a href="#parameterized-prompts">Parameterized Prompts</a></strong>
-            <li><strong>📋 <a href="#directive-processing">Directive Processing</a></strong>
-            <li><strong>🎨 <a href="#erb-and-shell-integration">ERB Integration</a></strong>
-            <li><strong>🌍 <a href="#erb-and-shell-integration">Shell Integration</a></strong>
-            <li><strong>📖 <a href="#comments-and-documentation">Inline Documentation</a></strong>
-            <li><strong>📊 <a href="#parameter-history">Parameter History</a></strong>
-            <li><strong>⚡ <a href="#error-handling">Error Handling</a></strong>
-            <li><strong>🔌 <a href="#extensible-architecture">Extensible Architecture</a></strong>
-        </ul>
-      </td>
-    </tr>
-  </table>
-</div>
-
-## Table of Contents
-
-* [Installation](#installation)
-* [Quick Start](#quick-start)
-* [Core Features](#core-features)
-  * [Parameterized Prompts](#parameterized-prompts)
-    * [Keyword Syntax](#keyword-syntax)
-    * [Custom Patterns](#custom-patterns)
-    * [Working with Parameters](#working-with-parameters)
-  * [Directive Processing](#directive-processing)
-    * [Built\-in Directives](#built-in-directives)
-    * [Directive Syntax](#directive-syntax)
-    * [Custom Directive Processors](#custom-directive-processors)
-  * [ERB and Shell Integration](#erb-and-shell-integration)
-    * [ERB Templates](#erb-templates)
-    * [Environment Variables](#environment-variables)
-  * [Comments and Documentation](#comments-and-documentation)
-    * [Line Comments](#line-comments)
-    * [Block Comments](#block-comments)
-    * [Blank Lines](#blank-lines)
-  * [Parameter History](#parameter-history)
-  * [Error Handling](#error-handling)
-* [Storage Adapters](#storage-adapters)
-  * [FileSystemAdapter](#filesystemadapter)
-    * [Configuration](#configuration)
-    * [File Structure](#file-structure)
-    * [Custom Search](#custom-search)
-    * [Extra Methods](#extra-methods)
-  * [ActiveRecordAdapter](#activerecordadapter)
-    * [Configuration](#configuration-1)
-    * [Database Setup](#database-setup)
-  * [Custom Adapters](#custom-adapters)
-* [Configuration](#configuration-2)
-  * [Initialization Options](#initialization-options)
-  * [Global Configuration](#global-configuration)
-* [Advanced Usage](#advanced-usage)
-  * [Custom Keyword Patterns](#custom-keyword-patterns)
-  * [Dynamic Directives](#dynamic-directives)
-  * [Search Capabilities](#search-capabilities)
-* [Examples](#examples)
-  * [Basic Usage](#basic-usage)
-  * [With Search](#with-search)
-  * [Custom Storage](#custom-storage)
-* [Extensible Architecture](#extensible-architecture)
-  * [Extension Points](#extension-points)
-  * [Potential Extensions](#potential-extensions)
-* [Roadmap](#roadmap)
-  * [v0\.9\.0 \- Modern Prompt Format (Breaking Changes)](#v090---modern-prompt-format-breaking-changes)
-  * [v1\.0\.0 \- Stability Release](#v100---stability-release)
-  * [Future Enhancements](#future-enhancements)
-* [Development](#development)
-* [Contributing](#contributing)
-* [License](#license)
+# PM (PromptManager)
+
+<table>
+<tr>
+<td width="50%" align="center" valign="top">
+<img src="docs/assets/images/prompt_manager.gif" alt="PromptManager" width="70%"><br>
+<em>"Prompts with superpowers"</em>
+</td>
+<td width="50%" valign="top">
+  Like an enchanted librarian enhancing books of knowledge, PromptManager (PM) helps you masterfully orchestrate and organize your AI prompts through wisdom and experience. Each prompt becomes a living entity that can be categorized, parameterized, and interconnected with golden threads of relationships. 
+
+  <h3>Key Features</h3>
+
+- <strong>YAML Metadata</strong> - Parse from markdown strings or files<br>
+- <strong>Conditional Shell Expansion</strong> - $ENVAR, ${ENVAR}, $(command) substitution<br>
+- <strong>Conditional ERB Templates</strong> - On-demand rendering with named parameters<br>
+- <strong>Reclusive Include System</strong> - Compose prompts from multiple files<br>
+- <strong>Custom Directives</strong> - Register custom methods for ERB templates<br>
+- <strong>Configurable Pipeline</strong> - Enable/disable stages per prompt or globally<br>
+- <strong>Comment Stripping</strong> - HTML comments removed before processing
+</td>
+</tr>
+</table>
 
 ## Installation
 
-Install the gem and add to the application's Gemfile by executing:
-
-    bundle add prompt_manager
-
-If bundler is not being used to manage dependencies, install the gem by executing:
-
-    gem install prompt_manager
-
-## Quick Start
-
-```ruby
-require 'prompt_manager'
-
-# Configure storage adapter
-PromptManager::Prompt.storage_adapter =
-  PromptManager::Storage::FileSystemAdapter.config do |config|
-    config.prompts_dir = '~/.prompts'
-  end.new
-
-# Load and use a prompt
-prompt = PromptManager::Prompt.new(id: 'greeting')
-prompt.parameters = {
-  "[NAME]" => "Alice",
-  "[LANGUAGE]" => "English"
-}
-
-# Get the processed prompt text
-result = prompt.to_s
-```
-
-## Core Features
-
-### Parameterized Prompts
-
-The heart of PromptManager is its ability to manage parameterized prompts - text templates with embedded keywords that can be replaced with dynamic values.
-
-#### Keyword Syntax
-
-By default, keywords are enclosed in square brackets: `[KEYWORD]`, `[MULTIPLE WORDS]`, or `[WITH_UNDERSCORES]`.
-
 ```ruby
-prompt_text = "Hello [NAME], please translate this to [LANGUAGE]"
+require 'pm'
 ```
 
-#### Custom Patterns
+## Configuration
 
-You can customize the keyword pattern to match your preferences:
+Set global defaults with `PM.configure`:
 
 ```ruby
-# Use {{mustache}} style
-PromptManager::Prompt.parameter_regex = /(\{\{[A-Za-z_]+\}\})/
-
-# Use :colon style
-PromptManager::Prompt.parameter_regex = /(:[a-z_]+)/
+PM.configure do |config|
+  config.prompts_dir = '~/.prompts'   # default: ''
+  config.shell       = true           # default: true
+  config.erb         = true           # default: true
+end
 ```
 
-The regex must include capturing parentheses `()` to extract the keyword.
-
-#### Working with Parameters
+**`prompts_dir`** is prepended to relative file paths passed to `PM.parse`. Absolute paths bypass it:
 
 ```ruby
-prompt = PromptManager::Prompt.new(id: 'example')
-
-# Get all keywords found in the prompt
-keywords = prompt.keywords  #=> ["[NAME]", "[LANGUAGE]"]
+PM.configure { |c| c.prompts_dir = '/usr/share/prompts' }
 
-# Set parameter values
-prompt.parameters = {
-  "[NAME]" => "Alice",
-  "[LANGUAGE]" => "French"
-}
+PM.parse('code_review.md')
+#=> reads /usr/share/prompts/code_review.md
 
-# Get processed text with substitutions
-final_text = prompt.to_s
-
-# Save changes
-prompt.save
+PM.parse('/absolute/path/review.md')
+#=> reads /absolute/path/review.md (prompts_dir ignored)
 ```
 
-### Directive Processing
-
-Directives are special line oriented instructions in your prompts that begin with `//` starting in column 1. They're inspired by IBM JCL and provide powerful prompt composition capabilities.  A character string that begins with `//` but is not at the very beginning of the line will NOT be processed as a directive.
-
-#### Built-in Directives
+**`shell`** and **`erb`** set the global defaults for new parses. Per-file YAML metadata overrides the global setting:
 
-**`//include` (alias: `//import`)** - Include content from other files:
-
-```text
-//include common/header.txt
-//import [TEMPLATE_NAME].txt
+```ruby
+PM.configure { |c| c.shell = false }
 
-Main prompt content here...
+# All files now default to shell: false
+# A file with "shell: true" in its YAML still gets shell expansion
 ```
 
-Features:
-- Loop protection prevents circular includes
-- Supports keyword substitution in file paths
-- Processes included files recursively
-
-#### Directive Syntax
+Reset all settings to defaults:
 
-```text
-//directive_name [PARAM1] [PARAM2] options
-
-# Dynamic directives using keywords
-//[COMMAND] [OPTIONS]
+```ruby
+PM.config.reset!
 ```
 
-#### Custom Directive Processors
-
-You can create custom directive processors:
+Access the current configuration:
 
 ```ruby
-class MyDirectiveProcessor < PromptManager::DirectiveProcessor
-  def process_directive(directive, prompt)
-    case directive
-    when /^\/\/model (.+)$/
-      set_model($1)
-    when /^\/\/temperature (.+)$/
-      set_temperature($1.to_f)
-    else
-      super
-    end
-  end
-end
-
-prompt = PromptManager::Prompt.new(
-  id: 'example',
-  directives_processor: MyDirectiveProcessor.new
-)
+PM.config.prompts_dir  #=> ''
+PM.config.shell        #=> true
+PM.config.erb          #=> true
 ```
 
-### ERB and Shell Integration
-
-#### ERB Templates
+## Usage
 
-Enable ERB processing for dynamic content generation:
+`PM.parse` accepts a file path, a Symbol, a single word, or a string:
 
 ```ruby
-prompt = PromptManager::Prompt.new(
-  id: 'dynamic',
-  erb_flag: true
-)
-```
+# File path (String ending in .md or Pathname)
+parsed = PM.parse('code_review.md')
+parsed = PM.parse(Pathname.new('code_review.md'))
 
-Example prompt with ERB:
+# Symbol or single word (treated as basename, .md appended)
+parsed = PM.parse(:code_review)    #=> parses code_review.md
+parsed = PM.parse('code_review')   #=> parses code_review.md
 
-```text
-Today's date is <%= Date.today %>
-<% 5.times do |i| %>
-  Item <%= i + 1 %>
-<% end %>
+# String content
+parsed = PM.parse("---\ntitle: Hello\n---\nContent here")
 ```
 
-#### Environment Variables
+When given a file path, `parse` adds `directory`, `name`, `created_at`, and `modified_at` to the metadata. Both forms run the full processing pipeline.
+
+Given a file `code_review.md`:
+
+```md
+---
+title: Code Review
+provider: openai
+model: gpt-4
+temperature: 0.3
+parameters:
+  language: ruby
+  code: null
+  style_guide: ~/guides/default.md
+---
+Review the following <%= language %> code using the style guide
+at <%= style_guide %>:
+
+<%= code %>
+```
 
-Enable automatic environment variable substitution:
+Parse it:
 
 ```ruby
-prompt = PromptManager::Prompt.new(
-  id: 'with_env',
-  envar_flag: true
-)
+parsed = PM.parse('code_review.md')
+parsed.metadata.parameters
+#=> {'language' => 'ruby', 'code' => nil, 'style_guide' => '~/guides/default.md'}
 ```
 
-Environment variables are automatically replaced in the prompt text.
-
-### Comments and Documentation
-
-PromptManager supports comprehensive inline documentation:
-
-#### Line Comments
-
-Lines beginning with `#` are treated as comments:
+Build the prompt with `to_s`:
 
-```text
-# This is a comment
-# Description: This prompt does something useful
-
-Actual prompt text here...
-```
-
-#### Block Comments
+```ruby
+# Provide required params, accept defaults for the rest
+parsed.to_s('code' => File.read('app.rb'))
 
-Everything after `__END__` is ignored:
+# Override defaults
+parsed.to_s('code' => File.read('app.py'), 'language' => 'python')
 
-```text
-Main prompt content...
+# All params have defaults — no arguments needed
+parsed.to_s
 
-__END__
-Development notes:
-- This section is completely ignored
-- Great for documentation
-- TODO items
+# Missing a required parameter raises an error
+parsed.to_s
+#=> ArgumentError: Missing required parameters: code
 ```
 
-#### Blank Lines
-
-Blank lines are automatically removed from the final output.
+Parameters with a `null` default in the YAML are required. Parameters with any other default are optional.
 
-### Parameter History
+### Shell expansion
 
-PromptManager maintains a history of parameter values (since v0.3.0):
+Shell references are expanded during parsing (when `shell: true`, the default):
 
-```ruby
-# Parameters are stored as arrays
-prompt.parameters = {
-  "[NAME]" => ["Alice", "Bob", "Charlie"]  # Charlie is most recent
-}
-
-# The last value is always the most recent
-current_name = prompt.parameters["[NAME]"].last
-
-# Useful for:
-# - Implementing value history in UIs
-# - Providing dropdown selections
-# - Tracking parameter usage over time
+```md
+---
+title: Deploy Check
+parameters:
+  environment: null
+---
+Current user: $USER
+Home directory: ${HOME}
+Date: $(date +%Y-%m-%d)
+Git branch: $(git rev-parse --abbrev-ref HEAD)
+Deploy to: <%= environment %>
 ```
 
-### Error Handling
+- `$ENVAR` and `${ENVAR}` are replaced with the environment variable's value.
+- `$(command)` is executed and replaced with its stdout.
+- Missing environment variables are replaced with an empty string.
+- Failed commands raise an error.
 
-PromptManager provides specific error classes for better debugging:
+Shell expansion is also available directly:
 
 ```ruby
-begin
-  prompt = PromptManager::Prompt.new(id: 'missing')
-rescue PromptManager::StorageError => e
-  # Handle storage-related errors
-  puts "Storage error: #{e.message}"
-rescue PromptManager::ParameterError => e
-  # Handle parameter substitution errors
-  puts "Parameter error: #{e.message}"
-rescue PromptManager::ConfigurationError => e
-  # Handle configuration errors
-  puts "Configuration error: #{e.message}"
-end
+PM.expand_shell(string)
 ```
 
-## Storage Adapters
-
-Storage adapters provide the persistence layer for prompts. PromptManager includes two built-in adapters and supports custom implementations.
+### Including other prompt files
 
-### FileSystemAdapter
+Use `include` in ERB to compose prompts from multiple files:
 
-Stores prompts as text files in a directory structure.
+```md
+---
+title: Full Review
+parameters:
+  code: null
+---
+<%= include 'common/header.md' %>
 
-#### Configuration
+Review this code:
+<%= code %>
 
-```ruby
-PromptManager::Storage::FileSystemAdapter.config do |config|
-  config.prompts_dir       = "~/.prompts"      # Required
-  config.search_proc       = nil               # Optional custom search
-  config.prompt_extension  = '.txt'            # Default
-  config.params_extension  = '.json'           # Default
-end
+<%= include 'common/footer.md' %>
 ```
 
-#### File Structure
+Included files go through the full processing pipeline (comment stripping, metadata extraction, shell expansion, ERB rendering). The parent's parameter values are passed to included files.
 
-```
-~/.prompts/
-├── greeting.txt        # Prompt text
-├── greeting.json       # Parameters
-├── email/
-│   ├── welcome.txt
-│   └── welcome.json
-```
-
-#### Custom Search
+Nested includes work — A can include B which includes C. Circular includes raise an error.
 
-Integrate with external search tools:
+After calling `to_s`, the parent's metadata has an `includes` key with a tree of what was included:
 
 ```ruby
-config.search_proc = ->(query) {
-  # Use ripgrep for fast searching
-  `rg -l "#{query}" #{config.prompts_dir}`.split("\n")
-}
+parsed = PM.parse('full_review.md')
+parsed.to_s('code' => File.read('app.rb'))
+
+parsed.metadata.includes
+#=> [
+#     {
+#       path:     "/prompts/common/header.md",
+#       depth:    1,
+#       metadata: { title: "Header", ... },
+#       includes: []
+#     },
+#     {
+#       path:     "/prompts/common/footer.md",
+#       depth:    1,
+#       metadata: { title: "Footer", ... },
+#       includes: []
+#     }
+#   ]
 ```
 
-#### Extra Methods
-
-- `list` - Returns array of all prompt IDs
-- `path(id)` - Returns Pathname to prompt file
+### Custom directives
 
-### ActiveRecordAdapter
-
-Stores prompts in a database using ActiveRecord.
-
-#### Configuration
+Register custom methods available in ERB templates:
 
 ```ruby
-PromptManager::Storage::ActiveRecordAdapter.config do |config|
-  config.model              = PromptModel      # Your AR model
-  config.id_column          = :prompt_id       # Column for ID
-  config.text_column        = :content         # Column for text
-  config.parameters_column  = :params          # Column for parameters
-end
+PM.register(:read) { |_ctx, path| File.read(path) }
+PM.register(:env)  { |_ctx, key| ENV.fetch(key, '') }
+PM.register(:run)  { |_ctx, cmd| `#{cmd}`.chomp }
 ```
 
-#### Database Setup
+Register multiple names for the same directive (aliases):
 
 ```ruby
-class CreatePrompts < ActiveRecord::Migration[7.0]
-  def change
-    create_table :prompts do |t|
-      t.string :prompt_id, null: false, index: { unique: true }
-      t.text :content
-      t.json :params
-      t.timestamps
-    end
-  end
-end
+PM.register(:webpage, :website, :web) { |_ctx, url| fetch_page(url) }
 ```
 
-### Custom Adapters
-
-Create your own storage adapter:
+All three names call the same block. Use any of them in ERB:
 
-```ruby
-class RedisAdapter
-  def initialize(redis_client)
-    @redis = redis_client
-  end
-
-  def get(id)
-    prompt_text = @redis.get("prompt:#{id}:text")
-    parameters = JSON.parse(@redis.get("prompt:#{id}:params") || '{}')
-    [prompt_text, parameters]
-  end
-
-  def save(id, text, parameters)
-    @redis.set("prompt:#{id}:text", text)
-    @redis.set("prompt:#{id}:params", parameters.to_json)
-  end
-
-  def delete(id)
-    @redis.del("prompt:#{id}:text", "prompt:#{id}:params")
-  end
-
-  def list
-    @redis.keys("prompt:*:text").map { |k| k.split(':')[1] }
-  end
-end
+```markdown
+<%= webpage 'https://example.com' %>
+<%= website 'https://example.com' %>
+<%= web 'https://example.com' %>
 ```
 
-## Configuration
-
-### Initialization Options
+Use them in any prompt file:
 
-When creating a prompt instance:
-
-```ruby
-prompt = PromptManager::Prompt.new(
-  id: 'example',
-  context: ['additional', 'context'],
-  directives_processor: CustomProcessor.new,
-  external_binding: binding,
-  erb_flag: true,
-  envar_flag: true
-)
+```md
+---
+title: Deploy Prompt
+---
+Hostname: <%= read '/etc/hostname' %>
+Environment: <%= env 'DEPLOY_ENV' %>
+Recent commits: <%= run 'git log --oneline -5' %>
 ```
 
-Options:
-- `id` - Unique identifier for the prompt
-- `context` - Additional context array
-- `directives_processor` - Custom directive processor
-- `external_binding` - Ruby binding for ERB
-- `erb_flag` - Enable ERB processing
-- `envar_flag` - Enable environment variable substitution
-
-### Global Configuration
+The first argument to every directive block is a `PM::RenderContext` with access to the current render state:
 
-Set the storage adapter globally:
+- `ctx.directory` — directory of the file being rendered
+- `ctx.params` — merged parameter values
+- `ctx.metadata` — the current file's metadata
+- `ctx.depth` — include nesting depth
+- `ctx.included` — Set of file paths already in the include chain
 
 ```ruby
-PromptManager::Prompt.storage_adapter = adapter_instance
+PM.register(:current_file) { |ctx| ctx.metadata.name || 'unknown' }
+PM.register(:depth) { |ctx| ctx.depth.to_s }
 ```
 
-## Advanced Usage
-
-### Custom Keyword Patterns
-
-Examples of different keyword patterns:
+Registering a name that already exists raises an error:
 
 ```ruby
-# Handlebars style: {{name}}
-PromptManager::Prompt.parameter_regex = /(\{\{[a-z_]+\}\})/
-
-# Colon prefix: :name
-PromptManager::Prompt.parameter_regex = /(:[a-z_]+)/
-
-# Dollar sign: $NAME
-PromptManager::Prompt.parameter_regex = /(\$[A-Z_]+)/
-
-# Percentage: %name%
-PromptManager::Prompt.parameter_regex = /(%[a-z_]+%)/
-```
-
-### Dynamic Directives
-
-Create directives that change based on parameters:
-
-```text
-# Set directive name via parameter
-//[DIRECTIVE_TYPE] [OPTIONS]
-
-# Conditional directives
-//include templates/[TEMPLATE_TYPE].txt
+PM.register(:include) { |_ctx, path| path }
+#=> RuntimeError: Directive already registered: include
 ```
 
-### Search Capabilities
-
-Implement powerful search across prompts:
+Reset to built-in directives only:
 
 ```ruby
-# With FileSystemAdapter
-adapter.search_proc = ->(query) {
-  # Custom search implementation
-  results = []
-  Dir.glob("#{prompts_dir}/**/*.txt").each do |file|
-    content = File.read(file)
-    if content.include?(query)
-      results << File.basename(file, '.txt')
-    end
-  end
-  results
-}
-
-# With ActiveRecordAdapter
-PromptModel.where("content LIKE ?", "%#{query}%").pluck(:prompt_id)
+PM.reset_directives!
 ```
 
-## Examples
+### Disabling processing stages
 
-### Basic Usage
+Set `shell: false` or `erb: false` in the metadata to skip those stages:
 
-```ruby
-# examples/simple.rb
-require 'prompt_manager'
-
-# Setup
-PromptManager::Prompt.storage_adapter =
-  PromptManager::Storage::FileSystemAdapter.config do |c|
-    c.prompts_dir = '~/.prompts'
-  end.new
-
-# Create and use a prompt
-prompt = PromptManager::Prompt.new(id: 'story')
-prompt.parameters = {
-  "[GENRE]" => "fantasy",
-  "[CHARACTER]" => "wizard"
-}
-
-puts prompt.to_s
+```md
+---
+title: Raw Template
+shell: false
+erb: false
+---
+This $USER and <%= name %> content is preserved as-is.
 ```
 
-### Advanced Integration with LLM and Streaming
-
-See [examples/advanced_integrations.rb](examples/advanced_integrations.rb) for a complete example that demonstrates:
-
-- **ERB templating** for dynamic content generation
-- **Shell integration** for environment variable substitution
-- **OpenAI API integration** with streaming responses
-- **Professional UI** with spinner feedback using `tty-spinner`
+Both default to `true` when not specified. You can change these defaults globally via `PM.configure` (see [Configuration](#configuration)). Per-file metadata always overrides the global setting.
 
-This example shows how to create sophisticated AI prompts that adapt to your system environment and stream responses in real-time.
+### HTML comment stripping
 
-### With Search
+HTML comments are stripped before any other processing:
 
-See [examples/using_search_proc.rb](examples/using_search_proc.rb) for advanced search integration.
+```md
+<!-- This comment will be removed -->
+---
+title: My Prompt
+---
+Content here. <!-- This too -->
+```
 
-### Custom Storage
+Comments are also available directly:
 
 ```ruby
-# examples/redis_storage.rb
-class RedisStorage
-  # ... implementation
-end
-
-PromptManager::Prompt.storage_adapter = RedisStorage.new(Redis.new)
+PM.strip_comments(string)
 ```
 
-## Extensible Architecture
-
-PromptManager is designed to be extended:
-
-### Extension Points
-
-1. **Storage Adapters** - Implement your own persistence layer
-2. **Directive Processors** - Add custom directives
-3. **Search Processors** - Integrate external search tools
-4. **Serializers** - Support different parameter formats
-
-### Potential Extensions
-
-- **CloudStorageAdapter** - S3, Google Cloud Storage
-- **RedisAdapter** - For caching and fast access
-- **ApiAdapter** - REST API backend
-- **GraphQLAdapter** - GraphQL endpoint storage
-- **GitAdapter** - Version controlled prompts
-
-## Roadmap
-
-### v0.9.0 - Modern Prompt Format (Breaking Changes)
-- **Markdown Support**: Full `.md` file support with YAML front matter
-- **Modern Parameter Syntax**: Support for `{{keyword}}` format
-- **Enhanced API**: New `set_parameter()` and `get_parameter()` methods
-- **Parameter Validation**: Built-in validation based on specifications
-- **HTML Comments**: Support for `<!-- comments -->`
-- **Migration Tools**: Automated conversion utilities
-
-### v1.0.0 - Stability Release
-- Performance optimizations
-- Complete documentation
-- Production hardening
-
-### Future Enhancements
-- Additional storage adapters
-- Enhanced directive system with plugins
-- Prompt versioning and inheritance
-- Performance optimizations for large collections
-
-## Development
-
-Looking for feedback and contributors to enhance the capability of prompt_manager.
-
-## Contributing
-
-Bug reports and pull requests are welcome on GitHub at [https://github.com/MadBomber/prompt_manager](https://github.com/MadBomber/prompt_manager).
-
-## License
+## Processing pipeline
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+1. Strip HTML comments
+2. Extract YAML metadata and markdown content
+3. Shell expansion (`$ENVAR`, `$(command)`) when `shell: true`
+4. ERB rendering on demand via `to_s` when `erb: true`