SuperAPI AI Directory

jugg-android-dev-loop

General & other

View repository

Updated 10-16 08:33

About this skill

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 (Chinese or English is acceptable). 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. Run compile-class commands (compile, deploy, gradle-build, and instrument) as a single foreground CLI call, wait for that process to exit, then parse its output once. These commands may trigger Gradle internally; do not start them in the background or poll status, processes, logs, files, or Git state to infer progress. Process exit is the only completion signal. Completion means the compile/deploy job reached a terminal state; CLI does not add an extra app-ready wait.

Block the agent loop as well as the CLI. A terminal tool may return a running session before the foreground command exits. Keep waiting for that same session inside one long-running tool invocation until the process exits; do not return control to the agent after short waits. In Codex, use one functions.exec call with an outer yield_time_ms long enough for the expected build, and await exec_command plus any required write_stdin session waits inside that call. Do not set a short outer yield (such as 1–30 seconds), repeatedly call wait tools from the agent loop, send progress messages, or inspect status/logs while the command is running. If the tool forces an early yield, use its longest supported blocking wait on the same session until exit. Parse the final output once.

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.