aia 1.0.0.pre.alpha → 1.0.0.pre.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79adae0e7c376a4b6aceab36d1378322ac8d35f3a716ec55f165744ebe7e901a
-  data.tar.gz: 0f8bc3fc75d717c1833ee13b9d37b447f674cc178d1c80e4367ec5781333f97b
+  metadata.gz: '068690ce0bebc601d0867f4dc98778a6fc1335d41dc742f483b2d1b911118051'
+  data.tar.gz: 9dfcb29be5b606fa29176e29105dde5a9f25f35c671b155ec8a35dd0ece8bd95
 SHA512:
-  metadata.gz: 880eb80b2670139b80461bd62e45f393072cea612f3067d8799c79ceceb60f5ac862e1527e6d6856bf7c8841140dc14c04621db0e282cb70c6a1b4a4ee13fdfc
-  data.tar.gz: 3b345422fa6aab72da7a3baa28b347720a3fed7999b807da9b350a28459d6e64daa0f7bcdc731da8446c56929a3010518cfec17cc6a06c04bf28a4ea0e05e74e
+  metadata.gz: 179f47094d2c80f04d7d649122bd11492e12924bdf8f955873de67ffa4fe08047b655ac1e63e9024fe21eb807c6d500d724f15ef66b45b6d9ac3aa88cd1a405e
+  data.tar.gz: 46da1ec94f9a19b358868c3b148699b0158427b0d2b63d9a81fd9507a64868542823a2be9c0b4c5be6a17bff4a8f87f413714a67433d544b1931403eb2accd56

data/.version

@@ -1 +1 @@
-1.0.0-alpha
+1.0.0-beta

data/CHANGELOG.md

@@ -1,4 +1,59 @@
 # Changelog
+## [1.0.0-beta] - 2026-02-10
+
+### Breaking Changes
+- **Removed `--exec` / `-x` CLI Option**: Shebang auto-detection fully replaces the legacy `--exec` flag
+  - Prompt files with `#!/usr/bin/env aia ...` on the first line are auto-detected and processed as executable prompts
+  - Removed `executable_prompt` and `executable_prompt_file` config attributes
+  - Removed legacy code path in validator and session
+- **Removed deprecated `next` and `pipeline` directives**: These utility directive methods have been removed
+  - `next` and `pipeline` are now handled exclusively via CLI flags and front matter
+  - Removed `next` and `next=` methods from `AIA::Config`
+- **Upgraded to prompt_manager gem v1.0.2**: Directive system now uses PM::Directive base class hierarchy
+  - AIA directives inherit from `AIA::Directive < PM::Directive`
+  - Directive registration uses centralized `PM::Directive.directive_subclasses`
+
+### New Features
+- **`/skill` and `/skills` Directives**: Access Claude Code skills from within AIA
+  - `/skills` lists all available skills from `~/.claude/skills/`
+  - `/skill <name>` includes a specific skill's context into the conversation
+- **`model` Accessor on RubyLLMAdapter**: Added `model` method for programmatic access to the current model
+- **Comprehensive Examples Directory**: 23 progressive demo scripts (00–22) covering all AIA features
+  - Demos 00–05: Setup, basic usage, front matter, shell integration, ERB, shell+ERB
+  - Demos 06–07: Prompt chaining and pipelines
+  - Demos 08–10: Context files, roles, STDIN piping
+  - Demos 11–13: Multi-model comparison, token usage, cost tracking
+  - Demos 14–15: Output files and prompt parameters
+  - Demo 16: Directives (built-in `include` and custom directive creation)
+  - Demos 17–20: Require/conditionals, tools, local tools, MCP servers
+  - Demo 21: Executable prompts (shebang auto-detection, frontmatter+ERB, STDIN piping)
+  - Demo 22: Interactive chat mode (pure chat, prompt+chat, pipeline+chat, directives, live session)
+  - All demos use isolated `aia_config.yml` via `-c` flag for reproducible runs
+  - `common.sh` clears all `AIA_*` environment variables to prevent leakage
+
+### Improvements
+- **Directive Processor Refactoring**: Simplified directive detection and prefix handling
+  - Improved directive prefix and method name validation
+  - Streamlined directive processing logic
+- **Enhanced Prompt Handler**: Added pipeline override logging and logger method
+- **Error Handling Module**: Added `lib/aia/errors.rb` for centralized exception management
+- **Test Coverage Improvements**: Added SimpleCov prelude, CLI parser tests, and enhanced Ollama adapter tests
+
+### Documentation
+- **Examples README**: Comprehensive guide with prerequisites, API key configuration, and per-demo documentation links to https://madbomber.github.io/aia/
+- **Main README**: Added examples directory reference in "Examples & Tips" section; rewrote executable prompts section for shebang auto-detection
+- **CLI Reference**: Removed `--exec` section; updated executable prompt documentation
+- **Directives Reference**: Added `/skill` and `/skills` directive documentation
+- **Model Directive**: Updated with detailed usage examples
+
+### Technical Changes
+- Bumped version from 0.11.1 to 1.0.0-beta
+- Updated prompt_manager dependency to v1.0.2
+- Updated json gem to 2.18.1
+- Simplified directive registry (`lib/aia/directives/registry.rb`)
+- Enhanced PromptHandler with expanded prompt processing logic (326+ lines added)
+- Added `lib/aia/errors.rb` error handling module
+
 ## [0.11.1] - 2026-02-03
 
 ### New Features

