Workflow Orchestrator Skill

Execute declarative workflow files that orchestrate multiple PopeBot agent jobs. This skill brings OpenProse-style workflow orchestration to PopeBot's job-based architecture.

When to Activate

Activate this skill when the user:

• Wants to run multiple agent jobs in sequence or parallel

• Needs to coordinate tasks with dependencies

• Wants to create reusable automation pipelines

• Asks to run a .workflow file

• Mentions "workflow orchestration" or "multi-agent workflow"

Workflow File Format

Workflows use YAML-like syntax with clear structure:

Example: Code review workflow

name: "PR Review Pipeline" description: "Review PR, check for bugs, suggest improvements"

inputs:

• name: pr_number required: true description: "Pull request number to review"

agents: reviewer: personality: | You are a thorough code reviewer focused on security, best practices, and maintainability. tester: personality: | You are a QA engineer focused on edge cases and test coverage. documenter: personality: | You are a technical writer who creates clear documentation.

steps:

Sequential steps run one after another

• name: review_code agent: reviewer prompt: | Review pull request #{{pr_number}} for:
  • Security issues
  • Code quality
  • Best practices output: review_report

Parallel steps run concurrently

• name: parallel_tests parallel:

  • name: unit_tests agent: tester prompt: "Check test coverage for PR #{{pr_number}}" output: test_report

  • name: integration_tests agent: tester prompt: "Check integration tests for PR #{{pr_number}}" output: integration_report

Conditional execution

• name: write_summary agent: documenter prompt: | Write a PR summary based on:
  • Review: {{review_report}}
  • Tests: {{test_report}}
  • Integration: {{integration_report}} if: "all previous steps succeeded" output: final_summary

outputs:

• review_report
• test_report
• integration_report
• final_summary

Commands

Run a Workflow

Run a local workflow file

workflow run my-workflow.workflow

Run with inputs

workflow run my-workflow.workflow --input pr_number=123

Run a remote workflow

workflow run https://example.com/workflow.workflow

Compile/Validate

Validate workflow syntax without running

workflow compile my-workflow.workflow

List Available Workflows

Show workflows in current directory

workflow list

Execution Model

The workflow orchestrator:

• Parses the workflow file

• Validates syntax and required inputs

• Creates agent definitions with custom personalities

• Executes steps according to dependencies:

• Sequential steps wait for previous completion

• Parallel steps spawn multiple jobs concurrently

• Conditional steps evaluate AI-determined conditions

• Collects outputs from each step

• Reports final results

Job Management

Each workflow step creates a PopeBot job:

• Jobs are created in job/workflow-{workflow_id}-{step_name} branches

• Job results are stored in /job/tmp/workflows/{workflow_id}/{step_name}/

• Failed steps can be retried individually

• Workflows can be paused for approval gates

Approval Gates

Insert approval checkpoints in workflows:

steps:

• name: draft_email agent: assistant prompt: "Draft a response to the customer complaint" output: email_draft

• name: approval_gate type: approval prompt: "Send this email?" data: "{{email_draft}}" on_approve:

  • name: send_email agent: assistant prompt: "Send the approved email" on_reject:
  • name: revise_email agent: assistant prompt: "Revise the email based on feedback"

Error Handling

steps:

• name: risky_operation agent: assistant prompt: "Do something that might fail" retry: max_attempts: 3 backoff: exponential on_error:
  • name: handle_error agent: assistant prompt: "Handle this error: {{error_message}}"

Variable Substitution

Use {{variable_name}} to reference:

• Workflow inputs: {{pr_number}}

• Step outputs: {{review_report}}

• Previous step data in parallel blocks

Configuration

In config/WORKFLOWS.json (optional)

{ "default_timeout": 600, "max_parallel_jobs": 5, "workspace": "/job/tmp/workflows", "notification_channel": "telegram" }

Examples

Multi-Agent Research

name: "Research Deep Dive" inputs:

• name: topic required: true

steps:

• name: initial_research parallel:

  • agent: researcher prompt: "Research {{topic}} from technical perspective" output: tech_research
  • agent: researcher prompt: "Research {{topic}} market applications" output: market_research

• name: synthesize agent: analyst prompt: | Synthesize findings: Technical: {{tech_research}} Market: {{market_research}} output: final_report

CI/CD Pipeline

name: "Release Pipeline" inputs:

• name: version required: true

steps:

• name: build agent: builder prompt: "Build version {{version}} and run tests"

• name: security_scan agent: security prompt: "Scan {{version}} for vulnerabilities" parallel: true

• name: approval type: approval prompt: "Deploy version {{version}}?"

• name: deploy agent: deployer prompt: "Deploy {{version}} to production" if: "approval granted"

State Management

Workflow state persists in:

• /job/tmp/workflows/{workflow_id}/state.json

• Current execution state

• /job/tmp/workflows/{workflow_id}/steps/

• Individual step results

• /job/tmp/workflows/{workflow_id}/logs/

• Execution logs

API Integration

Workflows can be triggered via:

Via PopeBot chat

/workflow run my-workflow.workflow

Via API

curl -X POST /api/create-job
-H "x-api-key: YOUR_KEY"
-d '{"job": "workflow run my-workflow.workflow --input key=value"}'

When NOT to Use

• Single simple tasks (use direct agent jobs)

• Tasks requiring continuous human interaction

• Real-time data processing

• Tasks under 30 seconds (overhead not justified)

File Locations

File Location Purpose

Skill files Same dir as this SKILL.md Documentation and executor

User workflows Workspace *.workflow files User-created workflows

State /job/tmp/workflows/

Runtime state and results

Config config/WORKFLOWS.json (optional) Global settings