Prose

# Hello World
# The simplest OpenProse program - a single session

session "Say hello and briefly introduce yourself"

# Research and Summarize
# A two-step workflow: research a topic, then summarize findings

session "Research the latest developments in AI agents and multi-agent systems. Focus on papers and announcements from the past 6 months."

session "Summarize the key findings from your research in 5 bullet points. Focus on practical implications for developers."

# Code Review Pipeline
# Review code from multiple perspectives sequentially

# First, understand what the code does
session "Read the files in src/ and provide a brief overview of the codebase structure and purpose."

# Security review
session "Review the code for security vulnerabilities. Look for injection risks, authentication issues, and data exposure."

# Performance review
session "Review the code for performance issues. Look for N+1 queries, unnecessary allocations, and blocking operations."

# Maintainability review
session "Review the code for maintainability. Look for code duplication, unclear naming, and missing documentation."

# Synthesize findings
session "Create a unified code review report combining all the findings above. Prioritize issues by severity and provide actionable recommendations."

# Write and Refine
# Draft content, then iteratively improve it

# Create initial draft
session "Write a first draft of a README.md for this project. Include sections for: overview, installation, usage, and contributing."

# Self-review and improve
session "Review the README draft you just wrote. Identify areas that are unclear, too verbose, or missing important details."

# Apply improvements
session "Rewrite the README incorporating your review feedback. Make it more concise and add any missing sections."

# Final polish
session "Do a final pass on the README. Fix any typos, improve formatting, and ensure code examples are correct."

# Debug an Issue
# Step-by-step debugging workflow

# Understand the problem
session "Read the error message and stack trace. Identify which file and function is causing the issue."

# Gather context
session "Read the relevant source files and understand the code flow that leads to the error."

# Form hypothesis
session "Based on your investigation, form a hypothesis about what's causing the bug. List 2-3 possible root causes."

# Test hypothesis
session "Write a test case that reproduces the bug. This will help verify the fix later."

# Implement fix
session "Implement a fix for the most likely root cause. Explain your changes."

# Verify fix
session "Run the test suite to verify the fix works and doesn't break anything else."

# Explain Codebase
# Progressive exploration of an unfamiliar codebase

# Start with the big picture
session "List all directories and key files in this repository. Provide a high-level map of the project structure."

# Understand the entry point
session "Find the main entry point of the application. Explain how the program starts and initializes."

# Trace a key flow
session "Trace through a typical user request from start to finish. Document the key functions and modules involved."

# Document architecture
session "Based on your exploration, write a brief architecture document explaining how the major components fit together."

# Identify patterns
session "What design patterns and conventions does this codebase use? Document any patterns future contributors should follow."

# Refactor Code
# Systematic refactoring workflow

# Assess current state
session "Analyze the target code and identify code smells: duplication, long functions, unclear naming, tight coupling."

# Plan refactoring
session "Create a refactoring plan. List specific changes in order of priority, starting with the safest changes."

# Ensure test coverage
session "Check test coverage for the code being refactored. Add any missing tests before making changes."

# Execute refactoring
session "Implement the first refactoring from your plan. Make a single focused change."

# Verify behavior
session "Run tests to verify the refactoring preserved behavior. If tests fail, investigate and fix."

# Document changes
session "Update any documentation affected by the refactoring. Add comments explaining non-obvious design decisions."

# Write a Blog Post
# End-to-end content creation workflow

# Research the topic
session "Research the topic: 'Best practices for error handling in TypeScript'. Find authoritative sources and common patterns."

# Create outline
session "Create a detailed outline for the blog post. Include introduction, 4-5 main sections, and conclusion."

# Write first draft
session "Write the full blog post following the outline. Target 1500-2000 words. Include code examples."

# Technical review
session "Review the blog post for technical accuracy. Verify all code examples compile and work correctly."

# Editorial review
session "Review the blog post for clarity and readability. Simplify complex sentences and improve flow."

# Add finishing touches
session "Add a compelling title, meta description, and suggest 3-5 relevant tags for the post."

# Research Pipeline with Specialized Agents
# This example demonstrates defining agents with different models
# and using them in sessions with property overrides.

# Define specialized agents
agent researcher:
  model: sonnet
  prompt: "You are a research assistant skilled at finding and synthesizing information"

agent writer:
  model: opus
  prompt: "You are a technical writer who creates clear, concise documentation"

# Step 1: Initial research with the researcher agent
session: researcher
  prompt: "Research recent developments in renewable energy storage technologies"

# Step 2: Deep dive with a more powerful model
session: researcher
  model: opus
  prompt: "Analyze the top 3 most promising battery technologies and their potential impact"

# Step 3: Write up the findings
session: writer
  prompt: "Create a summary report of the research findings suitable for executives"

# Code Review Workflow with Agents
# This example shows how to use agents for a multi-step code review process.

# Define agents with specific roles
agent security-reviewer:
  model: opus
  prompt: "You are a security expert focused on identifying vulnerabilities"

agent performance-reviewer:
  model: sonnet
  prompt: "You are a performance optimization specialist"

agent style-reviewer:
  model: haiku
  prompt: "You check for code style and best practices"

# Step 1: Quick style check (fast)
session: style-reviewer
  prompt: "Review the code in src/ for style issues and naming conventions"

# Step 2: Performance analysis (medium)
session: performance-reviewer
  prompt: "Identify any performance bottlenecks or optimization opportunities"

# Step 3: Security audit (thorough)
session: security-reviewer
  prompt: "Perform a security review looking for OWASP top 10 vulnerabilities"

# Step 4: Summary
session: security-reviewer
  model: sonnet
  prompt: "Create a consolidated report of all review findings with priority rankings"

# Skills and Imports Example
# This demonstrates importing external skills and assigning them to agents.

# Import skills from external sources
import "web-search" from "github:anthropic/skills"
import "summarizer" from "npm:@example/summarizer"
import "file-reader" from "./local-skills/file-reader"

