androiduse-module-development

# AndroidUse Module Development Use this skill to develop AndroidUse runtime modules and dynamic hook tooling. Treat AndroidUse modules as Rust-first native components compiled into Android shared libraries. Avoid LSPosed APK, Vector database edits, or Java APK shell paths unless the user explicitly asks for a separate experiment. ## Required First Step Read `references/module-spec.md` before changing module code. Keep the spec and implementation aligned. When implementation reveals a better rule, update the spec in the same turn before continuing. ## Core Rules - Implement AndroidUse runtime modules in Rust. - Compile runtime modules as Android `.so` files. - Package `.so` files through the AndroidUse root module under `src/AndroidUse/`. - Use Zygisk for app-process injection. - Keep the MCP server as the control plane and dynamic tool registry. - Store user-editable config under `.config/androiduse/`. - Store runtime queues and logs under `.state/` and `.log/`. - Preserve user config during module upgrades. - Do not touch LSPosed/Vector databases. - Do not reintroduce LSPosed shell APK installation paths. ## Development Workflow 1. Inspect current state with `git status --short`, relevant source files, and existing AndroidUse config paths. 2. Read `references/module-spec.md`. 3. Make the smallest implementation step that moves the Rust `.so` and MCP dynamic tool pipeline forward. 4. Run local verification: - `cargo fmt -- --check` - `cargo check -p androiduse-cli` - `cargo check` inside Rust submodules changed in the turn - `tools/build_zygisk_module.sh` when native loader code changed 5. If a real device is connected and the change affects runtime behavior, build and install the AndroidUse module, reboot if needed, then verify with adb and logcat. 6. Update this skill or `references/module-spec.md` when practice exposes a new invariant, path, command, or failure mode. ## Dynamic Tool Workflow - Register MCP tools with `generate_new_hook_tool`. - Store blueprints and source under `.config/androiduse/dynamic-tools/`. - Queue calls under `.state/dynamic-tools/requests/`. - Expect injected Rust payloads to write responses under `.state/dynamic-tools/responses/`. - Use `dynamic_tool_status` to inspect the queue before debugging app-side code. - Treat dynamic tool completion as transport evidence only. For app-side behavior, require a payload response that proves the current in-app context was found and the intended internal path ran. ## In-App Hook Workflow - Start with a read-only probe that reports the active activity, fragment tree, candidate object classes, and why the hook is or is not ready. - Do not use stale cached objects for real actions. Cached app objects may be reported for diagnostics, but a real action must resolve the current live context in the target process. - Do not report success from `JNI call returned`, `no Java exception`, queued request completion, or a generic network byte signal. Report success only after a target-specific app callback, response object, server/network receipt, or user-visible confirmation. - Keep UI automation out of app-specific AUZM implementations. Generic UI tools can prepare state, but the AUZM tool itself must use the app's internal runtime path or return a clear not-ready response. - If an app changes from one internal surface to another, such as replacing a feature fragment with a shared keyboard/input fragment, add a diagnostic probe first. Do not keep adding blind fallbacks to the action path. - Design the final MCP tool as one call. Any multi-step discovery needed during development should be collapsed into payload-side readiness checks and actionable error fields before the tool is considered usable. ## Build Notes Use `cargo ndk` for Android shared libraries. Prefer arm64 first because the current test device is arm64 and AndroidUse currently packages `zygisk/arm64-v8a.so`. Extend ABI support only when the root module packaging and verification also cover those ABIs. ## Safety Boundary Focus on owner-controlled automation, observability, compatibility adaptation, and UI tooling. Do not implement credential theft, hidden monitoring, CAPTCHA bypass, DRM bypass, or unauthorized security-boundary bypass. ## References - `references/module-spec.md` - AndroidUse module specification and current protocol.