Imported from adrigm06/AndroBox (AGENTS.md). Install upstream with npx skills add adrigm06/AndroBox. Copyright stays with the author.

AGENTS.md

Guidance for agentic coding agents operating in this repository. Scope: entire repo (/).

1) Project Snapshot

• Project Name: AndroBox (Android Developer & Designer Workbench Utility)
• Build System: Gradle (KTS) with wrapper (gradlew.bat / ./gradlew)
• Target SDK Config (app/build.gradle.kts):
  • minSdk = 31 (Android 12)
  • targetSdk = 36 (Android 16 DP)
  • compileSdk = 36
• Main Module: :app
• Key Stack:
  • Kotlin + Compose Material3 + Navigation Compose
  • AndroidX Lifecycle ViewModels + Runtime Compose State Management
  • Glance AppWidget API (used for the Wireless ADB debug home screen widget)
  • Foreground Services (used for floating WindowManager overlays)
  • Google Play Services ML Kit Text Recognition (used for screen magnifying OCR)

2) Source Layout (Current)

All source code files are structured under the package name com.adrigm.androbox:

• App Entry Point: app/src/main/java/com/adrigm/androbox/MainActivity.kt
• Compose App Shell: app/src/main/java/com/adrigm/androbox/ui/AndroBoxApp.kt
• UI Screen Compositions: app/src/main/java/com/adrigm/androbox/ui/screens/*
• Theme & Design Tokens:
  • app/src/main/java/com/adrigm/androbox/ui/theme/*
  • app/src/main/java/com/adrigm/androbox/ui/design/*
• Developer Tools & Modules:
  • app/src/main/java/com/adrigm/androbox/ui/tools/* (Registry, features, and repositories)
• System Services & Floating Overlays:
  • app/src/main/java/com/adrigm/androbox/widget/overlay/* (ruler, eyedropper, magnifiers, etc.)
• Home Widget & Diagnostics:
  • app/src/main/java/com/adrigm/androbox/widget/wireless/* (Glance widgets)
  • app/src/main/java/com/adrigm/androbox/stats/* (system, RAM, CPU, thermal diagnostics)
• Resources: app/src/main/res/*

3) Build / Lint / Test Commands

Always use the Gradle wrapper only. Do not run global system Gradle commands.

Cross-platform Executables

• macOS / Linux / Bash: ./gradlew <task>
• Windows PowerShell / CMD: gradlew.bat <task>

Compilation and Packaging

• Build Debug APK:
  • gradlew.bat :app:assembleDebug
• Build Release APK:
  • gradlew.bat :app:assembleRelease
• Full Clean Build:
  • gradlew.bat clean build

Quality Assurance & Linting

• Lint Debug Variant:
  • gradlew.bat :app:lintDebug
• Lint All Variants:
  • gradlew.bat :app:lint

JVM Unit Tests

• Run All Unit Tests:
  • gradlew.bat :app:test
• Run Debug Unit Tests:
  • gradlew.bat :app:testDebugUnitTest
• Run Single Test Class:
  • gradlew.bat :app:testDebugUnitTest --tests "com.adrigm.androbox.ExampleUnitTest"
• Run Single Test Method:
  • gradlew.bat :app:testDebugUnitTest --tests "com.adrigm.androbox.ExampleUnitTest.addition_isCorrect"

Emulator/Device Instrumentation Tests

• Run Connected Android Tests:
  • gradlew.bat :app:connectedDebugAndroidTest
• Run Single Connected Class:
  • gradlew.bat :app:connectedDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.class=com.adrigm.androbox.ExampleInstrumentedTest

4) Code Style Guidelines

Follow official Kotlin conventions, Android Jetpack Compose best practices, and the custom styling guidelines of AndroBox.

Imports

• Use explicit imports; wildcard imports (import foo.*) are strictly forbidden.
• Clean up and remove unused imports before compiling.
• Keep imports ordered alphabetically.

Indentation and Formatting

• Use 4-space indentation. Never use tabs.
• Limit lines to a readable length (aim around 100-120 characters).
• Trailing commas are highly encouraged in multiline declarations for clean diff records.
• Keep Compose function parameters vertically aligned and readable.

Types, Scope, and States

• Maximize immutability: prefer val over var whenever possible.
• Use explicit types if a function call return is non-obvious; rely on type inference for standard definitions.
• Model UI states using immutable Kotlin data class models (e.g., WirelessDebugUiState).
• ViewModels must expose state flow as read-only properties (e.g., StateFlow<T>) using .asStateFlow().

Naming Conventions

• Packages: All lowercase (com.adrigm.androbox).
• Classes / Interfaces / Objects / Enums: PascalCase (e.g., ScreenMagnifierService).
• Functions / Properties / Variables: camelCase (e.g., activeToolsMap).
• Compile-time Constants: UPPER_SNAKE_CASE (e.g., const val EXTRA_COLOR_VALUE).
• Composable Functions: PascalCase and role-based (e.g., DashboardScreen).
• Resources (XML/Assets): snake_case (e.g., androbox_tool_ocr_title).

Jetpack Compose Standards

• Maintain modular design: extract large Composable UI trees into focused, isolated sub-composables.
• Hoist state upwards: keep composables stateless where possible and pass event callbacks back up.
• Never write heavy business logic, DB queries, or direct disk/network reads inside Composable functions.
• Never use hardcoded hexadecimal colors on individual screens. Always consume design tokens through the active theme structure (MaterialTheme.colorScheme or custom branding objects).
• All visible strings must be declared in strings.xml and loaded via stringResource(id). Do not embed raw string literals.

5) Custom Design & Styling Guidelines

AndroBox is constructed with a highly consistent Neo-Brutalist visual system. All new pages, components, and tools must align with these parameters:

Core Typography

• Font Family: JetBrains Mono exclusively. This monospaced aesthetic enforces developer-terminal raw data precision.
• Weights: Use bold (700) for headers and interface labels; regular (400) for body blocks.

Geometries and Shapes

• Light Mode (Blueprint theme):
  • Rounded corners: 4px (0.25rem) to maintain a soft-sharp structure.
  • Border stroke: 2px solid black for high-ink visibility.
  • Shadows: Hard zero-blur offset shadows (e.g., 4dp horizontal/vertical offset using pure black #000000).
• Dark Mode (Terminal theme):
  • Rounded corners: Strictly 0px (perfect sharp corners).
  • Border stroke: 1px or 2px solid white or Neon Green borders.
  • Shadows: Hard zero-blur offset shadows utilizing pure black or primary Neon Green.

Layout System

• Rhythm: Strictly stick to an 8px grid increment spacing standard. All offsets, gutters, card paddings, and column spacings must be multiples of 8.
• Margins: A standard 16px safety margin is enforced for mobile screen borders.
• Grids: Underlay layouts with a blueprint-style grey lines structure to visual scale.

6) Security and System Boundaries

• Permissions Gating: Always perform explicit runtime permission checks before invoking system alerts (SYSTEM_ALERT_WINDOW) or starting media captures (MediaProjection).
• Foreground Services: Starting in Android 14+ (targetSdk 34 to 36), foreground service classifications must be explicitly set. Ensure mediaProjection or other appropriate types are declared in the AndroidManifest.xml and associated notification banners are launched immediately.
• Safe Recoveries: Wrap critical platform capabilities (Clipboard access, file extraction, directory creation) in defensive try-catch structures. Render beautiful, user-safe error messages inside the UI state instead of crashing.
• Credentials Security: Never commit local properties, personal emulator paths, local keys, keystores, or platform credentials.

7) Agent Working Agreements

• Minimalist Scope: Apply focused, surgical adjustments. Never rewrite entire directories, layouts, or package declarations unless explicitly commanded.
• Commit Precision: Commit changes sequentially. Break features, enhancements, and refactoring sessions into independent, descriptive Git commits following the conventional style:
  • feat(component): add new capability
  • fix(component): resolve defect
  • refactor: clean up structure
  • docs: update documentation
• Verify Build Integrity: Never end a turn without verifying the project compiles successfully. Execute at least gradlew.bat :app:assembleDebug or gradlew.bat build after modifying any sources.
• Test Compliance: Run relevant local or instrumented tests to verify behavior and ensure that coverage remains complete.