# Define a research agent with web search capability
agent researcher:
  model: sonnet
  prompt: "You are a research assistant skilled at finding information"
  skills: ["web-search", "summarizer"]

# Define a documentation agent with file access
agent documenter:
  model: opus
  prompt: "You create comprehensive documentation"
  skills: ["file-reader", "summarizer"]

# Research phase
session: researcher
  prompt: "Search for recent developments in renewable energy storage"

# Documentation phase
session: documenter
  prompt: "Create a technical summary of the research findings"

# Secure Agent with Permissions Example
# This demonstrates defining agents with restricted access permissions.

# Import required skills
import "code-analyzer" from "github:anthropic/code-tools"

# Define a read-only code reviewer
# This agent can read source files but cannot modify them or run shell commands
agent code-reviewer:
  model: sonnet
  prompt: "You are a thorough code reviewer"
  skills: ["code-analyzer"]
  permissions:
    read: ["src/**/*.ts", "src/**/*.js", "*.md"]
    write: []
    bash: deny

# Define a documentation writer with limited write access
# Can only write to docs directory
agent doc-writer:
  model: opus
  prompt: "You write technical documentation"
  permissions:
    read: ["src/**/*", "docs/**/*"]
    write: ["docs/**/*.md"]
    bash: deny

# Define a full-access admin agent
agent admin:
  model: opus
  prompt: "You perform administrative tasks"
  permissions:
    read: ["**/*"]
    write: ["**/*"]
    bash: prompt
    network: allow

# Workflow: Code review followed by documentation update
session: code-reviewer
  prompt: "Review the codebase for security issues and best practices"

session: doc-writer
  prompt: "Update the documentation based on the code review findings"

# Example 13: Variables & Context
#
# This example demonstrates using let/const bindings to capture session
# outputs and pass them as context to subsequent sessions.

# Define specialized agents for the workflow
agent researcher:
  model: sonnet
  prompt: "You are a thorough research assistant who gathers comprehensive information on topics."

agent analyst:
  model: opus
  prompt: "You are a data analyst who identifies patterns, trends, and key insights."

agent writer:
  model: opus
  prompt: "You are a technical writer who creates clear, well-structured documents."

# Step 1: Gather initial research (captured in a variable)
let research = session: researcher
  prompt: "Research the current state of quantum computing, including recent breakthroughs, major players, and potential applications."

# Step 2: Analyze the research findings (using research as context)
let analysis = session: analyst
  prompt: "Analyze the key findings and identify the most promising directions."
  context: research

# Step 3: Get additional perspectives (refreshing context)
let market-trends = session: researcher
  prompt: "Research market trends and commercial applications of quantum computing."
  context: []

# Step 4: Combine multiple contexts for final synthesis
const report = session: writer
  prompt: "Write a comprehensive executive summary covering research, analysis, and market trends."
  context: [research, analysis, market-trends]

# Step 5: Iterative refinement with variable reassignment
let draft = session: writer
  prompt: "Create an initial draft of the technical deep-dive section."
  context: research

# Refine the draft using its own output as context
draft = session: writer
  prompt: "Review and improve this draft for clarity and technical accuracy."
  context: draft

# Final polish
draft = session: writer
  prompt: "Perform final editorial review and polish the document."
  context: draft

# Example 14: Composition Blocks
# Demonstrates do: blocks, block definitions, and inline sequences

# Define reusable agents
agent researcher:
  model: sonnet
  prompt: "You are a thorough research assistant"

agent writer:
  model: opus
  prompt: "You are a skilled technical writer"

agent reviewer:
  model: sonnet
  prompt: "You are a careful code and document reviewer"

# Define a reusable research block
block research-phase:
  session: researcher
    prompt: "Gather information on the topic"
  session: researcher
    prompt: "Analyze key findings"

# Define a reusable writing block
block writing-phase:
  session: writer
    prompt: "Write initial draft"
  session: writer
    prompt: "Polish and refine the draft"

# Define a review block
block review-cycle:
  session: reviewer
    prompt: "Review for accuracy"
  session: reviewer
    prompt: "Review for clarity"

# Main workflow using blocks
let research = do research-phase

let document = do writing-phase

do review-cycle

# Use anonymous do block for final steps
do:
  session "Incorporate review feedback"
  session "Prepare final version"

# Example 15: Inline Sequences
# Demonstrates the -> operator for chaining sessions

# Quick pipeline using arrow syntax
session "Plan the task" -> session "Execute the plan" -> session "Review results"

# Inline sequence with context capture
let analysis = session "Analyze data" -> session "Draw conclusions"

session "Write report"
  context: analysis

# Combine inline sequences with blocks
block quick-check:
  session "Security scan" -> session "Performance check"

do quick-check

# Use inline sequence in variable assignment
let workflow = session "Step 1" -> session "Step 2" -> session "Step 3"

session "Final step"
  context: workflow

# Parallel Code Reviews
# Run multiple specialized reviews concurrently

agent reviewer:
  model: sonnet
  prompt: "You are an expert code reviewer"

# Run all reviews in parallel
parallel:
  security = session: reviewer
    prompt: "Review for security vulnerabilities"
  perf = session: reviewer
    prompt: "Review for performance issues"
  style = session: reviewer
    prompt: "Review for code style and readability"

# Synthesize all review results
session "Create unified code review report"
  context: { security, perf, style }

# Parallel Research
# Gather information from multiple sources concurrently

agent researcher:
  model: sonnet
  prompt: "You are a research assistant"

# Research multiple aspects in parallel
parallel:
  history = session: researcher
    prompt: "Research the historical background"
  current = session: researcher
    prompt: "Research the current state of the field"
  future = session: researcher
    prompt: "Research future trends and predictions"

# Combine all research
session "Write comprehensive research summary"
  context: { history, current, future }

# Mixed Parallel and Sequential Workflow
# Demonstrates nesting parallel and sequential blocks

agent worker:
  model: sonnet

# Define reusable blocks
block setup:
  session "Initialize resources"
  session "Validate configuration"

