Table of Contents

• Overview
• The Problem We Solve
• Quickstart in 2 Minutes
• Architecture Workflow
• Shift-Left Proactive Quality Invariants
• The Five-Leaf Review Gate
  • 1. Bug & Network Resiliency Reviewer
  • 2. Convention, Accessibility & KMP Reviewer
  • 3. Security & Privacy Reviewer
  • 4. Performance, Battery & ANR Guardian
  • 5. Regression Blast Radius Reviewer
• Dedicated On-Demand Specialists
• Safety Hooks & Execution Governance
  • Strict Git Mutation Protection
  • Anti-Polling Guardrails
  • Ephemeral State Machine
• Preflight Verification Pipeline
  • Fast Kotlin Lint
  • Room Database Migration Guard
  • Bilingual String Parity Check
• Live Gradle Streaming Runner
• Physical Device Runner & Logcat Doctor
• Zoho Sprints MCP Integration
• Supported AI Tools & Adapters Matrix
• Installation & Setup Modes
  • Mode A: Existing Android / KMP App
  • Mode B: Greenfield / Blank Project
  • Upgrades & Rollbacks
• Setup Wizard & Configuration Reference
• Self-Tests & CI/CD Pipeline
• Contributing & Community
• License

Overview

Android Agent Harness is an enterprise-grade delivery gate, safety framework, and architecture governance engine for Android and Kotlin Multiplatform (KMP) development.

When AI coding assistants like Cursor, Google Antigravity, Claude Code, or GitHub Copilot work on production Android codebases, they operate without awareness of architectural guardrails, lifecycle boundaries, or physical device constraints.

Android Agent Harness solves this by installing an active Five-Leaf Review Gate, deterministic safety hooks, live Gradle execution monitors, Room database validation, bilingual string parity, and physical device test runners directly into your repository.

The Problem We Solve

Quickstart in 2 Minutes

To install the harness in your Android app:

1. Open your AI assistant (Antigravity, Cursor, Claude Code, etc.) in your Android project root directory.
2. Select a deep reasoning model (e.g. Claude Opus 5 / 3.7 Sonnet (Thinking), Gemini 3.1 Pro (Deep Think), GPT-5.6 Sol, or DeepSeek-R1).
3. Copy and paste the installer prompt:

Read and execute the Android Harness Kit installer:
https://raw.githubusercontent.com/rabee-elkholy/android-harness-kit/main/docs/install-prompt.md

1. Follow the interactive questionnaire to configure your project. Once verified with Total test failures: 0, your repository is fully protected.

For step-by-step guidance, see the Quickstart Guide.

Architecture Workflow

The harness enforces a deterministic, 7-stage quality delivery lifecycle:

flowchart TD
    Start(["1. Task / Feature Request"]) --> Plan["2. Planning Guard: implementation_plan.md"]
    Plan --> Approval{"Developer Approval"}
    Approval -- Revisions --> Plan
    Approval -- Approved --> Code["3. Code Implementation & Edits"]
    
    Code --> ReviewGate["4. Five-Leaf Parallel Review Gate"]
    subgraph ReviewGate ["Parallel Reviewer Subagents"]
        R1["Bug & Null-Safety Reviewer"]
        R2["Architecture & Convention"]
        R3["Security & Permissions"]
        R4["Perf & ANR Guardian"]
        R5["Regression Blast Radius"]
    end
    
    ReviewGate --> Verdict{"All 5 Leaves PASS?"}
    Verdict -- Findings Found --> Code
    Verdict -- All 5 PASS --> Preflight["5. Preflight Sanity Verification"]
    
    subgraph Preflight ["Automated Preflight Suite"]
        P1["Fast Kotlin Lint"]
        P2["Room DB Migrations"]
        P3["Bilingual String Parity"]
    end
    
    Preflight --> TestCheck{"Unit Tests Enabled?"}
    TestCheck -- Enabled --> UnitTests["Unit Tests: testDebugUnitTest"]
    UnitTests -- Tests Fail --> Code
    UnitTests -- Tests PASS --> Gradle["6. Live Gradle Runner: assembleDebug"]
    TestCheck -- Skipped --> Gradle
    
    Gradle --> Device["7. Physical Device Runner: run_device.py"]
    Device --> ManualSignoff["Manual 4-Phase Verification"]
    ManualSignoff -- Bugs Found --> Code
    ManualSignoff -- All PASS --> ZohoCheck{"Zoho Sprints Connected?"}
    ZohoCheck -- Enabled --> Zoho["Zoho Sprints: Status Update & Commit Traceability"]
    ZohoCheck -- Skipped --> Finish(["Delivery Complete & Safe Manual Commit"])
    Zoho --> Finish

Shift-Left Proactive Quality Invariants

The harness enforces proactive engineering standards before any code is generated, ensuring the Primary Lead Agent achieves first-pass review approval:

