Skip to content

Workflows Execution

Jump to bottom
Mo Abualruz edited this page Dec 9, 2025 · 2 revisions

Workflows & Execution Guide

Define and execute complex multi-step automated processes with human oversight and risk assessment.

Status: ✅ Complete

Phase: Phase 2 - Alpha Enhanced Features (v0.1.2)

Last Updated: December 4, 2025

Overview

The RiceCoder Workflows module provides a declarative workflow definition language for orchestrating complex multi-step agentic operations. Workflows support conditional branching, error handling with automatic recovery, human approval gates, and risk-scored execution with safety constraints.

Key Concepts

  • Declarative workflows: Define workflows in YAML with clear step dependencies
  • State management: Persist workflow state across restarts; pause and resume execution
  • Error handling: Automatic retry, skip, fail, or rollback on step failures
  • Approval gates: Human approval checkpoints for critical operations
  • Risk scoring: Automatic risk assessment with approval requirements for high-risk steps
  • Progress tracking: Real-time status updates with estimated completion time
  • Activity logging: Complete audit trail of all workflow activities

Getting Started

Basic Workflow

Create a simple workflow in .ricecoder/workflows/example.yaml:

id: code-review-workflow
name: Code Review Workflow
description: Automated code review with human approval

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    config:
      scope: changed_files
      
  - id: review-approval
    name: Review Approval
    type: approval
    dependencies: [analyze]
    message: "Review findings and approve changes"
    timeout: 1h
    
  - id: apply-fixes
    name: Apply Fixes
    type: agent
    agent: refactor
    dependencies: [review-approval]
    approval_required: true
    on_error: rollback

Running a Workflow

Execute a workflow:

# Run workflow
rice workflow run code-review-workflow

# Run with parameters
rice workflow run code-review-workflow --param scope=src/

# Run in dry-run mode (preview only)
rice workflow run code-review-workflow --dry-run

# Run with specific approval timeout
rice workflow run code-review-workflow --approval-timeout 2h

Monitoring Workflow Execution

View workflow status:

# View current status
rice workflow status code-review-workflow

# View progress
rice workflow progress code-review-workflow

# View activity log
rice workflow logs code-review-workflow

# View risk assessment
rice workflow risk-report code-review-workflow

Pausing and Resuming

Pause and resume workflows:

# Pause workflow
rice workflow pause code-review-workflow

# Resume workflow
rice workflow resume code-review-workflow

# Cancel workflow
rice workflow cancel code-review-workflow

Workflow Definition

Step Types

Workflows support five step types:

Agent Steps

Execute an agent (code review, refactoring, etc.):

- id: analyze
  name: Analyze Code
  type: agent
  agent: code-review
  config:
    scope: changed_files
    checks: [naming, security, performance]
  timeout: 30s
  on_error: retry

Command Steps

Execute shell commands:

- id: build
  name: Build Project
  type: command
  command: cargo build --release
  args: []
  timeout: 5m
  on_error: fail

Condition Steps

Branch based on previous step results:

- id: check-quality
  name: Check Code Quality
  type: condition
  condition: "analyze.severity_score < 5"
  then_steps: [apply-fixes]
  else_steps: [notify-team]
  dependencies: [analyze]

Parallel Steps

Execute multiple steps concurrently:

- id: parallel-analysis
  name: Parallel Analysis
  type: parallel
  steps: [code-review, security-scan, performance-analysis]
  max_concurrency: 3
  dependencies: []

Approval Steps

Request human approval:

- id: review-approval
  name: Review Approval
  type: approval
  message: "Review findings and approve changes"
  timeout: 1h
  default: reject
  dependencies: [analyze]

Step Dependencies

Define execution order with dependencies:

steps:
  - id: step1
    name: First Step
    type: agent
    agent: code-review
    
  - id: step2
    name: Second Step
    type: agent
    agent: security-scan
    dependencies: [step1]  # Runs after step1 completes
    
  - id: step3
    name: Third Step
    type: agent
    agent: refactor
    dependencies: [step1, step2]  # Runs after both complete

Error Handling

Configure error handling for each step:

- id: risky-operation
  name: Risky Operation
  type: agent
  agent: refactor
  on_error: rollback  # Options: fail, retry, skip, rollback
  
  # Retry configuration
  retry:
    max_attempts: 3
    delay: 5s
    backoff: exponential  # linear, exponential, fixed
    
  # Rollback configuration
  rollback:
    steps: [undo-changes]  # Steps to execute on failure

Parameters

Define workflow parameters:

id: parameterized-workflow
name: Parameterized Workflow
description: Workflow with parameters