data/README.md

@@ -1210,6 +1210,8 @@ The above examples show the shared_tools being used within an interactive chat s
 
 ## Examples & Tips
 
+For a hands-on introduction, see the [examples/](examples/) directory. It contains 20 progressive demo scripts that walk through AIA's batch mode features — from basic prompts through pipelines, multi-model comparison, tools, and MCP servers. Each script is self-contained and runnable with a local Ollama model.
+
 ### Practical Examples
 
 #### Code Review Prompt
@@ -1276,15 +1278,15 @@ aia --chat -m gpt-4o-mini,gpt-3.5-turbo --consensus
 
 ### Executable Prompts
 
-The `--exec` flag is used to create executable prompts.  If it is not present on the shebang line then the prompt file will be treated like any other context file.  That means that the file will be included as context in the prompt but no dynamic content integration or directives will be processed. All other AIA options are, well, optional.  All you need is an initial prompt ID and the --exec flag.
+AIA auto-detects executable prompts by their shebang line (`#!`). Just add a shebang, make the file executable with `chmod +x`, and run it directly. No special flag is needed.
 
-In the example below the option `--no-output` is used to direct the output from the LLM processing of the prompt to STDOUT.  This way the executable prompts can be good citizens on the *nix command line receiving piped in input via STDIN and send its output to STDOUT.
+The option `--no-output` directs the output from the LLM to STDOUT so executable prompts can be good citizens on the *nix command line, receiving piped input via STDIN and sending output to STDOUT.
 
 Create executable prompts:
 
 **weather_report** (make executable with `chmod +x`):
 ```bash
-#!/usr/bin/env aia run --no-output --exec
+#!/usr/bin/env aia run --no-output
 # Get current storm activity for the east and south coast of the US
 
 Summarize the tropical storm outlook fpr the Atlantic, Caribbean Sea and Gulf of America.

data/docs/cli-reference.md

@@ -397,16 +397,6 @@ aia --pipeline "analysis,summary,report" my_data
 aia -p "review,optimize,test" my_code.py
 ```
 
-### `-x, --[no-]exec`
-Designate an executable prompt file.
-
-```bash
-# Treat prompt as executable
-aia --exec my_script_prompt
-
-# Treat as regular prompt (default)
-aia --no-exec my_script_prompt
-```
 
 ### `--system-prompt PROMPT_ID`
 System prompt ID to use for chat sessions.

