Workflow YAML Specification

Workflows are defined in YAML files placed in ~/.pilot/workflows/ (Global) or .pilot/workflows/ (Project).

Schema

workflow:
  id: string
  name: string
  
inputs:               # Define required inputs
  - name: string
    type: string
    required: boolean

steps:
  - id: string        # Step identifier
    type: string      # agent | script | mcp | human | api
    
    # Type-specific config
    agent: string     # Agent ID (for type: agent)
    command: string   # Shell command (for type: script)
    action: string    # Tool name (for type: mcp)
    message: string   # Prompt (for type: human)

transitions:
  - from: string      # Step ID
    to: string        # Next Step ID
    when: expression  # Condition (e.g., step.success == true)

Example: Add API Endpoint

From samples/express-blog/.pilot/workflows/add-endpoint.yaml:

id: add-endpoint
name: Add API Endpoint
description: Add a new REST endpoint
version: "1.0"

steps:
  - id: analyze
    name: Analyze Requirements
    type: agent
    config:
      agent: node-coder
      model: reasoning
      prompt: |
        Analyze the endpoint requirements.
        Determine route, method, request/response format.
        Check existing patterns for consistency.

  - id: implement
    name: Implement Endpoint
    type: agent
    config:
      agent: node-coder
      model: default
      prompt: |
        Implement the Express route.
        Add validation and error handling.
        Follow RESTful conventions.

  - id: security-check
    name: Security Review
    type: agent
    config:
      agent: security-reviewer
      model: reasoning
      prompt: |
        Review for security issues:
        - Input validation
        - SQL injection
        - XSS vulnerabilities

  - id: test
    name: Write Tests
    type: agent
    config:
      agent: api-tester
      model: fast
      prompt: |
        Write Jest tests for the endpoint.
        Test success and error cases.

on_failure: pause