parameters:
  - name: scope
    type: string
    default: "src/"
    description: "Code scope to analyze"
    
  - name: severity_threshold
    type: string
    default: "warning"
    description: "Minimum severity level"
    enum: [critical, warning, info]

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    config:
      scope: ${scope}
      severity_threshold: ${severity_threshold}

Approval Gates

Configure approval requirements:

- id: approval
  name: Approval Gate
  type: approval
  message: "Please review and approve"
  timeout: 1h
  default: reject  # reject or approve
  
  # Approval requirements
  required_approvers: 2
  allowed_roles: [admin, lead]

Configuration

Workflow Configuration

Configure workflows in .ricecoder/config.yaml:

workflows:
  # Default timeout for all steps
  default-timeout: 30m
  
  # Default approval timeout
  approval-timeout: 1h
  
  # Retry configuration
  retry:
    enabled: true
    max-attempts: 3
    backoff: exponential
    
  # State persistence
  state:
    enabled: true
    location: ~/.ricecoder/workflows/state/
    
  # Risk scoring
  risk-scoring:
    enabled: true
    threshold: 50  # Require approval for scores > 50
    
  # Logging
  logging:
    enabled: true
    level: info
    location: ~/.ricecoder/workflows/logs/

Risk Scoring Configuration

Configure risk assessment:

risk-scoring:
  enabled: true
  threshold: 50  # Require approval for scores > 50
  
  # Risk factors
  factors:
    impact: 0.4      # Data loss potential (0-1)
    reversibility: 0.3  # Ability to undo (0-1)
    complexity: 0.3  # Number of dependencies (0-1)
  
  # Safety constraints for high-risk operations
  safety-constraints:
    timeout: 5m
    memory-limit: 1GB
    cpu-limit: 50%
    file-handles-limit: 100

Approval Configuration

Configure approval requirements:

approval:
  # Approval timeout
  timeout: 1h
  
  # Default action on timeout
  default-on-timeout: reject
  
  # Required approvers
  required-approvers: 1
  
  # Allowed roles
  allowed-roles:
    - admin
    - lead
    - reviewer

Usage Examples

Example 1: Simple Sequential Workflow

Execute steps in sequence:

id: simple-workflow
name: Simple Workflow
description: Execute steps sequentially

steps:
  - id: step1
    name: First Step
    type: agent
    agent: code-review
    
  - id: step2
    name: Second Step
    type: agent
    agent: refactor
    dependencies: [step1]
    
  - id: step3
    name: Third Step
    type: agent
    agent: test-generator
    dependencies: [step2]

Run it:

rice workflow run simple-workflow

Example 2: Conditional Workflow

Branch based on conditions:

id: conditional-workflow
name: Conditional Workflow
description: Branch based on code quality

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    
  - id: check-quality
    name: Check Quality
    type: condition
    condition: "analyze.severity_score < 5"
    then_steps: [apply-fixes]
    else_steps: [notify-team]
    dependencies: [analyze]
    
  - id: apply-fixes
    name: Apply Fixes
    type: agent
    agent: refactor
    
  - id: notify-team
    name: Notify Team
    type: command
    command: echo "Code quality issues found"

Run it:

rice workflow run conditional-workflow

Example 3: Parallel Workflow

Execute steps in parallel:

id: parallel-workflow
name: Parallel Workflow
description: Run multiple agents in parallel

steps:
  - id: parallel-analysis
    name: Parallel Analysis
    type: parallel
    steps: [code-review, security-scan, performance-analysis]
    max_concurrency: 3
    
  - id: aggregate
    name: Aggregate Results
    type: agent
    agent: result-aggregator
    dependencies: [parallel-analysis]

Run it:

rice workflow run parallel-workflow

Example 4: Workflow with Approval

Include approval gates:

id: approval-workflow
name: Approval Workflow
description: Workflow with approval gates

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    
  - id: approval
    name: Approval Gate
    type: approval
    message: "Review findings and approve changes"
    timeout: 1h
    dependencies: [analyze]
    
  - id: apply
    name: Apply Changes
    type: agent
    agent: refactor
    dependencies: [approval]
    approval_required: true
    on_error: rollback

Run it:

rice workflow run approval-workflow

Example 5: Parameterized Workflow

Use parameters:

id: parameterized-workflow
name: Parameterized Workflow
description: Workflow with parameters

parameters:
  - name: scope
    type: string
    default: "src/"
    
  - name: checks
    type: string
    default: "naming,security"

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    config:
      scope: ${scope}
      checks: ${checks}

Run it:

rice workflow run parameterized-workflow --param scope=src/main.rs --param checks=security

Example 6: Error Handling Workflow

Configure error handling:

id: error-handling-workflow
name: Error Handling Workflow
description: Workflow with error handling