data/examples/00_setup_aia.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# examples/00_setup_aia.sh
+#
+# Sets up the environment for running AIA example demos.
+# Run this script first before any other example script.
+#
+# What it does:
+#   1. Verifies aia is installed
+#   2. Verifies ollama is installed and running
+#   3. Pulls the qwen3 model (good tool-calling support)
+#   4. Verifies examples/prompts_dir exists
+#   5. Writes examples/aia_config.yml for use with -c flag
+#
+# Each demo script sources common.sh which clears AIA_* env vars
+# and sets CONFIG=aia_config.yml for clean, isolated runs.
+#
+# Usage:
+#   cd examples
+#   bash 00_setup_aia.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROMPTS_DIR="${SCRIPT_DIR}/prompts_dir"
+CONFIG_FILE="${SCRIPT_DIR}/aia_config.yml"
+
+# The model to use for demos. qwen3 is Ollama's reference model
+# for tool calling and has strong instruction-following ability.
+DEMO_MODEL="qwen3"
+
+echo "=== AIA Examples Setup ==="
+echo
+
+# --- Step 1: Check that aia is installed ---
+
+if ! command -v aia &> /dev/null; then
+  echo "ERROR: 'aia' is not installed."
+  echo "       Install with: gem install aia"
+  exit 1
+fi
+
+AIA_VERSION=$(aia --version 2>/dev/null || echo "unknown")
+echo "[ok] aia is installed (v${AIA_VERSION})"
+
+# --- Step 2: Check that ollama is installed and running ---
+
+if ! command -v ollama &> /dev/null; then
+  echo "ERROR: 'ollama' is not installed."
+  echo "       Install from: https://ollama.com"
+  echo "       macOS: brew install ollama"
+  exit 1
+fi
+
+echo "[ok] ollama is installed"
+
+# Check if ollama is serving
+OLLAMA_BASE="${OLLAMA_API_BASE:-http://localhost:11434}"
+
+if ! curl -s "${OLLAMA_BASE}/api/tags" > /dev/null 2>&1; then
+  echo "WARNING: ollama does not appear to be running."
+  echo "         Start it with: ollama serve"
+  echo "         Then re-run this script."
+  exit 1
+fi
+
+echo "[ok] ollama is running at ${OLLAMA_BASE}"
+
+# --- Step 3: Pull the demo model ---
+
+echo
+echo "Checking for model: ${DEMO_MODEL} ..."
+
+if ollama list 2>/dev/null | grep -q "^${DEMO_MODEL}"; then
+  echo "[ok] ${DEMO_MODEL} is already available"
+else
+  echo "Pulling ${DEMO_MODEL} (this may take a few minutes on first run) ..."
+  ollama pull "${DEMO_MODEL}"
+  echo "[ok] ${DEMO_MODEL} pulled successfully"
+fi
+
+# --- Step 4: Verify prompts directory ---
+
+echo
+if [ -d "${PROMPTS_DIR}" ]; then
+  echo "[ok] prompts_dir exists at ${PROMPTS_DIR}"
+else
+  mkdir -p "${PROMPTS_DIR}"
+  echo "[ok] created prompts_dir at ${PROMPTS_DIR}"
+fi
+
+# --- Step 5: Write the config file ---
+
+cat > "${CONFIG_FILE}" <<EOF
+# AIA configuration for example demos
+# Used by all demo scripts via: aia -c aia_config.yml ...
+#
+# This file is loaded with the -c / --config-file flag.
+# It replaces the user's personal config (~/.config/aia/aia.yml),
+# starting from bundled defaults + these values only.
+# CLI flags passed directly to aia still take precedence.
+#
+# NOTE: Relative paths resolve against the directory where aia is invoked.
+#       Run demo scripts from the examples/ directory.
+
+prompts:
+  dir: ./prompts_dir
+
+models:
+  - name: ollama/${DEMO_MODEL}
+
+output:
+  file: ~
+
+flags:
+  chat: false
+EOF
+
+echo "[ok] wrote ${CONFIG_FILE}"
+
+# --- Done ---
+
+echo
+echo "=== Setup Complete ==="
+echo
+echo "All demo scripts use:"
+echo "  aia -c aia_config.yml ..."
+echo "  Model:       ollama/${DEMO_MODEL}"
+echo "  Prompts dir: ${PROMPTS_DIR}"