block cleanup:
  session "Save results"
  session "Release resources"

# Main workflow with mixed composition
do:
  do setup

  # Parallel processing phase
  parallel:
    # Each parallel branch can have multiple steps
    do:
      session: worker
        prompt: "Process batch 1 - step 1"
      session: worker
        prompt: "Process batch 1 - step 2"
    do:
      session: worker
        prompt: "Process batch 2 - step 1"
      session: worker
        prompt: "Process batch 2 - step 2"

  session "Aggregate results"

  do cleanup

# Advanced Parallel Execution (Tier 7)
#
# Demonstrates join strategies and failure policies
# for parallel blocks.

agent researcher:
  model: haiku
  prompt: "You are a research assistant. Provide concise information."

# 1. Race Pattern: First to Complete Wins
# ----------------------------------------
# Use parallel ("first") when you want the fastest result
# and don't need all branches to complete.

parallel ("first"):
  session: researcher
    prompt: "Find information via approach A"
  session: researcher
    prompt: "Find information via approach B"
  session: researcher
    prompt: "Find information via approach C"

session "Summarize: only the fastest approach completed"

# 2. Any-N Pattern: Get Multiple Quick Results
# --------------------------------------------
# Use parallel ("any", count: N) when you need N results
# but not necessarily all of them.

parallel ("any", count: 2):
  a = session "Generate a creative headline for a tech blog"
  b = session "Generate a catchy headline for a tech blog"
  c = session "Generate an engaging headline for a tech blog"
  d = session "Generate a viral headline for a tech blog"

session "Choose the best from the 2 headlines that finished first"
  context: { a, b, c, d }

# 3. Continue on Failure: Gather All Results
# ------------------------------------------
# Use on-fail: "continue" when you want all branches
# to complete and handle failures afterwards.

parallel (on-fail: "continue"):
  session "Fetch data from primary API"
  session "Fetch data from secondary API"
  session "Fetch data from backup API"

session "Combine all available data, noting any failures"

# 4. Ignore Failures: Best-Effort Enrichment
# ------------------------------------------
# Use on-fail: "ignore" for optional enrichments
# where failures shouldn't block progress.

parallel (on-fail: "ignore"):
  session "Get optional metadata enrichment 1"
  session "Get optional metadata enrichment 2"
  session "Get optional metadata enrichment 3"

session "Continue with whatever enrichments succeeded"

# 5. Combined: Race with Resilience
# ---------------------------------
# Combine join strategies with failure policies.

parallel ("first", on-fail: "continue"):
  session "Fast but might fail"
  session "Slow but reliable"

session "Got the first result, even if it was a handled failure"

# Example: Fixed Loops in OpenProse
# Demonstrates repeat, for-each, and parallel for-each patterns

# Repeat block - generate multiple ideas
repeat 3:
  session "Generate a creative app idea"

# For-each block - iterate over a collection
let features = ["authentication", "dashboard", "notifications"]
for feature in features:
  session "Design the user interface for this feature"
    context: feature

# Parallel for-each - research in parallel
let topics = ["market size", "competitors", "technology stack"]
parallel for topic in topics:
  session "Research this aspect of the startup idea"
    context: topic

session "Synthesize all research into a business plan"

# Pipeline Operations Example
# Demonstrates functional-style collection transformations

# Define a collection of startup ideas
let ideas = ["AI tutor", "smart garden", "fitness tracker", "meal planner", "travel assistant"]

# Filter to keep only tech-focused ideas
let tech_ideas = ideas | filter:
  session "Is this idea primarily technology-focused? Answer yes or no."
    context: item

# Map to expand each idea into a business pitch
let pitches = tech_ideas | map:
  session "Write a compelling one-paragraph business pitch for this idea"
    context: item

# Reduce all pitches into a portfolio summary
let portfolio = pitches | reduce(summary, pitch):
  session "Integrate this pitch into the portfolio summary, maintaining coherence"
    context: [summary, pitch]

# Present the final portfolio
session "Format and present the startup portfolio as a polished document"
  context: portfolio

# Parallel map example - research multiple topics concurrently
let topics = ["market analysis", "competition", "funding options"]

let research = topics | pmap:
  session "Research this aspect of the startup portfolio"
    context: item

# Final synthesis
session "Create an executive summary combining all research findings"
  context: research

# Error Handling Example
# Demonstrates try/catch/finally patterns for resilient workflows

# Basic try/catch for error recovery
try:
  session "Attempt to fetch data from external API"
catch:
  session "API failed - use cached data instead"

# Catch with error variable for context-aware handling
try:
  session "Parse and validate complex configuration file"
catch as err:
  session "Handle the configuration error"
    context: err

# Try/catch/finally for resource cleanup
try:
  session "Open database connection and perform queries"
catch:
  session "Log database error and notify admin"
finally:
  session "Ensure database connection is properly closed"

# Nested error handling
try:
  session "Start outer transaction"
  try:
    session "Perform risky inner operation"
  catch:
    session "Recover inner operation"
    throw  # Re-raise to outer handler
catch:
  session "Handle re-raised error at outer level"

# Error handling in parallel blocks
parallel:
  try:
    session "Service A - might fail"
  catch:
    session "Fallback for Service A"
  try:
    session "Service B - might fail"
  catch:
    session "Fallback for Service B"

session "Continue with whatever results we got"

# Throwing custom errors
session "Validate input data"
throw "Validation failed: missing required fields"

# Retry with Backoff Example
# Demonstrates automatic retry patterns for resilient API calls

# Simple retry - try up to 3 times on failure
session "Call flaky third-party API"
  retry: 3

# Retry with exponential backoff for rate-limited APIs
session "Query rate-limited service"
  retry: 5
  backoff: "exponential"

# Retry with linear backoff
session "Send webhook notification"
  retry: 3
  backoff: "linear"

# Combining retry with context passing
let config = session "Load API configuration"

session "Make authenticated API request"
  context: config
  retry: 3
  backoff: "exponential"