• Null-Safety & Network Resiliency: Catch IOException/SocketTimeoutException, avoid !!, use repeatOnLifecycle.
• Clean Architecture & Imports: Strict MVI StateFlow single source of truth, zero inline FQCNs, explicit top-level imports.
• Accessibility & Compose: Mandatory contentDescription on non-decorative images/icons, touch targets >= 48dp, dual-locale @Preview (en/ar).
• Performance & Battery: Zero I/O on Dispatchers.Main, sensor unregistration in onPause()/DisposableEffect.onDispose, Android 14 foreground service rules.
• Room Database Migrations: Mandatory version bump and explicit Migration(from, to) on any @Entity schema modification.

The Five-Leaf Review Gate

Before any Gradle build or device installation can proceed, the AI assistant must dispatch 5 specialized reviewer subagents in parallel. Every subagent inspects the exact package diff and outputs a structured pass token:

[BUG_PASS]         -- Verified by Bug & Network Resiliency Reviewer
[CONVENTION_PASS]  -- Verified by Architecture, Accessibility & KMP Reviewer
[SECURITY_PASS]    -- Verified by Security & Privacy Reviewer
[PERF_PASS]        -- Verified by Performance, Battery & ANR Guardian
[REGRESSION_PASS]  -- Verified by Regression Blast Radius Reviewer

1. Bug & Network Resiliency Reviewer (bug-reviewer-agent)

• Focus: Logical correctness, null safety, lifecycle, and network error recovery.
• Catches: Unhandled NullPointerException risks, uncaught coroutine cancellations, improper StateFlow collection without repeatOnLifecycle, uncaught SocketTimeoutException/IOException in API flows, missing error UI states, and infinite retry storms without exponential backoff.

2. Convention, Accessibility & KMP Reviewer (convention-reviewer-agent)

• Focus: Structural cleanliness, MVI/Clean Architecture, accessibility compliance, and KMP code purity.
• Catches: Mutable state exposed outside ViewModels, missing contentDescription on Compose icons/images, clickable components with touch targets < 48dp, android.* framework imports leaking into KMP commonMain, and missing dual-locale @Preview annotations (en/ar).

3. Security & Privacy Reviewer (security-reviewer-agent)

• Focus: Android component security, permission boundaries, and data storage.
• Catches: Exported Activities/Receivers without explicit intent filters or permissions, plaintext credentials/API keys, SQL injection in raw Room queries, and sensitive data printed to production Logcat.

4. Performance, Battery & ANR Guardian (perf-anr-guardian-agent)

• Focus: UI fluidity (60/120 FPS), main thread responsiveness, sensor lifecycles, and battery footprint.
• Catches: Disk or network I/O executed on Dispatchers.Main, heavy allocations during Jetpack Compose recomposition phases, unreleased WakeLocks, active SensorEventListener (pedometer/accelerometer) leaks during background/pause, and Android 14+ foreground service type violations.

5. Regression Blast Radius Reviewer (regression-impact-reviewer-agent)

• Focus: Cross-feature dependency graphs and change impact radius.
• Catches: Renamed ViewModel functions breaking secondary screens, altered data models breaking JSON serialization, modified navigation arguments breaking deep links, and shared database migrations.

Dedicated On-Demand Specialists

For specific investigations and testing tasks, the harness provides dedicated on-demand specialists:

• qa-diagnostics-agent: Physical device Logcat forensic analysis and ANR root-cause investigation.
• android-ui-expert-agent: Jetpack Compose and legacy XML UI layout, theming, RTL, and responsiveness.
• test-quality-reviewer-agent: Audits unit and UI test suites (*Test.kt), verifying assertion depth, mocking integrity, and Coroutine runTest dispatchers.

Safety Hooks & Execution Governance

The harness incorporates a Python-driven safety interception layer (pre_tool_safety.py and hooks.json) that monitors all AI tool invocations in real time.

Strict Git Mutation Protection

AI models frequently attempt to cover mistakes by making unauthorized commits or force-pushing branches. The harness intercepts:

• git commit / git push / git reset --hard
• PowerShell and bash subshell bypasses (sh -c "git commit", cmd.exe /c git commit)
• Executable paths (git.exe commit)

Developers retain sole authority over repository history.

Anti-Polling Guardrails

To prevent models from getting stuck in infinite polling loops (>2 calls to manage_task or manage_subagents), the hook enforces event-driven reactive wakeups and denies redundant poll requests.

Ephemeral State Machine

_hook_state.py tracks the review lifecycle per conversation:

• Packages are hashed to ensure reviewers inspect the exact active changes.
• Automatically unlocks re-dispatching if missing subagent templates are defined (re_dispatch_allowed).
• Clears review tokens when new code modifications are detected.

Preflight Verification Pipeline

Before compiling the application with Gradle, preflight_check.py runs three rapid static verification checks in under 2 seconds:

Fast Kotlin Lint

• Verifies package declarations, import hygiene, and Kotlin syntax.
• Enforces Jetpack Compose @Preview tags for both LTR (English) and RTL (Arabic) locales.

Room Database Migration Guard

• Scans @Database and @Entity declarations for schema changes.
• Requires explicit Migration(from, to) classes and schema version bumps whenever database fields are added or modified.

