Dewayne VanHoozer

Visionary leader with extensive technical expertise and a proven track record in steering complex projects to success.

17 minute read

Building AI Workflows: AIA’s Prompt Sequencing and Pipelines

AIA (AI Assistant) is a command-line interface (CLI) written in Ruby and distributed as a Ruby gem (gem install aia). This article is the third installment in a comprehensive series that provides an in-depth exploration of the AIA CLI application, focusing on how to build sophisticated multi-step workflows that link prompts together for complex task automation. While AIA is not an agentic system, it can be effectively utilized to automate tasks by chaining prompts. AIA’s shell and ERB integration enable users to dynamically modify the sequence of steps in a multi-step workflow.

AIA is designed around the concept of managing a prompt pipeline, whether it consists of a single prompt or multiple prompts. This flexibility allows users to create intricate multi-step workflows by connecting several prompts, each building upon the results of the previous ones. This article emphasizes how to construct advanced, dynamic multi-step workflows that effectively link prompts for complex task automation.

Series Articles:

  1. The Philosophy of Prompt-Driven Development with AIA
  2. Mastering AIA’s Batch Mode: From Simple Questions to Complex Workflows
  3. Building AI Workflows: AIA’s Prompt Sequencing and Pipelines (This Article)
  4. Interactive AI Sessions: AIA’s Chat Mode Deep Dive (Coming Soon)
  5. Extending AIA: Custom Tools and Function Callbacks (Coming Soon)

Table of Contents

Prerequisites and Setup

Before diving into AIA’s workflow capabilities, ensure you have the foundation in place:

Installation Requirements:

  • Ruby 3.3+ installed on your system
  • AIA gem installed: gem install aia
  • Basic familiarity with command-line operations

Essential Setup:

  • Configure your prompts directory: export AIA_PROMPTS_DIR="$HOME/.prompts"
  • Set up your preferred AI provider credentials (OpenAI, Anthropic, etc.)
  • Review the previous articles in this series for context on AIA’s philosophy and batch mode

Key Concepts from Previous Articles:

  • Understanding of prompt management and the $AIA_PROMPTS_DIR structure
  • Familiarity with AIA’s configuration hierarchy and directive system
  • Experience with basic batch mode operations from Article 2

This article builds directly on the concepts introduced in our previous discussions of AIA’s philosophy and batch mode capabilities. If you’re new to AIA, we recommend reviewing those articles first for the foundational context.

Introduction: From Single Shots to Sophisticated Sequences

In our previous article, we explored AIA’s batch mode capabilities, seeing how individual prompts could process audio files, analyze code, and generate documentation. Now we transition from those single-step operations to the sophisticated multi-step processes that make AIA truly powerful for complex, real-world tasks.

Think of the difference between taking a single photograph and directing a movie. Both involve the same fundamental technology, but one captures a moment while the other tells a complete story through a sequence of carefully orchestrated scenes. AIA’s workflow features transform your AI interactions from single-shot operations into sophisticated multi-step processes that can handle complex, real-world tasks.

The power of workflows lies in decomposition: breaking complex problems into smaller, focused steps that can be individually optimized and maintained. Each step in an AIA workflow is a specialized prompt designed for a specific transformation, with the ability to pass results seamlessly to the next step in the sequence.

The Evolution of Our Audio Example

Building on the simple audio transcription example from our previous article, let’s evolve it into a complete meeting processing workflow that demonstrates the power of prompt sequencing. This progression shows how workflows naturally emerge from single-step operations.

Step 1: Audio to Transcript

  • Prompt ID: audio_to_transcript
  • Filepath: $AIA_PROMPTS_DIR/audio_to_transcript.txt
# audio_to_transcript.txt
//config model = whisper-1
//config out_file = raw_transcript.txt
//next transcript_to_summary

<!-- Process audio file with high accuracy transcription -->
Transcribe the following audio file with professional meeting standards:

**Audio File:** <%= AIA.context_files.first %>

