Basic execution

adb-workflow-orchestrator

TOON workflow orchestration engine for coordinating ADB automation scripts across phases with error recovery

diegosouzapw/awesome-omni-skill·0installs62starsProductivity & Planning

SKILL.md

Full skill instructions

Quick Reference (30 seconds)

Workflow Orchestration for ADB Automation

What It Does: Parses and executes TOON YAML workflow files that coordinate multiple ADB scripts across phases with error recovery, verification, and state management.

Core Capabilities:

🔄 Phase-Based Execution: Multi-stage workflows
🔀 Parameter Templating: {{ variable }} substitution
✅ Verification Steps: Validate state after each action
🔁 Error Recovery: Retry with fallback logic
📊 State Tracking: Progress through phases
⏱️ Timeout Management: Per-action timeout control

When to Use:

Running complex multi-step automation sequences
Coordinating multiple scripts with dependencies
Need error recovery and retry logic
Building reusable workflow definitions

TOON Workflow Format

Basic Structure

name: Workflow Name
description: What this workflow does
version: 1.0.0

parameters:
  device_id: "127.0.0.1:5555"
  timeout: 10

phases:
  - id: phase1_setup
    name: "Setup Phase"
    steps:
      - id: step1
        action: adb-tap
        params:
          x: 100
          y: 200
          device: "{{ device_id }}"
      - id: step2
        action: adb-wait-for
        params:
          method: text
          target: "Loaded"
          timeout: "{{ timeout }}"

recovery:
  - on_error: phase1_setup
    action: retry
    max_attempts: 3
  - on_error: step1
    action: adb-screen-capture
    then: continue

Parameter Templating

parameters:
  device: "127.0.0.1:5555"
  search_text: "Login"
  timeout: 10

steps:
  - action: adb-find-element
    params:
      method: ocr
      target: "{{ search_text }}"
      device: "{{ device }}"
      timeout: "{{ timeout }}"

Phase-Based Organization

phases:
  - id: phase1_init
    name: "Initialization"
    steps:
      # Steps execute sequentially
      - id: capture
        action: adb-screen-capture

  - id: phase2_interact
    name: "User Interaction"
    steps:
      # Each phase waits for previous to complete
      - id: tap_button
        action: adb-tap
        params:
          x: 100
          y: 200

  - id: phase3_verify
    name: "Verification"
    steps:
      - id: check_result
        action: adb-wait-for
        params:
          method: text
          target: "Success"

Error Recovery

recovery:
  # Retry on phase error
  - on_error: phase2_interact
    action: retry
    max_attempts: 3
    delay: 1

  # Fallback action
  - on_error: step_tap
    action: adb-swipe
    params:
      direction: up
      distance: 300
    then: retry

  # Custom recovery script
  - on_error: phase3_verify
    action: adb-screenshot-capture  # Run script
    then: continue

Scripts

adb-run-workflow.py

Execute TOON YAML workflow file.

# Basic execution
uv run adb-run-workflow.py --workflow magisk-setup.toon

# With parameters override
uv run adb-run-workflow.py --workflow magisk-setup.toon \
    --param device_id=192.168.1.100:5555 \
    --param timeout=15

# Dry run (show what would execute)
uv run adb-run-workflow.py --workflow magisk-setup.toon --dry-run

# With detailed logging
uv run adb-run-workflow.py --workflow magisk-setup.toon --verbose

# JSON output for integration
uv run adb-run-workflow.py --workflow magisk-setup.toon --json

Output:

✅ Workflow: Magisk Setup
   Phase 1: Initialization
     ├─ Step 1: capture       [✅ Success]
     ├─ Step 2: verify       [✅ Success]

   Phase 2: User Interaction
     ├─ Step 1: tap_button   [✅ Success - attempt 1/3]
     ├─ Step 2: wait_load    [✅ Success]

   Phase 3: Verification
     ├─ Step 1: check_result [✅ Success]

✅ Workflow completed successfully in 23.5s

Usage Patterns

Pattern 1: Simple Sequential Workflow

name: Simple Login
phases:
  - id: login
    steps:
      - id: tap_username
        action: adb-tap
        params: {x: 100, y: 200}

      - id: wait_password_field
        action: adb-wait-for
        params: {method: text, target: "Password"}

      - id: tap_password
        action: adb-tap
        params: {x: 100, y: 300}

Pattern 2: Error Recovery with Retry

name: Resilient Login
parameters:
  max_attempts: 3

phases:
  - id: attempt_login
    steps:
      - id: tap_login
        action: adb-tap
        params: {x: 100, y: 200}

recovery:
  - on_error: attempt_login
    action: retry
    max_attempts: "{{ max_attempts }}"
    delay: 2

Pattern 3: Fallback Action

name: Scroll and Find
phases:
  - id: find_element
    steps:
      - id: wait_element
        action: adb-wait-for
        params: {method: text, target: "Target", timeout: 3}