# Retry inside try/catch for fallback after all retries fail
try:
  session "Call primary payment processor"
    retry: 3
    backoff: "exponential"
catch:
  session "All retries failed - use backup payment processor"
    retry: 2

# Parallel retries for redundant services
parallel:
  primary = try:
    session "Query primary database"
      retry: 2
      backoff: "linear"
  catch:
    session "Primary DB unavailable"
  replica = try:
    session "Query replica database"
      retry: 2
      backoff: "linear"
  catch:
    session "Replica DB unavailable"

session "Merge results from available databases"
  context: { primary, replica }

# Retry in a loop for batch processing
let items = ["batch1", "batch2", "batch3"]
for item in items:
  try:
    session "Process this batch item"
      context: item
      retry: 2
      backoff: "exponential"
  catch:
    session "Log failed batch for manual review"
      context: item

# Choice Blocks Example
# Demonstrates AI-selected branching based on runtime criteria

# Simple choice based on analysis
let analysis = session "Analyze the current codebase quality"

choice **the severity of issues found**:
  option "Critical":
    session "Stop all work and fix critical issues immediately"
      context: analysis
    session "Create incident report"
  option "Moderate":
    session "Schedule fixes for next sprint"
      context: analysis
  option "Minor":
    session "Add to technical debt backlog"
      context: analysis

# Choice for user experience level
choice **the user's technical expertise based on their question**:
  option "Beginner":
    session "Explain concepts from first principles"
    session "Provide step-by-step tutorial"
    session "Include helpful analogies"
  option "Intermediate":
    session "Give concise explanation with examples"
    session "Link to relevant documentation"
  option "Expert":
    session "Provide technical deep-dive"
    session "Include advanced configuration options"

# Choice for project approach
let requirements = session "Gather project requirements"

choice **the best development approach given the requirements**:
  option "Rapid prototype":
    session "Create quick MVP focusing on core features"
      context: requirements
    session "Plan iteration cycle"
  option "Production-ready":
    session "Design complete architecture"
      context: requirements
    session "Set up CI/CD pipeline"
    session "Implement with full test coverage"
  option "Research spike":
    session "Explore technical feasibility"
      context: requirements
    session "Document findings and recommendations"

# Multi-line criteria for complex decisions
let market_data = session "Gather market research data"
let tech_analysis = session "Analyze technical landscape"

choice ***
  the optimal market entry strategy
  considering both market conditions
  and technical readiness
***:
  option "Aggressive launch":
    session "Prepare for immediate market entry"
      context: [market_data, tech_analysis]
  option "Soft launch":
    session "Plan limited beta release"
      context: [market_data, tech_analysis]
  option "Wait and iterate":
    session "Continue development and monitor market"
      context: [market_data, tech_analysis]

# Nested choices for detailed decision trees
let request = session "Analyze incoming customer request"

choice **the type of request**:
  option "Technical support":
    choice **the complexity of the technical issue**:
      option "Simple":
        session "Provide self-service solution"
          context: request
      option "Complex":
        session "Escalate to senior engineer"
          context: request
  option "Sales inquiry":
    session "Forward to sales team with context"
      context: request
  option "Feature request":
    session "Add to product backlog and notify PM"
      context: request

# Conditionals Example
# Demonstrates if/elif/else patterns with AI-evaluated conditions

# Simple if statement
let health_check = session "Check system health status"

if **the system is unhealthy**:
  session "Alert on-call engineer"
    context: health_check
  session "Begin incident response"

# If/else for binary decisions
let review = session "Review the pull request changes"

if **the code changes are safe and well-tested**:
  session "Approve and merge the pull request"
    context: review
else:
  session "Request changes with detailed feedback"
    context: review

# If/elif/else for multiple conditions
let status = session "Check project milestone status"

if **the project is ahead of schedule**:
  session "Document success factors"
  session "Consider adding stretch goals"
elif **the project is on track**:
  session "Continue with current plan"
  session "Prepare status report"
elif **the project is slightly delayed**:
  session "Identify bottlenecks"
  session "Adjust timeline and communicate to stakeholders"
else:
  session "Escalate to management"
  session "Create recovery plan"
  session "Schedule daily standups"

# Multi-line conditions
let test_results = session "Run full test suite"

if ***
  all tests pass
  and code coverage is above 80%
  and there are no linting errors
***:
  session "Deploy to production"
else:
  session "Fix issues before deploying"
    context: test_results

# Nested conditionals
let request = session "Analyze the API request"

if **the request is authenticated**:
  if **the user has admin privileges**:
    session "Process admin request with full access"
      context: request
  else:
    session "Process standard user request"
      context: request
else:
  session "Return 401 authentication error"

# Conditionals with error handling
let operation_result = session "Attempt complex operation"

if **the operation succeeded partially**:
  session "Complete remaining steps"
    context: operation_result

try:
  session "Perform another risky operation"
catch as err:
  if **the error is recoverable**:
    session "Apply automatic recovery procedure"
      context: err
  else:
    throw "Unrecoverable error encountered"

# Conditionals inside loops
let items = ["item1", "item2", "item3"]

for item in items:
  session "Analyze this item"
    context: item

  if **the item needs processing**:
    session "Process the item"
      context: item
  elif **the item should be skipped**:
    session "Log skip reason"
      context: item
  else:
    session "Archive the item"
      context: item

# Conditionals with parallel blocks
parallel:
  security = session "Run security scan"
  performance = session "Run performance tests"
  style = session "Run style checks"

if **security issues were found**:
  session "Fix security issues immediately"
    context: security
elif **performance issues were found**:
  session "Optimize performance bottlenecks"
    context: performance
elif **style issues were found**:
  session "Clean up code style"
    context: style
else:
  session "All checks passed - ready for review"

# Parameterized Blocks Example
# Demonstrates reusable blocks with arguments for DRY workflows

# Simple parameterized block
block research(topic):
  session "Research {topic} thoroughly"
  session "Summarize key findings about {topic}"
  session "List open questions about {topic}"