data/examples/01_basic_usage.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+# examples/01_basic_usage.sh
+#
+# Demonstrates the simplest use of aia: sending a prompt to a model
+# and printing the response.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 01_basic_usage.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 01: Basic Usage ==="
+echo
+echo "The prompt file prompts_dir/hello.md contains:"
+echo "==="
+cat prompts_dir/hello.md
+echo "==="
+echo
+echo "Running: aia -c ${CONFIG} --no-output hello"
+echo
+
+aia -c "${CONFIG}" --no-output hello

data/examples/02_frontmatter.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# examples/02_frontmatter.sh
+#
+# Demonstrates YAML front matter in prompt files.
+# Front matter lets you embed configuration directly in the prompt,
+# such as temperature, model, top_p, and more.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 02_frontmatter.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 02: YAML Front Matter ==="
+echo
+echo "Prompt files can include a YAML front matter block between"
+echo "--- delimiters. AIA applies these settings before sending"
+echo "the prompt to the model."
+echo
+echo "Supported root-level shorthands:"
+echo "  model, temperature, top_p, next, pipeline, shell, erb"
+echo
+echo "The prompt file prompts_dir/creative.md contains:"
+echo "==="
+cat prompts_dir/creative.md
+echo "==="
+echo
+echo "The 'temperature: 0.9' setting makes the response more creative."
+echo
+echo "Running: aia -c ${CONFIG} --no-output creative"
+echo
+
+aia -c "${CONFIG}" --no-output creative

data/examples/03_shell_integration.sh

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# examples/03_shell_integration.sh
+#
+# Demonstrates shell integration in prompts.
+# By default, $(command) is executed and replaced with its output
+# before the prompt is sent to the model. You can disable this
+# with 'shell: false' in the YAML front matter.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 03_shell_integration.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 03: Shell Integration ==="
+echo
+echo "AIA expands \$(command) and \$ENVAR in prompts before sending"
+echo "them to the model. This lets prompts include live system data."
+echo
+
+# --- Part 1: shell expansion ON (default) ---
+
+echo "--- Part 1: Shell expansion ON (default) ---"
+echo
+echo "The prompt file prompts_dir/sysinfo.md contains:"
+echo "==="
+cat prompts_dir/sysinfo.md
+echo "==="
+echo
+echo "The \$(command) references will be replaced with real values."
+echo
+echo "Running: aia -c ${CONFIG} --no-output sysinfo"
+echo
+
+aia -c "${CONFIG}" --no-output sysinfo
+
+echo
+echo
+
+# --- Part 2: shell expansion OFF via front matter ---
+
+echo "--- Part 2: Shell expansion OFF (shell: false) ---"
+echo
+echo "The prompt file prompts_dir/sysinfo_raw.md contains:"
+echo "==="
+cat prompts_dir/sysinfo_raw.md
+echo "==="
+echo
+echo "With 'shell: false' in the front matter, the \$(command)"
+echo "references are sent to the model as literal text."
+echo
+echo "Running: aia -c ${CONFIG} --no-output sysinfo_raw"
+echo
+
+aia -c "${CONFIG}" --no-output sysinfo_raw

data/examples/04_erb_templating.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# examples/04_erb_templating.sh
+#
+# Demonstrates ERB templating in prompts.
+# By default, <%= expression %> is evaluated as Ruby and replaced
+# with the result before the prompt is sent to the model. You can
+# disable this with 'erb: false' in the YAML front matter.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 04_erb_templating.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 04: ERB Templating ==="
+echo
+echo "AIA processes <%= expression %> tags as Ruby (ERB) before"
+echo "sending prompts to the model. This gives prompts access to"
+echo "the full Ruby language."
+echo
+
+# --- Part 1: ERB processing ON (default) ---
+
+echo "--- Part 1: ERB processing ON (default) ---"
+echo
+echo "The prompt file prompts_dir/erbinfo.md contains:"
+echo "==="
+cat prompts_dir/erbinfo.md
+echo "==="
+echo
+echo "The <%= %> tags will be evaluated and replaced with real values."
+echo
+echo "Running: aia -c ${CONFIG} --no-output erbinfo"
+echo
+
+aia -c "${CONFIG}" --no-output erbinfo
+
+echo
+echo
+
+# --- Part 2: ERB processing OFF via front matter ---
+
+echo "--- Part 2: ERB processing OFF (erb: false) ---"
+echo
+echo "The prompt file prompts_dir/erbinfo_raw.md contains:"
+echo "==="
+cat prompts_dir/erbinfo_raw.md
+echo "==="
+echo
+echo "With 'erb: false' in the front matter, the <%= %> tags"
+echo "are sent to the model as literal text."
+echo
+echo "Running: aia -c ${CONFIG} --no-output erbinfo_raw"
+echo
+
+aia -c "${CONFIG}" --no-output erbinfo_raw

