adb-workflow-orchestrator

---

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:

1. Create a new .toon file in the workflow/ directory
2. Define phases, steps, and parameters using TOON v4.0 syntax
3. Create corresponding .md file with comprehensive documentation
4. 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)