steps:
  - id: risky-operation
    name: Risky Operation
    type: agent
    agent: refactor
    on_error: retry
    retry:
      max_attempts: 3
      delay: 5s
      backoff: exponential
      
  - id: fallback
    name: Fallback Operation
    type: agent
    agent: code-review
    dependencies: [risky-operation]
    on_error: skip

Run it:

rice workflow run error-handling-workflow

Example 7: Risk-Scored Workflow

Automatic risk assessment:

id: risk-scored-workflow
name: Risk-Scored Workflow
description: Workflow with risk assessment

steps:
  - id: analyze
    name: Analyze Code
    type: agent
    agent: code-review
    
  - id: high-risk-refactor
    name: High-Risk Refactor
    type: agent
    agent: refactor
    dependencies: [analyze]
    approval_required: true  # Requires approval due to risk
    on_error: rollback

Run it:

rice workflow run risk-scored-workflow

State Management

Workflow State

Workflows persist state automatically:

# View workflow state
rice workflow state code-review-workflow

# Output:
# Workflow: code-review-workflow
# Status: Running
# Current Step: analyze
# Progress: 33%
# Completed Steps: [step1]
# Started: 2025-12-04 10:30:00
# Updated: 2025-12-04 10:35:00

Pause and Resume

Pause workflows and resume later:

# Pause workflow
rice workflow pause code-review-workflow

# Resume workflow
rice workflow resume code-review-workflow

# Workflow resumes from paused step without re-executing completed steps

State Persistence

State is persisted to disk:

# View state file
cat ~/.ricecoder/workflows/state/code-review-workflow.json

# Output:
# {
#   "workflow_id": "code-review-workflow",
#   "status": "paused",
#   "current_step": "analyze",
#   "completed_steps": ["step1"],
#   "step_results": {...},
#   "started_at": "2025-12-04T10:30:00Z",
#   "updated_at": "2025-12-04T10:35:00Z"
# }

Progress Tracking

Real-Time Status

View workflow progress:

# View progress
rice workflow progress code-review-workflow

# Output:
# Workflow: code-review-workflow
# Status: Running
# Progress: 66% (2/3 steps completed)
# Current Step: review-approval
# Estimated Completion: 2025-12-04 10:45:00 (10 minutes remaining)

Activity Log

View all workflow activities:

# View activity log
rice workflow logs code-review-workflow

# Output:
# 2025-12-04 10:30:00 [INFO] Workflow started
# 2025-12-04 10:30:05 [INFO] Step 'analyze' started
# 2025-12-04 10:35:00 [INFO] Step 'analyze' completed (5 minutes)
# 2025-12-04 10:35:01 [INFO] Step 'review-approval' started
# 2025-12-04 10:35:02 [INFO] Waiting for approval

Metrics

View workflow metrics:

# View metrics
rice workflow metrics code-review-workflow

# Output:
# Total Duration: 15 minutes
# Step Durations:
#   - analyze: 5 minutes
#   - review-approval: 8 minutes (waiting for approval)
#   - apply-fixes: 2 minutes
# Success Rate: 100%
# Retry Count: 0

Risk Assessment

Risk Scoring

Workflows automatically calculate risk scores:

# View risk assessment
rice workflow risk-report code-review-workflow

# Output:
# Risk Assessment Report
# ====================
# 
# Overall Risk Score: 45/100 (Medium)
# 
# Step Risk Scores:
#   - analyze: 10/100 (Low)
#   - review-approval: 20/100 (Low)
#   - apply-fixes: 75/100 (High)
# 
# Risk Factors:
#   - Impact (data loss potential): 0.8
#   - Reversibility (ability to undo): 0.6
#   - Complexity (dependencies): 0.5
# 
# Approval Decisions:
#   - apply-fixes: Approved by admin at 2025-12-04 10:35:00
# 
# Safety Constraints Applied:
#   - Timeout: 5 minutes
#   - Memory Limit: 1GB
#   - CPU Limit: 50%

High-Risk Operations

High-risk steps require approval:

- id: high-risk-operation
  name: High-Risk Operation
  type: agent
  agent: refactor
  approval_required: true  # Requires approval
  on_error: rollback       # Rollback on failure

Safety Constraints

Safety constraints are applied to high-risk operations:

risk-scoring:
  safety-constraints:
    timeout: 5m
    memory-limit: 1GB
    cpu-limit: 50%
    file-handles-limit: 100

Error Handling

Retry Logic

Automatically retry failed steps:

- id: step
  name: Step
  type: agent
  agent: code-review
  on_error: retry
  retry:
    max_attempts: 3
    delay: 5s
    backoff: exponential

Skip on Error

Skip failed steps and continue:

- id: step
  name: Step
  type: agent
  agent: code-review
  on_error: skip

Rollback on Error

Rollback changes on failure:

- id: step
  name: Step
  type: agent
  agent: refactor
  on_error: rollback
  rollback:
    steps: [undo-changes]

Error Recovery

Resume from last completed step:

# Workflow fails at step 3
rice workflow run workflow-name

# Fix the issue
# Resume workflow
rice workflow resume workflow-name

# Workflow resumes from step 3 without re-executing steps 1-2

Troubleshooting

Issue: Workflow is stuck waiting for approval

Solution: Check approval status and approve or reject:

# View approval status
rice workflow status workflow-name

# Approve workflow
rice workflow approve workflow-name

# Or reject
rice workflow reject workflow-name

Issue: Workflow step times out

Solution: Increase timeout or reduce scope:

# Increase timeout
rice workflow run workflow-name --timeout 10m

# Or edit workflow to increase step timeout
# - id: step
#   timeout: 10m

Issue: Workflow fails with error

Solution: Check error details and retry:

# View error details
rice workflow logs workflow-name

# Retry workflow
rice workflow resume workflow-name

Issue: Workflow state is corrupted

Solution: Reset state and restart:

# Reset state
rice workflow reset workflow-name

# Restart workflow
rice workflow run workflow-name

Issue: Approval timeout expired

Solution: Restart workflow with longer timeout:

# Restart workflow with longer approval timeout
rice workflow run workflow-name --approval-timeout 2h

Issue: High-risk operation blocked

Solution: Approve high-risk operation:

# View risk assessment
rice workflow risk-report workflow-name

# Approve operation
rice workflow approve workflow-name

Issue: Workflow parameters not substituted

Solution: Check parameter syntax and values:

# View workflow definition
cat .ricecoder/workflows/workflow-name.yaml

# Check parameter syntax: ${param_name}
# Run with parameters
rice workflow run workflow-name --param param_name=value

Issue: Rollback failed

Solution: Check rollback steps and fix:

# View rollback steps
cat .ricecoder/workflows/workflow-name.yaml

# Check rollback step configuration
# Ensure rollback steps are valid
# Retry workflow
rice workflow resume workflow-name

Advanced Usage

Custom Workflows

Create custom workflows for your project:

# Create workflow
rice workflow create my-workflow

# Edit workflow
vim .ricecoder/workflows/my-workflow.yaml

# Run workflow
rice workflow run my-workflow

Workflow Composition

Compose workflows into larger workflows:

id: master-workflow
name: Master Workflow
description: Composed of multiple workflows

steps:
  - id: workflow1
    name: First Workflow
    type: workflow
    workflow: workflow-1
    
  - id: workflow2
    name: Second Workflow
    type: workflow
    workflow: workflow-2
    dependencies: [workflow1]

Integration with CI/CD

Run workflows in CI/CD pipeline:

# .github/workflows/workflow.yml
- name: Run workflow
  run: rice workflow run code-review-workflow

- name: Check workflow status
  run: |
    status=$(rice workflow status code-review-workflow | grep Status)
    if [[ $status == *"Failed"* ]]; then
      exit 1
    fi

Programmatic Usage

Use workflows programmatically:

use ricecoder_workflows::{WorkflowEngine, Workflow};

let engine = WorkflowEngine::new();
let workflow = Workflow::from_file("workflows/example.yaml")?;

let state = engine.execute(&workflow).await?;
println!("Status: {:?}", state.status);

Best Practices

1. Start Simple

Begin with simple sequential workflows:

steps:
  - id: step1
    type: agent
    agent: code-review
    
  - id: step2
    type: agent
    agent: refactor
    dependencies: [step1]

2. Use Meaningful Names

Use clear, descriptive names:

- id: analyze-code-quality
  name: Analyze Code Quality
  type: agent
  agent: code-review

3. Add Error Handling

Always configure error handling:

- id: step
  type: agent
  agent: refactor
  on_error: retry
  retry:
    max_attempts: 3
    delay: 5s

4. Use Approval Gates

Add approval gates for critical operations:

- id: approval
  type: approval
  message: "Review and approve changes"
  timeout: 1h

5. Monitor Progress

Check workflow progress regularly:

rice workflow progress workflow-name

6. Review Logs

Review activity logs for issues:

rice workflow logs workflow-name

7. Test Workflows

Test workflows in dry-run mode:

rice workflow run workflow-name --dry-run

8. Document Workflows

Document workflow purpose and steps:

id: my-workflow
name: My Workflow
description: |
  This workflow performs code review and applies fixes.
  It requires approval before applying changes.

See Also

Last updated: December 4, 2025

Clone this wiki locally