data/examples/05_shell_then_erb.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# examples/05_shell_then_erb.sh
+#
+# Demonstrates that shell expansion runs BEFORE ERB processing.
+# This means $(command) and $ENVAR are replaced with their values
+# first, and then ERB evaluates the result as Ruby.
+#
+# This ordering lets you use shell output inside Ruby expressions.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 05_shell_then_erb.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 05: Shell Runs Before ERB ==="
+echo
+echo "AIA processes prompts in this order:"
+echo "  1. Shell: \$(command) and \$ENVAR are expanded"
+echo "  2. ERB:  <%= expression %> is evaluated as Ruby"
+echo
+echo "This means shell output becomes part of the Ruby expression"
+echo "that ERB then evaluates."
+echo
+echo "The prompt file prompts_dir/shell_then_erb.md contains:"
+echo "==="
+cat prompts_dir/shell_then_erb.md
+echo "==="
+echo
+echo "For example:"
+echo "  <%= \"\$(uname -s)\".downcase %>"
+echo "  Step 1 (shell): <%= \"Darwin\".downcase %>"
+echo "  Step 2 (ERB):   darwin"
+echo
+echo "Running: aia -c ${CONFIG} --no-output shell_then_erb"
+echo
+
+aia -c "${CONFIG}" --no-output shell_then_erb

data/examples/06_prompt_chaining.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# examples/06_prompt_chaining.sh
+#
+# Demonstrates prompt chaining with --next and the 'next:' front
+# matter key. The first prompt's response becomes context for
+# the second prompt.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 06_prompt_chaining.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 06: Prompt Chaining ==="
+echo
+echo "AIA can chain prompts so the output of the first becomes"
+echo "context for the second. Two ways to do this:"
+echo "  1. CLI:        --next prompt_id"
+echo "  2. Front matter: next: prompt_id"
+echo
+
+# --- Part 1: --next via CLI ---
+
+echo "--- Part 1: Chaining with --next CLI flag ---"
+echo
+echo "The prompt file prompts_dir/tell_joke.md contains:"
+echo "==="
+cat prompts_dir/tell_joke.md
+echo "==="
+echo
+echo "The prompt file prompts_dir/explain_joke.md contains:"
+echo "==="
+cat prompts_dir/explain_joke.md
+echo "==="
+echo
+echo "Running: aia -c ${CONFIG} --no-output --next explain_joke tell_joke"
+echo
+
+aia -c "${CONFIG}" --no-output --next explain_joke tell_joke
+
+echo
+echo
+
+# --- Part 2: next: in front matter ---
+
+echo "--- Part 2: Chaining with 'next:' in front matter ---"
+echo
+echo "The prompt file prompts_dir/tell_joke_with_next.md contains:"
+echo "==="
+cat prompts_dir/tell_joke_with_next.md
+echo "==="
+echo
+echo "The 'next: explain_joke' front matter does the same thing"
+echo "as --next but is embedded in the prompt file itself."
+echo
+echo "Running: aia -c ${CONFIG} --no-output tell_joke_with_next"
+echo
+
+aia -c "${CONFIG}" --no-output tell_joke_with_next

data/examples/07_pipeline.sh