Bilingual String Parity Check

• Analyzes res/values/strings.xml and res/values-ar/strings.xml.
• Flags missing translations, mismatched placeholder arguments (%1$s), and ignores translatable="false" system strings.

Live Gradle Streaming Runner

Executing Gradle builds directly through AI tool interfaces often causes timeouts, silent freezes, or lost output.

run_gradle_task.py provides:

• 10-Second Live Heartbeat: Continuously streams stdout/stderr to prevent assistant timeout.
• Intelligent Error Parser (gradle_error_parser.py): Filters thousands of lines of Gradle output to extract the exact compiler error, file path, and line number.
• Build Isolation: Executes safely with project-specific daemon configurations.

python .agents/scripts/run_gradle_task.py :app:assembleDebug

Physical Device Runner & Logcat Doctor

The harness prioritizes real-world physical hardware testing over emulators:

python .agents/scripts/run_device.py --package com.example.app --activity .MainActivity

• Auto-Discovery: Automatically identifies connected physical Android devices over ADB USB / Wi-Fi.
• Logcat Doctor (logcat_doctor.py): Captures real-time stack traces, uncaught exceptions, and ANR traces specifically filtered to your application ID.
• Screen Capture (capture_screen.py): Automatically captures UI screenshots for visual sign-off.

Zoho Sprints MCP Integration

The harness includes a built-in Model Context Protocol (MCP) server for Zoho Sprints:

sequenceDiagram
    participant Dev as Developer / AI Agent
    participant MCP as Zoho Sprints MCP Server
    participant Zoho as Zoho Sprints API
    participant QA as QA Testing Team

    Dev->>MCP: zoho_get_task_details(task_id)
    MCP->>Zoho: Fetch Bug Description & Attachments
    Zoho-->>Dev: Ticket Context, Steps to Reproduce
    Note over Dev: Code Implementation & 5-Leaf Review Gate
    Dev->>MCP: zoho_update_task_status("Ready To ReTest")
    Dev->>MCP: zoho_add_comment(Arabic/English QA Handoff + Commit Hash)
    MCP-->>Zoho: Status Updated & Commit Traceability Logged
    Zoho-->>QA: Notification with Exact Testing Steps

• Bi-Directional Sync: Reads tasks, subtasks, bug reports, and attachments directly.
• QA Handoff: Generates structured Arabic and English testing handoff notes with the exact Git Commit SHA for complete audit traceability.

Supported AI Tools & Adapters Matrix

The harness supports 14+ AI coding assistants and IDEs, automatically generating native configuration adapters:

Installation & Setup Modes

Mode A: Existing Android / KMP App

Run the installer in an established codebase. The setup wizard inspects your libs.versions.toml, Gradle dependencies, and existing architecture (MVI/MVVM, Compose, Room, Koin/Hilt) and generates custom domain reference skills tailored to your app.

Mode B: Greenfield / Blank Project

For brand-new or blank projects, the wizard guides you through an 8-question Architecture Foundation Questionnaire:

1. Target Platform: Android Native vs Kotlin Multiplatform (KMP).
2. Architecture: MVI (Unidirectional) vs MVVM.
3. Dependency Injection: Koin vs Hilt vs Manual.
4. Navigation: Voyager vs AndroidX Navigation Compose.
5. UI Framework: Jetpack Compose vs XML Views.
6. Local Database: Room vs SQLDelight vs Realm.
7. Networking: Ktor Client vs Retrofit + OkHttp.
8. Localization: Bilingual Arabic (RTL) + English (LTR) vs Single Locale.

Upgrades & Rollbacks

• Upgrade: Paste docs/update-prompt.md into your chat. Upgrades preserve custom domain references and product configurations while updating core scripts and hooks.
• Rollback: Paste docs/rollback-prompt.md into your chat to cleanly restore previous backups.

Setup Wizard & Configuration Reference

The setup wizard configures 18 parameters (I.1 to I.18) stored in _product.py:

Self-Tests & CI/CD Pipeline

The harness includes a comprehensive self-test suite (_hook_selftest.py) validating:

• Hook blocking rules (git commit, adb monkey, pm clear).
• 5-Leaf Review Gate verification tokens and hash lockout recovery.
• Python syntax, fast linting, and Room migration parsers.
• Zero credential leaks in MCP configurations.

Run Local Self-Tests:

python agents/scripts/_hook_selftest.py
python agents/scripts/preflight_check.py

GitHub Actions CI Matrix:

Every push and pull request is automatically tested across:

• Operating Systems: ubuntu-latest, windows-latest
• Python Versions: 3.10, 3.11, 3.12, 3.13

Contributing & Community

Contributions from the Android and Kotlin Multiplatform development community are welcome.

• Report Bugs: Use our Bug Report Form.
• Suggest Features: Propose new reviewer subagents or tool adapters via our Feature Request Form.
• Contributing Guide: Read CONTRIBUTING.md for local setup and commit standards.
• Discussions: Connect on GitHub Discussions.

License

Distributed under the MIT License. See LICENSE for complete terms.