# Invoke with different arguments
do research("quantum computing")
do research("machine learning")
do research("blockchain technology")

# Block with multiple parameters
block review_code(language, focus_area):
  session "Review the {language} code for {focus_area} issues"
  session "Suggest {focus_area} improvements for {language}"
  session "Provide {language} best practices for {focus_area}"

do review_code("Python", "performance")
do review_code("TypeScript", "type safety")
do review_code("Rust", "memory safety")

# Parameterized block for data processing
block process_dataset(source, format):
  session "Load data from {source}"
  session "Validate {format} structure"
  session "Transform to standard format"
  session "Generate quality report for {source} data"

do process_dataset("sales_db", "CSV")
do process_dataset("api_logs", "JSON")
do process_dataset("user_events", "Parquet")

# Blocks with parameters used in control flow
block test_feature(feature_name, test_level):
  session "Write {test_level} tests for {feature_name}"

  if **the tests reveal issues**:
    session "Fix issues in {feature_name}"
    session "Re-run {test_level} tests for {feature_name}"
  else:
    session "Mark {feature_name} {test_level} testing complete"

do test_feature("authentication", "unit")
do test_feature("payment processing", "integration")
do test_feature("user dashboard", "e2e")

# Parameterized blocks in parallel
block analyze_competitor(company):
  session "Research {company} products"
  session "Analyze {company} market position"
  session "Identify {company} strengths and weaknesses"

parallel:
  a = do analyze_competitor("Company A")
  b = do analyze_competitor("Company B")
  c = do analyze_competitor("Company C")

session "Create competitive analysis report"
  context: { a, b, c }

# Block with error handling
block safe_api_call(endpoint, method):
  try:
    session "Call {endpoint} with {method} request"
      retry: 3
      backoff: "exponential"
  catch as err:
    session "Log failed {method} call to {endpoint}"
      context: err
    session "Return fallback response for {endpoint}"

do safe_api_call("/users", "GET")
do safe_api_call("/orders", "POST")
do safe_api_call("/inventory", "PUT")

# Nested block invocations
block full_review(component):
  do review_code("TypeScript", "security")
  do test_feature(component, "unit")
  session "Generate documentation for {component}"

do full_review("UserService")
do full_review("PaymentGateway")

# Block with loop inside
block process_batch(batch_name, items):
  session "Start processing {batch_name}"
  for item in items:
    session "Process item from {batch_name}"
      context: item
  session "Complete {batch_name} processing"

let batch1 = ["a", "b", "c"]
let batch2 = ["x", "y", "z"]

do process_batch("alpha", batch1)
do process_batch("beta", batch2)

# String Interpolation Example
# Demonstrates dynamic prompt construction with {variable} syntax

# Basic interpolation
let user_name = session "Get the user's name"
let topic = session "Ask what topic they want to learn about"

session "Create a personalized greeting for {user_name} about {topic}"

# Multiple interpolations in one prompt
let company = session "Get the company name"
let industry = session "Identify the company's industry"
let size = session "Determine company size (startup/mid/enterprise)"

session "Write a customized proposal for {company}, a {size} company in {industry}"

# Interpolation with context
let research = session "Research the topic thoroughly"

session "Based on the research, explain {topic} to {user_name}"
  context: research

# Multi-line strings with interpolation
let project = session "Get the project name"
let deadline = session "Get the project deadline"
let team_size = session "Get the team size"

session """
Create a project plan for {project}.

Key constraints:
- Deadline: {deadline}
- Team size: {team_size}

Include milestones and resource allocation.
"""

# Interpolation in loops
let languages = ["Python", "JavaScript", "Go"]

for lang in languages:
  session "Write a hello world program in {lang}"
  session "Explain the syntax of {lang}"

# Interpolation in parallel blocks
let regions = ["North America", "Europe", "Asia Pacific"]

parallel for region in regions:
  session "Analyze market conditions in {region}"
  session "Identify top competitors in {region}"

# Interpolation with computed values
let base_topic = session "Get the main topic"
let analysis = session "Analyze {base_topic} from multiple angles"

let subtopics = ["history", "current state", "future trends"]
for subtopic in subtopics:
  session "Explore the {subtopic} of {base_topic}"
    context: analysis

# Building dynamic workflows
let workflow_type = session "What type of document should we create?"
let audience = session "Who is the target audience?"
let length = session "How long should the document be?"

session """
Create a {workflow_type} for {audience}.

Requirements:
- Length: approximately {length}
- Tone: appropriate for {audience}
- Focus: practical and actionable

Please structure with clear sections.
"""

# Interpolation in error messages
let operation = session "Get the operation name"
let target = session "Get the target resource"

try:
  session "Perform {operation} on {target}"
catch:
  session "Failed to {operation} on {target} - attempting recovery"
  throw "Operation {operation} failed for {target}"

# Combining interpolation with choice blocks
let task_type = session "Identify the type of task"
let priority = session "Determine task priority"

choice **the best approach for a {priority} priority {task_type}**:
  option "Immediate action":
    session "Execute {task_type} immediately with {priority} priority handling"
  option "Scheduled action":
    session "Schedule {task_type} based on {priority} priority queue"
  option "Delegate":
    session "Assign {task_type} to appropriate team member"

# Interpolation with agent definitions
agent custom_agent:
  model: sonnet
  prompt: "You specialize in helping with {topic}"

session: custom_agent
  prompt: "Provide expert guidance on {topic} for {user_name}"

# Automated PR Review Workflow
# This workflow performs a multi-dimensional review of a codebase changes.

agent reviewer:
  model: sonnet
  prompt: "You are an expert software engineer specializing in code reviews."

agent security_expert:
  model: opus
  prompt: "You are a security researcher specializing in finding vulnerabilities."

agent performance_expert:
  model: sonnet
  prompt: "You are a performance engineer specializing in optimization."

# 1. Initial overview
let overview = session: reviewer
  prompt: "Read the changes in the current directory and provide a high-level summary of the architectural impact."