recovery:
  - on_error: wait_element
    action: adb-swipe
    params: {direction: up, distance: 300}
    then: retry

Pattern 4: Multi-Phase Coordination

name: Complex Workflow
phases:
  - id: phase1_setup
    name: "Setup"
    steps:
      - id: init
        action: adb-screenshot-capture

  - id: phase2_interact
    name: "Interaction"
    steps:
      - id: tap
        action: adb-tap
        params: {x: 100, y: 200}

  - id: phase3_verify
    name: "Verification"
    steps:
      - id: verify
        action: adb-wait-for
        params: {method: text, target: "Done"}

Architecture

Design Principles:

Declarative: Workflows defined as YAML, not code
Composable: Reuse workflows via parameters
Resilient: Built-in error recovery and retry
Observable: Detailed logging and state tracking
Extensible: Easy to add new action types

Execution Flow:

Load YAML → Validate → Parse Parameters → Execute Phases
                                              ↓
                                        Execute Steps
                                              ↓
                                        Verify Results
                                              ↓
                                        Handle Errors
                                              ↓
                                        Report Status

State Machine:

IDLE → VALIDATING → EXECUTING → VERIFYING → COMPLETE
  ↑                      ↓
  └──────← ERROR RECOVERY ←──────┘

Integration Points

Calls:

adb-screen-detection (capture, find-element)
adb-navigation-base (tap, swipe, wait-for)
Any adb-* script via command name

Used By:

adb-magisk (magisk-setup.toon, install-module.toon)
adb-karrot (karrot-bypass-playintegrity.toon)
Custom workflows

Example Workflows

Magisk Module Installation Workflow

name: Install Magisk Module
version: 1.0.0

parameters:
  device: "127.0.0.1:5555"
  module_path: "/sdcard/PlayIntegrityFork.zip"

phases:
  - id: phase1_launch
    name: "Launch Magisk Manager"
    steps:
      - id: launch
        action: adb-magisk-launch
        params: {device: "{{ device }}"}

  - id: phase2_navigate
    name: "Navigate to Modules"
    steps:
      - id: wait_home
        action: adb-wait-for
        params: {method: text, target: "Modules", timeout: 5}
      - id: tap_modules
        action: adb-tap
        params: {x: 100, y: 200, device: "{{ device }}"}

  - id: phase3_install
    name: "Install Module"
    steps:
      - id: tap_fab
        action: adb-tap
        params: {x: 400, y: 800, device: "{{ device }}"}
      - id: select_file
        action: adb-file-select
        params: {path: "{{ module_path }}"}
      - id: wait_complete
        action: adb-wait-for
        params: {method: text, target: "Installation complete", timeout: 10}

recovery:
  - on_error: phase2_navigate
    action: retry
    max_attempts: 2
  - on_error: phase3_install
    action: adb-screenshot-capture
    then: continue

Workflows

This skill includes TOON-based workflow definitions for automation.

What is TOON?

TOON (Task-Oriented Orchestration Notation) is a structured workflow definition language that pairs with Markdown documentation. Each workflow consists of:

[name].toon - Orchestration logic and execution steps
[name].md - Complete documentation and usage guide

This TOON+MD pairing approach is inspired by the BMAD METHOD pattern, adapted to use TOON instead of YAML for better orchestration support.

Available Workflows

Workflow files are located in workflow/ directory:

Example Workflows (adb-workflow-orchestrator):

workflow/phase-execution.toon - Multi-phase workflow coordination
workflow/error-recovery.toon - Error handling and recovery patterns
workflow/parameter-templating.toon - Parameter substitution examples

Running a Workflow

Execute any workflow using the ADB workflow orchestrator:

uv run .claude/skills/adb-workflow-orchestrator/scripts/adb-run-workflow.py \
  --workflow .claude/skills/adb-workflow-orchestrator/workflow/phase-execution.toon \
  --param device="127.0.0.1:5555"

Workflow Documentation

Each workflow includes comprehensive documentation in the corresponding .md file:

Purpose and use case
Prerequisites and requirements
Available parameters
Execution phases and steps
Success criteria
Error handling and recovery
Example commands

See the workflow/ directory for complete TOON file definitions and documentation.

Creating New Workflows

To create custom workflows for this skill:

Create a new .toon file in the workflow/ directory
Define phases, steps, and parameters using TOON v4.0 syntax
Create corresponding .md file with comprehensive documentation
Test with the workflow orchestrator

For more information, refer to the TOON specification and the workflow orchestrator documentation.

Version: 1.0.0 Status: ✅ Orchestration Layer Scripts: 1 main + 2 lib modules Last Updated: 2025-12-01 Tier: 2 (Foundation)

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/diegosouzapw/awesome-omni-skill --skill adb-workflow-orchestrator

View on GitHub

skills/data-ai/adb-workflow-orchestrator/SKILL.md