adb-navigation-base

---

Quick Reference (30 seconds)

Base Navigation Patterns for Android Automation

What It Does: Provides fundamental gesture and wait-for patterns used in all UI automation. Smart retry logic, verification, and timeout handling.

Core Capabilities:

• 👆 Smart Tap: Retry-enabled tapping with verification
• 👉 Swipe Gesture: Directional swiping for scrolling
• ⏱️ Wait For: Element/text waiting with polling

When to Use:

• Building reliable automation workflows
• Handling timing-sensitive UI transitions
• Creating reusable navigation patterns
• Combining with adb-screen-detection for full automation

---

Scripts

1. adb-tap.py

Smart tap action with automatic retry logic.

# Basic tap
uv run .claude/skills/adb-navigation-base/scripts/adb-tap.py --x 100 --y 200

# Tap with retry (auto-retry on failure)
uv run .claude/skills/adb-navigation-base/scripts/adb-tap.py --x 100 --y 200 --retry 3

# Tap with verification
uv run .claude/skills/adb-navigation-base/scripts/adb-tap.py --x 100 --y 200 --verify-text "Next"

# Tap with both
uv run .claude/skills/adb-navigation-base/scripts/adb-tap.py \
    --x 100 --y 200 --retry 3 --verify-text "Loaded" --timeout 5

Features:

• Automatic retry on failure (configurable attempts)
• Post-tap screen verification
• Timeout protection
• Detailed logging

---

2. adb-swipe.py

Perform directional swipe gesture.

# Swipe up (scroll down content)
uv run .claude/skills/adb-navigation-base/scripts/adb-swipe.py --direction up --distance 300

# Swipe left (next page)
uv run .claude/skills/adb-navigation-base/scripts/adb-swipe.py --direction left --distance 500

# Swipe with verification
uv run .claude/skills/adb-navigation-base/scripts/adb-swipe.py \
    --direction down --distance 400 --verify-text "End of List"

# Custom start position
uv run .claude/skills/adb-navigation-base/scripts/adb-swipe.py \
    --direction up --distance 300 --start-x 500 --start-y 1000

Directions: up, down, left, right Features:

• 4-direction swiping
• Configurable distance (pixels)
• Custom start position
• Post-swipe verification
• Momentum-aware (handles scroll inertia)

---

3. adb-wait-for.py

Wait for UI element or text to appear.

# Wait for text (default 10s timeout)
uv run .claude/skills/adb-navigation-base/scripts/adb-wait-for.py \
    --method text --target "Loaded"

# Wait for element by text with timeout
uv run .claude/skills/adb-navigation-base/scripts/adb-wait-for.py \
    --method text --target "Login" --timeout 5

# Wait with polling interval
uv run .claude/skills/adb-navigation-base/scripts/adb-wait-for.py \
    --method text --target "Results" --interval 0.5

# JSON output for scripting
uv run .claude/skills/adb-navigation-base/scripts/adb-wait-for.py \
    --method text --target "Ready" --json

Detection Methods: text (OCR-based) Features:

• Configurable timeout (1-60s)
• Polling interval configuration
• Timeout exception handling
• Success/failure reporting
• Return element coordinates when found

---

Usage Patterns

Pattern 1: Basic Navigation Sequence

# 1. Tap login button
adb-tap.py --x 100 --y 200

# 2. Wait for login form
adb-wait-for.py --method text --target "Username" --timeout 5

# 3. Swipe down to see password field
adb-swipe.py --direction down --distance 200

# 4. Tap password field
adb-tap.py --x 100 --y 300

Pattern 2: Reliable Action with Retry

# Tap with automatic retry (up to 3 times)
adb-tap.py --x 100 --y 200 --retry 3 --verify-text "Next Screen"

Pattern 3: Scroll and Find

# 1. Start at top
# 2. Swipe up (scroll down) multiple times looking for element
for i in {1..5}; do
  adb-swipe.py --direction up --distance 300
  # Check if element appears
  if adb-wait-for.py --method text --target "Find Me" --timeout 1; then
    # Found! Tap it
    adb-tap.py --x 150 --y 400
    break
  fi
done

---

Architecture

Design Principles:

• Composable: Chain together for complex workflows
• Fault-Tolerant: Automatic retry and timeout protection
• Verifiable: All actions can have post-action verification
• Observable: Detailed logging of all operations
• Stateless: No dependency on previous state

Dependency Relationship:

adb-screen-detection/ (provides capture, OCR, find-element)
         ↓
adb-navigation-base/ (uses for wait-for and verification)
         ↓
adb-workflow-orchestrator/ (coordinates these patterns)

---

Integration Points

Used By:

• adb-workflow-orchestrator - Workflow step execution
• adb-magisk - Magisk Manager navigation
• adb-karrot - Karrot app automation

Dependency On:

• adb-screen-detection - Screen capture and OCR
• System: adb command-line tool

---

Error Handling

Retry Logic

Attempt 1: Try action
  ├─ Success → Return
  └─ Failure → Wait, Try again

Attempt 2: Try action
  ├─ Success → Return
  └─ Failure → Wait, Try again

Attempt 3: Try action
  ├─ Success → Return
  └─ Failure → Return error

Timeout Handling

• Polls every N seconds (configurable)
• Returns TIMEOUT error if deadline exceeded
• Allows caller to handle timeout gracefully

---

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-navigation-base):

• workflow/tap-and-wait.toon - Tap element and wait for result
• workflow/scroll-and-find.toon - Scroll to find element
• workflow/gesture-sequence.toon - Complex gesture combinations

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-navigation-base/workflow/tap-and-wait.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: ✅ Foundation Tier Scripts: 3 Last Updated: 2025-12-01 Tier: 2 (Foundation)