UnifyWeaver

Book 4: Workflows and Playbooks

Strategic Guides for AI Agents

Part of the UnifyWeaver Education Series

Welcome to the comprehensive guide for designing workflows and playbooks that enable AI agents to work effectively with UnifyWeaver!

Prerequisites: Complete Books 1-3 for core concepts. This book helps you plan before exploring more targets.

What This Book Covers

This book teaches you how to create strategic guides for AI agents that go beyond simple scripts:

The Paradigm Shift

From Scripts to Strategies

Traditional programming: Write scripts that execute fixed sequences of commands.

Workflow-based AI: Provide agents with:

The AI agent becomes an economic strategist, not just a script executor.

Chapters

Chapter 1: Introduction - Thinking in Workflows

From scripts to strategies. Learn the distinction between workflows (strategic guides) and playbooks (specific execution plans), and how AI agents use them.

Chapter 2: Playbook Format

The standardized format for creating playbooks. Covers frontmatter, callout types ([!output], [!example-record]), and best practices.

Chapter 3: Pipeline Orchestration

Design multi-stage pipelines that chain compilation targets. AWK → Python → Go and other cross-language workflows.

Chapter 4: Economic Decision Making

How AI agents choose strategies based on cost, speed, and quality trade-offs. Heuristics and decision frameworks.

Chapter 5: Example Libraries

Create, organize, and use reusable code patterns. Naming conventions, cross-references, and maintenance.

Additional Resources

Example Libraries

examples_library/

Reusable code patterns and examples:

Sample Playbooks

playbooks/

Complete playbook examples:

Quick Start

5-Minute Introduction

  1. Read Chapter 1: Introduction (5 min)
  2. Skim Chapter 2: Playbook Format (2 min)
  3. Look at Factorial Playbook (3 min)

Complete Guide

Work through all chapters (1-2 hours).

Key Concepts

Workflows

Definition: The overarching strategic guide for an AI agent.

Contains:

Characteristics:

Example: “When compiling Prolog to Bash, analyze the recursion pattern first, then choose between linear recursion, transitive closure, or general recursive compilation based on pattern detection results.”

Playbooks

Definition: Specific, detailed project plans for accomplishing particular tasks.

Contains:

Characteristics:

Example: “To compile factorial: 1) Create /tmp/factorial.pl with this code, 2) Run compiler_driver with factorial/2, 3) Verify output script exists, 4) Test with inputs 0, 5, 10.”

Example Libraries

Purpose: Provide concrete instances of patterns, tools, and solutions.

Structure:

Usage: Playbooks reference examples rather than embedding large code blocks.

Design Principles

1. Separation of Concerns

Workflows: Strategic thinking and decision-making Playbooks: Concrete execution plans Examples: Reusable implementation patterns

Don’t mix these! Keep strategies separate from tactics.

2. Economic Awareness

Every strategy should have:

AI agents use this data to make trade-offs.

3. Heuristic Guidance

Provide rules of thumb:

4. Composability

Design playbooks and examples to work together:

5. Verifiability

Every playbook should include:

Callout Reference

[!output] - Expected Output

Specifies what the agent should generate.

> [!output]
> language: prolog
> purpose: Define factorial predicate
> format: executable
>
> ```prolog
> factorial(0, 1).
> factorial(N, F) :- N > 0, N1 is N-1, factorial(N1, F1), F is N * F1.
> ```

Guidelines:

[!example-record] - Example Reference

Tags reusable examples in libraries.

> [!example-record]
> id: 20251108-factorial-compile
> name: unifyweaver.compilation.factorial
> pattern: linear_recursion
> child_examples: [unifyweaver.testing.factorial_runner]

Metadata:

Common Patterns

Pattern 1: Compile-and-Test Workflow

  1. Define Prolog predicate
  2. Save to file
  3. Compile with compiler_driver
  4. Generate test runner
  5. Execute tests
  6. Verify results

Example: Factorial Complete Workflow

Pattern 2: Data Source Integration

  1. Declare data source (:- source(...))
  2. Define domain predicate
  3. Compile with dynamic source
  4. Generate target scripts
  5. Verify pipeline

Example: Data Source Playbooks

Pattern 3: Multi-Target Generation

  1. Define predicate once
  2. Compile to Bash
  3. Compile to C#
  4. Test both targets
  5. Compare results

Pattern 4: Recursive Pattern Optimization

  1. Analyze recursion type
  2. Choose optimizer (linear, transitive, general)
  3. Compile with appropriate strategy
  4. Verify optimization applied

Example: Ancestor Compilation

Tool Integration

UnifyWeaver Compiler Driver

What: Main compilation orchestrator When: Always use for Prolog→Bash/C# compilation How: compile(Predicate/Arity, Options, Scripts)

Options:

Test Runner Inference

What: Automatically generate test suites When: After compilation, for verification How: generate_test_runner_inferred(Output, Options)

Options:

Example Extraction Tool

What: Perl script to extract examples from libraries When: Building playbooks dynamically How: extract_example.pl --id <example-id>

Creating New Content

Adding a New Playbook

  1. Start with playbook format template
  2. Define goal clearly
  3. Provide strategies (if multiple approaches exist)
  4. Reference relevant examples from libraries
  5. Include expected outputs
  6. Add verification steps

Adding to Example Libraries

  1. Choose appropriate library file
  2. Use [!example-record] callout
  3. Assign unique ID (timestamp-based)
  4. Use namespaced naming (e.g., unifyweaver.pattern.name)
  5. Tag with pattern classification
  6. Cross-reference related examples

Expanding Workflows

  1. Identify strategic decision points
  2. Document alternative approaches
  3. Provide economic data (cost/speed/quality)
  4. Add heuristics for selection
  5. Reference playbooks for each strategy

Current Status

Complete ✅

In Progress 🚧

Planned 📝

Best Practices

For Workflow Designers

  1. Think economically: Always include cost/speed/quality data
  2. Provide options: Multiple strategies > single approach
  3. Use heuristics: Guide decisions with rules of thumb
  4. Stay abstract: Workflows define principles, not details

For Playbook Creators

  1. Be specific: Concrete steps, specific tools
  2. Reference examples: Don’t embed large code blocks
  3. Include verification: How to know it worked
  4. Handle errors: What to do when things fail
  5. Keep outputs minimal: <10% of content in [!output] blocks

For Example Library Maintainers

  1. Tag consistently: Use pattern classifications
  2. Cross-reference: Link related examples
  3. Keep examples small: Focus on one pattern
  4. Provide context: Explain what and why
  5. Update metadata: IDs, names, relationships

Getting Help

Contributing

Want to contribute?

  1. New playbooks: Follow format spec, reference examples
  2. Example patterns: Add to appropriate library file
  3. Documentation: Improve existing content
  4. Workflows: Submit strategic guides

All contributions welcome!

This is part of the UnifyWeaver Educational Series:

  1. Book 1: Foundations - Architecture, Prolog basics
  2. Book 2: Bash Target - Stream compilation
  3. Book 3: C# Target - Fixed-point approaches
  4. Book 4: Workflows (This Book)

Continue to Book 5 or 6 to explore more targets:

Version: 0.2.0 Last Updated: 2025-12-07 Focus: Strategic AI agent guidance

This site is open source. Improve this page.