# 2. Parallel deep-dive reviews
parallel:
  security = session: security_expert
    prompt: "Perform a deep security audit of the changes. Look for OWASP top 10 issues."
    context: overview

  perf = session: performance_expert
    prompt: "Analyze the performance implications. Identify potential bottlenecks or regressions."
    context: overview

  style = session: reviewer
    prompt: "Review for code style, maintainability, and adherence to best practices."
    context: overview

# 3. Synthesis and final recommendation
session: reviewer
  prompt: "Synthesize the security, performance, and style reviews into a final PR comment. Provide a clear 'Approve', 'Request Changes', or 'Comment' recommendation."
  context: { security, perf, style, overview }

# The Captain's Chair
#
# A project management orchestration pattern where a prime agent dispatches
# specialized subagents for all coding, validation, and task execution.
# The captain never writes code directly—only coordinates, validates, and
# maintains strategic oversight.
#
# Key principles:
# - Context isolation: Subagents receive targeted context, not everything
# - Parallel execution: Multiple subagents work concurrently where possible
# - Critic agents: Continuous review of plans and outputs
# - Checkpoint validation: User approval at key decision points

input task: "The feature or task to implement"
input codebase_context: "Brief description of the codebase and relevant files"

# ============================================================================
# Agent Definitions: The Crew
# ============================================================================

# The Captain: Orchestrates but never codes
agent captain:
  model: opus
  prompt: """You are a senior engineering manager. You NEVER write code directly.
Your job is to:
- Break down complex tasks into discrete work items
- Dispatch work to appropriate specialists
- Validate that outputs meet requirements
- Maintain strategic alignment with user intent
- Identify blockers and escalate decisions to the user

Always think about: What context does each subagent need? What can run in parallel?
What needs human validation before proceeding?"""

# Research agents - fast, focused information gathering
agent researcher:
  model: haiku
  prompt: """You are a research specialist. Find specific information quickly.
Provide concise, actionable findings. Cite file paths and line numbers."""

# Coding agents - implementation specialists
agent coder:
  model: sonnet
  prompt: """You are an expert software engineer. Write clean, idiomatic code.
Follow existing patterns in the codebase. No over-engineering."""

# Critic agents - continuous quality review
agent critic:
  model: sonnet
  prompt: """You are a senior code reviewer and architect. Your job is to find:
- Logic errors and edge cases
- Security vulnerabilities
- Performance issues
- Deviations from best practices
- Unnecessary complexity
Be constructive but thorough. Prioritize issues by severity."""

# Test agent - validation specialist
agent tester:
  model: sonnet
  prompt: """You are a QA engineer. Write comprehensive tests.
Focus on edge cases and failure modes. Ensure test isolation."""

# ============================================================================
# Block Definitions: Reusable Operations
# ============================================================================

# Parallel research sweep - gather all context simultaneously
block research-sweep(topic):
  parallel (on-fail: "continue"):
    docs = session: researcher
      prompt: "Find relevant documentation and README files for: {topic}"
    code = session: researcher
      prompt: "Find existing code patterns and implementations related to: {topic}"
    tests = session: researcher
      prompt: "Find existing tests that cover functionality similar to: {topic}"
    issues = session: researcher
      prompt: "Search for related issues, TODOs, or known limitations for: {topic}"

# Parallel code review - multiple perspectives simultaneously
block review-cycle(code_changes):
  parallel:
    security = session: critic
      prompt: "Review for security vulnerabilities and injection risks"
      context: code_changes
    correctness = session: critic
      prompt: "Review for logic errors, edge cases, and correctness"
      context: code_changes
    style = session: critic
      prompt: "Review for code style, readability, and maintainability"
      context: code_changes
    perf = session: critic
      prompt: "Review for performance issues and optimization opportunities"
      context: code_changes

# Implementation cycle with built-in critic
block implement-with-review(implementation_plan):
  let code = session: coder
    prompt: "Implement according to the plan"
    context: implementation_plan

  let review = do review-cycle(code)

  if **critical issues found in review**:
    let fixed = session: coder
      prompt: "Address the critical issues identified in the review"
      context: { code, review }
    output result = fixed
  else:
    output result = code

# ============================================================================
# Main Workflow: The Captain's Chair in Action
# ============================================================================

# Phase 1: Strategic Planning
# ---------------------------
# The captain breaks down the task and identifies what information is needed

let breakdown = session: captain
  prompt: """Analyze this task and create a strategic plan:

Task: {task}
Codebase: {codebase_context}

Output:
1. List of discrete work items (what code needs to be written/changed)
2. Dependencies between work items (what must complete before what)
3. What can be parallelized
4. Key questions that need user input before proceeding
5. Risks and potential blockers"""

# Phase 2: Parallel Research Sweep
# --------------------------------
# Dispatch researchers to gather all necessary context simultaneously

do research-sweep(task)

# Phase 3: Plan Synthesis and Critic Review
# -----------------------------------------
# Captain synthesizes research into implementation plan, critic reviews it

let implementation_plan = session: captain
  prompt: """Synthesize the research into a detailed implementation plan.

Research findings:
{docs}
{code}
{tests}
{issues}

For each work item, specify:
- Exact files to modify
- Code patterns to follow
- Tests to add or update
- Integration points"""
  context: { breakdown, docs, code, tests, issues }

# Critic reviews the plan BEFORE implementation begins
let plan_review = session: critic
  prompt: """Review this implementation plan for:
- Missing edge cases
- Architectural concerns
- Testability issues
- Scope creep
- Unclear requirements that need user clarification"""
  context: implementation_plan

# Checkpoint: User validates plan before execution
if **the plan review raised critical concerns**:
  let revised_plan = session: captain
    prompt: "Revise the plan based on critic feedback"
    context: { implementation_plan, plan_review }
  # Continue with revised plan
  let final_plan = revised_plan
else:
  let final_plan = implementation_plan