@@ -0,0 +1,46 @@
+#!/usr/bin/env bash
+# examples/07_pipeline.sh
+#
+# Demonstrates a prompt pipeline — a sequence of prompts where
+# each step's response becomes context for the next.
+#
+# The --pipeline flag accepts comma-separated prompt IDs.
+# The first prompt ID is the main argument; the rest go in --pipeline.
+#
+# NOTE: The same chain could be embedded in the first prompt's
+# front matter instead:
+#   ---
+#   pipeline: evaluate, pick_best, tagline
+#   ---
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 07_pipeline.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 07: Prompt Pipeline ==="
+echo
+echo "A pipeline chains multiple prompts in sequence. Each prompt's"
+echo "response becomes context for the next. This is useful for"
+echo "multi-step reasoning and refinement workflows."
+echo
+echo "This demo runs a 4-step pipeline:"
+echo "  1. brainstorm   — generate five gem names"
+echo "  2. evaluate     — rate each name 1-5"
+echo "  3. pick_best    — choose the winner"
+echo "  4. tagline      — write a tagline for it"
+echo
+
+echo "The prompt files:"
+echo
+for p in brainstorm evaluate pick_best tagline; do
+  echo "--- prompts_dir/${p}.md ---"
+  cat "prompts_dir/${p}.md"
+done
+echo
+
+echo "Running: aia -c ${CONFIG} --no-output --pipeline evaluate,pick_best,tagline brainstorm"
+echo
+
+aia -c "${CONFIG}" --no-output --pipeline evaluate,pick_best,tagline brainstorm

data/examples/08_context_files.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# examples/08_context_files.sh
+#
+# Demonstrates the --context-files option, which attaches the
+# contents of one or more files to the prompt so the model can
+# reference them in its response.
+#
+# Context files are listed as positional arguments after the
+# prompt ID:
+#   aia PROMPT_ID FILE1 FILE2 ...
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 08_context_files.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 08: Context Files ==="
+echo
+echo "Context files let you attach file contents to a prompt so"
+echo "the model can read and reference them. List the files after"
+echo "the prompt ID on the command line."
+echo
+
+echo "The prompt file prompts_dir/summarize_context.md contains:"
+echo "==="
+cat prompts_dir/summarize_context.md
+echo "==="
+echo
+
+echo "We will attach two context files:"
+echo
+echo "--- context/project_goals.md ---"
+cat context/project_goals.md
+echo
+echo "--- context/tech_stack.md ---"
+cat context/tech_stack.md
+echo
+
+echo "Running: aia -c ${CONFIG} --no-output summarize_context context/project_goals.md context/tech_stack.md"
+echo
+
+aia -c "${CONFIG}" --no-output summarize_context context/project_goals.md context/tech_stack.md

data/examples/09_roles.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# examples/09_roles.sh
+#
+# Demonstrates the --role option, which prepends a role prompt
+# to the main prompt. Roles live as .md files in the roles/
+# subdirectory under the prompts directory.
+#
+# Prerequisites: Run 00_setup_aia.sh first.
+# Usage: cd examples && bash 09_roles.sh
+
+set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/common.sh"
+
+echo "=== Demo 09: Roles ==="
+echo
+echo "Roles are reusable system prompts stored as .md files in"
+echo "the roles/ subdirectory of your prompts directory. Use"
+echo "--role ROLE_ID to prepend a role to any prompt."
+echo
+
+echo "The prompt file prompts_dir/weather.md contains:"
+echo "==="
+cat prompts_dir/weather.md
+echo "==="
+echo
+
+echo "Available roles:"
+echo
+for role in prompts_dir/roles/*.md; do
+  name=$(basename "$role" .md)
+  echo "--- roles/${name}.md ---"
+  cat "$role"
+done
+echo
+
+# --- Part 1: No role (baseline) ---
+
+echo "--- Part 1: No role (baseline) ---"
+echo
+echo "Running: aia -c ${CONFIG} --no-output weather"
+echo
+
+aia -c "${CONFIG}" --no-output weather
+
+echo
+echo
+
+# --- Part 2: Pirate role ---
+
+echo "--- Part 2: With --role pirate ---"
+echo
+echo "Running: aia -c ${CONFIG} --no-output --role pirate weather"
+echo
+
+aia -c "${CONFIG}" --no-output --role pirate weather
+
+echo
+echo
+
+# --- Part 3: Formal butler role ---
+
+echo "--- Part 3: With --role formal ---"
+echo
+echo "Running: aia -c ${CONFIG} --no-output --role formal weather"
+echo
+
+aia -c "${CONFIG}" --no-output --role formal weather