jugg-android-dev-loop

name	jugg-android-dev-loop
version	1.0.27
date	2026-09-04T00:00:00.000Z
description	Use when editing source files (Java/Kotlin/XML/layout/AndroidManifest/Gradle) in a Android project, or when user asks to build/deploy/verify an Android app. Don't trigger on a non-Android project e.g. IntelliJ plugin project or common java/kotlin project.

Jugg Android Dev Loop

What is Jugg? Jugg is an Android tools that bypasses full Gradle builds via incremental compilation and deployment, reducing build frequency while preserving Gradle artifacts.

This skill use Jugg CLI to drive development loop for Android: modify → build → deploy → verify → iterate.

---

Definition - Auto-Run Entry

An auto-run entry is a user-designated method (e.g. com.myapp.Test.run) that runs automatically after app launch. Agent writes verification code into it and inspects logs/UI to confirm behavior. It is the primary verification mechanism in the Jugg dev loop.

⚠️ Entry location is NOT auto-discoverable. The user must declare the fully-qualified method name in the prompt (中文或 English 均可). If not declared and not visible in context, stop and ask — do not guess or search the codebase. To author the entry body, see references/guide_write_auto_run_entry_code.md.

---

Phase 0 — Context Interview

Collect mandatory variables before any action. For install-only requests, skip Jugg project status collection.

Variable	Source	Fallback
projectDir	CLI auto-resolved from $PWD, or explicit --project-dir <path> when provided	Ask user only if neither current directory nor provided path identifies the target project
hasAutoRunEntry	true only when the user has explicitly declared the entry's fully-qualified method (e.g. com.myapp.Test.run) in the prompt or current context. See § Auto-Run Entry.	Default false. Never infer from code search.
enabledAndroidTest	Project status context. Reuse existing credible context first, e.g. a hook block's Jugg status plain key-value output. If absent, run python3 {SKILL_DIR}/scripts/jugg.py --console=json status and read data.enabledAndroidTest.	Default unknown. Do not assume.

---

Phase 1 — Scenario Route & Load

Route based on context, then load primary reference:

if user asks to install jugg CLI (e.g. "install jugg cli", "add jugg cli to PATH"):
  → references/guide_install_cli.md
elif user asks to run androidTest / instrumented unit tests, or the task is anchored in src/androidTest:
  → references/flow_android_test.md
elif hasAutoRunEntry == true:
  → references/flow_with_auto_run.md
else:
  → references/flow_compile_deploy.md

Scenario	Primary Reference	Supplementary (on-demand)
install jugg CLI	references/guide_install_cli.md	—
androidTest / instrumented unit tests	references/flow_android_test.md	references/error_patterns.md, references/cli_manual.md
compile/deploy	references/flow_compile_deploy.md	references/error_patterns.md, references/policy_incremental_compile_limits.md
verify with auto-run entry	references/flow_with_auto_run.md	references/guide_write_auto_run_entry_code.md, references/error_patterns.md

Supplementary references load on-demand at the step that needs them.

---

Mandatory Rules

#	Rule
1	Route by scenario first; do not mix flows
2	Complete all source file edits first, then trigger compile/deploy once. Never compile after each individual file edit.
3	Any source modification must pass compilation before task is done

---

CLI Quick Reference

Entry

python3 {SKILL_DIR}/scripts/jugg.py [--project-dir <path>] <subcommand> [options]
python3 {SKILL_DIR}/scripts/jugg.py help <subcommand>

Output Format

Build & Deploy Commands

All build commands block until completion; no polling needed. Completion means the compile/deploy job reached a terminal state; CLI does not add an extra app-ready wait.

Command	Purpose	When to Use
compile	Compile modified sources, skip deploy	Default after ordinary source edits, including generic "verify/check modification"
deploy	Compile + deploy to device	Need to launch/run app to inspect runtime/UI state, or perform device-side verification
gradle-build	Full Gradle compile fallback	After deploy/compile retries exhausted and still failed
clean-reinstall	Clear app data(compat with apply changes) + launch device	Only for clean APP data
instrument	Run androidTest	Verify android test result

python3 {SKILL_DIR}/scripts/jugg.py compile
python3 {SKILL_DIR}/scripts/jugg.py deploy
python3 {SKILL_DIR}/scripts/jugg.py gradle-build
python3 {SKILL_DIR}/scripts/jugg.py clean-reinstall

python3 {SKILL_DIR}/scripts/jugg.py instrument --source-path library1/src/androidTest/kotlin/com/example/FooTest.kt
python3 {SKILL_DIR}/scripts/jugg.py instrument --source-path library1/src/androidTest/kotlin/com/example/FooTest.kt --class com.example.FooTest
python3 {SKILL_DIR}/scripts/jugg.py instrument --source-path library1/src/androidTest/kotlin/com/example/FooTest.kt --class com.example.FooTest --method testSomething
python3 {SKILL_DIR}/scripts/jugg.py instrument --source-path library1/src/androidTest/kotlin/com/example/FooTest.kt --extras 'size=large;clearPackageData=true'

Runtime Basic Commands

python3 {SKILL_DIR}/scripts/jugg.py restart              # restart app
python3 {SKILL_DIR}/scripts/jugg.py status               # refresh changed files and show status summary
python3 {SKILL_DIR}/scripts/jugg.py status --refresh-changes false  # skip changed-file refresh
python3 {SKILL_DIR}/scripts/jugg.py status --full-info true  # return full status information and all file paths
python3 {SKILL_DIR}/scripts/jugg.py activity-stack       # show current Activity stack
python3 {SKILL_DIR}/scripts/jugg.py devices              # list connected devices
python3 {SKILL_DIR}/scripts/jugg.py wait-logs --marker '\[JUGG_AR\] DONE'  # --marker: Java Pattern regex matched against log message; block until marker/crash/timeout

python3 {SKILL_DIR}/scripts/jugg.py wait-logs --marker '<regex>' [--tags t1,t2] [--timeout-ms ms]
# stopReason: marker → parse logs; crash → FAIL; timeout → INCONCLUSIVE → see references/cli_manual.md §wait-logs for flags

UI Commands (low-frequency)

For UI interaction/inspection (tap, view-locate, view-inspect, layout-dump) → load references/cli_manual.md.

Build Fallback Chain

On compile/deploy failure, follow this order:

1. Read error detail.
2. Modify source and retry the selected command (compile or deploy) up to 3 times.
3. If still failing → gradle-build.
4. Call ssh-info (requires explicit user consent) when gradle-build is remote compile and still failing.
5. Still unclear → stop, ask user.