# Phase 4: Parallel Implementation
# --------------------------------
# Identify independent work items and execute in parallel where possible

let work_items = session: captain
  prompt: "Extract the independent work items that can be done in parallel from this plan"
  context: final_plan

# Execute independent items in parallel, each with its own review cycle
parallel (on-fail: "continue"):
  impl_a = do implement-with-review(work_items)
  impl_b = session: tester
    prompt: "Write tests for the planned functionality"
    context: { final_plan, code }

# Phase 5: Integration and Final Review
# -------------------------------------
# Captain validates all pieces fit together

let integration = session: captain
  prompt: """Review all implementation results and verify:
1. All work items completed successfully
2. Tests cover the new functionality
3. No merge conflicts or integration issues
4. Documentation updated if needed

Summarize what was done and any remaining items."""
  context: { impl_a, impl_b, final_plan }

# Final critic pass on complete implementation
let final_review = do review-cycle(integration)

if **final review passed**:
  output result = session: captain
    prompt: "Prepare final summary for user: what was implemented, tests added, and next steps"
    context: { integration, final_review }
else:
  output result = session: captain
    prompt: "Summarize what was completed and what issues remain for user attention"
    context: { integration, final_review }

# Simple Captain's Chair
#
# The minimal captain's chair pattern: a coordinating agent that dispatches
# subagents for all execution. The captain only plans and validates.

input task: "What to accomplish"

# The captain coordinates but never executes
agent captain:
  model: opus
  prompt: "You are a project coordinator. Never write code directly. Break down tasks, dispatch to specialists, validate results."

agent executor:
  model: opus
  prompt: "You are a skilled implementer. Execute the assigned task precisely."

agent critic:
  model: opus
  prompt: "You are a critic. Find issues, suggest improvements. Be thorough."

# Step 1: Captain creates the plan
let plan = session: captain
  prompt: "Break down this task into work items: {task}"

# Step 2: Dispatch parallel execution
parallel:
  work = session: executor
    prompt: "Execute the plan"
    context: plan
  review = session: critic
    prompt: "Identify potential issues with this approach"
    context: plan

# Step 3: Captain synthesizes and validates
if **critic found issues that affect the work**:
  output result = session: captain
    prompt: "Integrate the work while addressing critic's concerns"
    context: { work, review }
else:
  output result = session: captain
    prompt: "Validate and summarize the completed work"
    context: { work, review }

# Captain's Chair with Memory and Self-Improvement
#
# An advanced orchestration pattern that includes:
# - Retrospective analysis after task completion
# - Learning from mistakes to improve future runs
# - Continuous critic supervision during execution
#
# From the blog post: "Future agents will flip the plan:execute paradigm
# to 80:20 from today's 20:80"

input task: "The task to accomplish"
input past_learnings: "Previous session learnings (if any)"

# ============================================================================
# Agent Definitions
# ============================================================================

agent captain:
  model: opus
  prompt: """You are a senior engineering manager. You coordinate but never code directly.

Your responsibilities:
1. Strategic planning with 80% of effort on planning, 20% on execution oversight
2. Dispatch specialized subagents for all implementation
3. Validate outputs meet requirements
4. Learn from each session to improve future runs

Past learnings to incorporate:
{past_learnings}"""

agent planner:
  model: opus
  prompt: """You are a meticulous planner. Create implementation plans with:
- Exact files and line numbers to modify
- Code patterns to follow from existing codebase
- Edge cases to handle
- Tests to write"""

agent researcher:
  model: haiku
  prompt: "Find specific information quickly. Cite sources."

agent executor:
  model: sonnet
  prompt: "Implement precisely according to plan. Follow existing patterns."

agent critic:
  model: sonnet
  prompt: """You are a continuous critic. Your job is to watch execution and flag:
- Deviations from plan
- Emerging issues
- Opportunities for improvement
Be proactive - don't wait for completion to raise concerns."""

agent retrospective:
  model: opus
  prompt: """You analyze completed sessions to extract learnings:
- What went well?
- What could be improved?
- What should be remembered for next time?
Output actionable insights, not platitudes."""

# ============================================================================
# Phase 1: Deep Planning (80% of effort)
# ============================================================================

# Parallel research - gather everything needed upfront
parallel:
  codebase = session: researcher
    prompt: "Map the relevant parts of the codebase for: {task}"
  patterns = session: researcher
    prompt: "Find coding patterns and conventions used in this repo"
  docs = session: researcher
    prompt: "Find documentation and prior decisions related to: {task}"
  issues = session: researcher
    prompt: "Find known issues, TODOs, and edge cases for: {task}"

# Create detailed implementation plan
let detailed_plan = session: planner
  prompt: """Create a comprehensive implementation plan for: {task}

Use the research to specify:
1. Exact changes needed (file:line format)
2. Code patterns to follow
3. Edge cases from prior issues
4. Test coverage requirements"""
  context: { codebase, patterns, docs, issues }

# Critic reviews plan BEFORE execution
let plan_critique = session: critic
  prompt: "Review this plan for gaps, risks, and unclear requirements"
  context: detailed_plan

# Captain decides if plan needs revision
if **plan critique identified blocking issues**:
  let revised_plan = session: planner
    prompt: "Revise the plan to address critique"
    context: { detailed_plan, plan_critique }
else:
  let revised_plan = detailed_plan

# ============================================================================
# Phase 2: Supervised Execution (20% of effort)
# ============================================================================

# Execute with concurrent critic supervision
parallel:
  implementation = session: executor
    prompt: "Implement according to the plan"
    context: revised_plan
  live_critique = session: critic
    prompt: "Monitor implementation for deviations and emerging issues"
    context: revised_plan

# Captain validates and integrates
let validated = session: captain
  prompt: """Validate the implementation:
- Does it match the plan?
- Were critic's live concerns addressed?
- Is it ready for user review?"""
  context: { implementation, live_critique, revised_plan }

# ============================================================================
# Phase 3: Retrospective and Learning
# ============================================================================