**Transcription Requirements:**
- Clean, accurate transcription with proper punctuation
- Speaker identification where possible (Speaker 1, Speaker 2, etc.)
- Preserve technical terminology and proper nouns
- Note significant pauses or interruptions as **PAUSE** or **INTERRUPTION**
- Include timestamps every few minutes: 12:34

**Output Format:**
Raw transcript suitable for downstream processing - minimal formatting, focus on accuracy.

<!--
This is the first step in our meeting processing pipeline.
The output will be consumed by the summary generation step.
-->

Step 2: Transcript to Summary

  • Prompt ID: transcript_to_summary
  • Filepath: $AIA_PROMPTS_DIR/transcript_to_summary.txt
# transcript_to_summary.txt
//config model = gpt-4o-mini
//config out_file = meeting_summary.md
//next summary_to_actions

//include raw_transcript.txt

<!-- Convert raw transcript into structured meeting summary -->

Create a comprehensive meeting summary from the transcript above:

## Meeting Overview
- **Date:** $(date)
- **Duration:** [Extract from transcript timestamps]
- **Participants:** [Identify from speaker patterns]
- **Meeting Type:** [Determine from content - standup, planning, review, etc.]

## Executive Summary
Keep the executive summary short no more than 2-3 sentence as an overview of the meeting.

## Key Discussion Points
This section discusses the main topics discussed, organized by theme

## Decisions Made
This section discusses the main decisions made, organized by theme

## Questions Raised
This section includes the open questions that need follow-up

## Technical Details
This section has any technical specifications, requirements, or architectural decisions

---
*Generated from transcript: raw_transcript.txt*
*Processing date: $(date)*

Step 3: Summary to Action Items

Prompt ID: summary_to_actions Filepath: $AIA_PROMPTS_DIR/summary_to_actions.txt

# summary_to_actions.txt
//config model = gpt-4
//config out_file = action_items.md

//include meeting_summary.md

<!-- Extract actionable items and create tracking document -->

Extract and organize actionable items from the meeting summary above:

# Action Items - $(date)

## Immediate Actions (Next 24-48 hours)
| Task | Assigned To | Due Date | Priority | Context |
|------|-------------|----------|----------|---------|

## Short-term Actions (This Sprint/Week)
| Task | Assigned To | Due Date | Priority | Context |
|------|-------------|----------|----------|---------|

## Long-term Actions (Future Sprints)
| Task | Assigned To | Due Date | Priority | Context |
|------|-------------|----------|----------|---------|

## Follow-up Meetings Required
- **Meeting:** [Purpose]
  - **Participants:** [Who needs to attend]
  - **Target Date:** [When]
  - **Agenda Items:** [What to discuss]

---
*Source meeting summary: meeting_summary.md*
*Action items generated: $(date)*
*Next review: $(date -d '+1 week')*

Running the Complete Workflow

# Execute the complete meeting processing pipeline
 aia audio_to_transcript meeting_audio.wav

The workflow automatically proceeds through all three steps, with each prompt building on the results of the previous one. The //next directive ensures seamless progression, while the //include directive incorporates the results from previous steps.

Important Security Note: The //include directive inserts content directly into the prompt, which will be processed by AIA’s shell and ERB integration. This means any shell commands or ERB code within the included file will be executed. For security-sensitive workflows, consider using ERB syntax instead: <% AIA.context_files << 'filepath' %> to reference files without executing their dynamic content.

This security consideration becomes particularly important as we move into more complex workflow patterns where data flows between multiple steps.

Understanding AIA’s Sequencing Mechanisms

With our audio example demonstrating the basic concept, let’s explore the two primary mechanisms AIA provides for creating workflows: individual step sequencing with //next and complete pipeline definition with //pipeline. Understanding these mechanisms is crucial for designing effective workflows.

The //next Directive

The //next directive like the --next CLI option specifies the next prompt to append to the prompt pipeline. All pipelines start with the initial prompt for batch mode processing. For example consider the following:

aia one -n two -n three -n four
# Is the same as:
aia one -p two,three,four

The initial prompt ID is one. Its the first in the pipeline of prompts to be executed followed by two, three and four as prompt IDs. Another way to setup this specific four prompt workflow is to include the `//pipeline two, three, four” directive in the “one.txt” prompt file.

One of the advantages of having a pipeline is that it allows for a more structured and organized approach to prompt execution. By defining a pipeline, you can ensure that each prompt is executed in the correct order, with its desired environment and that the results of one prompt cam be used as input for the next prompt. This can help to streamline the workflow and reduce the risk of errors.

Example: Research workflow

  • Prompt ID: research_start
  • Filepath: $AIA_PROMPTS_DIR/research_start.txt
# research_start.txt
//config model    = o3
//temperature     = 0.3
//config out_file = initial_research.md

//next analyze_research

<!-- Begin research process with next step defined -->
Research the following topic comprehensively: $TOPIC

Include academic sources, industry reports, and recent developments.
Focus on factual information and credible sources.

Research initiated by: $USER
Working directory: $PWD

This creates a chain where research_start automatically triggers analyze_research upon completion, providing a seamless transition from data gathering to analysis.

The //pipeline Directive

For complex workflows, the //pipeline directive like the --pipeline CLI option defines the complete sequence of prompts to process after the initial prompt. This approach is particularly useful when you know the entire workflow structure upfront:

# comprehensive_analysis.txt
//config model    gpt-4.5
//config pipeline research, analyze, synthesize, report

<!--
This prompt starts a multi-step pipeline:
    - research - Gather information
    - analyze - Examine and evaluate
    - synthesize - Draw conclusions
    - report - Create formal documentation
-->

# Establish the role/persona of the LLM
You are my very capable research assistance who excels in gathering information
and providing insightful analysis on subjects that interests me.

# Tell the LLM what to do ...
Provide a comprehensive analysis of: $TOPIC

Pipeline initiated: $(date)
Topic: $TOPIC

Command-Line Pipeline Execution

You can also define pipelines directly from the command line, providing flexibility for different execution scenarios:

# Execute predefined pipeline
TOPIC="AI in Healthcare" aia comprehensive_analysis

# Define pipeline via CLI
TOPIC="Market Analysis" aia research_start --pipeline analyze,synthesize,report

NOTE: When a pipeline is specified on the command line AND the prompt also has a “//pipeline = prompts” directive, the sequence of prompts in the directived are appended to the sequence of prompts that are defined on the command-line. This allows you to establish a baseline sequence on the command-line and then add to that baseline within the prompt.

# Use environment variables for dynamic pipelines
AIA_PIPELINE="clean,analyze,visualize,report" DATA_SOURCE="dataset.csv" aia data_processing

This flexibility enables both predefined workflows and dynamic pipeline construction based on runtime conditions, which we’ll explore in the advanced patterns section.

Advanced Workflow Patterns

Now that we understand the basic sequencing mechanisms, let’s explore more sophisticated patterns that emerge in production workflows. These patterns address common challenges like data persistence, context management, and conditional processing.

File Output Management Across Steps

One of the key challenges in workflow design is ensuring that data flows correctly between steps. Each step in a workflow should produce named output files that subsequent steps can reference:

step1_data_collection

Filepath: $AIA_PROMPTS_DIR/step1_data_collection.txt

# step1_data_collection.txt
//config out_file = collected_data.json
//config model = gpt-4o-mini
//next step2_data_cleaning

<!-- Collect and structure raw data -->
Collect data on: $DATA_TOPIC
Output as structured JSON for downstream processing.

step2_data_cleaning

Filepath: $AIA_PROMPTS_DIR/step2_data_cleaning.txt

# step2_data_cleaning.txt
//config out_file = cleaned_data.json
//config model    = gpt-4o-mini
//next step3_analysis

//include collected_data.json

<!-- Clean and validate the collected data -->
Clean and validate the data above:
- Remove duplicates and inconsistencies
- Standardize formats and naming
- Flag questionable data points
- Output cleaned JSON structure

step3_analysis

Filepath: $AIA_PROMPTS_DIR/step3_analysis.txt

# step3_analysis.txt
//config out_file = analysis_results.md
//config model    = gpt-4

//include cleaned_data.json

<!-- Perform comprehensive analysis -->
Analyze the cleaned data and provide insights for the following area:

- Data Quality Assessment
- Key Patterns and Trends
- Statistical Analysis
- Recommendations

Analysis completed: $(date)

This pattern ensures clean data flow and makes each step’s dependencies explicit, facilitating both debugging and workflow maintenance.

Context Preservation Between Prompts

For workflows that need to maintain state across multiple steps, you can use ERB (Embedded Ruby) to create persistent context that travels with your workflow:

workflow_start

Filepath: $AIA_PROMPTS_DIR/workflow_start.txt

# workflow_start.txt
//config pipeline clean,analyze,report
//config out_file = step1_complete.json

<%
  # Create workflow metadata for all steps
  workflow_context = {
    workflow_id: SecureRandom.uuid,
    start_time: Time.now.iso8601,
    user: ENV['USER'],
    working_dir: Dir.pwd,
    input_topic: ENV['TOPIC'],
    steps_completed: [],
    current_step: 'clean'
  }

  File.write('.workflow_context.json', workflow_context.to_json)
%>

<!-- Begin data cleaning with full context -->
Starting workflow: <%= workflow_context[:workflow_id] %>
Topic: <%= workflow_context[:input_topic] %>
Step 1 of 3: Data Cleaning

Process the following data with cleaning focus...

Each subsequent step can read and update this context:

analyze

Filepath: $AIA_PROMPTS_DIR/analyze.txt

# analyze.txt
//config out_file = step2_complete.json

<%
  context = JSON.parse(File.read('.workflow_context.json'))
  context['current_step'] = 'analyze'
  context['steps_completed'] << 'clean'
  File.write('.workflow_context.json', context.to_json)
%>

//include step1_complete.json

<!-- Analysis step with context awareness -->
Continuing workflow: <%= context['workflow_id'] %>
Previous step completed: <%= context['steps_completed'].last %>
Current step: <%= context['current_step'] %>

Analyze the cleaned data above...

This context preservation pattern is essential for workflows that need to maintain consistency across multiple AI interactions. It gives you the ability to restart the workflow in the middle should it fail or need to be interrupted.

TIP: within the AIA all ERB execution takes place within the same binding. This means that if you want to pass some kind of state information from one prompt execution to another you could use an instance variable instead of writing the state information to a file. This however, does not allow for restarting a workflow in the middle because the state information goes away when the AIA terminates.

Conditional Workflow Branching

Advanced workflows often need to adapt their behavior based on runtime conditions. Here’s how to create workflows that make intelligent decisions about their execution path:

# intelligent_processor.txt
<%
  input_file     = AIA.config.context_files.first
  file_size      = File.size(input_file)
  content_sample = File.read(input_file, 1000) # Read first 1KB
%>

<!-- Determine processing path based on file characteristics -->

<% if file_size > 1_000_000 %>
//config next large_file_processor
//config model = gpt-4

Large file detected (<%= file_size %> bytes).
Using enhanced processing with chunking strategy.

<% elsif content_sample.include?('URGENT') || content_sample.include?('CRITICAL') %>
//config next priority_processor
//config model = gpt-4
//config temperature = 0.1

Priority content detected in sample.
Using focused, deterministic processing mode.

<% else %>
//config next standard_processor
//config model = gpt-4o-mini

Standard content detected.
Using efficient general-purpose processing.
<% end %>

**File Analysis:**
- Size: <%= file_size %> bytes
- Sample content: <%= content_sample[0..200] %>...
- Processing route: <%= file_size > 1_000_000 ? 'large_file' : content_sample.include?('URGENT') ? 'priority' : 'standard' %>
- Timestamp: <%= Time.now.iso8601 %>

This conditional branching capability provided by ERB allows prompts to adapt intelligently to different conditions, optimizing both performance and cost.

Advanced Techniques for Production Workflows

As workflows become more complex and are deployed in production environments, additional patterns emerge for handling enterprise-level requirements.

Dynamic Pipeline Construction

For enterprise workflows, you may need pipelines that adapt based on runtime conditions or business rules:

# adaptive_pipeline.txt
<%
  # Determine pipeline based on environment variables
  AIA.config.pipeline = ["initial_assessment"]

  # Add conditional steps based on environment
  AIA.config.pipeline << "detailed_analysis"    if ENV['ANALYSIS_DEPTH'] == 'deep'
  AIA.config.pipeline << "statistical_modeling" if ENV['INCLUDE_STATISTICS'] == 'true'
  AIA.config.pipeline << "risk_assessment"      if ENV['RISK_ANALYSIS'] == 'required'
  AIA.config.pipeline << "executive_summary"    # Always include
%>

//config model = gpt-4

<!-- Dynamic pipeline construction based on runtime requirements -->

# Adaptive Analysis Pipeline

**Pipeline Configuration:** <%= AIA.config.pipeline.join(", ") %>
**Environment Settings:**
- Analysis Depth: <%= ENV['ANALYSIS_DEPTH'] || 'standard' %>
- Statistics: <%= ENV['INCLUDE_STATISTICS'] || 'false' %>
- Risk Analysis: <%= ENV['RISK_ANALYSIS']   || 'optional' %>

**Estimated Processing Time:** <%= pipeline_steps.length * 5 %> minutes
**Pipeline Initiated:** <%= Time.now.iso8601 %>

Beginning analysis with adaptive pipeline configuration...

This dynamic construction approach enables workflows that can be configured for different business scenarios without requiring separate prompt files for each variation.

Best Practices for Workflow Design

Successful workflow design requires attention to several key principles that ensure maintainability, reliability, and scalability.

Design Principles

Single Responsibility Principle Each prompt should have one clear, focused purpose. This makes prompts easier to debug, test, and reuse across different workflows.

Here is a good example:

# clean_data.txt
//config out_file = cleaned_data.json
//next validate_data

Clean and standardize the input dataset:
- Remove duplicates and null values
- Standardize date formats
- Normalize text fields
- Output structured JSON

Here is a bad example:

# Bad: Multiple responsibilities
# process_everything.txt
//config out_file = final_results.pdf

Clean data, analyze trends, generate visualizations,
create executive summary, and format final report...

Idempotency Prompts should be safely re-runnable without side effects. This enables error recovery and debugging.

# clean_data_idempotent.txt
# Do not over-write the previous version of the out_file
//config out_file = cleaned_data_$(date +%Y%m%d_%H%M).json

Clean and process raw data with idempotent operations...

File Management Strategies

Descriptive Output Naming Use descriptive file names that indicate content, step, and timestamp.

# research_step1_data_collection.txt
//config out_file = research_raw_data_$(date +%Y%m%d_%H%M).md
//ruby AIA.config.data_filename = AIA.config.out_file
//next research_step2_analysis

prompts instructions for data collection...

Use AIA.config to pass dynamic filenames from one workflow step to the next.

# analysis_step2_statistical.txt
//ruby AIA.config.context_files = [AIA.config.data_filename]
//config out_file = statistical_analysis_$(date +%Y%m%d_%H%M).md
//ruby AIA.config.data_filename = AIA.config.out_file

//next analysis_step3_synthesis

prompts instructions for statistical analysis...

Performance Optimization

Model Selection by Task Complexity Use appropriate models for different workflow steps to optimize cost and speed.

# data_cleaning.txt (Simple task)
//config model       = gpt-4o-mini
//config temperature = 0.1

Matching the model to the task can save both time and money.

# strategic_analysis.txt (Complex reasoning)
//config model       = gpt-4
//config temperature = 0.3

There is no reason to use the latest and greatest models for simple tasks.

# creative_content.txt (Creative task)
//config model       = gpt-3.5-turbo
//config temperature = 0.8

Security Considerations

Input Validation Validate all inputs at workflow entry points. If your prompt depends upon a system environment variable being set, make sure that it is set. If not you can always exit or use a default value.

# secure_workflow_entry.txt
$(
if [ -z "$TOPIC" ]; then
    export TOPIC="Prepending envar values to a shell commands in BASH"
    echo "TOPIC was not set. It has been set to: $TOPIC"
else
    echo "TOPIC is set to: $TOPIC"
fi
)

Tell me everything you know about $TOPIC

About the //clear Directive

The //clear directive is used to clear the prompt context window. When processing a pipeline of prompts, AIA maintains the context of user and AI interactions. Some models have a small context window, while others have a larger one. In the pipeline, a prompt begins with the context that has been saved by all of the preceding prompts. This context can become quite extensive. Often, it is not necessary to carry over a prompt’s context to the next prompt, and this is where the //clear directive proves useful. It allows you to clear the context window and start anew with a clean slate.

Regardless of its position within a prompt file, the //clear directive will clear the current context window and refresh it for the current prompt. The carryover of the context window from one prompt to the next can be both beneficial and problematic. For instance, if one step in your workflow involves handling sensitive information and you are using a local LLM provider like ollama or lm studio to process your prompt, then in the subsequent prompt in the pipeline, if you are processing against a model provided by OpenAI, you risk sending context that may include sensitive data to OpenAI.

Therefore, it may be prudent to use //clear in a prompt within a workflow to remove the prior context window before utilizing an external provider.

About the //Config directive

In this series of articles, you have seen example prompts that extensively utilize the //config <key> [=] <value> directive to change or establish the operating environment under which a prompt is processed. This article also highlights that the AIA.config object is an open, mutable object, allowing a prompt to dynamically save information that can be passed on to other prompts within a workflow pipeline. To enhance your ability to create dynamic, complex workflows, it is essential to understand all the existing objects within the AIA.config. The easiest way to do this is to use the //config directive in a prompt without any arguments.

When you use //config without any arguments within a prompt, the entire AIA.config object is printed in a human-readable format to STDOUT. It does not become part of the prompt’s context window. If you are only interested in a specific key then you can use the directive //config key to just get a printout of that specific key’s value.

Looking Forward: From Workflows to Interactive Sessions

The workflow capabilities we’ve explored in this article represent AIA’s power to automate complex, multi-step processes. By chaining prompts together, we can create sophisticated automation that handles everything from meeting processing to comprehensive research analysis.

But what happens when you need to interact with the AI during the process? When the workflow needs human input, clarification, or dynamic decision-making? This is where AIA’s chat mode capabilities become essential.

In our next article, “Interactive AI Sessions: AIA’s Chat Mode Deep Dive,” we’ll explore how AIA transforms from an automation engine into an interactive partner. We’ll see how chat sessions can incorporate workflow elements, maintain context across long conversations, and provide the flexibility needed for exploratory and collaborative AI work.

The progression from philosophy to batch mode to workflows to interactive sessions represents a complete spectrum of AI integration approaches. Each mode has its place in the developer’s toolkit, and mastering all of them provides the foundation for truly effective AI-assisted work.

Next in Series: “Interactive AI Sessions: AIA’s Chat Mode Deep Dive”

Installation and Setup:

gem install aia
aia --help

Explore Further:

You May Also Enjoy

AIA Batch Mode

13 minute read

Mastering AIA’s Batch Mode: From Simple Questions to Complex Workflows

AIA Philosophy

14 minute read

The Prompt is the Code: A Power Tool Philosophy for AI Integration