# Extract learnings for future sessions
let session_learnings = session: retrospective
  prompt: """Analyze this completed session:

Plan: {revised_plan}
Implementation: {implementation}
Critique: {live_critique}
Validation: {validated}

Extract:
1. What patterns worked well?
2. What caused friction or rework?
3. What should the captain remember next time?
4. Any codebase insights to preserve?"""
  context: { revised_plan, implementation, live_critique, validated }

# Output both the result and the learnings
output result = validated
output learnings = session_learnings

# PR Review + Auto-Fix
#
# A self-healing code review pipeline. Reviews a PR from multiple angles,
# identifies issues, and automatically fixes them in a loop until the
# review passes. Satisfying to watch as issues get knocked down one by one.
#
# Usage: Run against any open PR in your repo.

agent reviewer:
  model: sonnet
  prompt: """
You are a senior code reviewer. You review code for:
- Correctness and logic errors
- Security vulnerabilities
- Performance issues
- Code style and readability

Be specific. Reference exact file paths and line numbers.
Return a structured list of issues or "APPROVED" if none found.
"""

agent security-reviewer:
  model: opus          # Security requires deep reasoning
  prompt: """
You are a security specialist. Focus exclusively on:
- Injection vulnerabilities (SQL, command, XSS)
- Authentication/authorization flaws
- Data exposure and privacy issues
- Cryptographic weaknesses

If you find issues, they are HIGH priority. Be thorough.
"""

agent fixer:
  model: opus          # Fixing requires understanding + execution
  prompt: """
You are a code fixer. Given an issue report:
1. Understand the root cause
2. Implement the minimal fix
3. Verify the fix addresses the issue
4. Create a clean commit

Do NOT over-engineer. Fix exactly what's reported, nothing more.
"""

agent captain:
  model: sonnet        # Orchestration role
  persist: true
  prompt: """
You coordinate the PR review process. You:
- Track which issues have been found and fixed
- Decide when the PR is ready to merge
- Escalate to human if something is unfixable
"""

# Get the PR diff
let pr_diff = session "Fetch the PR diff"
  prompt: """
Read the current PR:
1. Run: gh pr diff
2. Also get: gh pr view --json title,body,files
3. Return the complete diff and PR metadata
"""

# Phase 1: Parallel multi-perspective review
session: captain
  prompt: "Starting PR review. I'll coordinate multiple reviewers."

parallel:
  general_review = session: reviewer
    prompt: "Review this PR for correctness, logic, and style issues"
    context: pr_diff

  security_review = session: security-reviewer
    prompt: "Security audit this PR. Flag any vulnerabilities."
    context: pr_diff

  test_check = session "Check test coverage"
    prompt: """
Analyze the PR:
1. What code changed?
2. Are there tests for the changes?
3. Run existing tests: npm test / pytest / cargo test
Return: test status and coverage gaps
"""
    context: pr_diff

# Phase 2: Captain synthesizes and prioritizes
let issues = resume: captain
  prompt: """
Synthesize all review feedback into a prioritized issue list.
Format each issue as:
- ID: issue-N
- Severity: critical/high/medium/low
- File: path/to/file.ts
- Line: 42
- Issue: description
- Fix: suggested approach

If all reviews passed, return "ALL_CLEAR".
"""
  context: { general_review, security_review, test_check }

# Phase 3: Auto-fix loop
loop until **all issues are resolved or unfixable** (max: 10):

  if **there are no remaining issues**:
    resume: captain
      prompt: "All issues resolved! Summarize what was fixed."
  else:
    # Pick the highest priority unfixed issue
    let current_issue = resume: captain
      prompt: "Select the next highest priority issue to fix."
      context: issues

    # Attempt the fix
    try:
      session: fixer
        prompt: """
Fix this issue:
{current_issue}

Steps:
1. Read the file
2. Understand the context
3. Implement the fix
4. Run tests to verify
5. Commit with message: "fix: [issue description]"
"""
        context: current_issue
        retry: 2
        backoff: exponential

      # Mark as fixed
      resume: captain
        prompt: "Issue fixed. Update tracking and check remaining issues."
        context: current_issue

    catch as fix_error:
      # Escalate unfixable issues
      resume: captain
        prompt: """
Fix attempt failed. Determine if this is:
1. Retryable with different approach
2. Needs human intervention
3. A false positive (not actually an issue)

Update issue status accordingly.
"""
        context: { current_issue, fix_error }

# Phase 4: Final verification
let final_review = session: reviewer
  prompt: "Final review pass. Verify all fixes are correct and complete."

resume: captain
  prompt: """
PR Review Complete!

Generate final report:
- Issues found: N
- Issues fixed: N
- Issues requiring human review: N
- Recommendation: MERGE / NEEDS_ATTENTION / BLOCK

If ready, run: gh pr review --approve
"""
  context: final_review

# RLM: Self-Refinement
# Recursive improvement until quality threshold

input artifact: "The artifact to refine"
input criteria: "Quality criteria"

agent evaluator:
  model: sonnet
  prompt: "Score 0-100 against criteria. List specific issues."

agent refiner:
  model: opus
  prompt: "Make targeted improvements. Preserve what works."

block refine(content, depth):
  if depth <= 0:
    output content

  let eval = session: evaluator
    prompt: "Evaluate against: {criteria}"
    context: content

  if **score >= 85**:
    output content

  let improved = session: refiner
    prompt: "Fix the identified issues"
    context: { artifact: content, evaluation: eval }

  output do refine(improved, depth - 1)

output result = do refine(artifact, 5)

# Iterative Refinement Example
# Write draft, get feedback, refine until approved

agent writer:
  model: opus

agent reviewer:
  model: sonnet

let draft = session: writer
  prompt: "Write a first draft about AI safety"

loop until **approved**:
  let feedback = session: reviewer
    prompt: "Review this draft and provide feedback"
    context: draft

  draft = session: writer
    prompt: "Improve the draft based on feedback"
    context: { draft, feedback }